Skip to content

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)

check_data abstractmethod

check_data()

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.

copy abstractmethod

copy()

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_analysis_description_for_gui

add_analysis_description_for_gui(description)

add_argument_for_gui

add_argument_for_gui(with_incremental_order=True, **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_dpi_arg_for_gui

add_dpi_arg_for_gui(family_widget)

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_image_format_package_for_gui

add_image_format_package_for_gui()

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_verbose_arg_for_gui

add_verbose_arg_for_gui()

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)

get_data_to_analyse

get_data_to_analyse()

get_data_identifiers

get_data_identifiers()

get_results_path

get_results_path()

create_results_directory

create_results_directory(dir_path)

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.