Getting started with CTF data

The reading of CTF data is supported using a set of low-level functions located in the fieldtrip/external/ctf directory, which are written by Dr. Harold Wilson and courtesy of MISL. These low-level functions are not used for clinical studies and the user assumes all risk with their use. Although the functions originate from MISL, these are included in in FieldTrip under the explicit agreement that MISL does not support these functions. If you find bugs or have sugegstions for improvements, please contact the FieldTrip developers and not MISL.

An alternative implementation for reading the CTF data is available in the older read_ctf_xxx functions, which can be used by specifying 'ctf_old' as headerformat and dataformat.

The following types of CTF data can be read and used in FieldTrip:

• MEG/EEG and AUX data: *.res4, *.meg4, *.1_meg4, *.2_meg4, etc.
• event information: *.meg4, ClassFile.cls, MarkerFile.mrk
• single sphere and multi-sphere volume conduction models: *.hdm
• anatomical MRI: *.mri

This page explains how to get started reading and using each of these file types in FieldTrip.

MEG datasets recorded with CTF acquisition software are written in a xxx.ds folder (with xxx the name of your dataset). This folder contains, among others, the xxx.meg4 file which contains the data of your recording, and the xxx.res4 file which contains the header information.

You should not store any scripts or mat files in the xxx.ds folder. When analyzing your CTF MEG data with FieldTrip, it is good practice to keep three separate folders:

1. a folder with the raw recorded data (i.e., containing your xxx.ds dataset)
2. a folder that contains your matlab scripts
3. a folder that contains the matlab/FieldTrip data that you want to save

To get started, you should add the FieldTrip main directory to your path, and execute the fieldtripdefs function, which sets the defaults and configures up the minimal required path settings (see the faq):

addpath <full_path_to_fieldtrip>
fieldtripdefs

To analyze your CTF MEG data in FieldTrip, you would usually start by calling high-level functions such as ft_definetrial or ft_preprocessing (see the tutorial documentation). These functions read the raw MEG data by calling low-level functions such as ft_read_header and ft_read_data. The header and data are in different files, and the data itself can be split over multiple 2GB files. You specify the combination of files as a dataset, i.e. with the directory

 cfg.dataset = 'Subject01.ds';

FieldTrip automatically figures out what the actual header and datafiles are.

To get started with reading your CTF MEG data into FieldTrip, it might be a good check to call the low-level reading functions directly. As an example for the code below, we will use the tutorial dataset, which can be downloaded from ftp://ftp.fcdonders.nl/pub/fieldtrip/tutorial/Subject01.zip.

The ft_read_header function reads header information and represents it in a common data-independent format. It takes the dataset filename as input. Alternatively, you can directly specify the header file.

To read the header from the tutorial dataset, use

hdr = ft_read_header('Subject01.ds')

or

hdr = ft_read_header('Subject01.ds/Subject01.res4')

This should return a header structure with the following elements:

hdr = 

             Fs: 300           % sampling frequency
         nChans: 187           % number of channels
       nSamples: 900           % number of samples per trial
    nSamplesPre: 300           % number of pre-trigger samples in each trial
        nTrials: 266           % number of trials
          label: {187x1 cell}  % cell-array with labels of each channel
           grad: [1x1 struct]  % gradiometer structure
           orig: [1x1 struct]  % additional header information

Make sure that the header information is correctly read.

The ft_read_data function reads the CTF MEG data and represents it in a common data-independent format. It takes the dataset filename as input. Alternatively, you can directly specify the data file.

To read the data from the tutorial dataset, use

dat = ft_read_data('Subject01.ds');

or

dat = ft_read_data('Subject01.ds/Subject01.meg4');

This returns a 3-D matrix of size Nchans*Nsamples*Ntrials: 187x900x266 in case of the tutorial data, which is a trial-based dataset. In case of continuous data, this function returns a 2-D matrix of size Nchans*Nsamples. Additional options should be specified in key-value pairs (see ft_read_data). When only the filename is specified, all data in the dataset will be read. To only read the first 3 trials from channels 5-9, use:

dat = ft_read_data('Subject01.ds', 'begtrial', 1, 'endtrial', 3, 'chanindx', [5:9]);

This returns a 3-D matrix of size Nchans*Nsamples*Ntrials: 5x900x3.

You can explicitly specify the data format (also see below), e.g.

dat = ft_read_data('Subject01.ds', 'dataformat', 'ctf_ds');

After checking that the low-level reading functions successfully read your CTF dataset, you are ready to start working with the high-level FieldTrip functions, such as ft_preprocessing. To preprocess the tutorial data, use:

