Skip to main content

CICADA GUI

Documentation

📖 Full documentation: cicada-analysis.readthedocs.io

cicada-gui is the PyQt5 desktop application for 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-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.

What's 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)

Install

User : install from release

From PyPI:

conda create -n cicada_env python=3.11
conda activate cicada_env
pip install cicada-gui

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_gui.git@0.3.2"

Contributor : install from clone

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

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

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:

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

How to use -- Quick start

Launch the GUI

conda activate cicada_env
python -m cicada_gui

CICADA GUI 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). 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 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.

Full GUI documentation

Page Content
GUI guide GUI workflow step by step, parameter form, group management

GUI / headless equivalence

The same analysis plugin runs identically in both modes:

# GUI mode
cicada_gui

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

See cicada-analysis for the full headless workflow.


Upgrade

For user installation

From PyPI, the latest release:

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

conda activate cicada_env
pip install "git+https://gitlab.com/cossartlab/cicada_gui.git@<new_version>"

For contributor installation

If you only cloned cicada-gui: pull cicada_gui, then update cicada-nwb and cicada-analysis from PyPI.

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.

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.

cd /path/to/cicada_nwb      && git pull
cd /path/to/cicada_analysis  && git pull
cd /path/to/cicada_gui       && git pull

Publication

See BiorXiv Preprint

Metadata

Release files for cicada-gui 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-gui 0.4.0
File Size Uploaded Provenance Actions
cicada_gui-0.4.0.tar.gz 331.4 kB Without provenance Details for cicada_gui-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cicada-gui 0.4.0
File Interpreter ABI Platform Actions
cicada_gui-0.4.0-py3-none-any.whl Python 3 none any Details for cicada_gui-0.4.0-py3-none-any.whl

Total release size: 786.9 kB

Release files / cicada_gui-0.4.0.tar.gz

Download URL cicada_gui-0.4.0.tar.gz
Size 331.4 kB
Tags Source
SHA-256 checksum
How to use checksums
46babb4fe372e2eef54cdc03f094c531c3dc62235628201c06f73360011edd7e
BLAKE2b-256 checksum
How to use checksums
f2cd7dccd5820be3f33497efaf6a8ebabf9856c2dd12ed44a32b2b5e6ef6119f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / cicada_gui-0.4.0-py3-none-any.whl

Download URL cicada_gui-0.4.0-py3-none-any.whl
Size 455.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fbceebeb1c28fc544ef35631ddb46d8f467be7acb87f3328632e5e56fd72eb26
BLAKE2b-256 checksum
How to use checksums
c25df5ffe0e9129b2b4bb2fb634741b74d783748ed49da9cf67ada43422518d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.11.18

Security for cicada-gui 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