How does MATLAB open exported data?

This is an advanced solution, and requires general knowledge of MATLAB terminology. 


By default, LabChart data is exported in the MATLAB Standard File format (*.mat), which can be opened with MATLAB v4.0 and later. This format efficiently handles large data files, supports multi-rate data, and can be reopened and plotted in MATLAB with the LabChart.m file located in the LabChart Welcome Center.


Exporting as MATLAB in LabChart produces a .mat file that contains vectors in matrix form. The matrices are arranged  depending on whether the parameter is given on a per channel, per block, or per channel and block basis. The columns (vertical) represent blocks, and rows (horizontal) represent channels.


servlet.ImageServer?id=015w0000002ulWY&oid=00D20000000HncM


The data is contained in a row vector. All the samples from each block and channel are combined and sequentially output to the Data Vector by first stepping through the channels, then through the blocks. Empty channels will be skipped over to keep the size small and increase performance for large amounts of data.


The data start and end positions of each block and channel in the Data Vector are contained in separate matrices called "datastart" and "dataend". Because columns represent blocks and rows represent channels, each block and channel can be addressed in the data vector. For example, the start and end points of Channel 1 in Block 2 are datastart(1, 2) and dataend(1, 2), which can be used to extract the data in MATLAB using:

data12 = data(datastart(1,2) : dataend(1,2));

servlet.ImageServer?id=015w0000002ulcH&oid=00D20000000HncM


The indices refer to closed intervals, i.e. for the example in the figure above, data(501) and data(550) are the first and last data point of this block.

The number of samples is:

numsamples = dataend(j,i) – datastart(j,i) + 1,


so that in the example above:

numsamples = 550 - 501 + 1

= 50 samples in Block 2 of Channel 1.


Empty channels in a block will be skipped over and have "datastart" and "dataend" values that don’t refer to an available index. For an empty channel, datastart = dataend = -1. By design, the last entry in "dataend" will be the length of the data vector.


The vector "blocktimes" is a row vector that contains the time of day at which the first sample in each block was recorded."blocktimes" is saved in MATLAB's preferred format, as a serial date number. Other time parameters, such as time of day and date can be derived for each data point using the tick or sample rate. In the case that only a selection is exported to MATLAB, "blocktimes" refers to the first sample in the selection, and then the first sample of every subsequent block in the selection, if the selection spans multiple blocks. "blocktimes" is not actively used by the LabChart.m file.


The vector "tickrate" is a column vector containing the tick rate (maximum sample rate) of each block. It is a vector rather than a matrix. Only active channels are eligible to provide the tick rate.


The sampling rate of each block and channel in the Data Vector are contained in the "samplerate" matrix in units of samples per second. Empty channels in a block will have a sampling rate of 0.


The "unittextmap" matrix contains indices that refer to the content of the "unittext" vector. Where units across blocks are the same, each string is only exported once. The dimensions of the "unittextmap"matrix are the same as "datastart"or "dataend"– it has the dimensions of ‘number of channels’ by ‘number of blocks’.

NOTE: that a displayed unit of ‘mV’ will be shown as ‘V’ – all units are exported in base units (i.e. without prefixes). Empty channels in a block will have -1 in the "unittextmap" maxtrix.

servlet.ImageServer?id=015w0000002ulcl&oid=00D20000000HncM


The "titles" vector is a column vector containing strings of each Channel name. Empty channels will still have a channel title.

servlet.ImageServer?id=015w0000002uld0&oid=00D20000000HncM





The Range Min/Max of each block and channel in the Data Vector are contained in the "rangemin" matrix and the "rangemax" matrix in the same units as defined in the "unittext" vector. Empty channels in a block will have range values of 0.


The Scale Units/Offset of each block and channel in the Data Vector are contained in the "scaleunits" matrix and the "scaleoffset" matrix. These matrices will only be exported for 16-bit signed integer data.

LabChart.m converts the 16-bit data into the Chart View units, by adding the "scaleoffset" to the data or range, and then multiplying with the appropriate "scaleunits" factor. Empty channels in a block will have scaleunits = scaleoffset = 0.


Information about comments is conveyed in the "com" matrix and the "comtext" column vector.The "com"matrix has the dimension of ‘number of comments’ by five. Each comment corresponds to one row in the matrix and they are sorted by time from start of file or selection.

1.Comment channel: "ComChan" is the channel each comment is located in. -1 means the comment is in all channels.
2.Comment block: "ComBlock" is the block number the comment was made in. A comment can be made in a block that contains no data (empty channel).
3.Comment tick position: "ComTickPos" gives the position of the comment in the block in reference to the tick rate of the block. The tick rate corresponds to the highest sampling rate in a block. For example, if you had three channels recorded at 1k /s, 2k /s and 500 sample/s, then the tick rate would be 2k /s and the comment positions would be at 2k /s ticks.
4.Comment type: "ComType" is the type of each comment. Currently, we distinguish between user comments (ComType = 1) which include preset comments, and Event Markers (ComType=2) used by Cyclic Measurements. Various extensions and modules also produce Event Markers. You can choose which types of comments to export in the Export as MATLAB dialogue. 
5.Comment Text Map: The "ComTextMap" column of the com matrix contains indices that refer to entries in the column vector "comtext". "comtext" holds every string only once, and can therefore have less rows than the "com" matrix.

In MATLAB entries of the "com" matrix can be used to selectively extract comments, such as: User comments only, All Channel comments only, or only those comments containing the word ‘Stimulator’ using string comparison.

servlet.ImageServer?id=015w0000002uldF&oid=00D20000000HncM





For applications where high levels of data integrity are required, we provide some additional information so that data in channels that was sampled at different rates can be lined up more accurately.


In the multi-rate case, it is possible for a block to start part way through a low rate sample, i.e. the start of the first sample in the channel can be earlier than the start of the block. The matrix "firstsampleoffset" contains a number typically between 0 and 1 indicating this fractional offset in units of samples. It indicates how long after the start of the first sample in the block the block actually started. For example, if the value in "firstsampleoffset" is 0.9, it means the block started 90% of the way through the first sample stored in that channel for that block.

This will typically be visible when one channel was sampled at a very slow, and another at a very high rate. In some PowerLabs, very slow sample rates are made up of an average of faster points, so the notion of a sample length applies.

When data is exported at the up-sampled rate (tickrate), this matrix is still exported but contains zeros only. When a selection is saved, "firstsampleoffset" is always zero. In this case, the data is padded out both to the front and end.

This feature is not used in the supplied LabChart.m script.


The following parameters exist for empty channel, but are set to specific values in some cases

  • tickrate
  • samplerate =  0
  • datastart and dataend indices -1
  • unittextmap = -1
  • rangemax = rangemin = 0

Empty channels can have comments (all channels or specific to the empty channel) and titles.