Skip to content

Parameter schema

cicada_analysis.base.argument_schema: how a declared parameter is stored, the rules between parameters (enabled_if, requires_data), and the error raised before a run when parameters are invalid. Plugins use it through CicadaAnalysis (add_*_for_gui, set_parameter_rules, validate_parameters).

cicada_analysis.base.argument_schema.ParameterError

Bases: ValueError

Parameter values that cannot be used (missing, impossible together, or with the loaded data).

cicada_analysis.base.argument_schema.AnalysisArgument

Schema object that holds metadata and current value for one analysis parameter.

Attributes are set dynamically from kwargs (arg_name, value_type, default_value, min_value, max_value, choices, mandatory, short_description, long_description, ...).

GUI widget management (get_gui_widget, set_widget_*) lives in cicada_gui, not here.

get_all_attributes

get_all_attributes()

Return a dict of all non-private attributes plus _final_value. Used when saving to YAML.

get_argument_value

get_argument_value()

Return the current value for this argument. - If a GUI widget is attached, delegate to the widget. - Otherwise return _final_value if set, else default_value.

get_default_value

get_default_value()

get_enabled_if

get_enabled_if()

{other parameter: required value} that must all hold for this parameter to be used.

get_enabled_if_any

get_enabled_if_any()

Condition sets ({other parameter: required value}) of which at least one must hold (none: no such rule).

get_family_widget

get_family_widget()

get_long_description

get_long_description()

get_requires_data

get_requires_data()

Data types (keys of DATA_REQUIREMENTS) at least one session must have, else the parameter is hidden.

get_role

get_role()

One line on what the parameter changes in the output (documentation).

get_short_description

get_short_description()

is_mandatory

is_mandatory()

set_argument_value

set_argument_value(value)

cicada_analysis.base.argument_schema.AnalysisArgumentsHandler

Manages the collection of AnalysisArgument instances for one CicadaAnalysis run.

Responsibilities: - Store and retrieve arguments - Validate that mandatory arguments have values - Save/load argument values as YAML (for reproducibility) - Execute the analysis with the current argument values

GUI widget creation (get_gui_widgets etc.) is NOT here — it lives in cicada_gui.

args_dict instance-attribute

args_dict: dict[str, AnalysisArgument] = {}

cicada_analysis instance-attribute

cicada_analysis = cicada_analysis

add_argument

add_argument(**kwargs)

check_arguments_validity

check_arguments_validity()

Return True if the current values can be used (see get_parameter_errors).

config_name_warnings

config_name_warnings(parameters_dict)

Warnings comparing the parameter names of a config with this plugin's parameters (set_values_from_config skips the unknown ones): names the plugin does not have (ignored, e.g. renamed or removed since the config was written) and parameters of the plugin missing from the config (default value used). Parameters that configs never contain are not reported missing: read-only ones, and those needing data none of the loaded sessions has (left out by get_analysis_arguments, as when the config is written).

disabled_reason

disabled_reason(arg, _seen=None)

Why the parameter is not used with the current values, or None if it is used.

effective_values

effective_values()

({arg_name: value}, [warnings]) passed to run_analysis: parameters not used with the current values (disabled or needing data the sessions don't have) get their default value; a warning is given when such a parameter was set to something else.

get_analysis_argument

get_analysis_argument(arg_name)

get_analysis_arguments

get_analysis_arguments(sorted=False, include_unavailable=False)

Arguments to show (GUI widgets, generated configs). Arguments whose required data is in none of the loaded sessions are left out unless include_unavailable.

get_parameter_errors

get_parameter_errors()

Messages for every problem with the current values: mandatory parameters without a value (among the parameters in use), then the plugin's own cross-parameter checks (CicadaAnalysis.validate_parameters, called with the effective values).

is_available

is_available(arg)

False if the parameter needs data that none of the loaded sessions has (no sessions: True).

is_enabled

is_enabled(arg)

load_analysis_argument_from_yaml_file

load_analysis_argument_from_yaml_file(file_name)

Load argument values from a full-schema YAML (as produced by save_analysis_arguments_to_yaml_file). Sets _final_value directly (no widget required).

rule_comment

rule_comment(arg)

Short text of the rules of a parameter, for config file comments.

run_analysis

run_analysis()

save_analysis_arguments_to_yaml_file

save_analysis_arguments_to_yaml_file(path_dir, yaml_file_name)

Save full argument schema + final values to YAML. This is the legacy format used inside the combined output config.

set_rules

set_rules(arg_name, role=None, enabled_if=None, requires_data=None, enabled_if_any=None)

Declare when parameter arg_name applies.

Parameters:

Name Type Description Default
role

one line on what the parameter changes in the output.

None
enabled_if

{other_arg: value}. The parameter is used only when every condition holds: a bool or a value (equality), a list of accepted values, SELECTED (any non-empty value), or Satisfies(test, description) (test(value) is true). Not used -> greyed out in the GUI, ignored with a warning when set in a config.

None
enabled_if_any

list of condition sets as enabled_if; the parameter is used only when at least one set holds (e.g. a seed used by two optional steps), on top of enabled_if.

None
requires_data

keys of DATA_REQUIREMENTS. If no loaded session has that data, the parameter is not shown at all (GUI, generated configs) and keeps its default value.

None

set_values_from_config

set_values_from_config(parameters_dict)

Set argument values from a flat {param_name: value} dict. Used by the headless runner after loading a parameters YAML.

YAML deserialises tuples as lists. Color arguments must remain tuples so that downstream code using isinstance(..., list) to distinguish a single RGBA color from a per-element color list works correctly.

For session-keyed dict choices (widefield_acquisition, roi_response_series, etc.) the GUI always shows all loaded sessions, defaulting unspecified ones to their first available choice. We mirror that behavior here: - session in config AND in choices → use config value - session in choices, not in config → first available choice - session in config, not in choices → silently ignored

validate

validate()

Raise ParameterError listing every problem; else return (kwargs, warnings) for run_analysis.

Data a parameter can require

requires_data names are checked on each loaded session by cicada_analysis.base.data_requirements.

Data a parameter can require (requires_data in the parameter rules). Each check reads one session through the standard cicada-nwb getters only; a parameter is shown if at least one loaded session passes all its checks.

DATA_REQUIREMENTS module-attribute

DATA_REQUIREMENTS = {'units': _has_units, 'spike_times': _has_spike_times, 'roi_response_series': _has_roi_response_series, 'sparse_activity': _has_sparse_activity, 'traces': _has_traces, 'raster_like': _has_raster_like, 'spike_raster': _has_spike_raster, 'rows_of_cells': _has_rows_of_cells, 'cell_types': _has_cell_types, 'good_cells': _has_good_cells, 'imaging_movie': _has_imaging_movie, 'background_image': _has_background_image, 'segmentation_without_series': _has_segmentation_without_series, 'electrical_series': _has_electrical_series, 'continuous_data': _has_continuous_data, 'behavioral_time_series': _has_behavioral_time_series, 'trial_table': _has_trial_table, 'epoch_table': _has_epoch_table, 'intervals': _has_intervals, 'epochs': _has_epochs, 'events': _has_events, 'speed': _has_speed, 'position': _has_position}

session_has

session_has(session, key)

True if session has the data named key (a key of DATA_REQUIREMENTS).