Skip to main content

CICADA NWB

Documentation

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

Source distribution for cicada-nwb 0.4.0
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)

Table of built distributions (wheels) for cicada-nwb 0.4.0
File Interpreter ABI Platform Actions
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.

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