cogpy.brainstates.brainstates

Short summary of the module.

This module provides utilities for mapping numerical values to interval-based states, organizing DataFrame columns into state labels, validating interval structures, and analyzing state transitions and durations.

Status

WIP

Metadata

Author : Arash Shahidi <A.Shahidi@campus.lmu.de> Last Updated : 2025-08-26

Extended description of the module.

The module focuses on interval-based state classification and transition analysis. It offers core tools for verifying disjoint intervals, mapping time series or numerical values to state definitions, computing state durations, handling micro- and macro-state relationships, and converting state dictionaries into structured DataFrames. Testing utilities are included to ensure correct mapping and labeling behavior.

Notes

  • State intervals are defined as [start, end] pairs in lists, tuples, or arrays.

  • Functions assume state labels are strings.

  • Many utilities operate on DataFrames containing time or numeric columns to be classified into state intervals.

  • Mapping functions return DataFrames that encode state membership using period indices or -1 for non-membership.

  • The module includes tools for cleaning corrupt intervals and subtracting microstates from macrostates to produce purified state sets.

  • Transition analysis functions generate DataFrames describing when and how states change over time.

See also

cogpy.brainstates.intervals

Tools for signal segmentation, event detection, or additional state-processing utilities.

Examples

Functions

append_intermediate_sleep_intervals(states)

IS_dur = 30 # transition window size

append_transition_intervals(states, ...[, ...])

Appends intervals around transitions between specified states to the dictionary of states.

check_disjoint_states(states)

Checks if the state intervals in a dictionary are non-overlapping.

drop_corrupt_intervals(states)

Drops intervals with end time less than or equal to start time.

drop_micro_states(macro_state_intervals, ...)

Drops microstate intervals from macrostate intervals.

filter_by_states(df_labeled_states, ...[, ...])

Filters a DataFrame based on the presence of certain states and the absence of others.

get_exclusive_state_df(rec_df, col, state, ...)

get_state_durations(states_df)

Calculates the total duration of each state from the state intervals.

get_states_df(states)

Converts a dictionary of state intervals to a DataFrame with state edges.

label_numbers_by_state_intervals(tarr, states)

purify_macro_states(states, macro_states, ...)

Purifies the state intervals by removing microstate intervals from macrostate intervals.

sort_col_into_states(df, col, states[, ...])

Sorts a column of a DataFrame into predefined state intervals and returns a DataFrame

state_transition_interval(states, ...)

Detects transitions between specified start and end states and creates intervals around the transition times.

state_transitions(states[, next_state_])

Converts a dictionary of state intervals to a DataFrame with state transitions.