Metadata-Version: 2.4
Name: cicada-analysis
Version: 0.4.0
Summary: CICADA analysis framework – headless analysis engine and plugins
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cicada-nwb<0.5,>=0.4
Requires-Dist: numpy<=2.4.4,>=2.0
Requires-Dist: pandas<=2.3.3,>=2.0
Requires-Dist: scipy<=1.17.1,>=1.11
Requires-Dist: matplotlib<=3.10.8,>=3.7
Requires-Dist: seaborn<=0.13.2,>=0.13
Requires-Dist: scikit-learn<=1.8.0,>=1.3
Requires-Dist: scikit-posthocs<=0.12.0
Requires-Dist: statsmodels<0.15,>=0.14
Requires-Dist: scikit-image<=0.26.0,>=0.21
Requires-Dist: opencv-python<=4.13.0.92,>=4.8
Requires-Dist: tifffile<=2026.3.3,>=2023.1.23
Requires-Dist: Pillow<=12.2.0,>=10.0
Requires-Dist: scanimage-tiff-reader==1.4.1.4
Requires-Dist: mat73<=0.65
Requires-Dist: read-roi<=1.6.0
Requires-Dist: networkx<=3.6.1,>=3.1
Requires-Dist: shapely<=2.1.2,>=2.0
Requires-Dist: fa2-modified<=0.4
Requires-Dist: sortedcontainers<=2.4.0,>=2.4
Requires-Dist: tqdm<=4.67.3,>=4.64
Requires-Dist: PyYAML<=6.0.3,>=6.0
Requires-Dist: openpyxl<=3.1.5,>=3.1
Requires-Dist: psutil<=7.2.2,>=5.9
Requires-Dist: packaging<=26.0,>=23.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: docs
Requires-Dist: zensical==0.0.74; extra == "docs"
Requires-Dist: mkdocstrings[python]<2,>=1.0; extra == "docs"
Dynamic: license-file

# CICADA Analysis

[![Documentation](https://readthedocs.org/projects/cicada-analysis/badge/?version=latest)](https://cicada-analysis.readthedocs.io/en/latest/analysis/)

📖 **Full documentation: [cicada-analysis.readthedocs.io](https://cicada-analysis.readthedocs.io/en/latest/analysis/)**

`cicada-analysis` is the extendable analysis engine of the CICADA pipeline (see [BiorXiv preprint](https://www.biorxiv.org/content/10.64898/2026.07.03.736318v1)).

The pipeline codebase is split into three independent, installable Python packages:

| Package | Role | Docs |
|---------|------|------|
| [`cicada-nwb`](https://gitlab.com/cossartlab/cicada_nwb) | NWB file access layer — opens files, exposes data through submodules | [docs](https://cicada-analysis.readthedocs.io/en/latest/nwb/) |
| [`cicada-analysis`](https://gitlab.com/cossartlab/cicada_analysis) | Headless analysis engine — plugin analyses, utils, config runner | [docs](https://cicada-analysis.readthedocs.io/en/latest/analysis/) |
| [`cicada-gui`](https://gitlab.com/cossartlab/cicada_gui) | PyQt5 desktop application | [docs](https://cicada-analysis.readthedocs.io/en/latest/gui/) |

<!-- --8<-- [start:intro] -->
`cicada-analysis` provides the analysis plugins and the tools ([`cicada-tools`](https://cicada-analysis.readthedocs.io/en/latest/analysis/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.
<!-- --8<-- [end:intro] -->

## What's inside

<!-- --8<-- [start: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)
```
<!-- --8<-- [end:inside] -->

---

## Install

### User : install from release

<!-- --8<-- [start:install-user] -->
From PyPI:
```bash
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install cicada-analysis
```

Or from GitLab, a given release (tag):
```bash
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"
```
<!-- --8<-- [end:install-user] -->

### Contributor : install from clone

<!-- --8<-- [start:install-dev] -->
**Contributing to `cicada-analysis` only** (`cicada-nwb` installed from PyPI):

```bash
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):

```bash
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
```
<!-- --8<-- [end:install-dev] -->

### Windows: enable long paths

<!-- --8<-- [start:windows-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:

```bash
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.
<!-- --8<-- [end:windows-long-paths] -->

---

## How to use

### Quick start — headless (no GUI needed)

<!-- --8<-- [start:quickstart] -->
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](https://gitlab.com/cossartlab/cicada_analysis/-/blob/master/templates/sessions_template.yaml)
- Fill in the list with your NWB identifiers and paths.
- _Optional : use the [template](https://gitlab.com/cossartlab/cicada_analysis/-/blob/master/templates/generate_sessions_config_template.py), 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](https://gitlab.com/cossartlab/cicada_analysis/-/blob/master/templates/generate_config_template.py)
- 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](https://gitlab.com/cossartlab/cicada_analysis/-/blob/master/templates/run_from_config_template.py)
- 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](https://cicada-analysis.readthedocs.io/en/latest/analysis/headless_workflow/#replaying-a-previous-run)).
Pass it back to `run_from_config` to run it again with the same parameters, random seeds and input files.
<!-- --8<-- [end:quickstart] -->

### Step by step workflow

See the full headless guide: [docs/analysis/headless_workflow.md](https://cicada-analysis.readthedocs.io/en/latest/analysis/headless_workflow/) 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](https://cicada-analysis.readthedocs.io/en/latest/overview/demo/).

### Integrate the pipeline in your workflow

<!-- --8<-- [start:integrate] -->
For an example usage of `cicada-analysis` within an analysis pipeline see [Bech & Dard, 2026](https://github.com/LSENS-BMI-EPFL/Bech_Dard_process_NWB)
<!-- --8<-- [end:integrate] -->

---

## Documentation

| Page | Content |
|------|---------|
| [Headless workflow](https://cicada-analysis.readthedocs.io/en/latest/analysis/headless_workflow/) | Headless workflow with config files |
| [Plugin catalogue](https://cicada-analysis.readthedocs.io/en/latest/analysis/cicada_analysis_plugins/) | Listing of available analysis plugins and plugin parameter tables |
| [Analysis engine and writing plugins](https://cicada-analysis.readthedocs.io/en/latest/analysis/cicada_analysis/) | Analysis framework, utils, writing plugins, importing analyses |
| [cicada-tools reference](https://cicada-analysis.readthedocs.io/en/latest/analysis/cicada_tools/) | Library supporting the analysis plugins |

---

## Optionally use the GUI

Parameters file can be generated through the GUI provided by [`cicada-gui`](https://gitlab.com/cossartlab/cicada_gui).

Full GUI guide: [cicada-gui docs](https://cicada-analysis.readthedocs.io/en/latest/gui/gui_guide/)

---

## Upgrade  

### For user installation 
<!-- --8<-- [start:upgrade-user] -->
From PyPI, the latest release:
```bash
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](https://gitlab.com/cossartlab/cicada_analysis/-/releases)):
```bash
conda activate cicada_env
pip install "git+https://gitlab.com/cossartlab/cicada_analysis.git@<new_version>"
```
<!-- --8<-- [end:upgrade-user] -->

### For contributor installation

<!-- --8<-- [start:upgrade-dev] -->
**If you only cloned `cicada_analysis`**:  
pull `cicada_analysis`, then update `cicada-nwb` from PyPI.

```bash
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.

```bash
cd /path/to/cicada_nwb && git pull
cd /path/to/cicada_analysis && git pull
```
<!-- --8<-- [end:upgrade-dev] -->

---

## Publication
See BiorXiv [Preprint](https://www.biorxiv.org/content/10.64898/2026.07.03.736318v1)
