nstat.extras.interop.nwb

NWB (Neurodata Without Borders) → nstat reader (Tier-B interop).

NWB:N is the BRAIN-Initiative-standard format for neurophysiology data. This module reads NWB files into nstat’s Trial / SpikeTrainCollection primitives so analyses written for nstat can run directly on NWB-formatted datasets.

The reverse direction (nstat → NWB writer) is deliberately omitted in the initial release: writing a faithful NWB file requires populating mandatory metadata (subject, session_description, experimenter, …) that nstat doesn’t track, so the conversion would need user-supplied fields the bridge can’t infer. Users who need to write NWB should construct the file via pynwb directly and use this module’s converters to populate the spike-train tables.

Install:

pip install nstat-toolbox[nwb]

Functions

nwb_units_to_collection(nwbfile, *[, ...])

Read the units table of an NWB file into a SpikeTrainCollection.

read_nwb_path(path, *[, sample_rate, ...])

Convenience: open an NWB file path and return a SpikeTrainCollection.
nstat.extras.interop.nwb.nwb_units_to_collection(nwbfile, *, sample_rate=30000.0, name_prefix='unit', time_window=None)[source]

Read the units table of an NWB file into a SpikeTrainCollection.

Recording-window resolution order (most specific → least specific):

  1. Explicit time_window=(t0, t1) parameter.

  2. Per-unit obs_intervals column if present (NWB-standard field for “intervals during which this unit was observed”). Uses the outer envelope [min(start), max(end)].

  3. Session-level nwbfile.session_start_time / nwbfile.timestamps_reference_time if both populated and NWB-style session_description carries a duration hint.

  4. Fallback: [min(spike_times), max(spike_times)] per unit — and a UserWarning is emitted because this silently understates the observation window for sparse-firing units.

Parameters:

  • nwbfile (pynwb.NWBFile) – Open NWB file with a populated units table.

  • sample_rate (float) – Recording sample rate in Hz. NWB’s Units table stores spike times directly, not raw samples, so this is metadata used by nstat’s primitives only — it does not affect the spike times. Defaults to 30 kHz (typical sorting acquisition rate).

  • name_prefix (str) – Prefix for auto-generated unit names; resulting names look like f"{name_prefix}_{row_id}".

  • time_window (tuple[float, float] | None) – Explicit (min_time_s, max_time_s) recording window applied uniformly to every unit. Strongly recommended when the NWB file does not carry obs_intervals — otherwise PSTH / rate-based downstream analyses will silently corrupt for sparsely-firing units.

Return type:

SpikeTrainCollection

nstat.extras.interop.nwb.read_nwb_path(path, *, sample_rate=30000.0, name_prefix='unit')[source]

Convenience: open an NWB file path and return a SpikeTrainCollection.

Parameters:
Return type:

SpikeTrainCollection