Family base classes¶
Plugins sharing the same kind of parameters derive from a family base class instead of
CicadaAnalysis directly. Each family adds its parameters (declared once, identical in all
its plugins) and the helpers that read them. Only the methods each class adds are listed
here; inherited ones are on the parent's page.
CicadaAnalysis
└── CicadaGroupsBase groups of cells, areas, epochs, sessions
└── CicadaEventsBase + events, trial groups, bands over plots
└── CicadaPsthBase + peri-event windows, reductions, PSTH figures
CicadaGroupsBase¶
Used by: Display calcium imaging cell maps, Connectivity graph, Spike-triggered population rate, Pairwise similarity, Transients' amplitude, Transients' frequency.
cicada_analysis.base.cicada_groups_base.CicadaGroupsBase ¶
Bases: CicadaAnalysis
Base of the plugins comparing groups: CicadaAnalysis plus the groups parameters (add_epoch_groups_arg_for_gui, add_session_groups_arg_for_gui, add_cell_types_groups_arg_for_gui, add_cell_index_groups_arg_for_gui, add_area_groups_arg_for_gui), the figure parameters (add_group_figure_args_for_gui), their readers (epoch_groups_times, session_groups, cell_groups, group_overlay, group_colors) and checks (group_params_errors). Not a plugin itself.
add_area_groups_arg_for_gui ¶
add_area_groups_arg_for_gui(family_widget='Groups', long_description=None)
'Location groups' (location_groups, units only): groups of unit areas or area groups (e.g. 'Somatosensory areas'). The plugin selects the units of each group (select_units_by_area).
add_cell_index_groups_arg_for_gui ¶
add_cell_index_groups_arg_for_gui(family_widget='Groups', long_description=None, default_value=None)
'Cell index groups' (cell_index_groups): groups of cells typed by index ('3 1 7-9', kept in the typed order; imaging: row of the activity array, units: unit id), part of the cell groups (cell_groups). default_value: groups shown at start, e.g. {"cells": [["0-9"], None]}.
add_cell_types_groups_arg_for_gui ¶
add_cell_types_groups_arg_for_gui(family_widget='Groups', long_description=None)
'Cell type groups' (cell_type_groups, shown when a loaded file has cell types): groups of cell types (ROI table for imaging, units table for ephys), part of the cell groups (cell_groups).
add_channel_groups_arg_for_gui ¶
add_channel_groups_arg_for_gui(family_widget='Groups', long_description=None)
'Channel groups' (channel_groups): groups of channels of the electrical series, by electrode group (e.g. shanks, ECoG grids and strips), location in the electrodes table or typed channel indices ('0-7 12', position in the series). Read with channel_groups; their channels: cicada_tools select_channels.
add_epoch_groups_arg_for_gui ¶
add_epoch_groups_arg_for_gui(family_widget='Groups', long_description=None)
'Epoch groups' (epoch_groups): groups of epochs or intervals the data is split by. Read with epoch_groups_times.
add_group_distribution_args_for_gui ¶
add_group_distribution_args_for_gui(kinds)
Parameters of the categorical figures of one value per cell (e.g. transient frequency, amplitude): add_group_figure_args_for_gui, the kind of groups on the x axis (x_axis), the kind of plot (representation), the comparison of the x groups (do_stats, pvalue), whether to save the figures (save_figure; the tables: save_figure_data), the image format and the figure style. Read with plot_group_distributions; checked by group_distribution_params_errors.
add_group_figure_args_for_gui ¶
add_group_figure_args_for_gui(kinds, family_widget='Figures', overlay_description=None)
Figure parameters, registered after every kind of groups is defined: 'Also one plot per session' (one_plot_per_session), 'Also one plot per mouse' (one_plot_per_mouse) and the kind of groups (among kinds) overlaid with colours (overlay_color, none by default). The plugin adds its second overlay (e.g. line styles, x axis) after it. Read with group_overlay and group_colors; checked by group_params_errors.
add_session_groups_arg_for_gui ¶
add_session_groups_arg_for_gui(family_widget='Groups')
Session groups: 'Session groups, by age' (sessions_grouped_by_age) when every session has an age under 24 days, 'Session groups' (sessions_groups) otherwise. Read with session_groups.
cell_groups
staticmethod
¶
cell_groups(**kwargs)
Cell groups (cell_type_groups and cell_index_groups) as [(name, items, color), ...] (normalize_groups): [(ALL_GROUP, None, None)] when none is defined. Their cells: cicada_tools select_cells.
channel_groups
staticmethod
¶
channel_groups(**kwargs)
Channel groups (channel_groups) as [(name, items, color), ...]: [(ALL_GROUP, None, None)] when none is defined.
epoch_groups_times ¶
epoch_groups_times(session, **kwargs)
Start / stop times of each epoch group (epoch_groups) in one session: {group: (2, n) array, the epochs and intervals of the group}, or {ALL_GROUP: None} when no epoch group is defined. Groups with no epoch in this session are left out, with a message.
group_colors ¶
group_colors(kind, **kwargs)
{group name: (r, g, b)} of the groups of one kind (keys of GROUP_ARGS, SESSION_GROUPS); groups without a colour left out, {} for kind None or a kind without colours.
group_distribution_params_errors ¶
group_distribution_params_errors(kinds, **kwargs)
Checks of add_group_distribution_args_for_gui, for validate_parameters.
group_overlay
staticmethod
¶
group_overlay(kinds, second_arg_name, **kwargs)
How the kinds of groups are drawn: (kind overlaid with colours or None, kind of the second overlay (parameter second_arg_name, e.g. overlay_style) or None, kinds drawn in separate figures), among kinds. The second overlay only with colours.
group_params_errors ¶
group_params_errors(second_arg_name, **kwargs)
Checks of the figure parameters (add_group_figure_args_for_gui and the plugin's second overlay second_arg_name), for validate_parameters.
plot_group_distributions ¶
plot_group_distributions(table, value, y_label, file_name, columns, path, **kwargs)
Figures (and comparisons if do_stats) of value by groups (cicada_tools plot_groups), as the parameters of
add_group_distribution_args_for_gui say. columns: {kind of groups: its column of the table}.
session_groups ¶
session_groups(session, **kwargs)
Session groups (sessions_grouped_by_age or sessions_groups) the session is in: [ALL_GROUP] when none is defined, [] when it is in none.
CicadaEventsBase¶
Used by: Display activity, Display behavior.
cicada_analysis.base.cicada_events_base.CicadaEventsBase ¶
Bases: CicadaGroupsBase
Base of the plugins using event times: CicadaGroupsBase (epoch and session groups, group figures) plus the table groups parameters (add_trial_groups_args_for_gui) and the readers table_event_times and opto_event_times. Not a plugin itself.
add_overlay_args_for_gui ¶
add_overlay_args_for_gui(family_widget='Events', epochs_family_widget='Epochs')
Parameters of the events, epochs and stimulations drawn over a display (Display activity, Display behavior): the source of the discrete events (events_from: behavioral events, or a table), the event groups (event_groups) or the trial groups (add_trial_groups_args_for_gui), the epoch groups (epoch_groups, add_epoch_groups_arg_for_gui) and, when a session has some, the optogenetic stimulations (show_opto_stimulations, opto_color). Read with overlay_bands. Their line width and opacity: the figure style (element "event_overlay").
add_trial_groups_args_for_gui ¶
add_trial_groups_args_for_gui(family_widget='Events', short_description='Trial groups', long_description=None, align_description='Align on')
'Table' (events_table: one of event_tables, the trial table by default), its groups of rows (trial_requirement_groups: rows picked by their values in the table's columns, 'Add group') and its time column used for them (align_column, default start_time); the groups and the time columns follow the table chosen. All used only when events_from is EVENTS_FROM_TABLE; nothing when the sessions have no such table. Read with table_event_times.
event_tables ¶
event_tables()
Interval tables of the loaded sessions with columns to filter their rows (get_table_choices): trial table, epoch table with labels, stimulus presentations...; the trial table first.
opto_event_times
staticmethod
¶
opto_event_times(session)
Optogenetic stimulations of one session, (2, n) start / stop times in seconds, or None (with a message) when there is none.
overlay_bands
staticmethod
¶
overlay_bands(session, frame_times=None, times_unknown=False, **kwargs)
Intervals to draw over a display of one session (add_overlay_args_for_gui): the event groups or the trial groups, then the epoch groups (cut to the recording), then the optogenetic stimulations, as (span_area_coords, span_area_colors, span_area_labels): per group, [(start, stop)] (start = stop for an event without duration), its color and its name (for a legend). frame_times: times of the imaging frames, the intervals then in frames; None: in seconds. times_unknown: imaging without frame times, events and epochs left out. Groups without any interval in the session are reported.
table_event_times
staticmethod
¶
table_event_times(session, trial_groups, column='start_time', table=None)
Times of each group of rows of interval table table (add_trial_groups_args_for_gui) in one session:
({group name: (2, n) array, both rows the column's times}, time_unit), time_unit 'seconds', or 'frames' for
a table storing frame indices. Rows without a time in the column are left out, and a group with none left
is skipped, with a message; a session without the table gives no group.
CicadaPsthBase¶
Used by: PSTH imaging - population, PSTH imaging - single neurons, PSTH ephys - units, PSTH behavior, Display calcium imaging movie.
cicada_analysis.base.cicada_psth_base.CicadaPsthBase ¶
Bases: CicadaEventsBase
Base of the PSTH plugins: CicadaEventsBase (groups, trial groups, optogenetic stimulations) plus the shared PSTH parameters (add_psth_*_args_for_gui), their readers (collect_psth_alignment_times, group_colors with the event groups) and checks (psth_events_params_errors). Not a plugin itself: the plugins inherit from it and implement the CicadaAnalysis methods.
add_psth_axes_args_for_gui ¶
add_psth_axes_args_for_gui(family_widget='Figures')
Axes of the population PSTH figures (save_population_psths): the same y range for every figure of a kind (plots_with_same_y_scale), a y top set by the user (use_defined_y_lim, user_defined_ylim), the x axis unit (x_axis_scale).
add_psth_events_args_for_gui ¶
add_psth_events_args_for_gui(family_widget='Events')
Parameters shared by the PSTH plugins, in this order: 'Events from' (the sources the loaded sessions have: events / epochs / intervals, a trial (or epoch) table, optogenetic stimulations), 'Event groups' (epochs_names), 'Trial groups' (trial_requirement_groups) and 'Align on': the start / end / middle of the events or stimulations (ref_in_epoch), or a time column of the table (align_column), and the close-events filter. Parameters that do not apply to the chosen source are greyed out. The times are collected with collect_psth_alignment_times; restricting them to epochs: add_psth_groups_args_for_gui.
add_psth_figure_args_for_gui ¶
add_psth_figure_args_for_gui(family_widget='Figures', extra_kinds=())
Parameters of the PSTH plugins that set the figures, registered after every kind of groups is defined: CicadaGroupsBase.add_group_figure_args_for_gui (one plot per session / per mouse, kind overlaid with colours) among the event, epoch and session groups and the plugin's extra_kinds (e.g. CELL_GROUPS), then the kind overlaid with line styles (overlay_style); each other kind gets separate figures, one per group. Read with group_overlay(kinds, "overlay_style", ...) and group_colors; checked by group_params_errors("overlay_style", ...).
add_psth_groups_args_for_gui ¶
add_psth_groups_args_for_gui(family_widget='Groups', session_groups=True)
Parameters of the PSTH plugins that set the epoch and session groups compared, after add_psth_events_args_for_gui: 'Epoch groups' and, if session_groups, session groups (CicadaGroupsBase). Inside a group everything is pooled; a kind with no group defined is one group, ALL_GROUP. How the groups are drawn: add_psth_figure_args_for_gui. Read with epoch_groups_times and session_groups.
add_psth_reduction_args_for_gui ¶
add_psth_reduction_args_for_gui(family_widget='Reduction', default_reduction='median', levels=('events', 'sessions', 'mice'), default_band='percentiles')
Parameters of the PSTH plugins that reduce the aligned data level by level: events of a session (event_reduction_fct), sessions of a mouse (session_reduction_fct), mice (mouse_reduction_fct), each mean or median; and the band around the line (band, PSTH_BANDS; low_percentile / high_percentile), computed over the units of the plot's last level: events (plot per session), sessions (plot per mouse), mice (all sessions). levels: the levels the plugin has (e.g. ("events",) for a single session).
add_psth_window_args_for_gui ¶
add_psth_window_args_for_gui(family_widget='Window', binned=False)
Parameters of the PSTH plugins that set the window: the time before (t_before) and after (t_after) the alignment point (s) and the baseline correction (baseline_correction: the mean of the time before the event subtracted). binned (ephys PSTH): also the bin size (bin_size) and the z-score (zscore, with the mean and SD of the time before the event). Checked by psth_window_params_errors.
check_psth_has_events
staticmethod
¶
check_psth_has_events(psth_data)
End of the session loop: raise ParameterError (not return, so that no combined YAML is written for a run without results) when no event group is left in any session after filtering, psth_data being what the plugin collected (list, dict or table; empty when nothing is left). The reasons are printed during the run.
collect_psth_alignment_times ¶
collect_psth_alignment_times(session, window_s=(0, 0), **kwargs)
Collect the times to align on in one session, from the parameters of add_psth_events_args_for_gui, with the cicada-nwb getters and cicada_tools functions: ({label: (2, n) array, row 0 = start, row 1 = stop (equal for a table column)}, time_unit). Event groups: the times of the group's names (behavior.get_event_times), merged and sorted by start; trial groups: the table column for the group's trials (filter_table_with_dict, table_column_times; trials without a time left out, with a message); optogenetic stimulations (optogenetic.get_opto_stimulation_times): one label. time_unit: 'seconds', or 'frames' for a table storing frame indices. Then, for every source, events are left out when their window (window_s: seconds before, after) touches invalid_times and when their window overlaps the previous kept one (filter_consecutive_movements); labels left empty are dropped, with a message.
event_group_times
staticmethod
¶
event_group_times(session, names)
(2, n) start / stop times of the events / epochs / intervals named, merged and sorted by start; None when the session has none of them.
event_onsets ¶
event_onsets(session, source, event_names=(), flag_column=None)
Onset times (s) of one session's events, sorted, from one source of psth_event_sources: the start of the events / epochs / intervals named in event_names (event_group_times), the start_time of the trial table's trials whose flag_column is 1 (table_event_times), or the start of the optogenetic stimulations. None, with a message, when the session has none.
events_within_data_errors ¶
events_within_data_errors(data_ranges, **kwargs)
For validate_parameters, before the run: a message when no event of the chosen groups, in any session, is kept as the run keeps them (collect_psth_alignment_times: invalid times and close events left out; then within the epoch groups) with its window (t_before before, t_after after its 'Align on' time) within the data aligned on it; with each session's data and event ranges. data_ranges: {session identifier: (start, stop) in s of that data}; sessions left out have no data to check (their own messages at run time).
group_colors ¶
group_colors(kind, **kwargs)
CicadaGroupsBase.group_colors, plus the event groups (event groups and trial groups).
psth_event_names ¶
psth_event_names()
Names of the periods (epoch_names: behavioral epochs, interval tables without columns to filter their rows, epoch-table labels 'epochs:
psth_event_sources ¶
psth_event_sources()
'Events from' choices the loaded sessions have: events / epochs / intervals, a table with rows to filter (event_tables), optogenetic stimulations (events / epochs / intervals when none).
psth_events_params_errors ¶
psth_events_params_errors(**kwargs)
Checks of the parameters of add_psth_events_args_for_gui, for validate_parameters: event groups or trial groups to align on, and at least one group with times in the loaded sessions (groups without any are skipped at run time, with a message).
psth_window_params_errors
staticmethod
¶
psth_window_params_errors(**kwargs)
Checks of add_psth_window_args_for_gui, for validate_parameters: positive times (and bin).
save_population_psths ¶
save_population_psths(session_psths, kind_columns, bins_edges, y_label, hue, style, separate, palette, value_scale=1, legend_group_columns=('cell_group',), count_column='n_cells', count_name='cells', **kwargs)
End of a population PSTH plugin, after its session loop: each session PSTH on the common time grid (combine_population_psth on bins_edges, values times value_scale), reduced over the sessions of each mouse, then over the mice (reduce_psth_level); the tables psth_sessions.csv, psth_mice.csv, psth_groups.csv; the figures of all the sessions and, if asked, per session and per mouse (add_psth_figure_args_for_gui, add_psth_axes_args_for_gui).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session_psths
|
list[dict]
|
One per session PSTH: its group columns (mouse_id, session_id, kind_columns), its counts (count_column, n_events) and 'psth': (times in ms, [line, low, high]). |
required |
kind_columns
|
list[str]
|
Columns of every kind of groups. |
required |
hue, style, separate, palette
|
Columns overlaid with colours and line styles, columns of separate figures, colours (group_overlay, group_colors). |
required | |
legend_group_columns, count_column, count_name
|
For the legend counts (psth_legend_counts). |
required |