Skip to content

Runner and config files

cicada_analysis.config: run analyses from YAML files, without the GUI. How to use them: Headless workflow.

Headless runner

cicada_analysis.config.runner.generate_config

generate_config(analysis_class, output_yaml_path, sessions_yaml, result_path, overrides=None, dandi_mode=None, dandi_download_dir=None)

Generate a parameters config file for a given analysis class.

All parameters are written with their types, ranges, defaults, and inline help comments. Session-specific choices (e.g. available RoI response series) are pre-populated from sessions_yaml so the auto-fill always matches the actual data that will be analyzed.

Parameters:

Name Type Description Default
analysis_class

the CicadaAnalysis subclass (not an instance).

required
output_yaml_path

where to write the .yaml file.

required
sessions_yaml

path to a sessions YAML file listing the NWB files to analyze. Create this file (manually or via the GUI group tool) before calling generate_config.

required
result_path

results_path written in the file (created if needed; None: the plugin's default, to set before the run).

required
overrides

optional dict {param_name: value} to pre-fill specific parameters (e.g. {"results_path": "/my/results"}).

None
dandi_mode

how DANDI files are opened: "stream", "download" or "auto" (None: "stream").

None
dandi_download_dir

folder of the DANDI files downloaded (download and auto modes), as /// (None: /cicada).

None

cicada_analysis.config.runner.run_from_config

run_from_config(combined_config=None, sessions=None, params=None, save_combined=True, extra_plugin_dirs=None, results_path=None, hash_inputs=False, dandi_mode=None, dandi_download_dir=None)

Run one or more analyses from config file(s), loading sessions only once.

Calling conventions

run_from_config(combined_config="combined.yaml") — single file containing sessions + analysis class + parameters. run_from_config(sessions="sessions.yaml", params="params.yaml") — single params file; sessions loaded once. run_from_config(sessions="sessions.yaml", params=["p1.yaml", "p2.yaml"]) — multiple params files; sessions loaded once, analyses run sequentially.

Parameters:

Name Type Description Default
combined_config

path to a combined config YAML (sessions + params in one file).

None
sessions

path to a sessions.yaml (used with params).

None
params

path to a parameters YAML, or a list of paths. Each file must contain 'analysis_class'.

None
save_combined

if True (default), write a combined_*.yaml after each run.

True
extra_plugin_dirs

list of directories to scan for external plugins.

None
results_path

if provided, overrides results_path in every config (created if needed; a results_path read from a config must exist; empty in the config: /cicada/results).

None
hash_inputs

if True, the combined YAML records the sha256 of local input files (slow on large files; DANDI files always get the archive's sha256).

False
dandi_mode

how DANDI files are opened: "stream", "download" or "auto" (None: "stream").

None
dandi_download_dir

folder of the DANDI files downloaded (download and auto modes), as /// (None: /cicada).

None

Returns:

Type Description

A single CicadaAnalysis instance when params is a single path (or

combined_config is used); a list of instances when params is a list.

cicada_analysis.config.runner.run_from_combined

run_from_combined(combined_yaml, save_combined=True, extra_plugin_dirs=None, results_path=None, hash_inputs=False, dandi_mode=None, dandi_download_dir=None)

Replay a run from a combined config file (as produced by a previous run).

Parameters:

Name Type Description Default
combined_yaml

path to a combined_*.yaml file.

required
save_combined

if True, write a new combined_*.yaml in the results dir.

True
extra_plugin_dirs

list of directories to scan for external plugins (same as run_from_config). Pass the same dirs used in the original run.

None
results_path

if provided, overrides the results_path in the combined file. Use this to redirect outputs without editing the YAML (created if needed). Without it, the results_path of the combined file is used; empty in the file, or a folder that does not exist on this machine: /cicada/results.

None
hash_inputs

if True, the new combined YAML records the sha256 of local input files.

False
dandi_mode

how DANDI files are opened: "stream", "download" or "auto" (None: "stream").

None
dandi_download_dir

folder of the DANDI files downloaded (download and auto modes), as /// (None: /cicada).

None

Returns:

Type Description

The CicadaAnalysis instance after the run.

Reading and writing the YAML files

CICADA config I/O — three YAML formats:

sessions.yaml — list of {identifier, path} for each session params.yaml — flat {param_name: value} + inline comments (human-editable) combined_*.yaml — sessions + analysis class + all parameter values in the same human-readable one-line-per-param format; saved after every run (reproducibility / replay) and can be generated before a run via generate_config() to serve as a pre-run editable config.

save_sessions_config

save_sessions_config(sessions, output_path)

Save a sessions config file.

Parameters:

Name Type Description Default
sessions

list of objects with .identifier and ._data_ref (path) attributes, OR a list of dicts with 'identifier' and 'path' keys.

required
output_path

destination .yaml file path.

required

load_sessions_config

load_sessions_config(yaml_path)

Load a sessions config file (a sessions YAML, or the sessions of a combined config). A relative path is resolved against the folder of the YAML file.

Returns:

Type Description

list of dicts: [{"identifier": ..., "path": ...}, ...]

save_parameters_config

save_parameters_config(analysis_instance, output_path, result_path=None, overrides=None, use_actual_values=False)

Generate a human-readable parameters YAML from a configured analysis instance.

Format

param_name: value # [type] short_description

The user edits values directly. The file is loaded by set_values_from_config().

Parameters:

Name Type Description Default
analysis_instance

a CicadaAnalysis instance after setup_parameters() has been called.

required
output_path

destination .yaml file path.

required
result_path

destination for the ouput of the analysis.

None
overrides

optional dict of {param_name: value} to pre-fill specific parameters.

None
use_actual_values

if True, write current widget/argument values instead of defaults. Use this when saving from the GUI after the user has filled params.

False

load_parameters_config

load_parameters_config(yaml_path)

Load a parameters YAML file.

Returns:

Name Type Description
dict

{param_name: value} — ready to pass to handler.set_values_from_config()

save_combined_config

save_combined_config(analysis_instance, sessions, output_path, duration_seconds=None, hash_inputs=False, packages_file=None)

Save a combined config: metadata + sessions + all parameter actual values, in the same human-readable one-line-per-param format as save_parameters_config.

This file can be: - Saved after a run for reproducibility (pass actual post-run values). - Generated before a run (with default values) via generate_config() in runner.py, then edited by the user and replayed with run_from_combined().

Parameters:

Name Type Description Default
analysis_instance

CicadaAnalysis instance after setup_parameters() (or after run).

required
sessions

list of session objects (with .identifier, ._data_ref and .source) or dicts.

required
output_path

destination .yaml file path.

required
hash_inputs

if True, compute the sha256 of local input files (slow on large files). DANDI files always get the sha256 given by the archive.

False
packages_file

name of the sidecar file listing the installed packages (save_environment_file), recorded in the environment block.

None

The environment block records the CICADA packages and, for a lab plugin, its package. The file records the hash of its own content (config_sha256, see _config_sha256), so that a replay can tell it was edited.

load_combined_config

load_combined_config(yaml_path)

Load a combined config file (new human-readable format).

The combined file is flat: metadata keys + 'sessions' + parameter keys all at the same top level. This function splits them into a structured dict.

Returns:

Type Description

dict with keys: analysis_class (str) analysis_module (str or None) run_timestamp (str or None) environment (dict: python, and version / git_hash / dirty of each CICADA package; None for configs written before CICADA 0.4) sessions (list of {identifier, path, ...} dicts; a relative path is resolved against the folder of yaml_path, an address such as dandi://... is kept) parameters (flat dict of param_name -> value) edited (True if the analysis, its parameters or its sessions differ from the hash the file recorded when it was written (_config_sha256); None without a hash)

current_environment

current_environment(extra_packages=())

The environment block of a combined config for the running Python: Python version, and for each CICADA package, then each of extra_packages ((pip name, import name) pairs: the lab package of the plugin that ran), its version, git hash and dirty flag (None: not installed; hash and flag None: not a git install). The CICADA versions stand for the environment; the full package list goes in the sidecar file of each run.

save_environment_file

save_environment_file(output_path)

Write the installed packages of the running Python next to a combined config (sidecar file of each run): pip freeze (editable and git installs with their full commit), or the name==version list of importlib.metadata if pip fails. Replay ignores it: it is for investigating a replay that differs.

check_version_compatibility

check_version_compatibility(config)

Return a list of warning strings for any Python version, CICADA version or git-hash mismatches between the current environment and what is recorded in a combined config dict (as returned by load_combined_config), and for uncommitted changes (dirty flag, development installs only) in the recorded run or now. A combined config without an environment block (written before CICADA 0.4) gets one warning: nothing can be compared. A params file (no sessions) has nothing to compare and gets none. A combined config also gets a warning for each installed package outside a range declared by cicada-nwb, cicada-analysis, cicada-gui or the recorded lab package (dependency_range_warnings), for a recorded lab package not installed now, and when its analysis, parameters or sessions were edited after the run (_config_sha256, checked by load_combined_config).

Never raises. Returns an empty list when everything matches. Callers are responsible for displaying the warnings (print / dialog / log).

dependency_range_warnings

dependency_range_warnings(packages=_CICADA_PACKAGES)

Warnings for each installed package outside a range declared by one of packages ((pip name, import name) pairs; default: cicada-nwb, cicada-analysis and cicada-gui), from their pyproject.toml as installed (an editable install sees an edited range only after reinstalling).

check_input_files

check_input_files(config, sessions)

Return a list of warning strings for each input file that differs from what is recorded in a combined config dict (as returned by load_combined_config): NWB identifier, size, sha256, DANDI version and asset ID. Keys missing from the config (older files) are not checked. A local sha256 is recomputed only when the config records one; without it, a note says the content was not checked (a file edited in place can keep its size).

Parameters:

Name Type Description Default
config

dict returned by load_combined_config.

required
sessions

the opened sessions; each recorded file is compared with the session opened from the same path, and recorded files without one are skipped.

required

Never raises. Callers are responsible for displaying the warnings.