brainbox.behavior.pawstates

Set of functions for plotting paw state data.

Adapted from https://github.com/rgs2151/plumber/blob/main/plumber/pipes/ibl_overview.py.

Functions

duration_data	Calculate state durations from processed data.
extract_marker_data	Extract and process marker data for pawstates analysis.
extract_pawstate_plot_data	Extract paw state, marker, and wheel data, and process for plotting
extract_transition_data
gen_data_df	Generate processed data DataFrame with state predictions and ensemble statistics.
interval_data	Process trial interval data for raster plots.
plot_ensemble_variance_histogram	Plot histogram of ensemble mode variance values.
plot_paw_positions_by_state	Plot paw positions overlaid on video frame for a specific behavioral state.
plot_paw_speed_transitions	Plot paw speed around various state transitions.
plot_state_duration_histogram	Plot histogram of durations for a specific behavioral state.
plot_state_raster	Plot raster of behavioral states across trials.
plot_total_duration_bars	Plot bar chart of total duration percentages for each behavioral state.
plot_trial_correctness	Plot trial correctness as a binary heatmap.
plot_trial_duration	Plot trial duration as a grayscale heatmap.
plot_variance_raster	Plot raster of ensemble variance values across trials.
plot_wheel_speed_transitions	Plot wheel speed around state transitions.
raster_data	Prepare raster plot data for ensemble modes and variances.
wheel_data	Identify transition frames for wheel and movement analysis.

extract_pawstate_plot_data(data, paw, tracker)

Extract paw state, marker, and wheel data, and process for plotting

Parameters:

• data – dict with ‘{tracker}’, ‘times’, and ‘pawstates’ keys

• paw – which paw to extract data for

• tracker – pose tracker used for plotting

Returns:

augmented data dict

extract_marker_data(paw, pose_data, times_data, wheel_data)

Extract and process marker data for pawstates analysis.

Parameters:

• paw – Paw identifier (‘paw_l’ or ‘paw_r’)

• pose_data – Pose tracking data

• times_data – Camera timestamps

• wheel_data – Wheel position and velocity data

Returns:

processed_markers_df

gen_data_df(marker_data, probs, ens_vars, cam_times)

Generate processed data DataFrame with state predictions and ensemble statistics.

Parameters:

• marker_data – DataFrame with marker positions and velocities

• probs – DataFrame of state probabilities

• ens_vars – DataFrame of ensemble variances

• cam_times – Camera timestamps

Returns:

Tuple of (processed_data_df, transition_frame_indices)

duration_data(data_df, any_transition_frames)

Calculate state durations from processed data.

Parameters:

• data_df – Processed data DataFrame

• any_transition_frames – Indices of transition frames

Returns:

Tuple of (state_duration_df, duration_summary)

interval_data(data_df, trials_data)

Process trial interval data for raster plots.

Parameters:

• data_df – Processed data DataFrame

• trials_data – Trials data object

Returns:

DataFrame with trial intervals and metadata

raster_data(interval_df, data_df, fps)

Prepare raster plot data for ensemble modes and variances.

Parameters:

• interval_df – Trial interval DataFrame

• data_df – Processed data DataFrame

• fps – Camera frame rate

Returns:

Tuple of (ensemble_raster, variance_raster)

wheel_data(data_df)

Identify transition frames for wheel and movement analysis.

Parameters:

data_df – Processed data DataFrame

Returns:

Dictionary with transition frame indices

extract_transition_data(data_df, frames, data_col, pre_window=30, post_window=50)

plot_paw_positions_by_state(ax, frame, data_df, state, state_idx, camera, paw, tracker)

Plot paw positions overlaid on video frame for a specific behavioral state.

Parameters:

• ax – Matplotlib axis to plot on

• frame – Video frame as numpy array

• data_df – Processed data DataFrame

• state – Behavioral state name

• state_idx – Index of state for coloring

• camera – Camera view name

• paw – Paw identifier

• tracker – Tracker type

plot_state_duration_histogram(ax, durations, state, state_idx, xlim=None)

Plot histogram of durations for a specific behavioral state.

Parameters:

• ax – Matplotlib axis to plot on

• durations – DataFrame with state durations

• state – Behavioral state name

• state_idx – Index of state for coloring

• xlim – x-limits of plot if computed externally

plot_total_duration_bars(ax, durations)

Plot bar chart of total duration percentages for each behavioral state.

Parameters:

• ax – Matplotlib axis to plot on

• durations – DataFrame with state durations

plot_ensemble_variance_histogram(ax, data_df)

Plot histogram of ensemble mode variance values.

Parameters:

• ax – Matplotlib axis to plot on

• data_df – Processed data DataFrame

plot_state_raster(ax, er, fps)

Plot raster of behavioral states across trials.

Parameters:

• ax – Matplotlib axis to plot on

• er – Ensemble raster data array

• fps – Camera frame rate

plot_variance_raster(ax, vr, fps)

Plot raster of ensemble variance values across trials.

Parameters:

• ax – Matplotlib axis to plot on

• vr – Variance raster data array

• fps – Camera frame rate

plot_wheel_speed_transitions(ax, wheel_transitions, data_df, fps, transition_start='still')

Plot wheel speed around state transitions.

Parameters:

• ax – Matplotlib axis to plot on

• wheel_transitions – Dictionary of transition frame indices

• data_df – Processed data DataFrame

• fps – Camera frame rate

• transition_start – which state to start with

plot_paw_speed_transitions(ax, wheel_transitions, data_df, fps)

Plot paw speed around various state transitions.

Parameters:

• ax – Matplotlib axis to plot on

• wheel_transitions – Dictionary of transition frame indices

• data_df – Processed data DataFrame

• fps – Camera frame rate

plot_trial_correctness(ax, interval_df)

Plot trial correctness as a binary heatmap.

Parameters:

• ax – Matplotlib axis to plot on

• interval_df – Trial interval DataFrame

plot_trial_duration(ax, interval_df)

Plot trial duration as a grayscale heatmap.

Parameters:

• ax – Matplotlib axis to plot on

• interval_df – Trial interval DataFrame