Prerequisite

You need Matlab and fieldtrip installed (see here for how to install fieldtrip properly).

Goal of this tutorial

The goal of this tutorial is to describe the fields of the most common data structures in fieldtrip (defined over space and time, but similar with frequency domain).

Sometimes you may want to create from scratch a fieldtrip-compatible data structure, in order to use fieldtrip functions on your data. You have to make sure you have all the fields in the correct format, so that fieldtrip functions can work properly.

Note that in some cases, you do not need to define all fields present in original fieldtrip data structures.

Step-by-step guide

1. Continuous data

Output from ft_preprocessing.

Fields in a variable containing continuous data:

- hdr: header, structure with the following fields: label, nChans, Fs, grad, elec, nSamples, nSamplesPre, nTrials, chantype, chanunit

- label: labels of channels, cell of strings (nChans x 1)

- time: time of each data point, cell containing the time vector (1 x nTimePoints)

- trial: data values, cell containing the data matrix (nChans x nTimePoints)

- fsample: frequency sampling, double (1 x 1)

- sampleinfo: first and last sample of the data, vector (1 x 2)

- grad: information about MEG channels, structure with the following fields: balance, chanori, chanpos, chantype, chanunit, coilori, coilpos, coordsys, label, tra, type, unit

- elec: information about other channels (EEG), structure with the following fields: chanpos, chantype, chanunit, elecpos, label, unit

- cfg: information about previous fieldtrip commands executed, structure.

2. Event structure

Output from ft_read_event.

Events are typically saved in a big data structure, containing one structure per event. The structure of each event contains the following fields:

- type: name of the event, string

- value: value of the corresponding trigger, double (1x1) or empty

- sample: sample number of the current event, double (1x1)

- duration: duration of the current event, double (1x1) or empty

- offset: offset of the current event, double (1x1) or empty

3. Epoched data

Output from ft_redefinetrial.

Fields in the variable containing the epoched data structure:

- hdr: header, structure

- trial: trial by trial data, cell (1 x nTrials) with nTrials matrices with the data of each trial (nChans x nTimePoints)

- time: time of each data point of each trial, cell (1 x nTrials) with nTrials vectors with the timings of each trial (1 x nTimePoints)

- fsample: frequency sampling, double (1 x 1)

- grad: information about MEG channels, structure

- label: labels of the channels, cell of strings (nChans x 1)

- sampleinfo: first and last sample of the data, vector (1 x 2)

- cfg: information about previous fieldtrip commands executed, structure.

4. Averaged data across trials

Output from ft_timelockanalysis.

Fields in the variable containing the averaged data structure:

- avg: averaged data, matrix (nChans x nTimePoints)

- var: variance over trials, matrix (nChans x nTimePoints)

- time: time of each data point (relative to the epoch), vector (1 x nTimePoints)

- dof: number of input arguments, matrix (nChans x nTimePoints)

- label: labels of the channels, cell of strings (nChans x 1)

- dimord: dimensions of the avg field, string ('chan_time': meaning the first dimension of avg is channels, the second dimension is time).

- grad: information about MEG channels, structure (see continuous data structure)

- cfg: information about previous fieldtrip commands executed, large structure.

5. Averaged data over subjects (grand average)

Output from ft_timelockgrandaverage.

Fields in the variable containing the grand average data structure:

if the option 'keepindividual' was selected:

- individual: contains the ERPs from all subjects, matrix (nSubjs x nChans x nTimePoints)

if the option 'keepindividual' was not selected:

- avg: contains the grand average ERP over all subjects, matrix (nChans x nTimePoints)

- var: contains the variance of the grand average ERP across subjects, matrix (nChans x nTimePoints)

- dof: number of input arguments, matrix (nChans x nTimePoints)

Other fields:

- time: time of each data point (relative to the epoch), vector (1 x nTimePoints)

- label: labels of the channels, cell of strings (nChans x 1)

- dimord: dimensions of the individual/avg field, string ('subj_chan_time' when the keepindividual option was selected, 'chan_time' when the keepindividual option was not selected)

- cfg: information about previous fieldtrip commands executed, large structure.

6. Output of the cluster-based permutation test

Output from ft_timelockstatistics, for a dependent samples T-test with clustering based on the maximal sum of t-values.

Fields in the variable containing the statistical results:

- prob: Monte-Carlo p-values for each data point, matrix (nChans x nTimePoints)

- posclusters: information about each positive candidate cluster, clusters ordered based on their Monte-Carlo p-value (ascending order), one structure for each candidate cluster with the fields: prob (Monte-Carlo p-value of the cluster), clusterstat (cluster statistics, ex: sum of t-values within the cluster), stddev, cirange (range of the confidence interval).

- posclusterslabelmat: indicates to which positive cluster each data point belongs to (0: data point does not belong to any positive cluster, 1: data point belongs to the first positive cluster, 2: data point belongs to the second positive cluster…), matrix (nChans x nTimePoints)

- posdistribution: distribution of statistics obtained at each permutation (ex: max sum of t-values), vector (1 x numrandomization)

- negclusters: same as posclusters but for negative candidate clusters

- negclusterslabelmat: same as posclusterslabelmat but for negative candidate clusters

- negdistribution: same as posdistribution but for negative candidate clusters

- cirange: for each data point indicates the range of the confidence interval of the corresponding candidate cluster, matrix (nChans x nTimePoints)

- mask: flags data points belonging to a cluster showing a significant result, logical (nChans x nTimePoints)

- stat: indicates the uncorrected t-value obtained for the statistical test applied to each data point, matrix (nChans x nTimePoints)

- ref: t-values obtained for the last randomization (??), matrix (nChans x nTimePoints)

- dimord: dimensions of the matrices reported (prob, stat, mask...), string (for example: 'chan_time' indicates that the first dimension corresponds to space and the second dimension corresponds to time)

- label: labels of the channels, cell of strings (nChans x 1)

- time: time of each point, vector (1 x nTimePoints)

- cfg: information about previous fieldtrip commands executed, large structure.

7. Important note about the .cfg field

The cfg field contains the history of the fieldtrip commands executed on the current data. It appears in almost all data structure generated with fieldtrip.

This field can grow quickly and reach a really large size.

Related articles