save_nwb_timeseries

save_nwb_timeseries#

class braintools.file.save_nwb_timeseries(path, data, dt, name, unit=None, *, description='no description', session_description='braintools time series', identifier=None, session_start_time=None, overwrite=False)#

Write a regularly sampled signal as an NWB TimeSeries in a new file.

The series is added to the file’s acquisition group, with time on axis 0, sampling rate 1 / dt in Hz and starting time 0 s.

Parameters:

  • path (str | PathLike) – Target .nwb file, written atomically.

  • data (Any) – Samples with time on axis 0, shape (T, ...).

  • dt (Any) – Sampling interval. A Quantity must have a time unit; a plain number is in seconds (the NWB time unit).

  • name (str) – Name of the TimeSeries.

  • unit (Unit | str | None) – Physical unit to store. If data is a Quantity, it is converted to unit (a str is parsed with brainunit.parse_unit), and the default is the unit of data. If data is a plain array, unit is only recorded as its string; the default is "n/a" (no unit).

  • description (str) – Description of the series.

  • session_description (str) – Description of the session (required by NWB).

  • identifier (str | None) – Unique file identifier; a random UUID by default.

  • session_start_time (datetime | None) – Timezone-aware session start; the current UTC time by default.

  • overwrite (bool) – Whether to replace an existing file at path.

Raises:

  • FileExistsError – If path exists and overwrite is False.

  • TypeError – If dt has a non-time unit or data is a JAX tracer.

  • ValueError – If dt is not positive, or data is 0-d.

  • brainunit.UnitMismatchError – If data cannot be converted to unit.

  • ImportError – If pynwb is not installed (pip install braintools[nwb]).

Return type:

None

See also

load_nwb_timeseries

Read the series back.

save_nwb_units

Write spike trains.

Notes

Host-only (not under jax.jit/jax.vmap). Each call creates a new file holding one series.

Examples

>>> import os, tempfile
>>> import brainunit as u
>>> import numpy as np
>>> from braintools.file._nwb import save_nwb_timeseries, load_nwb_timeseries
>>> path = os.path.join(tempfile.mkdtemp(), 'v.nwb')
>>> v = np.array([[-65., -64.], [-63., -60.], [-55., -70.]]) * u.mV
>>> save_nwb_timeseries(path, v, 0.1 * u.ms, 'membrane_potential')
>>> data, dt = load_nwb_timeseries(path, 'membrane_potential')
>>> data
Quantity([[-65. -64.]
          [-63. -60.]
          [-55. -70.]], "mV")
>>> dt.to_decimal(u.ms)
0.1