CICADA NWB
📖 Full documentation: cicada-analysis.readthedocs.io
cicada-nwb is the read-only NWB-file access layer for the CICADA analysis pipeline (see BiorXiv preprint).
The CICADA 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-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.
What's 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
Install
User : install from release
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"
Contributor : install from clone
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
Access the NWB data : available 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 |
How to use
Quick start to using the package - accessing NWB data
Use cicada-nwb submodules to access NWB data and use it for custom-made analysis.
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.
Tip
To facilitate analysis development it is possible to build custom-made scripts using the cicada-tools
provided by cicada-analysis.
This requires to install cicada-analysis and import functions from cicada-tools into your script.
See the cicada-tools quick start for example.
Lab-specific submodules
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 and session.cossart from
cicada-cossart.
See new_lab_submodule_template.py for example implementation.
Documentation
More detailed documentation available :
| Page | Content |
|---|---|
| User guide | Tutorial, lab submodules, writing extensions |
| API reference | Full API: NWBSession, submodules, lab submodules, DANDI |
Publication
See BiorXiv Preprint
Metadata
Release files for cicada-nwb 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cicada_nwb-0.4.0.tar.gz | 83.0 kB | Without provenance | Details for cicada_nwb-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cicada_nwb-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for cicada_nwb-0.4.0-py3-none-any.whl |
Total release size: 143.0 kB
Release files / cicada_nwb-0.4.0.tar.gz
| Download URL | cicada_nwb-0.4.0.tar.gz |
|---|---|
| Size | 83.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7d7c59a5c5532db0c6e1e8235a8466cfe6047bcd48686c202502cf4f1709cc92
|
|
BLAKE2b-256 checksum How to use checksums |
47c89823ddc3477d26be024017f6de715ee972cb45f3b1fc6bd213363a6c3d32
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / cicada_nwb-0.4.0-py3-none-any.whl
| Download URL | cicada_nwb-0.4.0-py3-none-any.whl |
|---|---|
| Size | 60.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
070eed5806f659ab18daaf481703ddc0892e3537f4b0bf9b3cbd8ad05d3e7a90
|
|
BLAKE2b-256 checksum How to use checksums |
da5c9dac1e2a67e57909f62e1fb59363371be1520231549082967990bf4146b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for cicada-nwb 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.