Neurodata Without Borders Extracellular Electrophysiology Tutorial
About This Tutorial
This tutorial describes storage of hypothetical data from extracellular electrophysiology experiments in NWB for the following data categories:
- Raw voltage recording
- Local field potential (LFP) and filtered electrical signals
- Spike times
Before You Begin
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. Important: The dimensions of timeseries data in MatNWB should be defined in the opposite order of how it is defined in the nwb-schemas. In NWB, time is always stored in the first dimension of the data, whereas in MatNWB time should be stored in the last dimension of the data. This is explained in more detail here: MatNWB <-> HDF5 Dimension Mapping. Setting 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 these required fields along with any additional metadata. In MatNWB, arguments are specified using MATLAB's keyword argument pair convention, where each argument name is followed by its value. 'session_description', 'mouse in open exploration',...
'identifier', 'Mouse5_Day3', ...
'session_start_time', datetime(2018, 4, 25, 2, 30, 3, 'TimeZone', 'local'), ...
'timestamps_reference_time', datetime(2018, 4, 25, 3, 0, 45, 'TimeZone', 'local'), ...
'general_experimenter', 'Last Name, First 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
Electrode Information
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 an electrodes table, which is also a DynamicTable. electrodes has several required fields: x, y, z, impedance, location, filtering, and electrode_group. The electrodes table references a required ElectrodeGroup, which is used to represent a group of electrodes. Before creating an ElectrodeGroup, you must define a Device object. The fields description, manufacturer, model_number, model_name, and serial_number are optional, but recommended. device = types.core.Device(...
'description', 'A 12-channel array with 4 shanks and 3 channels per shank', ...
'manufacturer', 'Array Technologies', ...
'model_number', 'PRB_1_4_0480_123', ...
'model_name', 'Neurovoxels 0.99', ...
'serial_number', '1234567890' ...
% Add device to nwb object
nwb.general_devices.set('array', device);
Electrodes Table
Since this is a DynamicTable, we can add additional metadata fields. We will be adding a "label" column to the table. numChannels = numShanks * numChannelsPerShank;
electrodesDynamicTable = types.hdmf_common.DynamicTable(...
'colnames', {'location', 'group', 'group_name', 'label'}, ...
'description', 'all electrodes');
shankGroupName = sprintf('shank%d', iShank);
electrodeGroup = types.core.ElectrodeGroup( ...
'description', sprintf('electrode group for %s', shankGroupName), ...
'location', 'brain area', ...
'device', types.untyped.SoftLink(device) ...
nwb.general_extracellular_ephys.set(shankGroupName, electrodeGroup);
for iElectrode = 1:numChannelsPerShank
electrodesDynamicTable.addRow( ...
'location', 'unknown', ...
'group', types.untyped.ObjectView(electrodeGroup), ...
'group_name', shankGroupName, ...
'label', sprintf('%s-electrode%d', shankGroupName, iElectrode));
electrodesDynamicTable.toTable() % Display the table
ans = 12×5 table
| | id | location | group | group_name | label |
|---|
| 1 | 0 | 'unknown' | 1×1 ObjectView | 'shank1' | 'shank1-electrode1' |
|---|
| 2 | 1 | 'unknown' | 1×1 ObjectView | 'shank1' | 'shank1-electrode2' |
|---|
| 3 | 2 | 'unknown' | 1×1 ObjectView | 'shank1' | 'shank1-electrode3' |
|---|
| 4 | 3 | 'unknown' | 1×1 ObjectView | 'shank2' | 'shank2-electrode1' |
|---|
| 5 | 4 | 'unknown' | 1×1 ObjectView | 'shank2' | 'shank2-electrode2' |
|---|
| 6 | 5 | 'unknown' | 1×1 ObjectView | 'shank2' | 'shank2-electrode3' |
|---|
| 7 | 6 | 'unknown' | 1×1 ObjectView | 'shank3' | 'shank3-electrode1' |
|---|
| 8 | 7 | 'unknown' | 1×1 ObjectView | 'shank3' | 'shank3-electrode2' |
|---|
| 9 | 8 | 'unknown' | 1×1 ObjectView | 'shank3' | 'shank3-electrode3' |
|---|
| 10 | 9 | 'unknown' | 1×1 ObjectView | 'shank4' | 'shank4-electrode1' |
|---|
| 11 | 10 | 'unknown' | 1×1 ObjectView | 'shank4' | 'shank4-electrode2' |
|---|
| 12 | 11 | 'unknown' | 1×1 ObjectView | 'shank4' | 'shank4-electrode3' |
|---|
nwb.general_extracellular_ephys_electrodes = electrodesDynamicTable;
Links
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 a construct that enables linking one neurodata type to another, allowing a neurodata type to reference another within the NWB file. Recorded Extracellular Signals
Referencing Electrodes
In order to create our ElectricalSeries object, we first need to reference a set of rows in the electrodes table to indicate which electrode (channel) each entry in the electrical series were recorded from. 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, using row indices. electrode_table_region = types.hdmf_common.DynamicTableRegion( ...
'table', types.untyped.ObjectView(electrodesDynamicTable), ...
'description', 'all electrodes', ...
'data', (0:length(electrodesDynamicTable.id.data)-1)');
Raw Voltage Data
Now create an ElectricalSeries object to hold acquisition data collected during the experiment. raw_electrical_series = types.core.ElectricalSeries( ...
'starting_time', 0.0, ... % seconds
'starting_time_rate', 30000., ... % Hz
'data', randn(numChannels, 3000), ... % nChannels x nTime
'electrodes', electrode_table_region, ...
This is the voltage data recorded directly from our electrodes, so it goes in the acquisition group.
nwb.acquisition.set('ElectricalSeries', raw_electrical_series);
Processed Extracellular Electrical Signals
LFP
LFP refers to data that has been low-pass filtered, typically below 300 Hz. This data may also be downsampled. Because it is filtered and potentially resampled, it is categorized as processed data. LFP data would also be stored in an ElectricalSeries. To help data analysis and visualization tools know that this ElectricalSeries object represents LFP data, we store it inside an LFP object and 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' in the behavior tutorial 
lfp_electrical_series = types.core.ElectricalSeries( ...
'starting_time', 0.0, ... % seconds
'starting_time_rate', 1000., ... % Hz
'data', randn(numChannels, 100), ... nChannels x nTime
'filtering', 'Low-pass filter at 300 Hz', ...
'electrodes', electrode_table_region, ...
lfp = types.core.LFP('ElectricalSeries', lfp_electrical_series);
ecephys_module = types.core.ProcessingModule(...
'description', 'extracellular electrophysiology');
ecephys_module.nwbdatainterface.set('LFP', lfp);
nwb.processing.set('ecephys', ecephys_module);
Other Types of Filtered Electrical Signals
If your acquired data is filtered for frequency ranges other than LFP—such as Gamma or Theta—you can store the result in an ElectricalSeries and encapsulate it within a FilteredEphys object instead of the LFP object. filtered_data = randn(50, 12); % 50 time points, 12 channels
filtered_data = permute(filtered_data, [2, 1]); % permute timeseries for matnwb
% Create an ElectricalSeries object
filtered_electrical_series = types.core.ElectricalSeries( ...
'description', 'Data filtered in the theta range', ...
'data', filtered_data, ...
'electrodes', electrode_table_region, ...
'filtering', 'Band-pass filtered between 4 and 8 Hz', ...
'starting_time', 0.0, ...
'starting_time_rate', 200.0 ...
% Create a FilteredEphys object and add the filtered electrical series
filtered_ephys = types.core.FilteredEphys();
filtered_ephys.electricalseries.set('FilteredElectricalSeries', filtered_electrical_series);
% Add the FilteredEphys object to the ecephys module
ecephys_module.nwbdatainterface.set('FilteredEphys', filtered_ephys);
Decomposition of LFP Data into Frequency Bands
In some cases, you may want to further process the LFP data and decompose the signal into different frequency bands for additional downstream analyses. You can then store the processed data from these spectral analyses using a DecompositionSeries object. This object allows you to include metadata about the frequency bands and metric used (e.g., power, phase, amplitude), as well as link the decomposed data to the original TimeSeries signal the data was derived from. In this tutorial, the examples for FilteredEphys and DecompositionSeries may appear similar. However, the key difference is that DecompositionSeries is specialized for storing the results of spectral analyses of timeseries data in general, whereas FilteredEphys is defined specifically as a container for filtered electrical signals. Note: When adding data to a DecompositionSeries, the data argument is assumed to be 3D where the first dimension is time, the second dimension is channels, and the third dimension is bands. As mentioned in the beginning of this tutorial, in MatNWB the data needs to be permuted because the dimensions are written to file in reverse order (See the dimensionMapNoDataPipes tutorial) % Define the frequency bands of interest (in Hz):
band_names = {'theta'; 'beta'; 'gamma'};
band_stdev = [2; 4.5; 12.5];
band_limits = [band_mean - 2*band_stdev, band_mean + 2*band_stdev];
% The bands should be added to the DecompositionSeries as a dynamic table
bands = table(band_names, band_mean, band_stdev, band_limits, ...
'VariableNames', {'band_name', 'band_mean', 'band_stdev', 'band_limits'})
bands = 3×4 table
| | band_name | band_mean | band_stdev |
|---|
| 1 | 2 |
|---|
| 1 | 'theta' | 8 | 2 | 4 | 12 |
|---|
| 2 | 'beta' | 21 | 4.5000 | 12 | 30 |
|---|
| 3 | 'gamma' | 55 | 12.5000 | 30 | 80 |
|---|
bands = util.table2nwb( bands );
% Generate random phase data for the demonstration.
phase_data = randn(50, 12, numel(band_names)); % 50 samples, 12 channels, 3 frequency bands
phase_data = permute(phase_data, [3,2,1]); % See dimensionMapNoDataPipes tutorial
decomp_series = types.core.DecompositionSeries(...
'starting_time', 0.0, ... % seconds
'starting_time_rate', 1000.0, ... % Hz
'source_channels', electrode_table_region, ...
'source_timeseries', lfp_electrical_series);
% Add decomposition series to ecephys module
ecephys_module.nwbdatainterface.set('theta', decomp_series);
Spike Times and Extracellular Events
Sorted Spike Times
Spike times are stored in a Units table, a specialization of the DynamicTable class. The default Units table is located at /units in the HDF5 file. You can add columns to the Units table just like you did for electrodes and trials (see convertTrials). Here, we generate some random spike time data and populate the table. Note: Spike times of a Units table should be sorted in ascending order. spike_times = cell(1, num_cells);
spike_times{iShank} = sort( rand(1, randi([16, 28])), 'ascend');
spike_times
spike_times = 1×10 cell
| | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
|---|
| 1 | 1×19 double | 1×16 double | 1×17 double | 1×28 double | 1×28 double | 1×25 double | 1×28 double | 1×19 double | 1×27 double | 1×24 double |
|---|
Ragged Arrays
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 table. These indexed columns have two components, the VectorData object that holds the data and the VectorIndex 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. For more information about ragged arrays, we refer you to the "Ragged Array Columns" section of the dynamic table tutorial. 
[spike_times_vector, spike_times_index] = util.create_indexed_column(spike_times);
nwb.units = types.core.Units( ...
'colnames', {'spike_times'}, ...
'description', 'units table', ...
'spike_times', spike_times_vector, ...
'spike_times_index', spike_times_index ...
nwb.units.toTable()
ans = 10×2 table
| | id | spike_times |
|---|
| 1 | 1 | 19×1 double |
|---|
| 2 | 2 | 16×1 double |
|---|
| 3 | 3 | 17×1 double |
|---|
| 4 | 4 | 28×1 double |
|---|
| 5 | 5 | 28×1 double |
|---|
| 6 | 6 | 25×1 double |
|---|
| 7 | 7 | 28×1 double |
|---|
| 8 | 8 | 19×1 double |
|---|
| 9 | 9 | 27×1 double |
|---|
| 10 | 10 | 24×1 double |
|---|
Unsorted Spike Times
While the Units table is used to store spike times and waveform data for spike-sorted, single-unit activity, you may also want to store spike times and waveform snippets of unsorted spiking activity. This is useful for recording multi-unit activity detected via threshold crossings during data acquisition. Such information can be stored using SpikeEventSeries objects. % In the SpikeEventSeries the dimensions should be ordered as
% [num_events, num_channels, num_samples].
% Define spike snippets: 20 events, 3 channels, 40 samples per event.
spike_snippets = rand(20, 3, 40);
% Permute spike snippets (See dimensionMapNoDataPipes tutorial)
spike_snippets = permute(spike_snippets, [3,2,1])
% Create electrode table region referencing electrodes 0, 1, and 2
shank0_table_region = types.hdmf_common.DynamicTableRegion( ...
'table', types.untyped.ObjectView(electrodesDynamicTable), ...
'description', 'shank0', ...
% Define spike event series for unsorted spike times
spike_events = types.core.SpikeEventSeries( ...
'data', spike_snippets, ...
'timestamps', (0:19)', ... % Timestamps for each event
'description', 'events detected with 100uV threshold', ...
'electrodes', shank0_table_region ...
% Add spike event series to NWB file acquisition
nwb.acquisition.set('SpikeEvents_Shank0', spike_events);
Detected Events
If you need to store the complete, continuous raw voltage traces, along with unsorted spike times, you should store the traces in ElectricalSeries objects in the acquisition group, and use the EventDetection class to identify the spike events in your raw traces. % Create the EventDetection object
event_detection = types.core.EventDetection( ...
'detection_method', 'thresholding, 1.5 * std', ...
'source_electricalseries', types.untyped.SoftLink(raw_electrical_series), ...
'source_idx', [1000; 2000; 3000], ...
'times', [.033, .066, .099] ...
% Add the EventDetection object to the ecephys module
ecephys_module.nwbdatainterface.set('ThresholdEvents', event_detection);
Storing Spike Features (e.g Principal Components)
NWB also provides a way to store features of spikes, such as principal components, using the FeatureExtraction class. % Generate random feature data (time x channel x feature)
features = rand(3, 12, 4); % 3 time points, 12 channels, 4 features
features = permute(features, [3,2,1]); % reverse dimension order for matnwb
% Create the FeatureExtraction object
feature_extraction = types.core.FeatureExtraction( ...
'description', {'PC1', 'PC2', 'PC3', 'PC4'}, ... % Feature descriptions
'electrodes', electrode_table_region, ... % DynamicTableRegion referencing the electrodes table
'times', [.033; .066; .099], ... % Column vector for times
% Add the FeatureExtraction object to the ecephys module (if required)
ecephys_module.nwbdatainterface.set('PCA_features', feature_extraction);
Choosing NWB-Types for Electrophysiology Data (A Summary)
As mentioned above, ElectricalSeries objects are meant for storing electrical timeseries data like raw voltage signals or processed signals like LFP or other filtered signals. In addition to the ElectricalSeries class, NWB provides some more classes for storing event-based electropysiological data. We will briefly discuss them here, and refer the reader to the API documentation and the section on Extracellular Physiology in the "NWB Format Specification" for more details on using these objects. For storing unsorted spiking data, there are two options. Which one you choose depends on what data you have available. If you need to store complete and/or continuous raw voltage traces, you should store the traces with ElectricalSeries objects as acquisition data, and use the EventDetection class for identifying the spike events in your raw traces. If you do not want to store the entire raw voltage traces, only the waveform ‘snippets’ surrounding spike events, you should use SpikeEventSeries objects. The results of spike sorting (or clustering) should be stored in the top-level Units table. The Units table can hold just the spike times of sorted units or, optionally, include additional waveform information. You can use the optional predefined columns waveform_mean, waveform_sd, and waveforms in the Units table to store individual and mean waveform data. Writing the NWB File
nwbExport(nwb, 'ecephys_tutorial.nwb')
Reading NWB Data
Data arrays are read passively from the file. Calling TimeSeries.data 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', 'ignorecache');
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.
nwb2.processing.get('ecephys'). ...
nwbdatainterface.get('LFP'). ...
electricalseries.get('ElectricalSeries'). ...
data(1:5, 1:10)
0.1819 -0.2465 0.6816 1.3952 0.4457 0.1669 1.5490 1.6078 0.3151 0.9513
-0.0743 -0.1750 1.0688 -1.5109 -0.9000 -0.2888 -0.7786 1.6026 -0.3550 -0.1655
-0.2510 -2.4219 1.8592 -1.4672 0.6872 0.3096 1.0881 0.7342 -1.4525 -0.6090
-0.4141 1.2920 0.9821 1.0815 1.3037 0.1962 1.4406 0.3505 1.0192 -0.4334
1.5505 1.1969 0.0549 1.2202 0.2010 -0.1484 0.0228 -0.4535 -0.5823 -0.0484
% 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.
nwb.units.getRow(1).spike_times{1}
0.0232
0.1476
0.2262
0.4041
0.4174
0.4817
0.4834
0.5164
0.5493
0.5517
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:
