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_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_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.