fMRI preprocess MATLAB toolbox version 1.0

Before detrending the linear drift component is present in the raw data, and is need to be removed.

After detrending the linear drift has been removed from the time series

Step by step tutorial on how to use this toolbox

  1. Download the following files and toolboxes, put them all and extract the zipped files into the main directory X (./X):
    1. NIFTI-MATLAB toolbox [.tar.gz]
    2. fMRI preprocessing toolbox [.tar.gz]
    3. main_preprocessingData_overview.m [matlab m-file]
    4. Haxby et al. data set [.tar.gz] from the Princeton MVPA download webpage.
  2. Make a directory outData in X, ( ./X/outData ), to store the output from the program
  3. Run the file main_preprocessingData_overview.m in MATLAB. The program would take approximately 10 minutes to run the whole 10 runs, and all the output will be in ./X/outData.

The technical note briefly discusses the regression process [pdf]. More details about the toolbox can be found in the section below.

MATLAB Toolbox version 1.0

clear, clc, close all;
% addpath to the preprocessing toolbox
addpath('../../../toolbox_preprocessing_fMRI');
% You have to first include the nifti toolbox
addpath('../../../toolbox_matlab_nifti');

First we need to download toolboxes 1) fMRI data preprocessing and 2) nifti toolbox for MATLAB, then add both to the path. 

%%
% 1) main_convertDataToVTFormat will read each nifti file in the Haxby's
% dataset and change into the VT format. This process will do for the whole
% brain without any mask. This program call the function
% convertDataVTFormat to convert the file to VT format. The output will in
% the format haxby8_r<run#>_VT.mat
main_convertDataToVTFormat

Next, we read the content from the nifti files into VT-format in MATLAB space. You will need to open the routine main_convertDataToVTFormat to make sure that the paths to the nifti files and the output directory are correct. Once done correctly, the output VT-format files will be stored as <filename>_VT.mat in the output directory. Within the output file, the structure out contains all the information you need.

out = 
       VT: [163840x121 double]
    sizeX: 64
    sizeY: 64
    sizeZ: 40
    sizeT: 121
    coorX: [163840x1 double]
    coorY: [163840x1 double]
    coorZ: [163840x1 double]
%%
% 2) main_convertMaskToVTFormat.m will read the mask determined in Haxby's
% dataset, and convert into the VT format in the similar manner to 1). The
% output file is MaskHaxby8.mat.
main_convertMaskToVTFormat
%

Since the whole brain voxels might be too large for a certain application, we usually narrow down the scope of the investigation by selecting a region of interest (ROI) in the brain. The ROI's are usually inthe form of mask voxels. Therefore, we might want to read the mask into VT format as well by usingmain_convertMaskToVTFormat, which has almost the same content as main_convertDataToVTFormat but specified to the mask.

You will need to open the routine and configure the input/output filename and directory. The output mask will be stored as structure mask with the same attributes as those of out.

mask = 
       VT: [163840x1 double]
    sizeX: 64
    sizeY: 64
    sizeZ: 40
    sizeT: 1
    coorX: [163840x1 double]
    coorY: [163840x1 double]
    coorZ: [163840x1 double]
%%
% 3) Next we will preprocess the data for each run by running
% main_preProcessFMRIData. Preprocessing also includes offset and drift
% removal, z-score and calculate for the beta_hat in each voxel (refer to Approach II below). User can
% define the design matrix and its basis in X. The output file is haxby8_r<run#>_beta.mat
%
% Approach II
% (1) Regress out both offset and the drift from each voxel individually
% (2) calculate z-score (standardize) from the time series, each voxel
% individually
% (3) Calculate the beta map for each voxel
main_preProcessFMRIData

This is the preprocessing procedure starting from

  1. Regressing out the "drift", namely detrending the data
  2. Standardize the time series in each voxel individually using z-score to make sure all the data are in the similar range
  3. Then we use a generalize linear model (GLM) to calculate the beta for each voxel; each block will be represented by a beta value.

You might want to open the file main_preProcessFMRIData to configure the input/output directories. The output will be <filename>_beta.mat containing the variables:

  • VT: The VT-format data matrix of dimension V x T, where V denotes number of voxels and T denotes number of time stamp
  • VT2: The time series after offset and drift are removed from each voxel
  • zVT: the z-scored version of VT2, each voxel individually
  • X: the regressor/predictor matrix of GLM containing basis used in the design matrix
  • VT3: The time series of the response of the basis defined in X
  • betaMatrix: MxN matrix, each entry is a GLM coefficient for each voxel n and each run m
  • betaDrift: The coefficients when detrending
  • X_offset_drift: The design matrix for the detrending
  • coorX, coorY, coorZ: the xyz coordinates for each voxel

Up to this point, all the voxels are processed and the information about the selected ROI is not deployed yet. Next step we can specify the voxels within the ROI and we also reshape the betaMatrix into a proper format, Box-table (BOT) format and hen joint-experiment (JOE) format, for further analysis.

%%
% 4) We can convert the data into Bot-format by running the program
% main_convertDataToBotFormat.m. The Bot-format is V x B x R, where
% V: the number of voxel
% B: the dimension of regression coefficient beta_hat
% R: the number of experiment run
% The program will read the VT data matrix from run1 to 10, and combine
% them together, and also output the class ground-truth matrix.
main_convertDataToBotFormat

In this step, you might want to open the file main_convertDataToBotFormat and configure the input/output directory. You can choose the ROI in this code. The end results are stored in X_betaMap_BotFormat.mat or X_betaMap_JoeFormat.mat depending on what format you use. We mainly use Joe format in further experiments as it is easy to handle. The output variables stored in the .mat file are

  • betaMap: MxN beta matrix in Joe format
  • classMatrix: MxN matrix indicating the class label for each entry. It is true that every column of classMatrix is the same.
  • coor: the xyz coordinate for each voxel