`nstat.extras.interop.nwb` — NWB:N reader

Read NWB files into nstat.SpikeTrainCollection. NWB:N is the BRAIN-Initiative-standard format for neurophysiology data; this bridge lets analyses written for nstat run directly on NWB-formatted datasets.

Install

pip install nstat-toolbox[nwb]

Pulls pynwb>=2.8 (and hdmf transitively).

API

Function	Notes
`nwb_units_to_collection(nwbfile, *, sample_rate, name_prefix, time_window)`	Reads the `units` table from an in-memory `NWBFile`
`read_nwb_path(path, *, sample_rate, name_prefix)`	File-path convenience wrapper

Recording-window resolution order

For each unit, minTime / maxTime are resolved most-specific to least-specific:

Explicit time_window=(t0, t1) parameter — applied uniformly to every unit.
Per-unit obs_intervals column (NWB-standard for “intervals during which the unit was observed”) — uses the outer envelope.
Fallback: per-unit [min(spike_times), max(spike_times)] — emits a UserWarning because this silently understates the observation window for sparsely-firing units, breaking PSTH / rate denominators.

Recipe

from pynwb import NWBHDF5IO
from nstat.extras.interop.nwb import nwb_units_to_collection, read_nwb_path

# Path-based convenience
coll = read_nwb_path("/path/to/session.nwb", sample_rate=30_000.0)

# Or open the file yourself for richer control
with NWBHDF5IO("/path/to/session.nwb", mode="r") as io:
    nwb = io.read()
    coll = nwb_units_to_collection(
        nwb,
        sample_rate=30_000.0,
        # Override per-unit obs_intervals — applied uniformly:
        time_window=(0.0, 600.0),
    )

print(f"Loaded {len(list(coll))} units")

Gotchas

Window discipline. If you ingest an NWB file without obs_intervals and without time_window=, you get a UserWarning on the first sparse unit. Treat this as an error in production — silent understatement of denominators is the #1 source of rate-comparison bugs across trials.
Sample rate. NWB stores spike times as seconds, not raw samples, so sample_rate= is metadata-only for nstat’s primitives — it does not affect the spike times themselves. Defaults to 30 kHz.
Writer omitted. No nstat → NWB writer ships today. A faithful NWB file needs mandatory metadata (subject, session_description, experimenter, …) that nstat doesn’t track. Construct NWB files via pynwb directly.

End-to-end demo

examples/extras/interop_nwb_demo.py builds an in-memory NWB file with obs_intervals, then demonstrates both the implicit-window path and the explicit time_window= override.

Upstream references

pynwb: https://github.com/NeurodataWithoutBorders/pynwb
License: BSD-3-Clause (GPL-2 compatible)
Maintained by: LBNL / Allen Institute / NIH

nstat.extras.interop.nwb — NWB:N reader