To ensure that the functions implemented in the FieldTrip toolbox can be mixed and matched, we always try to keep a small number of data structures.

The general principle is that a data structure should be as small as possible, but nevertheless contain enough information to fully understand its contents.

Information on the data in a structure should not be replicated. If there is replication, there would be the risk of one function might use one version of the information whereas another function would use the other version. Changing the data in a structure should only require changing the information once.

Wherever possible, use one of the existing data representations. If needed, these can be extended with additional information. The use of an existing data structure allows the reuse of existing functions for plotting and further analysis. E.g. you can do freqanalysis on the output of componentanalysis, because the IC timeseries are represented just as raw data that comes out of preprocessing.

If you give a structure as input to an existing function, the type of the input structure will be determined using the datatype helper-function.

A FieldTrip data structure consists at least of numeric data specific to that particular datatype, and of descriptive fields which are needed to interpret the data. The different datatypes and their features are listed below:

The raw datatype is sensor level time domain data typically obtained after calling ft_definetrial and ft_preprocessing. It contains the following fields:

          label: {307x1 cell}        the channel labels (e.g. 'MRC13')
           time: {1x10 cell}         the timeaxis [1xN double] per trial (n=10)
          trial: {1x10 cell}         the numeric data [307xN double] per trial (n=10)
           
            hdr: [1x1 struct]        the full header information of the original dataset on disk
        fsample: 600                 the sampling frequency
     sampleinfo: [10x2 double]       begin- and endsample of every trial relative to the recording
           grad: [1x1 struct]        information about the sensor array (for EEG-data it is called elec)
            cfg: [1x1 struct]        configuration structure used by the invoking FieldTrip function 
            

This contains the sensor level frequency domain data obtained after a call to ft_freqanalysis or ft_freqgrandaverage. The power can represent the complete trial, or it can be estimated (e.g. using wavelets) for multiple time points within each trial, resulting in a time-frequency representation (TFR).

The frequency representation of the data contains the following fields:

          dimord: 'chan_freq'          defines how the numeric data should be interpreted
       powspctrm: [307x120 double]     the numeric data (in this example it contains power values 
                                         for 307 channels x 120 frequencies)
           label: {307x1 cell}         the channel labels (e.g. 'MRC13')
            freq: [1x120 double]       the frequencies expressed in Hz 
             
           grad: [1x1 struct]          information about the sensor array (for EEG-data it is called elec)
            cfg: [1x1 struct]          configuration structure used by the invoking FieldTrip function 
            

The time-frequency data representation contains the following fields:

          dimord: 'chan_freq_time'     defines how the numeric data should be interpreted
       powspctrm: [307x45x600 double]  the numeric data (in this example it contains power values 
                                         for 307 channels x 45 frequencies x 600 timepoints)
           label: {307x1 cell}         the channel labels (e.g. 'MRC13')
            freq: [1x45 double]        the frequencies in Hz
            time: [1x600 double]       the timepoints in seconds
             
           grad: [1x1 struct]          information about the sensor array (for EEG-data it is called elec)
            cfg: [1x1 struct]          configuration structure used by the invoking FieldTrip function 
            

This contains sensor level data, time-locked to time point 0, either as an average over trials or represented as single trials in a 3-D array. It is obtained after a call to ft_timelockanalysis or ft_timelockgrandaverage. Optionally, it can contain the estimated covariance matrix (again averaged over trials or for each trial in a 3-D array). It contains the following fields:

          dimord: 'chan_time'       defines how the numeric data should be interpreted
             avg: [307x600 double]  the numeric data (in this example it contains the average values
                                      of the activity for 307 channels x 600 timepoints)  
           label: {307x1 cell}      the channel labels (e.g. 'MRC13')
            time: [1x600 double]    the timepoints in seconds
           
             var: [307x600 double]  the variance of the activity for 307 channels x 600 timepoints
             dof: [307x600 double]  the number of observations over which the avg and var were computed

            grad: [1x1 struct]      information about the sensor array (for EEG-data it is called elec)
             cfg: [1x1 struct]      configuration structure used by the invoking FieldTrip function 
                   

This contains the spatial topograpies of the components and the component timecourses and is obtained from a call to ft_componentanalysis. It is represented just as raw data, except that an additional matrix is added describing the spatial topographies of the components. The original channel labels are replaced by strings like 'ica001', 'ica002', … After ft_componentanalysis, you can call any function that can work with raw data, e.g. ft_timelockanalysis or ft_freqanalysis. The ft_topoplotIC function can be used to visualize the component topographies and the ft_databrowser to look at the component timecourses.

          label: {307x1 cell}        the component labels (e.g. 'ica001')
           time: {1x10 cell}         the timeaxis [1xN double] per trial (n=10)
          trial: {1x10 cell}         the numeric data [307xN double] per trial (n=10)
           topo: [307x307 double]    NxN matrix with the component topographies in each column
      topolabel: {307x1 cell}        the channel labels
           
            hdr: [1x1 struct]        the header information
        fsample: 600                 the sampling frequency
           grad: [1x1 struct]        information about the sensor array (for EEG-data it is called elec)
            cfg: [1x1 struct]        configuration structure used by the invoking FieldTrip function 
            

