Data structures used by FieldTrip
High-level FieldTrip functions expect input data as a MATLAB structure in a specific format, and produce output data as a structure in a specific format. These structures are documented in the following 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. This means that 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 data structure is updated to the expected format prior to the function doing its work. 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 data 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 pieces of the dimord matches a corresponding metadata field.
element | 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 pieces of the dimord do not have a corresponding metadata field, such as rpt
(for repetitions, i.e. trials) or comp
for components. These dimensions correspond in general 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. This is sometimes used to represent data elements of different size (e.g., spike timings). This is also used to to represent data that 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 source-level connectivity metric that is frequency resolved.