CICADA Analysis
📖 Full documentation: cicada-analysis.readthedocs.io
cicada-analysis is the extendable analysis engine of the CICADA pipeline (see BiorXiv preprint).
The pipeline codebase is split into three independent, installable Python packages:
| Package | Role | Docs |
|---|---|---|
cicada-nwb |
NWB file access layer — opens files, exposes data through submodules | docs |
cicada-analysis |
Headless analysis engine — plugin analyses, utils, config runner | docs |
cicada-gui |
PyQt5 desktop application | docs |
cicada-analysis provides the analysis plugins and the tools (cicada-tools) supporting them.
It is the entry point to analyze NWB files using existing plugins. cicada-analysis is dependent on cicada-nwb.
As cicada-nwb keeps the NWB files open for the entire duration of the analysis, which makes it run a lot faster,
launching analysis in parallel on the same NWBs is not possible.
What's inside
cicada_analysis/
├── base/ # CicadaAnalysis (plugin base class), parameter schema and rules,
│ # family base classes (events, groups, PSTH)
├── config/ # Headless runner (generate_config, run_from_config) and YAML I/O
├── core_analysis/ # Core plugins (standard NWB data only)
├── cicada_tools/ # Computation and figure library used by the plugins
└── demo/ # Small demo NWB files (also the plugin test files)
Install
User : install from release
From PyPI:
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install cicada-analysis
Or from GitLab, a given release (tag):
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install "git+https://gitlab.com/cossartlab/cicada_analysis.git@0.3.2"
Contributor : install from clone
Contributing to cicada-analysis only (cicada-nwb installed from PyPI):
git clone https://gitlab.com/cossartlab/cicada_analysis.git /path/to/cicada_analysis
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install -e /path/to/cicada_analysis
Contributing to both cicada-analysis and cicada-nwb (install cicada-nwb first: cicada-analysis then uses your local clone, whose version is within its range):
git clone https://gitlab.com/cossartlab/cicada_nwb.git /path/to/cicada_nwb
git clone https://gitlab.com/cossartlab/cicada_analysis.git /path/to/cicada_analysis
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install -e /path/to/cicada_nwb
pip install -e /path/to/cicada_analysis
Windows: enable long paths
Windows limits file paths to 259 characters unless long paths are enabled. Some analyses write files in sub-folders with long names, so with a results folder deep in your tree, saving can fail ("No such file or directory"). CICADA warns at the start of a run when this may happen. To remove the limit, once, as administrator:
reg add HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f
(or Local Group Policy Editor > Computer Configuration > Administrative Templates > System > Filesystem >
Enable Win32 long paths), then restart. Otherwise, choose a results folder with a short path (e.g. C:\results).
macOS and Linux have no such limit.
How to use
Quick start — headless (no GUI needed)
The headless runner handles session loading, parameter validation, and produces a reproducibility record.
Using a cicada-analysis plugin via the headless runner requires 2 configuration files : a session file, and an analysis parameters file.
Step 1 — Create a session YAML listing your NWB files (identifier + path)
- Copy the session YAML template
- Fill in the list with your NWB identifiers and paths.
- Optional : use the template, with the path to your NWB data folder or a DANDI address.
- Optional : export from the GUI: Sessions panel → Save Group.
Step 2 — Generate an analysis parameters file pre-filled with default values
- Copy the parameters generation template
- Adjust the paths (SESSION YAML + PARAMS YAML) and analysis plugin name (ANALYSIS_CLASS_NAME)
- Run the file
- Optional : analysis parameters can be saved from the GUI : Analysis panel → Save Parameters.
Step 3 — Adjusting the parameters
- Open the generated YAML and set your parameter values
Step 4 — Run the analysis
- Copy the runner template
- Decide if you run in mode A or B (first run versus replay of a previous run)
- Adjust the paths (SESSION YAML + PARAMS YAML or COMBINED_YAML)
- Run the file
Step 5 - Check the output
Each run output the analysis results (depending on analysis, this can be a series of plots and/or intermediate analysis files)
and a combined_<ClassName>_<timestamp>.yaml in the result directory.
This new yaml contains the analysis class, the final parameter values, the sessions with their input files
and the environment of the run; replaying it warns about every difference
(see Replaying a previous run).
Pass it back to run_from_config to run it again with the same parameters, random seeds and input files.
Step by step workflow
See the full headless guide: docs/analysis/headless_workflow.md for more details
Example data and configs
cicada-analysis installs nine small NWB files from public datasets (two-photon and widefield imaging,
Neuropixels units, ECoG, behaviour) and the configs that make the panels of Figure 3 of the CICADA paper from them:
see the Demo page.
Integrate the pipeline in your workflow
For an example usage of cicada-analysis within an analysis pipeline see Bech & Dard, 2026
Documentation
| Page | Content |
|---|---|
| Headless workflow | Headless workflow with config files |
| Plugin catalogue | Listing of available analysis plugins and plugin parameter tables |
| Analysis engine and writing plugins | Analysis framework, utils, writing plugins, importing analyses |
| cicada-tools reference | Library supporting the analysis plugins |
Optionally use the GUI
Parameters file can be generated through the GUI provided by cicada-gui.
Full GUI guide: cicada-gui docs
Upgrade
For user installation
From PyPI, the latest release:
conda activate cicada_env
pip install -U cicada-analysis
Or from GitLab, a given release: replace the tag with its version (check available releases on GitLab):
conda activate cicada_env
pip install "git+https://gitlab.com/cossartlab/cicada_analysis.git@<new_version>"
For contributor installation
If you only cloned cicada_analysis:
pull cicada_analysis, then update cicada-nwb from PyPI.
cd /path/to/cicada_analysis && git pull
conda activate cicada_env
pip install -U cicada-nwb
If you cloned both (cicada-analysis and cicada-nwb) repos : pull each repo.
cd /path/to/cicada_nwb && git pull
cd /path/to/cicada_analysis && git pull
Publication
See BiorXiv Preprint
Metadata
Release files for cicada-analysis 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cicada_analysis-0.4.0.tar.gz | 73.6 MB | Without provenance | Details for cicada_analysis-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cicada_analysis-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for cicada_analysis-0.4.0-py3-none-any.whl |
Total release size: 147.4 MB
Release files / cicada_analysis-0.4.0.tar.gz
| Download URL | cicada_analysis-0.4.0.tar.gz |
|---|---|
| Size | 73.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
421c4eadbe3a827ee1e4fe54b1b5f5380cb676f67988f9bcd30c8b596e9970aa
|
|
BLAKE2b-256 checksum How to use checksums |
0a4848e7488acd800a1b7260044aab442160a2da9ad9b995e3a22890bc95eeea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / cicada_analysis-0.4.0-py3-none-any.whl
| Download URL | cicada_analysis-0.4.0-py3-none-any.whl |
|---|---|
| Size | 73.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0d5f7fbc5e81561d287b0b31de4d071bb2d6f2f3036848e08e0a99ac1e545087
|
|
BLAKE2b-256 checksum How to use checksums |
cb7103410d5410ac95b72e0c85878931143a86bb86cc66ab4fab8dbafad4c8c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for cicada-analysis 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.