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_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:
|
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
|
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: |
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
|
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.