Loading data generated by CMOS-MEA software

Starting from version 2, CMOS-MEA-Control generates HDF5 files with the extensions .cmcr and .cmce, while CMOS-MEA-Tools generates HDF5 files with the extensions .cmtr and .cmte. All these files can be imported into Matlab with the command

data = McsHDF5.McsData('SOME_CMOS_MEA_FILE');

where 'SOME_CMOS_MEA_FILE' is the name of one of the HDF5 files mentioned above.

Up to this point, only the metadata has been read from the file. The actual data within the datasets will be loaded as soon as you try to access the datasets, for example in a plot function. The data is organized as follows within the data structure:

• Top-level: General information and a cell array of McsRecording objects:

data

• Each recording is stored in its individual cell: `

data.Recording{1}

• Each recording can contain different data sources which may or may not be present in the file:

data.Recording{1}.Acquisition
data.Recording{1}.FilterTool
data.Recording{1}.SpikeExplorer
data.Recording{1}.NetworkExplorer
data.Recording{1}.SpikeSorter
data.Recording{1}.UnknownDataSources

Each of the data sources has a typical data structure which will be explained below. The UnknownDataSources array contains all data sources that did not match any of the known data sources. The toolbox can't fully support these data sources.

Most streams and data sources have an 'Info' field which contains metadata about the stream or data source:

data.Recording{1}.SpikeSorter.Info

Some data sources also have a 'Settings' field that contains the settings that were used in the software for this particular tool:

data.Recording{1}.SpikeSorter.Settings

Acquisition Data Source

Data files generated by CMOS-MEA-Control with extension .cmcr will usually contain the recorded raw data, as well as different analog, event and spike streams in their Acquisition data source. The actual contents of the file depend on the settings used when recording the file. These contents are arranged as cell arrays of streams:

data.Recording{1}.Acquisition.ChannelStream
data.Recording{1}.Acquisition.EventStream
data.Recording{1}.Acquisition.SensorStream
data.Recording{1}.Acquisition.SpikeStream

The contents of the ChannelStream, EventStream and SensorStream arrays are described in more detail in the DataManager help page of the Toolbox (see the Tutorial wiki page).

For files generated by CMOS-MEA-Tools, the Acquisition source will usually just be a link to the .cmcr file from which the results have been generated.

SpikeStream and SpikeExplorer

The SpikeStream array of the Acquisition data source and the SpikeExplorer data source both hold spike streams objects. These contain the results of channel-wise spike detection:

data.Recording{1}.Acquisition.SpikeStream{1}
data.Recording{1}.SpikeExplorer

The spikes are stored in the SpikeData field. They will be loaded from the file when the SpikeData field is accessed for the first time:

data.Recording{1}.Acquisition.SpikeStream{1}.SpikeData

FilterTool

The FilterTool data source contains information about the filter pipeline defined in the CMOS-MEA-Tools software. The details of each filter can be found in the Pipeline field:

data.Recording{1}.FilterTool.Pipeline{1}

NetworkExplorer

The NetworkExplorer data source holds the results of the Network Explorer Tool in CMOS-MEA-Tools. The STAs are stored in its STAData field and read from the file only when the STAData field is accessed for the first time:

data.Recording{1}.NetworkExplorer.STAData

Metadata about the STAs can be found in the STAInfos field:

data.Recording{1}.NetworkExplorer.STAInfos

For each channel/unit, there are two additional data sets available in the NetworkExplorer data source: Spikes and STAStdDev. These are mainly relevant for axon tracking in the STA. The Spikes field represents the results of a channel-wise spike detection in the STA and the STAStdDev field contains the standard deviations of each sensor in the STA which is used to compute the threshold for the spike detection. Both are read from the file the first time the respective field is accessed and have Info fields storing their metadata:

data.Recording{1}.NetworkExplorer.Spikes
data.Recording{1}.NetworkExplorer.SpikeInfos
data.Recording{1}.NetworkExplorer.STAStdDev
data.Recording{1}.NetworkExplorer.STAStdDevInfos

Reading a subset of STAs from the NetworkExplorer

In order to save memory, it is possible to load only a subset of STAs from the file instead of all of them. To achieve this, one needs to take care to not directly access the STAData field as this would trigger loading them from the field. Instead, one has to load first the metadata and then use the readPartialSTAData function:

data = McsHDF5.McsData('SOME_CMOS_MEA_FILE');
cfg = [];
cfg.sta = [2 4 8];
stas = data.Recording{1}.NetworkExplorer.readPartialSTAData(cfg);

'stas' will be a McsCmosNetworkExplorerSource object, containing the 2nd, 4th and 8th STA of the original data. In order to find out which indices to use in the cfg.sta array, you can access the STAInfos field which contains the metadata for each STA and is loaded from the beginning:

data.Recording{1}.NetworkExplorer.STAInfos

SpikeSorter

The SpikeSorter data source holds the results of the Spike Sorter Tool in CMOS-MEA-Tools. The UnitInfos field contains some details about each extracted unit, such as its location on the chip and the extracted quality measures:

data.Recording{1}.SpikeSorter.UnitInfos

It also contains a projection matrix that transforms raw data to the source signals of the units. For more information on how to perform this projection, please consult the CMOS-MEA software manual:

data.Recording{1}.SpikeSorter.ProjectionMatrix

Each extracted unit has its own entry in the UnitEntities array:

data.Recording{1}.SpikeSorter.UnitEntities{1}

For each unit, this data structure stores information about the extracted (spike) peaks, STAs of channels in its vicinity, the trace of its source signal and the coefficients for the projection from raw data to its source signal:

data.Recording{1}.SpikeSorter.UnitEntities{1}.Peaks
data.Recording{1}.SpikeSorter.UnitEntities{1}.RoiSTAs
data.Recording{1}.SpikeSorter.UnitEntities{1}.Source
data.Recording{1}.SpikeSorter.UnitEntities{1}.Unmixing

With the exception of the 'Unmixing' field, the contents of these fields are loaded from the file only when the field is accessed for the first time. Metadata about these fields can be found in the respective Info fields (PeaksInfo, RoiSTAsInfo, ...)

Plotting

Simple plot functions exist for the streams in the Acquisition data source:

plot(data.Recording{1}.Acquisition.ChannelStream{1},[])
plot(data.Recording{1}.Acquisition.EventStream{1},[])
plot(data.Recording{1}.Acquisition.SensorStream{1},[])
plot(data.Recording{1}.Acquisition.SpikeStream{1},[])

If for example the event stream and the spike streams have not been accessed before, their data is loaded during the execution of the respective plot function.

Plot functions can also be accessed at Acquisition, Recording or top level, in order to get an overview over all streams in the file/recording:

plot(data.Recording{1}.Acquisition,[]) plot(data.Recording{1},[]) plot(data,[])

If the second parameter of the plot function is empty, the default parameters are used for plotting. Otherwise, one can specify configuration structures for more fine-grained plotting. For example, the following commands will plot channels 1 and 2 of the second analog stream:

cfg = [];
cfg.channel = [1 2];
plot(data.Recording{1}.Acquisition.ChannelStream{2},cfg);

Each plot function has its own set of options, so you need to check the individual help functions for the specifics:

help McsHDF5.McsEventStream.plot

You can specify these configuration options also in higher level plot functions to achieve the same thing:

cfg = [];
cfg.acq.analog{2}.channel = [1 2];
plot(data.Recording{1},cfg);
cfg = [];
cfg.conf.acq.analog{2}.channel = [1 2];
plot(data,cfg);

You can also specify additional options in the plot function. These are forwarded to the underlying MATLAB plotting functions. The following command produces a time series plot of the first analog stream with thick dashed red lines:

plot(data.Recording{1}.Acquisition.ChannelStream{1},cfg,'--r','LineWidth',5);

Interactive Plots

Plot functions for the NetworkExplorer data source and the SpikeSorter data source produce interactive figures, i.e.

plot(data.Recording{1}.NetworkExplorer,[])
plot(data.Recording{1}.SpikeSorter,[])

The STAExplorer data source plot produces a Heat Map that visualizes the location of each detected sta and the realtive number of contributing sweeps. Upon clicking an non-active sensor on the Heat Map, labels for all units may be switched between visible and invisible. Clicking an active sensor opens a separate figure with corresponding detailed information. Namely, three graphics appear:

• the signals of all sensors in a defined neighborhood of the clicked sensor
• the signal of the clicked sensor
• an animation showing the STA across the entire sensor array over time

The animation may started/paused by clicking into it. A bar in the magnified signal plot (middle) shows the timely position of the animation within the recording. By clicking into the signal, the current animation frame may be changed.

For more detailed information on configuration options please refer to the specific function help

help McsHDF5.McsCmosNetworkExplorerSource.plot

The SpikeSorter data source plot visualizes the entire sensor array. Several components of the visualization, including the grid, labels, etc., are configurable prior to calling the plot function. However, they may be adjusted via the interface as needed. Upon clicking a unit, the plot function for the corresponding SpikeSorter unit is called.

For more detailed information on configuration options please refer to the specific function help

help McsHDF5.McsCmosSpikeSorterSource.plot