Data structures used by FieldTrip
High-level FieldTrip functions usually expect input data as a MATLAB structure in a specific format, and produce output data. The data is represented as MATLAB structures which are documented in the following helper functions:
- ft_datatype_comp
- ft_datatype_dip
- ft_datatype_freq
- ft_datatype_headmodel
- ft_datatype_mvar
- ft_datatype_parcellation
- ft_datatype_raw
- ft_datatype_segmentation
- ft_datatype_sens
- ft_datatype_source
- ft_datatype_spike
- ft_datatype_timelock
- ft_datatype_volume
Checking and converting
Besides documenting the data structures, these ft_datatype_xxx
functions also check the internal consistency of the structures and - where needed - update the data structures to the latest standard. So if a user loads a data structure from an old .mat
file on disk and feeds it into a newer version of a FieldTrip function, the structure is updated to the expected format prior to the function starting to work on it. This works by each FieldTrip function calling ft_checkdata at the start of the function, and ft_checkdata
calling the corresponding ft_datatype_xxx
function.
Dimord
FieldTrip data structures have “data” fields and “metadata” fields. The metadata fields make the data interpretable.
Some of the “data” fields are for example:
- avg
- trial
- powspctrm
- cohspctrm
- prob
- stat
Some of the “metadata” fields that describe the data are:
- label
- labelcmb
- time
- freq
- pos
To document the data fields unambiguously, the structure can include a dimord
field that specifies the order of the dimensions, and that links each of the dimensions to the corresponding metadata field.
- A data structure can have a single
dimord
field; in that case the dimord refers to the most important data field in the structure. - A data structure can have a one or multiple
xxxdimord
fields, where xxx refers to the data parameter. For examplepowspctrmdimord
to documentpowspctrm
, andcohspctrmdimord
to documentcohspctrm
. - It is also allowed that a data structure does not have an explicit dimord. In that case FieldTrip will - where needed - use heuristics to determine how the data field is to be interpreted.
To determine what the dimensions of a data field represent, FieldTrip functions use the private getdimord function. To determine their size, they use the private getdimsiz function. Another private function that plays a role for managing the dimord field is fixdimord.
Most of the elements of the dimord match a corresponding metadata field.
dimord element | corresponding metadata field |
---|---|
time |
time |
freq |
freq |
chan |
label |
chancmb |
labelcmb |
refchan |
label |
pos |
pos |
ori |
n/a, dipole orientations |
subj |
n/a, subjects |
rpt |
n/a, repetitions/trials |
rpttap |
n/a, repetitions and tapers |
comp |
n/a, components |
Some elements of the dimord do not have a corresponding metadata field, such as rpt
(for repetitions, i.e. trials) or comp
for components. These dimensions in general correspond to a numbered list from 1 to N.
Data as a N-dimensional array
Most data fields are represented as a N-dimensional numeric array; the dimord is in that case a simple concatenation of the corresponding strings like xxx_yyy_zzz
. For example chan_time
or rpttap_chan_freq_time
.
Data as a cell-array
Some data fields are represented as a cell-array to represent matrices of different size (e.g., trials prior to averaging, or spike timings). Cell-arrays are also used when the data is sparse and partially empty (e.g., leadfields and beamformer filters). For these type of data structures the cell-array is always the outer-most (first) dimension and the corresponding dimension is described as {xxx}
, i.e. with curly brackets. For a multi-dimensional cell-array this could be {xxx_yyy_zzz}
.
The subsequent dimensions of the arrays that are contained in each cell are described as before, subsequently the dimord can be for example {pos}_chan_ori
(for leadfields) or {pos_pos}_freq
for a frequency-resolved source-level connectivity metric.