Behavior specific: cicada_tools.behavior¶
from cicada_analysis.cicada_tools.behavior.<module> import <function>
behavior.behavior_analysis_utils (DLC traces)¶
-
build_dlc_psth_df¶
build_dlc_psth_df(signals, trial_timestamps, psth_start_in_sec, psth_stop_in_sec, subtract_baseline=True) -> pd.DataFrame
Behavioral series aligned on events: one row per series column and event; the caller adds its own columns (groups, session...). Each series is aligned on its own timestamps, at its own rate. A 2-3 column series (e.g. x / y position) gives '<name> x', '<name> y' ('<name> z'). Events whose window leaves the recording are left out.
| Parameter | Type | Default | Description |
|---|---|---|---|
signals |
dict | {name: (values, timestamps)}: values (n_frames,) or (n_frames, n_columns), timestamps in seconds |
|
trial_timestamps |
np.ndarray | Event times (s) | |
psth_start_in_sec |
float | Window before each event (s) | |
psth_stop_in_sec |
float | Window after each event (s) | |
subtract_baseline |
bool | True | Each event minus the mean of its window before the event |
Returns: pd.DataFrame — columns behavior_movie_data_event (the aligned values of one event, an array), time (the time of each value relative to the event, s, an array) and bodypart (the series column); empty when no event is kept
-
preprocess_dlc_series¶
preprocess_dlc_series(values) -> np.ndarray
preprocess_dlc_trace on each column of a series.
| Parameter | Type | Description |
|---|---|---|
values |
np.ndarray | (n_frames,) or (n_frames, n_columns) |
Returns: np.ndarray — float (n_frames, n_columns), also for a 1-D input
-
preprocess_dlc_trace¶
preprocess_dlc_trace(trace) -> np.ndarray
Remove the statistical outliers of a DLC trace: samples with |z-score| > 20 become NaN, then the NaN are interpolated linearly. A constant trace is unchanged; an all-NaN trace stays NaN.
| Parameter | Type | Description |
|---|---|---|
trace |
np.ndarray | 1-D DLC trace |
Returns: np.ndarray — float copy, same length
behavior.behavior_analysis_plots (Behavior plots)¶
-
plot_behavior_series¶
plot_behavior_series(series, path_results, file_name, title='', bands=None, band_alpha=0.5, figsize=(15, 8), line_width=None, event_line_width=None, legend_position='outside right', save_formats='png', dpi=150, time_range=None) -> None
Behavioral time series over time, one panel each on a shared time axis, with bands over every panel (events, epochs, stimulations). Text sizes, axes and colours follow the matplotlib settings (the figure style of a run).
| Parameter | Type | Default | Description |
|---|---|---|---|
series |
list[dict] | One panel each, in order: {'name', 'unit', 'times' (s), 'values' ((n_samples,) or (n_samples, n_columns)), 'color', 'columns' (names of the columns, for the legend)}; the columns of a series take the colours of the matplotlib cycle |
|
path_results |
str | Folder of the figure | |
file_name |
str | File name without extension | |
title |
str | '' | Figure title |
bands |
tuple | None | (intervals, colors, labels): per group, [(start, stop)] in s (a line when start = stop), its colour and its name |
band_alpha |
float | 0.5 | Opacity of the bands |
figsize |
tuple | (15, 8) | (width, height) in inches |
line_width |
float | None | Width of the lines (pt); None: the matplotlib settings |
event_line_width |
float | None | Width of the bands without duration (pt); None: line_width |
legend_position |
str | 'outside right' | 'outside right', 'inside' or 'none' |
save_formats |
str | list | 'png' | Format(s) of the figure |
dpi |
int | 150 | Resolution |
time_range |
tuple | None | (start, end) of the time axis (s), the bands cut to it; None: first to last time of the series |
Returns: None — the figure is saved
behavior.dlc_visualization (DeepLabCut trajectories)¶
-
plot_psth_trajectory¶
plot_psth_trajectory(data, name, x='time', hue=None, palette=None, figsize=(10, 10), dpi=300, xkcd_mode=False, save_path=None, save_formats='pdf', file_name='psth_trajectory', **figure_style) -> None
Trajectory of a 2-D series aligned on events (e.g. a position): y against x in the top panel, points coloured by time; x over time and y over time below it, on one shared time axis, with their band. One line per hue level.
| Parameter | Type | Default | Description |
|---|---|---|---|
data |
pd.DataFrame | Reduced PSTH lines (stats.line_and_band / reduce_psth_level rows): bodypart '<name> x' and '<name> y', the time column x, line, low, high (NaN: no band) |
|
name |
str | Name of the series (the bodypart prefix), also the title |
|
x |
str | 'time' | Time column |
hue |
str | None | Column of the lines |
palette |
dict | None | {hue level: colour}; grey for a level without colour |
figsize |
tuple | (10, 10) | Figure size (inches); the height is adjusted so the top panel is square |
dpi |
int | 300 | Resolution |
xkcd_mode |
bool | False | xkcd style |
save_path |
str | None | Folder of the figure |
save_formats |
str | list | 'pdf' | Format(s) of the figure |
file_name |
str | 'psth_trajectory' | File name without extension |
**figure_style |
Keys of core_plots.FIGURE_STYLE (line width, band opacity, marker size, colormap of the time and its colour bar, legend position) |
Returns: None — the figure is saved