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 in the LabChart Welcome Center.
Exporting as MATLAB in LabChart produces a .mat file containing matrix vectors. The matrices are arranged depending on whether the parameter is given per channel, per block, or per channel and block basis. The columns (vertical) represent blocks, and the rows (horizontal) represent channels.
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 and 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));
The indices refer to closed intervals, i.e., for the example in the figure above, data(501) and data(550) are this block's first and last data point.
The number of samples is:
numsamples = dataend(j,i) – datastart(j,i) + 1,
So, 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. If only a selection is exported to MATLAB, "blocktimes" refers to the first sample in the selection. 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 each block's tick rate (maximum sample rate). 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: 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.
The "titles" vector is a column vector containing strings of each Channel name. Empty channels will still have a channel title.
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 multiplying it with the appropriate "scaleunits" factor. Empty channels in a block will have scaleunits = scaleoffset = 0.
Comment information 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 is sorted by time from the start of the 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 about the tick rate of the block. The tick rate corresponds to the highest sampling rate in a block. For example, if you recorded three channels at 1k /s, 2k /s, and 500 sample/s, 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), including 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 fewer rows than the "com" matrix. |
In MATLAB, entries of the "com" matrix can be used to extract comments, such as User comments selectively, All Channel comments only, or only those comments containing the word 'Stimulator' using string comparison.
For applications with high levels of data integrity, we provide some additional information so that data in channels sampled at different rates can be lined up more accurately.
In the multi-rate case, a block can 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 shows how long after the start of the first sample in the block, the block 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 is sampled at a very slow and another at a very high rate. In some PowerLabs, prolonged sample rates comprise 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 to the front and end.
This feature is not used in the supplied LabChart.m script.
The following parameters exist for empty channels 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.
For further technical assistance with this or any other issue, please contact ADInstruments Technical Support by clicking HERE.