PyNWB

3.1.3 · active · verified Thu Apr 16

PyNWB is the official Python API for working with Neurodata Without Borders (NWB) files, a standardized data format for neurophysiology data. It facilitates reading, writing, and manipulating NWB files, providing a high-level interface to the underlying HDF5 structure. The current version is 3.1.3, and it maintains an active release cadence with regular minor updates and less frequent major versions supporting new NWB schema versions.

Common errors

```
ModuleNotFoundError: No module named 'pynwb.io'
```
cause Attempting to import `NWBHDF5IO` from a submodule `pynwb.io` which is not the primary import path for recent pynwb versions.

fix Import `NWBHDF5IO` directly from the top-level `pynwb` package: `from pynwb import NWBHDF5IO`.
```
ValueError: NWBFile requires 'session_start_time' and 'identifier'
```
cause When creating an `NWBFile` instance, the `session_start_time` and `identifier` arguments are mandatory according to the NWB schema.

fix Ensure `session_start_time` (a `datetime` object) and `identifier` (a unique string) are always provided during `NWBFile` initialization. Example: `NWBFile(session_description='...', identifier='my_session', session_start_time=datetime.now().astimezone())`.
```
RuntimeError: Unable to open object (object 'acquisition' not found)
```
cause This usually means you are trying to access a group or data field within the NWB file (e.g., `nwbfile.acquisition['my_data']`) that does not exist or has a different name.

fix Verify the exact name of the object you are trying to access. Use `nwbfile.acquisition.keys()` to list available acquisition objects, or consult the NWB file's structure or the code that generated it.

Warnings

breaking The behavior of `pynwb.validate(io=...)` changed in version 3.0.0. It now matches `pynwb.validate(path=...)` and uses cached namespaces. Previous versions did not use cached namespaces for `io` validation.
Fix: If you rely on the pre-3.0.0 behavior of `pynwb.validate(io=...)` without cached namespaces, update your call to `pynwb.validate(io=..., use_cached_namespaces=False)` to explicitly disable caching for that operation.
breaking Several unused internal functions (e.g., `prepend_string`, `_not_parent` in `core.py`, `_not_parent` in `file.py`, `NWBBaseTypeMapper.get_nwb_file` in `io/core.py`) were removed.
Fix: These were internal functions. If your code was inadvertently using them, you will need to refactor to use documented public APIs or directly interact with the NWB schema as needed.
gotcha Files written with `NWBHDF5IO` without a `.nwb` extension will trigger a warning.
Fix: Always ensure your NWB file paths end with the `.nwb` extension (e.g., `myfile.nwb`) to adhere to NWB best practices and avoid warnings.
gotcha A performance regression introduced in pynwb 2.8.0 affected reading NWB files with a large number of objects or fields of objects.
Fix: Upgrade to pynwb version 3.1.2 or later to benefit from the performance fix for large NWB files.

Install

pip install pynwb Install PyNWB

Imports

NWBFile
```
from pynwb import NWBFile
```
NWBHDF5IO
wrong:
```
from pynwb.io import NWBHDF5IO
```
correct:
```
from pynwb import NWBHDF5IO
```
NWBHDF5IO is directly available from the top-level pynwb package since version 2.0.0. Importing from pynwb.io is deprecated.
TimeSeries
```
from pynwb.base import TimeSeries
```

ElectricalSeries

from pynwb.ecephys import ElectricalSeries

ImageSeries
```
from pynwb.ophys import ImageSeries
```

Quickstart

This quickstart demonstrates how to create a basic NWB file, add a TimeSeries to it, and then write and read the file from disk using `NWBFile` and `NWBHDF5IO`. It covers the fundamental steps for data archival in the NWB format.

from datetime import datetime
from pynwb import NWBFile, TimeSeries, NWBHDF5IO
import numpy as np
import os

# 1. Create a new NWBFile
nwbfile = NWBFile(
    session_description='My first NWB file tutorial',
    identifier='NWB_Tutorial_1',
    session_start_time=datetime.now().astimezone(),
    experimenter='John Doe',
    lab='Neuroscience Lab',
    institution='University of Example',
    experiment_description='Simple data creation for testing PyNWB.'
)

# 2. Add some TimeSeries data
data = np.random.rand(100, 1)
timestamps = np.linspace(0, 9.9, 100)
series = TimeSeries(
    name='my_timeseries',
    data=data,
    timestamps=timestamps,
    unit='volts',
    description='A simple random time series.'
)

nwbfile.add_acquisition(series)

# 3. Write the NWBFile to disk
filename = 'quickstart_example.nwb'
with NWBHDF5IO(filename, 'w') as io:
    io.write(nwbfile)

print(f"NWB file '{filename}' created successfully.")

# 4. Read the NWBFile from disk
with NWBHDF5IO(filename, 'r') as io:
    read_nwbfile = io.read()
    print(f"\nRead NWB file. Session description: {read_nwbfile.session_description}")
    read_series = read_nwbfile.acquisition['my_timeseries']
    print(f"Read TimeSeries data shape: {read_series.data.shape}")
    print(f"Read TimeSeries unit: {read_series.unit}")

# Clean up the created file
# os.remove(filename)

view raw JSON →