Neurodata Without Borders Extracellular Electrophysiology Tutorial

Table of Contents

This tutorial

Create fake data for a hypothetical extracellular electrophysiology experiment. The types of data we will convert are:
It is recommended to first work through the Introduction to MatNWB tutorial, which demonstrates installing MatNWB and creating an NWB file with subject information, animal position, and trials, as well as writing and reading NWB files in MATLAB.

Set up the NWB file

An NWB file represents a single session of an experiment. Each file must have a session_description, identifier, and session start time. Create a new NWBFile object with those and additional metadata. For all MatNWB functions, we use the Matlab method of entering keyword argument pairs, where arguments are entered as name followed by value.
nwb = NwbFile( ...
'session_description', 'mouse in open exploration',...
'identifier', ['Mouse5_Day3'], ...
'session_start_time', datetime(2018, 4, 25, 2, 30, 3), ...
'general_experimenter', 'My Name', ... % optional
'general_session_id', 'session_1234', ... % optional
'general_institution', 'University of My Institution', ... % optional
'general_related_publications', 'DOI:10.1016/j.neuron.2016.12.011'); % optional
nwb =
NwbFile with properties: nwb_version: '2.5.0' file_create_date: [] general_source_script_file_name: [] identifier: 'Mouse5_Day3' session_description: 'mouse in open exploration' session_start_time: 2018-04-25T02:30:03.000000-04:00 timestamps_reference_time: [] acquisition: [0×1 types.untyped.Set] analysis: [0×1 types.untyped.Set] general: [0×1 types.untyped.Set] general_data_collection: [] general_devices: [0×1 types.untyped.Set] general_experiment_description: [] general_experimenter: 'My Name' general_extracellular_ephys: [0×1 types.untyped.Set] general_extracellular_ephys_electrodes: [] general_institution: 'University of My Institution' general_intracellular_ephys: [0×1 types.untyped.Set] general_intracellular_ephys_experimental_conditions: [] general_intracellular_ephys_filtering: [] general_intracellular_ephys_intracellular_recordings: [] general_intracellular_ephys_repetitions: [] general_intracellular_ephys_sequential_recordings: [] general_intracellular_ephys_simultaneous_recordings: [] general_intracellular_ephys_sweep_table: [] general_keywords: [] general_lab: [] general_notes: [] general_optogenetics: [0×1 types.untyped.Set] general_optophysiology: [0×1 types.untyped.Set] general_pharmacology: [] general_protocol: [] general_related_publications: 'DOI:10.1016/j.neuron.2016.12.011' general_session_id: 'session_1234' general_slices: [] general_source_script: [] general_stimulus: [] general_subject: [] general_surgery: [] general_virus: [] intervals: [0×1 types.untyped.Set] intervals_epochs: [] intervals_invalid_times: [] intervals_trials: [] processing: [0×1 types.untyped.Set] scratch: [0×1 types.untyped.Set] stimulus_presentation: [0×1 types.untyped.Set] stimulus_templates: [0×1 types.untyped.Set] units: []

Extracellular electrophysiology

In order to store extracellular electrophysiology data, you first must create an electrodes table describing the electrodes that generated this data. Extracellular electrodes are stored in a electrodes table, which is also a DynamicTable. electrodes has several required fields: x, y, z, impedence, location, filtering, and electrode_group.

Electrode table