This represents data that corresponds to locations in 3-D space. Compared to volume data, this representation is more general and also supports irregular source locations, e.g. a folded cortical sheet. It is always possible to convert volume data to source data. If the source data represents a regular 3-D grid (i.e. like a box), it is also possible to convert source data back to volume data. An example of a source structure obtained after performing a frequency domain source reconstruction using ft_sourceanalysis is shown here:

          pos: [6732x3 double]       positions at which the source activity could have been estimated
       inside: [1x3415 double]       indices to the positions at which the source activity is actually estimated
      outside: [1x3317 double]       indices to the positions at which the source activity has not been estimated

          dim: [xdim ydim zdim]      if the positions are described as a 3D regular grid, this contains the 
                                       dimensionality of the 3D volume
          vol: [1x1 struct]          volume conductor model
    cumtapcnt: [10x1 double]         information about the number of tapers per original trial
         freq: 6,                    the frequency of the oscillations at which the activity is estimated
       method: 'singletrial'         specifies how the data is represented
          cfg: [1x1 struct]          configuration structure used by the invoking FieldTrip function
        trial: [10x1 struct]         contain the numeric data, each structure source.trial(x) can look like this:
        
               source.trial(1)
               
                 pow: [6732x1 double]    Npositions x 1 array containing the power at each source location for the given trial
               noise: [6732x1 double]    Npositions x 1 array containing an estimate of the noise at each source location
                 csd: {6732x1 cell}      Npositions x 1 cell-array containing the source cross-spectral density
                                           at each source location  

This is the new definition of a data structure that represents data corresponding to locations in 3-D space. In the future this will replace the 'old style' definition. It has been designed to be more flexible and more easy to manage. Also, exchange with other software toolboxes and code development should be facilitated by this. An example of such a source structure obtained after performing a frequency domain source reconstruction is shown here:

          pos: [6732x3 double]       positions at which the source activity could have been estimated
       inside: [1x3415 double]       indices to the positions at which the source activity is actually estimated
      outside: [1x3317 double]       indices to the positions at which the source activity has not been estimated

          dim: [xdim ydim zdim]      if the positions can be described as a 3D regular grid, this contains the 
                                       dimensionality of the 3D volume
          vol: [1x1 struct]          volume conductor model
    cumtapcnt: [120x1 double]        information about the number of tapers per original trial
         freq: 6                     the frequency of the oscillations at which the activity is estimated
       method: 'singletrial'         specifies how the data is represented
          cfg: [1x1 struct]          configuration structure used by the invoking FieldTrip function
          pow: [6732x120 double]     the numeric data
    powdimord: 'pos_rpt'             defines how the numeric data has to be interpreted, in this case
                                       6732 dipole positions x 120 observations

This represents data on a regular 3-D grid, like an anatomical MRI, a functional MRI. It can also represent a source reconstructed estimate of the activity measured with MEG in case the source reconstruction is done on a regular 3-D dipole grid (like a box).

          dim: [181 217 181]         the dimensionality of the 3D volume
    transform: [4x4 double]          affine transformation matrix mapping voxel coordinates to another coordinate
                                       system
      anatomy: [181x217x181 double]  numeric data, in this case anatomical information
          pow: [181x217x181 double]  numeric data, in this case functional data
      

This contains sensor level MVAR model data in the time domain obtained by ft_mvaranalysis.

         dimord: 'chan_chan_lag'     defines how the numeric data should be interpreted 
          label: {3x1 cell}          the channel labels
         coeffs: [3x3x5 double]      numeric data (MVAR model coefficients 3 channels x 3 channels x 5 time lags)
       noisecov: [3x3 double]        more numeric data (covariance matrix of the noise residuals 3 channels x 3 channels)
            dof: 500                 
    fsampleorig: 200
            cfg: [1x1 struct]

This contains sensor level MVAR model data in the frequency domain obtained by processing the output of ft_mvaranalysis with ft_freqanalysis.

        label: {3x1 cell}
         freq: [1x101 double]
       dimord: 'chan_chan_freq'
     transfer: [3x3x101 double]
    itransfer: [3x3x101 double]
     noisecov: [3x3 double]
    crsspctrm: [3x3x101 double]
          dof: 500
          cfg: [1x1 struct]
          

This is characterised as a sparse point-process, i.e. each neuronal firing is only represented as the time at which the firing happened. Optionally, the spike waveform can also be represented. Using the spike waveform, the neuronal firing events can be sorted into their single units. Spike data is obtained using ft_read_spike to read it from a Plexon, Neuralynx or other animal electrophysiology system file format containing spikes.

        label: {'chan1', 'chan2', 'chan3'}                            the channel labels
    timestamp: {[1x993 uint64]    [1x423 uint64]   [1x3424 uint64]}   timestamp in arbitrary units, depends 
                                                                        on the acquisition system
     waveform: {[32x993 double]   [32x433 double]  [32x3424 double]}  spike waveform, here described with 32 samples
          hdr: [1x1 struct]

The example above contains three spike channels, each with varying numbers of detected spikes. The timestamps of the spikes are represented, with their waveforms (32 samples per waveform). This type of representation can be seen as raw spike data, because there is no reference to the experimental trials.

The spike data representation can also represent spike timepoints in relation to the experimental trials:

        label: {'chan1'  'chan2'  'chan3'}                             the channel labels
         time: {[50481x1 double]  [50562x1 double]  [50537x1 double]}  the time in the trial for each 
                                                                         spike (in seconds) 
        trial: {[50481x1 double]  [50562x1 double]  [50537x1 double]}  the trial in which each spike was observed
    trialtime: [100x2 double]                                          the begin- and end-time of each 
                                                                         trial (in seconds)
          cfg: [1x1 struct]