Metadata-Version: 2.4
Name: cicada-gui
Version: 0.4.0
Summary: CICADA GUI — PyQt5 application for calcium imaging data analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cicada-analysis<0.5,>=0.4
Requires-Dist: PyQt5<=5.15.11,>=5.15
Requires-Dist: qtpy<=2.4.3,>=2.3
Requires-Dist: matplotlib<=3.10.8,>=3.7
Requires-Dist: sortedcontainers<=2.4.0,>=2.4
Requires-Dist: PyYAML<=6.0.3,>=6.0
Requires-Dist: platformdirs<=4.14.4,>=3.0
Requires-Dist: numpy<=2.4.4,>=2.0
Dynamic: license-file

# CICADA GUI

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

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

`cicada-gui` is the PyQt5 desktop application for 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-gui` provides a graphical interface to browse NWB sessions, configure analysis parameters interactively, and launch analyses. 

The GUI also allows the user to create NWB session groups and save analysis parameters to YAML to be used headlessly — the GUI and the headless runner use identical analysis plugins.
<!-- --8<-- [end:intro] -->

## What's inside

<!-- --8<-- [start:inside] -->
```
cicada_gui/
├── main_window.py   # Main window: menus, sessions panel, analysis tree
├── sessions/        # Loading sessions (local folder, DANDI dialog), groups (sessions YAML)
├── analysis/        # Analysis tree, parameter window built from each plugin's parameters,
│                    # run thread, results viewer (files and figures)
├── metadata/        # Session metadata display
└── config/          # User settings (results folder, last folders, DANDI mode)
```
<!-- --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-gui
```

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_gui.git@0.3.2"
```
<!-- --8<-- [end:install-user] -->

### Contributor : install from clone

<!-- --8<-- [start:install-dev] -->
Install the clones from the bottom up (`cicada-nwb`, `cicada-analysis`, `cicada-gui`): each one then uses the clones installed before it; the packages you did not clone come from PyPI.

**Contributing to `cicada-gui` only** (`cicada-analysis` and `cicada-nwb` installed from PyPI):

```bash
git clone https://gitlab.com/cossartlab/cicada_gui.git /path/to/cicada_gui
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install -e /path/to/cicada_gui
```

**Contributing to `cicada-gui` and `cicada-analysis`** (`cicada-nwb` installed from PyPI):

```bash
git clone https://gitlab.com/cossartlab/cicada_analysis.git /path/to/cicada_analysis
git clone https://gitlab.com/cossartlab/cicada_gui.git /path/to/cicada_gui
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install -e /path/to/cicada_analysis
pip install -e /path/to/cicada_gui
```

**Contributing to all three repos**:

```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
git clone https://gitlab.com/cossartlab/cicada_gui.git /path/to/cicada_gui
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
pip install -e /path/to/cicada_gui
```
<!-- --8<-- [end:install-dev] -->

---

## How to use -- Quick start

### Launch the GUI

<!-- --8<-- [start:launch] -->
```bash
conda activate cicada_env
python -m cicada_gui
```
<!-- --8<-- [end:launch] -->
<!-- --8<-- [start:quickstart] -->
![CICADA GUI](https://gitlab.com/cossartlab/cicada_gui/-/raw/master/docs/cicada_main_gui.png)
_`cicada-gui` main window with example NWB loaded and sorted by 'Subject ID'_

### Minimal use workflow

#### 1. Load sessions

Click **Open new dataset** using the *File* menu and select the directory containing
your `.nwb` files.  All valid NWB files are listed in the sessions panel.

#### 2. Select sessions

Tick the sessions you want to include in the next analysis run.

Use **Group by** from the *View* menu to sort the list by metadata field (age, genotype, sex, subject ID,
session type, etc.) — useful for quickly selecting a subset of sessions.

#### 3. Save / load a group

**Create group** in the *File* menu writes a `sessions_<name>.yaml` file to your configured result
directory (see *Configuration* in [the GUI guide](https://cicada-analysis.readthedocs.io/en/latest/gui/gui_guide/)).  This file can be reloaded later (*Load group*) or used directly in
the headless workflow.  

Tip: the *Load group* option can replace *Open folder* — it will load only the files listed in the selected group.

#### 4. Pick an analysis

The analysis tree shows all available plugins, organized by family.
Click a family header to expand it.

Analyses that are **incompatible** with the currently checked sessions are greyed out
(the  `cicada-analysis` - `check_data()` guard reported a problem — hover to see why).

#### 5. Open the parameter form

**Double-click** an analysis to open its parameter window.
The form is organized into collapsible sections (families).

![CICADA GUI PARAMS](https://gitlab.com/cossartlab/cicada_gui/-/raw/master/docs/cicada_gui_example_parameter_window.png)
_`cicada-gui` analysis window for the `cicada-analysis` 'Display cell maps' plugin._

Session-specific parameters (ROI response series, epoch names, etc.) are pre-filled
from the checked sessions.

#### 6. Save / load parameters

- **Save parameters** — writes a `params_<ClassName>.yaml` to disk.
  Compatible with the headless runner: use it as the `params` argument of `run_from_config`.
- **Load parameters** — loads a previously saved `params_<ClassName>.yaml` or
  `combined_*.yaml`.  Session-specific parameters (ROI response series, etc.) are
  skipped automatically when loading across different session groups.

#### 7. Run

Fill all mandatory parameters (highlighted if missing), then click **RUN ANALYSIS**.

After the run:
- Results are saved to the `results_path` parameter you set.
- A `combined_<ClassName>_<timestamp>.yaml` file is written alongside the results —
  it records the exact sessions and parameters used, enabling headless replay.
<!-- --8<-- [end:quickstart] -->

---

## Full GUI documentation

| Page | Content |
|------|---------|
| [GUI guide](https://cicada-analysis.readthedocs.io/en/latest/gui/gui_guide/) | GUI workflow step by step, parameter form, group management |


---

## GUI / headless equivalence

<!-- --8<-- [start:equivalence] -->
The same analysis plugin runs identically in both modes:

```bash
# GUI mode
cicada_gui

# Headless mode — same analysis, same parameters, no GUI required
python templates/run_from_config_template.py
```

See [cicada-analysis](https://gitlab.com/cossartlab/cicada_analysis) for the full headless workflow.
<!-- --8<-- [end:equivalence] -->

---

## Upgrade

### For user installation
<!-- --8<-- [start:upgrade-user] -->
From PyPI, the latest release:
```bash
conda activate cicada_env
pip install -U cicada-gui
```

Or from GitLab, a given release: replace the tag with its version (check available releases on [GitLab](https://gitlab.com/cossartlab/cicada_gui/-/releases)):
```bash
conda activate cicada_env
pip install "git+https://gitlab.com/cossartlab/cicada_gui.git@<new_version>"
```
<!-- --8<-- [end:upgrade-user] -->

### For contributor installation

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

```bash
cd /path/to/cicada_gui && git pull
conda activate cicada_env
pip install -U cicada-analysis cicada-nwb
```

**If you cloned `cicada-gui` and `cicada-analysis`**: pull both repos, then update `cicada-nwb` from PyPI.

```bash
cd /path/to/cicada_analysis && git pull
cd /path/to/cicada_gui && git pull
conda activate cicada_env
pip install -U cicada-nwb
```

**If you cloned all three repos**: pull each repo.

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

---

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