Skip to content

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")]
  1. Open the files. The GUI (folder, group, DANDI) or the runner (sessions YAML) opens each NWB file as an NWBSession.
  2. 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.
  3. Read the data. run_analysis gets the data through the session submodules (session.calcium_imaging...), never by reading the NWB file directly.
  4. Compute with cicada-tools functions, which work on plain arrays and tables.
  5. 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:

  1. Installed packages (the normal way): a package installed with pip lists its plugins in its pyproject.toml (entry-point group cicada_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.
  2. Plugin folders (while developing a plugin): a folder of .py files, 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)