Quickstart: Read and write NWB files

Goal

This tutorial walks you step-by-step through creating, writing, and reading a minimal NWB file with MatNWB. It is designed to be a short, learning-oriented introduction.

Prerequisites

  • MATLAB R2019b or later

  • MatNWB installed and added to your MATLAB path

Introduction

Creating an NWB file involves three main steps:

  1. Create an NwbFile object with required metadata

  2. Add neurodata types (time series, processed data, etc.)

  3. Export the file using the nwbExport() function

Step 1 — Create a minimal NWB file

An NWB file always needs three required fields:

  • identifier (unique ID)

  • session_description (short text summary)

  • session_start_time (timestamp of the session start)

nwb = NwbFile( ...
    'identifier', 'quickstart-demo-20250411T153000Z', ...
    'session_description', 'Quickstart demo session', ...
    'session_start_time', datetime(2025,4,11,15,30,0,'TimeZone','UTC'));

Step 2 — Add a TimeSeries

We’ll add a short synthetic signal sampled at 10 Hz for 1 second using the types.core.TimeSeries neurodata type.

t = 0:0.1:0.9;        % 10 time points
data = sin(2*pi*1*t); % simple sine wave

ts = types.core.TimeSeries( ...
    'data', data, ...
    'data_unit', 'arbitrary', ...
    'starting_time', 0.0, ...
    'starting_time_rate', 10.0);

nwb.acquisition.set('DemoSignal', ts);

Note

MatNWB uses MATLAB array ordering when writing to HDF5. For multi-dimensional time series, the time dimension should be the last dimension of the MATLAB array. See the Data Dimensions section in the “MatNWB important considerations” page.

Step 3 — Write the File

nwbExport(nwb, 'quickstart_demo.nwb', 'overwrite');

This writes the NWB file to your current working directory.

Verify — Read the File Back

nwb_in = nwbRead('quickstart_demo.nwb');

Confirm that the DemoSignal was written and read back:

ts_in = nwb_in.acquisition.get('DemoSignal');

% Data is a DataStub (lazy loading). Index like an array or load fully:
first_five = ts_in.data(1:5);     % reads a slice
all_data   = ts_in.data.load();   % reads all values

That’s it!

You have written and read an NWB file with MatNWB.

Next steps