CicadaAnalysis (every plugin)¶
cicada_analysis.base.cicada_analysis.CicadaAnalysis is the base class of every plugin.
Plugins that group cells, sessions or events derive from one of the
family base classes, which derive from it.
How a plugin is built: Analysis engine.
Methods a plugin implements¶
cicada_analysis.base.cicada_analysis.CicadaAnalysis ¶
Bases: ABC
Abstract base class for all CICADA analyses.
Subclasses must implement
- copy()
- check_data()
- setup_parameters() (formerly set_arguments_for_gui)
- run_analysis(**kwargs)
setup_parameters
abstractmethod
¶
setup_parameters()
Declare all parameters for this analysis by calling add_argument_for_gui() (or add_*_arg_for_gui() helpers).
Must call super().setup_parameters() first — that resets the handler and adds the results_path argument.
set_arguments_for_gui ¶
set_arguments_for_gui()
Backward compatibility alias — calls setup_parameters().
validate_parameters ¶
validate_parameters(**kwargs)
Cross-parameter checks of the plugin, run before the analysis starts (GUI and headless). Receives the values run_analysis would get (unused parameters at their default). Override to return a list of messages, one per impossible combination; empty if valid.
run_analysis
abstractmethod
¶
run_analysis(**kwargs)
Subclass implementations must call super().run_analysis(**kwargs) first.
Declaring parameters¶
Called in setup_parameters(): each adds one parameter (or a set of related ones) with its
widget in the GUI and its entry in the parameters YAML.
Bases: ABC
Abstract base class for all CICADA analyses.
Subclasses must implement
- copy()
- check_data()
- setup_parameters() (formerly set_arguments_for_gui)
- run_analysis(**kwargs)
add_background_image_arg_for_gui ¶
add_background_image_arg_for_gui(family_widget='Background image')
'Background image' (background_image, shown when a loaded session has one): per session, a summary image of the file ([module, images, image], e.g. suite2p meanImg) or the mean / std of the first frames of an imaging movie (["CI movie", "mean" or "std", movie]); none chosen: no background. Plus the number of movie frames used (n_sample_frame). Read with background_image.
add_bool_option_for_gui ¶
add_bool_option_for_gui(arg_name, true_by_default, short_description, long_description=None, family_widget=None)
add_choices_arg_for_gui ¶
add_choices_arg_for_gui(arg_name, choices, short_description, default_value, multiple_choices, long_description=None, family_widget=None, follow=None)
follow: name of another parameter; choices are then {its value: choices} (choices_follow).
add_choices_for_groups_for_gui ¶
add_choices_for_groups_for_gui(arg_name, choices, with_color, short_description, long_description=None, family_widget=None, mandatory=False, add_custom_group_field=False, custom_group_validation_fct=None, custom_group_processor_fct=None, default_value=None)
add_ci_movie_arg_for_gui ¶
add_ci_movie_arg_for_gui(long_description=None, family_widget='Calcium imaging movie to use')
'Imaging movie' (ci_movie): per session, one of its imaging movies with frames (2-photon or one-photon / widefield, in acquisition or processing; calcium_imaging.get_imaging_movie_names). Shown when a loaded session has one; read per session with selected_series.
add_color_arg_for_gui ¶
add_color_arg_for_gui(arg_name, default_value, short_description, long_description=None, family_widget=None)
add_electrical_series_arg_for_gui ¶
add_electrical_series_arg_for_gui(short_description, long_description=None, arg_name='electrical_series', family_widget=None)
Session-keyed choice of an ElectricalSeries (LFP, ECoG, raw): [location, container, series].
add_epoch_dict_arg_for_gui ¶
add_epoch_dict_arg_for_gui(short_description, long_description=None, multiple_choices=False, arg_name=None, family_widget=None)
add_field_float_option_for_gui ¶
add_field_float_option_for_gui(arg_name, default_value, mandatory, short_description, long_description=None, family_widget=None, min_value=None, max_value=None)
A typed float; min_value / max_value (inclusive, None: no bound): a value outside is refused before the run, with a message (AnalysisArgumentsHandler.get_parameter_errors).
add_field_text_option_for_gui ¶
add_field_text_option_for_gui(arg_name, default_value, short_description, long_description=None, family_widget=None)
add_figure_style_args_for_gui ¶
add_figure_style_args_for_gui(elements=(), defaults=None, standard=STANDARD_ELEMENTS, labels=None)
Figure style parameters, read with figure_style, in the GUI group "Figure style": a preset (sizes, fonts, lines and ticks; 'custom' to type them), text, axes, lines, colours, legend; and in the group "Figure saving": formats, interactive viewing, transparency, dpi, rasterizing. Sizes in mm, fonts and lines in pt. Every option added changes the plugin's figures (matplotlib settings of the run, core_plots. finish_figure at saving, and the values the plugin passes to its tools). elements: what the plugin's figures also have, among FIGURE_ELEMENTS (their options are added only then). defaults: {FigureStyle field: value}, the plugin's own defaults (e.g. a dark theme, its colormap). standard: the STANDARD_ELEMENTS the figures have (all by default; a map without axes: fewer). labels: {parameter name: GUI label}, the plugin's own labels (e.g. what its line width draws).
add_good_cells_arg_for_gui ¶
add_good_cells_arg_for_gui(family_widget='Cell quality')
'Keep only good cells' (keep_good_cells, True by default), shown if a loaded session has a cell quality column in its ROI table. Read with good_cells(session, keys, **kwargs).
add_index_groups_for_gui ¶
add_index_groups_for_gui(arg_name, short_description, long_description=None, family_widget=None, default_value=None)
Groups of typed indices (e.g. cells '3 1 7-9', kept in the typed order), each with a name and a colour: {group_name: [[indices text], color]}, the format of add_choices_for_groups_for_gui (normalize_groups reads both); {} without group.
add_int_values_arg_for_gui ¶
add_int_values_arg_for_gui(arg_name, min_value, max_value, short_description, default_value, long_description=None, family_widget=None)
add_intervals_arg_for_gui ¶
add_intervals_arg_for_gui(short_description, arg_name='intervals', long_description=None)
add_open_dir_dialog_arg_for_gui ¶
add_open_dir_dialog_arg_for_gui(arg_name, mandatory, short_description, long_description=None, key_names=None, family_widget=None)
add_open_file_dialog_arg_for_gui ¶
add_open_file_dialog_arg_for_gui(arg_name, extensions, mandatory, short_description, long_description=None, key_names=None, family_widget=None)
add_random_seed_arg_for_gui ¶
add_random_seed_arg_for_gui(used_for, family_widget=None, short_description='Random seed', enabled_if=None, enabled_if_any=None)
The run's random_seed (default 0, so runs are replayable and the seed is in every combined YAML), read
with random_generator / random_generators. used_for: what the seed draws, completing "Seed of ...".
enabled_if / enabled_if_any: when a random step is on (set_parameter_rules).
add_roi_response_series_arg_for_gui ¶
add_roi_response_series_arg_for_gui(short_description, long_description=None, keywords_to_exclude=None, arg_name=None, family_widget=None, kinds=None, optional=False)
Selector of one ROI response series per session. kinds: kinds of activity offered (e.g. ("traces",), see the session's get_roi_response_serie_kind); None offers every series. optional: 'none' offered first (the default; NOT_SELECTED, not is_selected).
add_save_formats_arg_for_gui ¶
add_save_formats_arg_for_gui(family_widget=None, default_value='pdf')
add_segmentation_arg_for_gui ¶
add_segmentation_arg_for_gui(family_widget='Segmentation to use', short_description=' ', long_description=None)
add_spiketimes_series_arg_for_gui ¶
add_spiketimes_series_arg_for_gui(short_description, long_description=None, keywords_to_exclude=None, arg_name=None, family_widget=None)
add_trial_dict_arg_for_gui ¶
add_trial_dict_arg_for_gui(short_description, long_description=None, arg_name=None, family_widget=None, source='trial', tables=None, follow=None)
Register a trial-table arg rendered as TrialGroupBuilderWidget.
The user builds one or more (req_dict, color) groups by ticking per-category
checkboxes and clicking "Add group".
kwargs value: [[name, req_dict, color_rgba], ...]
tables, follow: the columns of the table chosen in parameter follow (choices {table: {column: values}},
choices_follow), for each of tables; else those of source ('trial', 'epoch' or a table name).
add_unit_label_args_for_gui ¶
add_unit_label_args_for_gui(family_widget='Units')
'Filter units by quality labels of' (unit_label_column) and 'Units to keep' (unit_labels, 'good' and 'mua' by default), from the label columns of the loaded sessions' units tables; nothing without any. Read with electrophysiology.get_spike_times(..., labels=unit_labels, label_col=unit_label_column).
add_widefield_acquisitions_dict_for_gui ¶
add_widefield_acquisitions_dict_for_gui(short_description, long_description=None, arg_name=None, family_widget=None)
Parameter rules¶
Bases: ABC
Abstract base class for all CICADA analyses.
Subclasses must implement
- copy()
- check_data()
- setup_parameters() (formerly set_arguments_for_gui)
- run_analysis(**kwargs)
set_parameter_rules ¶
set_parameter_rules(arg_name, role=None, enabled_if=None, requires_data=None, enabled_if_any=None, hide_when_unused=False)
Declare when a parameter (already added) applies; see AnalysisArgumentsHandler.set_rules. hide_when_unused: the GUI hides the parameter instead of greying it out, for the branches of an either-or choice (e.g. the parameters of the other event sources or modes): True when it is not used for any reason, or the name of the selector (e.g. "events_from") to hide it only when the condition on that selector fails (greyed out for its other conditions, e.g. a tick box). Parameters depending on a hidden one are hidden too.
Example
self.set_parameter_rules("downsampling_factor", enabled_if={"downsample_traces": True}) self.set_parameter_rules("spike_size", requires_data=["spike_times"]) self.set_parameter_rules("random_seed", enabled_if_any=[{"pick_n_random_units": True}, {"artifact_correction": True}])
During the run¶
Bases: ABC
Abstract base class for all CICADA analyses.
Subclasses must implement
- copy()
- check_data()
- setup_parameters() (formerly set_arguments_for_gui)
- run_analysis(**kwargs)
update_progressbar ¶
update_progressbar(time_started, increment_value=0, new_set_value=0)
No-op in headless mode. GUI layer sets _progress_fn to forward updates to the progress bar.
random_generator
staticmethod
¶
random_generator(**kwargs)
np.random.default_rng of the run's random_seed (add_random_seed_arg_for_gui).
random_generators
staticmethod
¶
random_generators(n, **kwargs)
n independent generators from the run's random_seed, one per random step, so that one step does not change the draws of another (np.random.SeedSequence.spawn).
Data helpers¶
Bases: ABC
Abstract base class for all CICADA analyses.
Subclasses must implement
- copy()
- check_data()
- setup_parameters() (formerly set_arguments_for_gui)
- run_analysis(**kwargs)
selected_series ¶
selected_series(roi_response_series)
Value of add_roi_response_series_arg_for_gui ({session identifier: keys}, or the same keys for every session): [(session, keys), ...] of the loaded sessions with a series selected.
selected_in_a_session ¶
selected_in_a_session()
enabled_if value for a per-session selector (series, background image, ...): something chosen for at least one session.
selected_series_are_traces ¶
selected_series_are_traces(roi_response_series)
True if a series is selected and every selected series is traces (raw, dF/F, deconvolved). For the rule of traces-only parameters: enabled_if={"roi_response_series": Satisfies(self.selected_series_are_traces, ...)}.
good_cells
staticmethod
¶
good_cells(session, keys, **kwargs)
Boolean mask of the cells kept by add_good_cells_arg_for_gui (one value per row of the series), None when all are kept (option off, or no cell quality column).
background_image
staticmethod
¶
background_image(session, keys, n_frames=2000)
Image (2D array) of add_background_image_arg_for_gui keys for one session, None if none is chosen.
binarize_sparse_activity
staticmethod
¶
binarize_sparse_activity(session, keys, data)
data of the ROI response series keys, binarized (1 where > 0, see activity_to_raster) with a message if it is spike counts or event amplitudes; unchanged otherwise (binary rasters, traces).
check_binary_raster ¶
check_binary_raster(spikes_accepted=False, traces_keyword=None, raster_dur_only=False)
check_data for plugins working on a binary raster of inferred activity: every session needs a ROI response series found by its values, whatever its name: a binary raster, spike counts or event amplitudes (the last two binarized by the plugin), or only a raster dur (transients over several frames) if raster_dur_only; or spike times if spikes_accepted; and, if traces_keyword is given, a series whose name contains it (the plugin reads its traces by that name). Sets invalid_data_help and returns False otherwise.