Skip to main content

CICADA Analysis

Documentation

📖 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)

Source distribution for cicada-analysis 0.4.0
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)

Table of built distributions (wheels) for cicada-analysis 0.4.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.4.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page