This is a collaborative space. In order to contribute, send an email to maximilien.chaumon@icm-institute.org
On any page, type the letter L on your keyboard to add a "Label" to the page, which will make search easier.

Typical fieldtrip structures

Owned by mariana.baborebelo (Unlicensed)
Last updated: Oct 09, 2018 by Maximilien CHAUMON
4 min read

 

Prerequisite

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

Goal of this tutorial

Sometimes you may want to create a FieldTrip-compatible data structure from scratch, 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.

Here we will describe the fields of the most common data structures in FieldTrip (defined over space and time, but similar with frequency domain).

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.

Required fields in a variable containing continuous data:

- 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)

 

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:

- 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)

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


4. Averaged data across trials

Output from ft_timelockanalysis.

Fields in the variable containing the averaged data structure:

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

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

- 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 avg field, string ('chan_time': meaning the first dimension of avg is channels, the second dimension is time).

 

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)

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)

 

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.

Consider deleting the .cfg field from your data structure, if you have little disk space!


8. Checking format of input data

To check if your data structure is in the correct FieldTrip format, you can use the function ft_checkdata.


Related articles