cfg=[];
cfg.dataset = 'Subject01.ds';
data = ft_preprocessing(cfg)

This should return the following data structure:

data = 

        hdr: [1x1 struct]    % header information
      label: {187x1 cell}    % channel labels
      trial: {1x266 cell}    % data (Nchans*Nsamples) for each trial
       time: {1x266 cell}    % time axis for each trial
    fsample: 300             % sampling frequency
       grad: [1x1 struct]    % gradiometer structure
        cfg: [1x1 struct]    % the configuration used for processing the data

With cfg.continuous = 'yes' or 'no' you can specify whether the file contains continuous data. The default is determined automatically. Data that is measured pseudo-continuously should be treated as cfg.continuous = 'yes'.

For more preprocessing options and information on how to define trials, see the tutorial documentation.

The default low-level reading functions for the MEG data are the functions supplied by CTF, which are located in the fieldtrip/external/ctf directory. There is also an old implementation of the reading functions, which will be used if you specify

cfg.headerformat = 'ctf_old'
cfg.dataformat   = 'ctf_old'

in ft_preprocessing or in any of the other FieldTrip functions that reads the data from disk. Other dataformat options include 'ctf_ds', 'ctf_meg4' and 'ctf_res4'.

The old 64-channel CTF datasets are not supported in the native CTF reading functions. However, they do seem to work with the old reading functions. So if you specify the headerformat and the dataformat as 'ctf_old', you can analyze the old 64-channel data.

Usually, you would call ft_definetrial to select pieces of data around those events in the data that interest you, either using a generic definition or using your own “trialfun”. The trialfunction calls the low-level reading function ft_read_event. The ft_read_event function reads event information and represents it in a common data-independent format. It takes the dataset filename as input. Alternatively, you can directly specify the data file.

ft_read_event reads the triggers from the trigger channels in the MEG dataset (*.meg4), and if available classified trials from the classification file (ClassFile.cls) and markers from the marker file (MarkerFile.mrk), and combines all the available events into one structure. For more information on events, triggers and trials refer to the faq.

To read the events from the tutorial data, use

event = ft_read_event('Subject01.ds')

This automatically reads the events from the trigger channels, from the class file and from the marker file and combines them in a single uniform representation. On the tutorial dataset it returns the following event structure:

event = 

1343x1 struct array with fields:
    type
    sample
    value
    offset
    duration

To access the first event, use

>> event(1)

ans = 
        type: 'trial'
      sample: 1
       value: []
      offset: -300
    duration: 900

Single sphere and multi sphere headmodels can be prepared using the CTF software MRIViewer and the CTF command-line utility localSpheres. Both CTF programs will write the headmodel to a *.hdm file. The *.hdm headmodel files can be read using ft_read_vol and visualized using ft_headmodelplot. Alternative to using the CTF software, you can also use the FieldTrip functions like ft_prepare_localspheres or ft_prepare_singleshell to create MEG headmodels.

For example, to read and plot the single sphere model produced with CTF software for the tutorial data, use

% read in the single sphere model produced with CTF software
ctf_ss = ft_read_vol('Subject01.hdm');
 
% plotting the headmodel
hdr = ft_read_header('Subject01.ds');

cfg             = [];
cfg.grad        = hdr.grad;
cfg.headshape   = 'Subject01.shape';
cfg.vol         = ctf_ss;
cfg.inwardshift = [];

figure
ft_headmodelplot(cfg);

For more information on reading, creating and plotting headmodels refer to this page.

Anatomical MRI files can be converted into CTF compatible data using the CTF software MRIConverter and MRIViewer. After this process, a *.mri file is saved which can be used in FieldTrip.

• Open the original MRI data in MRIConverter
• Make sure that the View Direction and Image Orientation are correctly set
• Save the file in the *.mri format
• Open the newly created *.mri file in MRIViewer
• Mark the fiducials: left and right ear and nasion; they should reflect the location of the MEG coils
• Save the changes in the *.mri file

The *.mri file can be read into FieldTrip using ft_read_mri. To read the mri file of the tutorial data, use

mri = ft_read_mri('Subject01.mri');

The FieldTrip mri can be visualized using ft_sourceplot,

cfg = [];
figure
ft_sourceplot(cfg, mri)

To enter interactive mode (i.e, to browse through the volume), use

cfg = [];
cfg.interactive = 'yes';
figure
ft_sourceplot(cfg, mri)

The mri file can subsequently be used for e.g. plotting source localization results (see the plotting tutorial) or for preparing a headmodel (see the beamformer tutorial).