Since this is a DynamicTable, we can add additional metadata fields. We will be adding a "label" column to the table.
Here, we also demonstate another method for creating DynamicTables, by first creating a MATLAB native Table object and then calling util.table2nwb to convert this Table object into a DynamicTable.
nshanks = 4;
nchannels_per_shank = 3;
variables = {'x', 'y', 'z', 'imp', 'location', 'filtering', 'group', 'label'};
tbl = cell2table(cell(0, length(variables)), 'VariableNames', variables);
device = types.core.Device(...
'description', 'the best array', ...
'manufacturer', 'Probe Company 9000' ...
nwb.general_devices.set('array', device);
for ishank = 1:nshanks
electrode_group = types.core.ElectrodeGroup( ...
'description', ['electrode group for shank' num2str(ishank)], ...
'location', 'brain area', ...
'device', types.untyped.SoftLink(device) ...
nwb.general_extracellular_ephys.set(['shank' num2str(ishank)], electrode_group);
group_object_view = types.untyped.ObjectView(electrode_group);
for ielec = 1:nchannels_per_shank
electrode_label = ['shank' num2str(ishank) 'elec' num2str(ielec)];
tbl = [...
tbl; ...
{5.3, 1.5, 8.5, NaN, 'unknown', 'unknown', group_object_view, electrode_label} ...
tbl = 12×8 table
15.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank1elec1'
25.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank1elec2'
35.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank1elec3'
45.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank2elec1'
55.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank2elec2'
65.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank2elec3'
75.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank3elec1'
85.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank3elec2'
95.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank3elec3'
105.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank4elec1'
115.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank4elec2'
125.30001.50008.5000NaN'unknown''unknown'1×1 ObjectView'shank4elec3'
electrode_table = util.table2nwb(tbl, 'all electrodes');
nwb.general_extracellular_ephys_electrodes = electrode_table;


In the above loop, we create ElectrodeGroup objects. The electrodes table then uses an ObjectView in each row to link to the corresponding ElectrodeGroup object. An ObjectView is an object that allow you to create a link from one neurodata type referencing another.


Voltage data are stored in ElectricalSeries objects. ElectricalSeries is a subclass of TimeSeries specialized for voltage data. In order to create our ElectricalSeries object, we will need to reference a set of rows in the electrodes table to indicate which electrodes were recorded. We will do this by creating a DynamicTableRegion, which is a type of link that allows you to reference specific rows of a DynamicTable, such as the electrodes table, by row indices.
Create a DynamicTableRegion that references all rows of the electrodes table.
electrode_table_region = types.hdmf_common.DynamicTableRegion( ...
'table', types.untyped.ObjectView(electrode_table), ...
'description', 'all electrodes', ...
'data', (0:height(tbl)-1)');
Now create an ElectricalSeries object to hold acquisition data collected during the experiment.
electrical_series = types.core.ElectricalSeries( ...
'starting_time', 0.0, ... % seconds
'starting_time_rate', 30000., ... % Hz
'data', randn(12, 3000), ...
'electrodes', electrode_table_region, ...
'data_unit', 'volts');
This is the voltage data recorded directly from our electrodes, so it goes in the acquisition group.
nwb.acquisition.set('ElectricalSeries', electrical_series);


Local field potential (LFP) refers in this case to data that has been downsampled and/or filtered from the original acquisition data and is used to analyze signals in the lower frequency range. Filtered and downsampled LFP data would also be stored in an ElectricalSeries. To help data analysis and visualization tools know that this ElectricalSeries object represents LFP data, store it inside an LFP object, then place the LFP object in a ProcessingModule named 'ecephys'. This is analogous to how we stored the SpatialSeries object inside of a Position object and stored the Position object in a ProcessingModule named 'behavior' earlier.
electrical_series = types.core.ElectricalSeries( ...
'starting_time', 0.0, ... % seconds
'starting_time_rate', 1000., ... % Hz
'data', randn(12, 100), ...
'electrodes', electrode_table_region, ...
'data_unit', 'volts');
lfp = types.core.LFP('ElectricalSeries', electrical_series);
ecephys_module = types.core.ProcessingModule(...
'description', 'extracellular electrophysiology');
ecephys_module.nwbdatainterface.set('LFP', lfp);
nwb.processing.set('ecephys', ecephys_module);

Spike times

Ragged arrays

Spike times are stored in another DynamicTable of subtype Units. The default Units table is at /units in the HDF5 file. You can add columns to the Units table just like you did for electrodes and trials. Here, we generate some random spike data and populate the table.
num_cells = 10;
firing_rate = 20;
spikes = cell(1, num_cells);
for ishank = 1:num_cells
spikes{ishank} = rand(1, randi([16, 28]));
spikes = 1×10 cell
11×17 double1×18 double1×16 double1×21 double1×25 double1×27 double1×25 double1×16 double1×23 double1×27 double
Spike times are an example of a ragged array- it's like a matrix, but each row has a different number of elements. We can represent this type of data as an indexed column of the units DynamicTable. These indexed columns have two components, the vector data object that holds the data and the vector index object that holds the indices in the vector that indicate the row breaks. You can use the convenience function util.create_indexed_column to create these objects.
[spike_times_vector, spike_times_index] = util.create_indexed_column(spikes);
nwb.units = types.core.Units( ...
'colnames', {'spike_times'}, ...
'description', 'units table', ...
'id', types.hdmf_common.ElementIdentifiers( ...
'data', int64(0:length(spikes) - 1) ...
), ...
'spike_times', spike_times_vector, ...
'spike_times_index', spike_times_index ...

Write the file

nwbExport(nwb, 'ecephys_tutorial.nwb')

Reading NWB data

Data arrays are read passively from the file. Calling does not read the data values, but presents an HDF5 object that can be indexed to read data. This allows you to conveniently work with datasets that are too large to fit in RAM all at once. load with no input arguments reads the entire dataset:
nwb2 = nwbRead('ecephys_tutorial.nwb');
nwb2.processing.get('ecephys'). ...
nwbdatainterface.get('LFP'). ...
electricalseries.get('ElectricalSeries'). ...

Accessing data regions

If all you need is a data region, you can index a DataStub object like you would any normal array in MATLAB, as shown below. When indexing the dataset this way, only the selected region is read from disk into RAM. This allows you to handle very large datasets that would not fit entirely into RAM.
% read section of LFP
nwb2.processing.get('ecephys'). ...
nwbdatainterface.get('LFP'). ...
electricalseries.get('ElectricalSeries'). ...
data(1:5, 1:10)
ans = 5×10
0.5938 -0.4753 -0.5075 0.3021 -0.2914 0.0077 1.2020 0.0749 0.6444 0.0383 0.0893 0.8383 2.0713 0.6750 0.2827 2.7530 1.1147 -0.3998 0.2750 -1.3381 -0.2557 0.7498 -0.1889 -0.5439 -2.0241 -0.3986 0.4520 -1.0113 0.2583 -0.3130 -0.3645 -0.1192 0.9762 0.1519 0.5527 -0.7931 -0.6456 1.4499 0.4875 -2.0865 1.5314 1.6395 1.8022 0.8296 1.2646 1.6529 -0.2080 1.4211 -0.4894 0.4756
% You can use the getRow method of the table to load spike times of a specific unit.
% To get the values, unpack from the returned table.
ans = 17×1
0.6501 0.3082 0.2028 0.9918 0.8831 0.4310 0.0796 0.8529 0.9656 0.1383

Learn more!

See the API documentation to learn what data types are available.

MATLAB tutorials

Python tutorials

See our tutorials for more details about your data type:
Check out other tutorials that teach advanced NWB topics: