Skip to content

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