Freesurfer BOLD files

Freesurfer, like SPM, can perform functional analyses on fMRI data. These analyses generally employ the general linear model (GLM) to assess the degree to which the blood-oxygen dependent (BOLD) signal correlates with different predictors (e.g., group, experimental condition, task or even nuisance regressors such as motion).

For Freesurfer and SPM, these files will start off as NIfTI (.nii) files. Each file contains a header, which contains important information directing the software how to interpret the data, and one or more 3D matrices of raw data, representing the signal at each voxel at a particular point in time, as measured by the scanner during the experiment. The data for a single run (e.g., a 5-minute scan of an experimental task) can be stored as a series of individual 3D volume files, with each file representing a single scan of the brain like a single frame of a 5-minute movie. Alternately, multiple volumes can be concatenated together and stored in a single 4D file. Whereas SPM operates on either 3D or 4D data, Freesurfer seems to require 4D data.

The header information is important because it provides the context required to interpret the data matrix. For example, an experiment looking at hippocampal processing might use a 32 x 32 x 24 array of 1mm voxels and look at a relatively small subcortical volume. Another experiment looking at global cortical processing might use a 32 x 32 x 24 array of 3mm voxels to look at the entire brain volume. Without knowing the voxel size, it would be impossible for any piece of software to interpret the data matrix. The NIfTI header includes information about how big the voxels are, the orientation, and many other important bits of information, though not all software makes use of all the header information.

File Fixing

Freesurfer expects the BOLD data to be organized into individual folders for each experimental run, and that each file is called "f.nii". Moreover, Freesurfer (but not SPM) appears to make use of the TR value stored in the NIfTI header. In order to ensure that the filename requirement is met and that the TR value is correctly set, a script called set_TR.m can be found in the ubfs Scripts/Matlab folder. Another issue, specific to our scanner, is the fact that the Toshiba scanner at the CTRC does not (currently) do anything to account for the magnetic field inhomogeneity that invariably accompanies the first several seconds of a functional run. Other scanners (e.g., Siemens) automatically discard the first several seconds of data. Because the BOLD data from the CTRC will have this magnetic field inhomogeneity artifact, we must manually drop the affected volumes and also remember to adjust the onsets of the experimental events accordingly.

Dropping initial volumes using nii_4D_drop_vols.m

A MATLAB function, nii_4D_drop_vols.m can be found along with the rest of our library of MATLAB code. This code relies on Jimmy Shen's NiFTI Tools toolbox. Ensure that this function and the toolbox are in your MATLAB path. If they are, you can type help nii_4D_drop_vols.m, which will tell you that you can call the function with or without a filename (you will be prompted to find a file if none is provided). The second parameter is the list of volumes to drop. Positive values are the volumes, relative to the start of the series, to drop. Values 0 or less are the volumes from the end of the series. For example:

nii_4D_drop_vols('4D.nii', [1 2 3 4 0 -1 -2]); 
%will drop volumes 1 to 4, as well as the last (0), second-last (-1) and third-last (-2)

The original file will be saved with a .bak extension

If this function doesn't work, the first thing you should check is that the NiFTI tools toolbox folder is in your path.

Dropping the first 8 to 10 seconds should suffice. With a TR of just over 2 seconds, this would be the first 4 or 5 volumes. The functionality of dropping the end volumes was added because it was trivial to do so. In practice, there will seldom be a reason to provide drop indices of zero or less (in other words, stick to dropping volumes 1+ unless you have a good reason to do otherwise).

Remember to account for the dropped volumes when creating your Par-files

Fixing the TR header field using set_TR.m

The first requirement is that the source files for a participant be organized into numbered folders, ideally in a directory called "bold":

• participant_id
  • bold
    • 001
      • 4D.nii
    • 002
      • 4D.nii
    • 003
      • 4D.nii

After this is done, you can use the MATLAB set_TR.m function to simultaneously rename the source files and set the TR to the correct value (you will, of course, have to know what the correct TR value is!). Data coming from the CTRC currently have the TR header field intialized to a value of 1.0, corresponding to a 1-second TR. SPM doesn't make use of the TR value from the header field, so this isn't a problem. However Freesurfer does use this value, so you may want to ensure that the header contains the correct TR value.

If you wish to simply inspect the values in a .nii file header, you can use a command-line FSL utility called fsledithd:

fsledithd 4D.nii

This will open up the header information in the default text editor (nano), and you can browse the values for various fields:

<nifti_image
 nifti_type = 'NIFTI-1+'
 image_offset = '352'
 ndim = '4'
 nx = '64'
 ny = '64'
 nz = '29'
 nt = '256'
 dx = '3.3125'
 dy = '3.3125'
 dz = '4.1'
 dt = '1' 
 datatype = '16'
 nbyper = '4'
 byteorder = 'LSB_FIRST'
 scl_slope = '1'
 scl_inter = '0'
 xyz_units = '2'
 time_units = '8' 
 descrip = 'FSL5.0'
 aux_file = 'none'
 qform_code = '1'
 quatern_b = '0'
 quatern_c = '0'
 quatern_d = '0'
 qoffset_x = '-106'
 qoffset_y = '-94.133'
 qoffset_z = '-42.618'
 qfac = '1'
 sform_code = '1
 sto_xyz_matrix = '3.3125 0 0 -106 0 3.3125 0 -94.133 0 0 4.1 -42.618 0 0 0 1'
 num_ext = '0'
/>

The above output gives information about the voxel dimensions in the x,y and z axes (dx, dy, dz are 3.3125, 3.3125 and 4.1 units, respectively). Those units are interpreted as millimeters, according to the xyz_units field value (2=mm). Similary, for the time dimension field, the value is set to 1 in this header, interpreted as seconds according to the time_units field (8=seconds; 16=milliseconds). Thus, according to this file header, the functional volumes were collected 1-second apart, which is not correct (the TR for this experiment was 2.047). This can be edited using fsledithd by simply changing the dt field value from 1 to 2.047 (if you do so, you would then type ^O (ctrl-O) to save the changes, then ^X (ctrl-X) to exit the editor). However, a MATLAB script exists that will update the fields for multiple files belonging to the same individual.

This script, set_TR.m can be found in the ubfs Scripts/Matlab folder. Ensure that this file can be found somewhere in your MATLAB path (e.g., copy it to your Documents/MATLAB folder)

First, open a terminal and start matlab:

matlab &

Your startup.m script should run automatically, setting your path to include the most commonly used toolboxes in the process. Nonetheless, you should ensure that set_TR and other needed functions are indeed in your path:

help load_untouch_nii
help set_TR

If either of these commands return a command not found type of message, ask for help in getting them permanently in your path. It could be simple matter of running a startup script (e.g., startup_spm8).

Assuming that these files are in your path, the next step is to use MATLAB to navigate to the directory containing your participant data. For example, working with a data set on ubfs:

cd ~/ubfs/cpmcnorg/openfmri/test/1001

Now you are in the directory for participant 1001. There should be a bold subdirectory with one or more numbered directories below it, as described above. Move into the bold directory:

cd bold

Now you can run the set_TR command:

set_TR(2.047, [1 2 5 6], '4D.nii')

The above command would look for a file called '4D.nii' in directories 001, 002, 005 and 006, modify the NIfTI header file information to have a TR of 2.047 seconds, and then save the changed files to 'f.nii', leaving the originals unchanged (if your files are already called f.nii, they will be overwritten).