Overview

MatNWB is a MATLAB package for working with NWB files. With MatNWB, you can read, write, and validate NWB files directly in MATLAB using intuitive functions like nwbRead() and nwbExport(), along with a comprehensive set of MATLAB classes representing neurodata types defined by the NWB schema.

Who is it for?

• MATLAB users working with neurophysiology data (extracellular and intracellular electrophysiology, optical physiology, behavior, images, and derived analyses)

• Labs seeking a reproducible, self-describing data format that works seamlessly across platforms and is supported by an expanding ecosystem of tools and archives (e.g., DANDI).

What you can do with MatNWB

• Read NWB files

  • One call to nwbRead opens a file and presents a hierarchical representation of the complete file and its contents.

  • Lazy I/O via DataStub lets you slice large datasets without loading them into RAM.

• Write NWB files

  • Build an NwbFile with standard neurodata types (e.g., TimeSeries, ElectricalSeries, Units, ImageSeries).

  • Export to disk with nwbExport.

• Scale to large data

  • Stream/append and compress data with the DataPipe interface.

  • Use predefined or custom configuration profiles to optimize files for local storage, cloud storage or archiving.

• Use NWB extensions

  • Install published Neurodata Extensions (NDX) with nwbInstallExtension

  • Generate classes from any namespace specification with generateExtension.

How it works

NWB files are containers for storing data and metadata in a hierarchical manner using groups and datasets. In this sense, an NWB file can be thought of as a tree of folders and files representing all the data associated with neurophysiological recording sessions. The data and metadata is represented through a set of neurodata types defined by the NWB schema. These neurodata types are the building blocks for NWB files and are often used together in specific configurations (see the tutorials for concrete patterns)

MatNWB generates MATLAB classes representing these neurodata types from the NWB core schema or any available neurodata extension. These neurodata type classes ensure that data is always conforming to the NWB specification, and provide a structured interface for reading, writing, and validating NWB files. When you read an NWB file, MatNWB maps each group and dataset in the file to the corresponding MATLAB class, so you interact with neurodata types directly in MATLAB code. When you write or export, MatNWB serializes your MATLAB objects back to NWB-compliant HDF5 files, preserving the schema and relationships between types.

The main categories of types you will work with

• Metadata: subject and session descriptors (e.g., Subject, NWBFile, Device).

• Containers/wrappers: organize related data (e.g., ProcessingModule).

• Time series: sampled data over time (e.g., TimeSeries, ElectricalSeries).

• Tables: columnar metadata or data (e.g., DynamicTable).

• Helpers: Helper types for common patterns like references, links, and data I/O.

Common questions you may encounter (and where to find answers)

• Which data type should I use?

  • Check out the Neurodata Types section in the NWB Overview Docs

  • Refer to the Core neurodata types index for the full list of MatNWB types.

• Where in the file should a type go?

  • Check out the section Anatomy of an NWB file in the NWB Overview Docs

  • Follow the domain tutorials for canonical placements (e.g., Extracellular ephys, Calcium imaging, Intracellular ephys).

• How do I name neurodata types when adding to sets?

  • Refer to the Naming Conventions section of the NWB Inspector docs.

• What properties are required and how do I set them?

  • Each class page lists required fields and their types (e.g., TimeSeries).

  • Refer to the Best Practices for more detailed recommendations.

• How do I add lab‑specific data?

  • See Neurodata Extensions for guides to install published NDX or to generate classes from your own namespace specification.

Important caveats when working with MatNWB:

• MATLAB vs. NWB dimension order : The dimensions of datasets (arrays) in MatNWB are represented in the opposite order relative to the NWB specification. For example, in NWB the time dimension of a TimeSeries is the first dimension of a dataset, whereas in MatNWB, it will be the last dimension of the dataset. See the mappings and examples in the Data dimensions section for a detailed explanation.

• NWB schema versions: When reading an NWB file, MatNWB will dynamically build class definitions for neurodata types from schemas that are embedded in the file. This ensures that the file is always represented correctly according to the schema version (and extensions) that was used when creating the file. However, the generated type classes will take the place of previously existing classes (i.e generated from different NWB versions), and therefore it is not recommended to work with NWB files of different NWB versions simultaneously.

Related resources

• NWB Overview documentation

• Python API (PyNWB)

• Object‑oriented programming refresher (MATLAB): https://www.mathworks.com/help/matlab/object-oriented-programming.html

• Share/discover data: DANDI Archive

Cite MatNWB

If MatNWB contributes to your work, please see Citing MatNWB.