Skip to content

session.behavior

Epochs, events, interval tables, trials, behavioural time series, speed and position, behaviour movies.

cicada_nwb.submodules.behavior.NWBBehavior

Read-only access to behavioral data stored in an NWB file. Covers: epochs, events, time series, intervals, trials, speed, position (optogenetic stimulation: see NWBOptogenetic). Methods specific to the Petersen lab (session metadata parsing, whisker reward) return None gracefully when the relevant metadata is not present. No computation — returns raw timestamps and data arrays as stored.

get_behavior_movies

get_behavior_movies(key_to_identify='behavior')

Return dict of behavior movie file paths: {key: file_path}. Only includes externally stored ImageSeries.

get_behavioral_epochs_names

get_behavioral_epochs_names()

Return list of epoch names stored in BehavioralEpochs containers.

get_behavioral_epochs_times

get_behavioral_epochs_times(epoch_name)

Return epoch times as a 2D array (2, n_epochs): row 0 = start, row 1 = stop. Start/stop are read from the IntervalSeries data sign (> 0 start, < 0 stop) when it is consistent, otherwise timestamps are paired two by two. Returns None if epoch not found.

get_behavioral_events_names

get_behavioral_events_names()

Return list of event names: BehavioralEvents TimeSeries and ndx-events Events.

get_behavioral_events_times

get_behavioral_events_times(event_name)

Return event timestamps as a 2D array (2, n_events) — both rows identical (point events). Returns None if event not found.

get_behavioral_time_series

get_behavioral_time_series(serie_name)

Return the raw pynwb TimeSeries object for a behavioral time series. Returns None if not found.

get_behavioral_time_series_column_names

get_behavioral_time_series_column_names(serie_name)

Names of the columns of a behavioral time series with several: 'x', 'y' ('z') for a position (SpatialSeries of 2 or 3 columns); None for one column, an unknown series or columns without a name.

get_behavioral_time_series_data

get_behavioral_time_series_data(serie_name, in_unit=False)

Return data for a behavioral time series as an array (n_samples, or n_samples x n_columns for e.g. x / y positions), or None. in_unit: data * conversion + offset, in the series' unit; a conversion or offset that is unknown (NaN) is left out (1, 0: data as stored, see get_behavioral_time_series_unit).

get_behavioral_time_series_names

get_behavioral_time_series_names()

Return list of time series names stored in BehavioralTimeSeries, PupilTracking, EyeTracking and Position containers.

get_behavioral_time_series_timestamps

get_behavioral_time_series_timestamps(serie_name)

Return timestamps for a behavioral time series as a 1D array, or None.

get_behavioral_time_series_unit

get_behavioral_time_series_unit(serie_name)

Return the unit of a behavioral time series (e.g. 'cm/s'), or None; 'a.u.' when its conversion factor is unknown (NaN, e.g. DANDI 000055 positions in pixels labelled 'meters'): the data are then as stored.

get_behaviors_movie_time_stamps

get_behaviors_movie_time_stamps()

Return dict of behavior movie timestamps: {cam_name: timestamps_array}. Looks for acquisition entries starting with 'cam_'.

get_epoch_table

get_epoch_table()

Return the epoch table as a pandas DataFrame, or None.

get_epochs_names_from_table

get_epochs_names_from_table(exclude_columns=_EPOCH_TABLE_EXCLUDED_COLUMNS)

Return a dict {col_name: [unique_values]} for the epoch-table columns usable to select epochs (more than one value, not unique per row). Ragged columns such as 'tags' are flattened into their unique values. Columns whose name contains one of exclude_columns are skipped. Returns None if no epoch table or no such column.

get_event_times

get_event_times(name)

Return the times (2, n) of an interval table, behavioral epoch, behavioral event or epoch-table label (value of a selectable column named ':

get_interval_as_data_frame

get_interval_as_data_frame(interval_name)

Return an interval table (see _interval_tables) as a pandas DataFrame, or None.

get_interval_times

get_interval_times(interval_name)

Return interval times as a 2D array (2, n_intervals): row 0 = start, row 1 = stop. Returns None if interval not found or missing start_time/stop_time columns.

get_intervals_names

get_intervals_names(include_trials=True, epoch_labels=False)

Return the names of the interval tables (nwb.intervals, TimeIntervals of nwb.stimulus, see _interval_tables). include_trials=False leaves out the trial table, e.g. for epoch choices when trials are an event source; epoch_labels=True replaces the epoch table by its labels (values of its selectable columns), named ':

get_mouse_position_info

get_mouse_position_info()

Return mouse position data as a transposed array and position timestamps, or position and None, or None and None. Search order: Position SpatialSeries → BehavioralTimeSeries → full NWB scan.

get_mouse_speed_info

get_mouse_speed_info()

Return mouse speed data as a transposed array and speed timestamps, or speed and None, or None and None. Search order: acquisition['running_speed'] → BehavioralTimeSeries → full NWB scan.

get_table_choices

get_table_choices(name)

{col_name: [unique values]} of the columns of interval table name (get_intervals_names) usable to select rows, as get_trials_names_from_table / get_epochs_names_from_table with their default excluded columns for the trial and epoch tables; other tables: time columns and object references left out. None if no such table or no such column.

get_table_timestamps

get_table_timestamps(name, requirements_dict, use_stop_time=False)

Return (timestamps_array, time_unit) for the rows of interval table name (get_intervals_names) matching requirements_dict ({col_name: [accepted values]}; for ragged columns such as 'tags', any accepted value matches). timestamps_array: (2, n_rows). Row 1 is stop_time if use_stop_time, else start_time + 1. time_unit: 'seconds' or 'frames' (files storing frame indices, see _table_time_unit). (None, None) if no such table or no matching row.

get_trial_table

get_trial_table()

Return the trial table as a pandas DataFrame, or None.

get_trial_table_name

get_trial_table_name()

Name of the trial table among the interval tables (get_intervals_names), or None.

get_trials_names_from_table

get_trials_names_from_table(exclude_columns=_TRIAL_TABLE_EXCLUDED_COLUMNS)

Return a dict {col_name: [unique_values]} for the trial-table columns usable to select trials (more than one value, not unique per row). Columns whose name contains one of exclude_columns are skipped (default: time columns, 'perf', 'timeseries'); which columns are relevant varies between labs, so callers can pass their own list. Returns None if no trial table or no such column.

has_epoch_table

has_epoch_table()

Return True if an epoch table is present.

has_trial_table

has_trial_table()

Return True if a trial table is present.