Architecture¶
CICADA is three Python packages stacked on top of each other: cicada-gui uses
cicada-analysis, which uses cicada-nwb. Each one can also be used on its own, with the
ones below it.
How a run goes¶
The GUI and the headless runner are two ways to drive the same steps, with the same plugins.
flowchart LR
gui["<b>cicada-gui</b><br/>forms, clicks"] --> plugin
runner["<b>runner</b><br/>sessions + params YAML"] --> plugin
plugin["<b>Plugin</b><br/>cicada-analysis"] -- reads through --> session["<b>NWBSession</b><br/>cicada-nwb"]
session --- files[("NWB files<br/>local or DANDI")]
plugin -- computes with --> tools["<b>cicada-tools</b><br/>cicada-analysis"]
plugin -- writes --> out[("figures, tables<br/>combined YAML")]
- Open the files. The GUI (folder, group, DANDI) or the runner (sessions YAML) opens
each NWB file as an
NWBSession. - Set up the plugin. The plugin checks that the sessions suit it (
check_data) and declares its parameters (setup_parameters): the GUI shows them as a form, the runner reads their values from the parameters YAML. The values are validated before the run. - Read the data.
run_analysisgets the data through the session submodules (session.calcium_imaging...), never by reading the NWB file directly. - Compute with
cicada-toolsfunctions, which work on plain arrays and tables. - Save the figures and tables, and a combined YAML with the sessions, the analysis, every parameter value and the package versions, which replays the run exactly.
Plugins are found the same way by the GUI, the commands and the runner
(base/plugin_registry.py), in two places:
- Installed packages (the normal way): a package installed with
piplists its plugins in itspyproject.toml(entry-point groupcicada_analysis.plugins): cicada-analysis for the core plugins, a lab package for its lab's. They are always found, and a package made for other CICADA versions is not loaded. - Plugin folders (while developing a plugin): a folder of
.pyfiles, not installed, found only when it is given (Manage plugins in the GUI,--plugin-dir,extra_plugin_dirs), at every run and replay.
Plugins that cannot be loaded are listed in the GUI's plugin manager instead of being skipped silently. Details: where plugins come from.
The three packages¶
| Package | Start with | Use it to | Depends on |
|---|---|---|---|
| cicada-gui | python -m cicada_gui |
Explore: select sessions by metadata, try analyses, tune parameters while looking at the results | cicada-analysis, Qt |
| cicada-analysis | cicada-run / run_from_config(...) with YAML files |
Run routines and batches on many sessions, replay runs, write plugins | cicada-nwb |
| cicada-nwb | NWBSession(path or DANDI address) |
Read NWB data in your own code | pynwb |
cicada-gui: the desktop application¶
Lists the sessions, shows which analyses suit the ticked sessions (incompatible ones are greyed out with the reason), builds each plugin's parameter form from its declared parameters, runs it and shows the results and figures. It reads and writes the same sessions, parameters and combined YAMLs as the runner. See the GUI guide.
cicada-analysis: plugins, tools and the runner¶
- Plugins derive from
CicadaAnalysis, or from a family base class that adds shared parameters (groups, events, PSTH). See the analysis engine. - cicada-tools holds the computation, independent of NWB, are to be reused if creating a new plugins and can be used / tested in your ownscripts. See cicada-tools.
- The runner (
generate_config,run_from_config) runs plugins from YAML files. See the headless workflow.
cicada-nwb: reading the data¶
NWBSession is a thin wrapper built around PyNWB allowing generic reading across NWB files
that may store information in various ways.It opens one NWB file and exposes its content through submodules.
Each submodule has getters (the data) and question methods (what the file contains). Since analyses only go
through these, a file layout is handled once, in cicada-nwb. Lab-specific conventions
(columns, naming) live in lab submodules (session.petersen, session.cossart).
The file stays open while the session object exists, which keeps data access fast and memory low. For the same reason, two analyses cannot run in parallel on the same files.
Extending CICADA¶
| To add | Write | Where |
|---|---|---|
| An analysis | A CicadaAnalysis plugin |
A lab package (template), or cicada-analysis for a core plugin; a plugin folder while developing it |
| A computation reused by plugins | A function on arrays / tables | cicada-tools (lab-specific: the lab package's tools/) |
| Support for a lab's data conventions | A lab submodule | A lab package (entry-point group cicada_nwb.lab_submodules) |