jnwb

Dataset-agnostic Python library for Neurodata Without Borders (NWB 2.0+) electrophysiology: addressing, spikes, LFP, spectral analysis, statistics, population methods, decoding, connectivity, laminar CSD, filtering, QC, and visualization.

Documentation: https://jnwb.readthedocs.io/ | Source: https://github.com/HNXJ/jnwb

jnwb is a toolbox, not a pipeline. It supplies small operations over NWB files, arrays, and metadata tables. Task structure, condition codes, and experimental hypotheses stay in project code.

• Dataset-agnostic. No experiment condition names or manuscript results live in the library.
• Explicit nulls. Label permutation requires an exchangeability scheme (global or within_group).
• Preserved signal semantics. Units, sampling rates, coordinate frames, and 0- vs 1-indexing do not change across a function boundary.

Capabilities

Installation

Requires Python 3.12 or newer. Tested in CI on 3.12 and 3.14.

pip install jnwb                  # latest published release
pip install "jnwb[torch,gpu]"     # optional backends

This checkout is 0.2.4. To install it from a clone instead of from PyPI:

pip install .                     # or: pip install -e ".[test,docs]" for development

Core dependencies: numpy, scipy, pandas, h5py, pynwb, hdmf, matplotlib, scikit-learn, statsmodels, joblib.

NWB workflow

jnwb.inspect lists acquisitions, electrodes, units, and every interval table with column samples — it does not pick a default event table. Event codes are opaque labels in a named column (default codes). Onsets from jnwb.event_onsets are in seconds. When several interval tables exist, pass table= explicitly; jnwb raises rather than guessing.

import jnwb

info = jnwb.inspect("recording.nwb")
events = jnwb.events("recording.nwb", table="test_synth_task")
onsets = jnwb.event_onsets("recording.nwb", table="test_synth_task", codes=["test-synth-1"])

Executable walkthroughs: Read the Docs tutorials or examples/tutorials/.

Quickstart (arrays)

import numpy as np
import jnwb

rng = np.random.default_rng(42)
spikes = np.sort(rng.uniform(0.0, 10.0, 300))
events = np.array([1.0, 3.0, 5.0, 7.0])

time_bins, rate_hz, _ = jnwb.raster_psth(spikes, events, win_ms=(-100.0, 400.0), bin_ms=10.0)
smooth_hz = jnwb.causal_exp_smooth(rate_hz, bin_ms=10.0, tau_ms=25.0)
fit = jnwb.fit_exponential_onset(time_bins, smooth_hz, t0_bounds=(0.0, 200.0))
print(f"Onset t0: {fit['t0']:.1f} ms (R2={fit['r2']:.2f}, {fit['bound_status']})")

fs = 1000.0
lfp = rng.normal(size=1000)
tfr = jnwb.complex_tfr(lfp, fs=fs, freqs=np.linspace(10.0, 60.0, 10))
beta = jnwb.band_power(lfp, fs=fs, freq_range=jnwb.CANONICAL_BANDS["beta"], normalize=False)
print(f"TFR shape: {tfr.shape}, beta power: {beta:.4f}")

Read spikes and LFP for alignment after you have onsets:

spikes = jnwb.unit_spike_times("recording.nwb", unit_index=0)
lfp, fs_hz = jnwb.acquisition_channel("recording.nwb", name="probe_0_lfp", channel=0)
epochs, t_axis_s = jnwb.epoch_continuous(lfp, onsets, win_s=(-0.1, 0.4), fs=fs_hz)

Unit and electrode census:

units = jnwb.get_all_units_metadata("session.nwb")
electrodes = jnwb.electrode_inventory("session.nwb")

Documentation

Guides, the public API (every symbol in jnwb.__all__), and common mistakes are on Read the Docs.

Contributing

Setup, the checks to run, the branch model and the release procedure are in CONTRIBUTING.md. Work lands on dev; main holds releases. The queued work is in artifacts/todo_stack.md.

If you are an AI agent, read AGENTS.md first.

License

MIT. See LICENSE.