Skip to content

Quick start (headless)

No data at hand? The demo page runs an analysis on the example files installed with CICADA, in a few lines of Python.

An analysis runs from two YAML files: a sessions file (the NWB files) and a parameters file (the analysis and its parameter values). Three template scripts write and run them: copy each one, set the variables at its top (each is explained there), and run it with python. The example uses Display activity, class CicadaDisplayRasterAnalysis.

Step 0 — List the NWB files in a sessions YAML

Copy generate_sessions_config_template.py:

LOCATION = "/path/to/nwb_folder"     # or a DANDI address: "dandi://000219@0.260826.1155/sub-180201-180208"
OUTPUT_PATH = "/path/to/sessions.yaml"
RECURSIVE = True                     # local folder: also its sub-folders
python generate_sessions_config_template.py

In the GUI: Sessions panel, tick the sessions, then Save Group.

Step 1 — Generate the parameters file

Copy generate_config_template.py: every parameter is written with its default value, and the choices found in the sessions.

SESSIONS_YAML = "/path/to/sessions.yaml"
ANALYSIS_CLASS_NAME = "CicadaDisplayRasterAnalysis"
PARAMS_YAML = f"/path/to/params_{ANALYSIS_CLASS_NAME}.yaml"
RESULTS_PATH = f"/path/to/results/{ANALYSIS_CLASS_NAME}"
python generate_config_template.py

In the GUI: open the analysis, set its parameters, then Save parameters (step 2 can then be skipped).

Step 2 — Edit the parameters

Open the parameters YAML in a text editor. Each parameter is one line: its value, then after the # its type, its choices, MANDATORY if it must have a value, and its help. Only the value is read. An extract:

analysis_class: CicadaDisplayRasterAnalysis
data_to_display: auto  # choices:['auto', 'imaging', 'spikes', 'LFPs'] | Data to display
roi_response_series: [ophys, DfOverF, DfOverF]  # available: ['ophys', 'DfOverF', 'DfOverF'] | ['ophys', 'Fluorescence', 'Corrected'] | ... | used when data_to_display is one of ['auto', 'imaging']
events_from: events  # choices:['events', 'table'] | Source of discrete events to display
time_slice: true  # type:bool | Plot slice of time
time_slice_start: 0  # type:int | range:0-39490 | Slice start time (seconds) | used when time_slice = True
time_slice_end: 600  # type:int | range:0-39490 | Slice end time (seconds) | used when time_slice = True
dpi: 300  # type:int | range:50-1200 | Resolution of the images (dpi)
results_path: /path/to/results/CicadaDisplayRasterAnalysis  # type:dir | Directory to save the results

Set at least the parameters marked MANDATORY that have no value. results_path is either empty (the results go to <Downloads folder>/cicada/results) or an existing folder.

Step 3 — Run

Copy run_from_config_template.py:

REPLAY = False
SESSIONS_YAML = "/path/to/sessions.yaml"
PARAMS_YAML = "/path/to/params_CicadaDisplayRasterAnalysis.yaml"
python run_from_config_template.py

The results folder then has the results of the analysis (figures, tables) and a combined_<ClassName>_<timestamp>.yaml: the analysis, its parameter values, the sessions with their input files and the environment of the run. To replay the run, set REPLAY = True and COMBINED_YAML to that file in the same template; the replay warns about every difference with the recorded run (see Replaying a previous run).

The same steps from the command line or in Python, with several session groups, several analyses and replays: Headless workflow.