Metadata-Version: 2.4
Name: cicada-nwb
Version: 0.4.0
Summary: NWB data access layer for CICADA — lazy read-only wrappers with no GUI or analysis dependencies
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pynwb<=3.1.3,>=2.5
Requires-Dist: numpy<=2.4.4,>=2.0
Requires-Dist: pandas<=2.3.3,>=2.0
Requires-Dist: h5py<=3.16.0,>=3.9
Requires-Dist: scikit-image<=0.26.0,>=0.21
Requires-Dist: remfile<=0.1.15,>=0.1.13
Requires-Dist: requests<=2.34.2,>=2.28
Requires-Dist: platformdirs<=4.14.4,>=3.0
Requires-Dist: packaging<=26.0,>=23.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# CICADA NWB

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

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

`cicada-nwb` is the read-only NWB-file access layer for the CICADA analysis pipeline (see [BiorXiv preprint](https://www.biorxiv.org/content/10.64898/2026.07.03.736318v1)).

The CICADA 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-nwb` opens NWB files and exposes their content through typed submodules
(`calcium_imaging`,`electrophysiology`, `behavior`, `widefield`, `metadata`, `subject`).
It has no GUI or analysis dependencies and can be used standalone as a lightweight NWB reader.
As `cicada-nwb` keeps the NWB files open, which makes it run fast with minimal RAM use,
launching analysis in parallel on the same NWBs is not possible.

This is the recommended approach for writing
custom analysis scripts that need direct control over data access.
<!-- --8<-- [end:intro] -->

## What's inside

<!-- --8<-- [start:inside] -->
```
cicada_nwb/
├── nwb_session.py     # NWBSession: opens one NWB file (local or DANDI), holds the submodules
├── submodules/        # metadata, calcium_imaging, electrophysiology, behavior, widefield,
│                      # optogenetic (getters and question methods)
├── lab_submodules/    # NWBLabSubmodule: base of the lab submodules of the lab packages
├── dandi.py           # DANDI addresses, streaming and download
└── testing/           # Synthetic NWB files for tests
```
<!-- --8<-- [end:inside] -->

---

## Install

### User : install from release

<!-- --8<-- [start:install-user] -->
```bash
cd 'path/to/'
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install "git+https://gitlab.com/cossartlab/cicada_nwb.git@0.3.2"
```
<!-- --8<-- [end:install-user] -->

### Contributor : install from clone

<!-- --8<-- [start:install-dev] -->
```bash
cd 'path/to/'
git clone https://gitlab.com/cossartlab/cicada_nwb.git
conda create -n cicada_env python=3.11
conda activate cicada_env
pip install -e /path/to/cicada_nwb
```
<!-- --8<-- [end:install-dev] -->

---

## Access the NWB data : available submodules

<!-- --8<-- [start:submodules] -->
`cicada-nwb` is organized into six generic submodules and any number of lab-specific submodules.

| Submodule                 | Accessed via               | Key methods                                                                                               |
|---------------------------|----------------------------|-----------------------------------------------------------------------------------------------------------|
| 2P calcium imaging        | `session.calcium_imaging`  | `get_roi_response_serie_data()`, `get_roi_response_serie_timestamps()`, `get_cell_indices_by_cell_type()` |
| Electrophysiology         | `session.electrophysiology` | `get_units_table`, `get_electrode_info`, `get_units_location`                                            |
| Behavior                  | `session.behavior`         | `get_trial_table()`, `get_behavioral_epochs_times()`, `get_behavioral_events_times()`                     |
| Widefield calcium imaging | `session.widefield`        | `get_widefield_timestamps()`, `get_widefield_dff0()`                                                      |
| Metadata                  | `session.metadata`         | `get_sessions_info()`                                                                                     |
| Subject                   | `session` (properties)     | `subject_id`, `age`, `genotype`, `sex`, `species`                                                         |
<!-- --8<-- [end:submodules] -->

---

## How to use

### Quick start to using the package - accessing NWB data

<!-- --8<-- [start:quickstart] -->
Use `cicada-nwb` submodules to access NWB data and use it for custom-made analysis.

```python
from cicada_nwb import NWBSession

with NWBSession("/path/to/file.nwb") as session:

    # Calcium imaging: a series is addressed by [module, interface, series name]
    rrs = session.calcium_imaging.get_roi_response_series()   # {module: {interface: [names]}}
    module = next(iter(rrs))
    interface = next(iter(rrs[module]))
    keys = [module, interface, rrs[module][interface][0]]
    traces = session.calcium_imaging.get_roi_response_serie_data(keys)       # (n_cells, n_frames)
    ts     = session.calcium_imaging.get_roi_response_serie_timestamps(keys)  # (n_frames,) seconds

    # Behavior
    trial_table = session.behavior.get_trial_table()          # DataFrame, or None without trials
    epochs      = session.behavior.get_behavioral_epochs_names()
    events      = session.behavior.get_behavioral_events_names()
    event_times = session.behavior.get_behavioral_events_times(event_name=events[0])

    # Widefield: an acquisition is addressed by [module, name]
    wf = session.widefield.get_wf_acquisition_dict()           # {module: [names]}
    wf_module = next(iter(wf))
    wf_ts = session.widefield.get_widefield_timestamps(keys=[wf_module, wf[wf_module][0]])

    # Metadata
    info = session.metadata.get_sessions_info()
    print(session.subject_id, session.age, session.genotype)

    # Custom-made analysis below

```

### Template

For an example on how to use `cicada-nwb` in a custom-made script for NWB based analysis.

See : [custom script template](https://gitlab.com/cossartlab/cicada_nwb/-/blob/master/templates/cicada_nwb_only_analysis_template.py).

### Tip

To facilitate analysis development it is possible to build custom-made scripts using the `cicada-tools`
provided by [`cicada-analysis`](https://gitlab.com/cossartlab/cicada_analysis).
This requires to install `cicada-analysis` and import functions from `cicada-tools` into your script.

See the [cicada-tools quick start](https://cicada-analysis.readthedocs.io/en/latest/analysis/cicada_tools_quickstart/) for example.
<!-- --8<-- [end:quickstart] -->

---

## Lab-specific submodules

<!-- --8<-- [start:lab] -->
`cicada-nwb` supports lab-specific NWB conventions through lab submodules, provided by installed packages that
declare them under the entry-point group `cicada_nwb.lab_submodules`. For example `session.petersen` from
[cicada-petersen](https://github.com/LSENS-BMI-EPFL/cicada_petersen) and `session.cossart` from
[cicada-cossart](https://gitlab.com/cossartlab/cicada_cossart).

See [new_lab_submodule_template.py](https://gitlab.com/cossartlab/cicada_nwb/-/blob/master/templates/new_lab_submodule_template.py) for example implementation.
<!-- --8<-- [end:lab] -->

---

## Documentation

More detailed documentation available :

| Page | Content |
|------|---------|
| [User guide](https://cicada-analysis.readthedocs.io/en/latest/nwb/cicada_nwb/) | Tutorial, lab submodules, writing extensions |
| [API reference](https://cicada-analysis.readthedocs.io/en/latest/nwb/api/nwb_session/) | Full API: NWBSession, submodules, lab submodules, DANDI |

---

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