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_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_requires_data ¶
get_requires_data()
Data types (keys of DATA_REQUIREMENTS) at least one session must have, else the parameter is hidden.
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.
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_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).
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).
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).