Tags: development

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.

1. A data structure can have a single dimord field; in that case the dimord refers to the most important data field in the structure.
2. A data structure can have a one or multiple xxxdimord fields, where xxx refers to the data parameter. For example powspctrmdimord to document powspctrm, and cohspctrmdimord to document cohspctrm.
3. 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.