Configure preproc-sess

You can preprocess multiple participants in a batch or individual participants, depending on how you invoke the preproc-sess command. This took ~30 min to run one participant on Brocasarea.

Before you start

Check down at the Problems section at the bottom of this page. In particular, there is an additional step you will have to do to work with data collected from the DENT Institute (Header Problems 1).

Create a subjectname file

The first thing you will need to do is create a file called subjectname in the folders for each of the participants you will be preprocessing. This file contains only a single line, indicating the Freesurfer subjectid by which that subject is known. For example, for the subject whose data is in $SUBJECTS_DIR/FS_T1_501/, there should be a file called subjectname that contains just a single line:

FS_T1_501

If such a file does not exist, create it. There are a couple of ways to do this. First:

cd $SUBJECTS_DIR/FS_T1_501
echo FS_T1_501 > subjectname

Alternatively, if you want to be fancy and not have to type out the name of the participant, you can use the output of the 'basename' linux command to generate the name of your directory, which should match your participant name:

cd $SUBJECTS_DIR/FS_T1_501
echo `basename "$PWD"` > subjectname

Using this method, the second command will always be the same for any participant.

Run preproc-sess

This command does motion correction, spatial smoothing (to reduce noise, thereby increasing the signal-to-noise ratio), and slice-time correction on your functional (BOLD) data. It can be run on a batch of participants or on individuals. This command takes ~25-35 minutes per person for 6 runs worth of data, depending on the number of surfaces processed (lh, rh, mni305).

Batch processing

Batch processing requires a sessid file containing the session names (i.e., the names of all the Freesurfer folders) for all your participants. The sessid file can be called anything you wish, and is simply a plain text file with one folder name on each line. For example:

chris_subjects.txt:
 FS_T1_501
 FS_T2_501
 FS_T1_505
 FS_T2_505

When doing a batch, you call using the -sf switch:

preproc-sess -sf <sessidfile> -df <srchdirfile> [options]

e.g.,

preproc-sess -sf chris_subjects.txt -surface fsaverage lhrh -mni305 -fwhm 4 -per-run -fsd bold -sliceorder down

If the -df switch isn't provided (it doesn't seem to be mandatory) then it uses a default directory (possibly $SUBJECTS_DIR, or possibly your current working directory) to start in.

Individuals

Preprocessing individuals works pretty much the same, except you do not require a sessid file. Instead, you provide it with the name of one of the session folders, and use the -s switch, rather than the -sf switch. For example:

preproc-sess -s FS_T1_501 -per-run -surface fsaverage lhrh -mni305 -fwhm 4 -fsd bold -sliceorder down 

This processes subject FS_T1_501 using the same parameters as used for the batch processing example above

Other options

Check Registration

Before you proceed with any functional analyses, you should ensure that the bold data has been coregistered to the T1 anatomical data. You can use tkregister-sess to view a representative volume from each run, with the white matter surface contours mapped on to the volume:

SUBJECT_ID=FS_T1_501
tkregister-sess -s ${SUBJECT_ID} -inorm -per-run

If the contours are out of alignment with the functional data, you can use this interface to manually perform affine (i.e., rigid-body) transformations so that they line up. More information on this can be found here and here.

Note: You must cd to your subjects directory for this to work.

Slice time correction

Slice time correction adjusts the functional data to account for the fact that, when you acquire an entire 3D volume as a series of 2-D planes (slices) over the span of 1 TR (commonly 2 seconds), then the very last slice you acquire is going to be delayed 2 seconds relative to the very first slice you acquire. There is a -sliceorder switch that you can provide telling Freesurfer what order the slices were acquired, which the software uses to algorithmically adjust the signals for each slice to account for the fact that they occurred earlier vs. later within that 1 TR time window. Using this switch requires you to know something about the scanner. It is prudent to check with the scanner technician to verify the slice acquisition order so that you can provide the correct value to go along with the -sliceorder switch. If you omit the -sliceorder switch, slice time correction is not performed on the data.

At the CRTC 3T magnet (as of November 2016), data are collected in sequential ascending order (i.e, from the chin to the crown of the head), corresponding to -sliceorder down (note: initially I had indicated that the code was -sliceorder up, but after looking at some basic task vs. rest maps (which should show some robust blobs) it's pretty clear that down is correct).

Problems

Header Problems 1: Misstated volume count in the header

Sigh of relief as I figured this out, so we didn't actually lose all of our DENT data.

It is more likely than not that the information about the number of volumes indicated in the header does not match the actual number of volumes recorded in the data for the SEMCAT experiment, which is self-paced. The MRI at DENT is configured to run for 256 volumes (512 seconds) per run. In practice, people typically finish before this. However, the .NII file headers are having the number of volumes listed as 256, and not the actual number of volumes acquired. When you go to run preproc-sess with these data, you will probably get an uninformative error right away when mri_convert tries to open up the data.

Fortunately, the problem is easily fixed (though discovering that it is easily fixed was not easy). Since this is 99.9% likely to affect any given functional run from a self-paced study (e.g., the SEMCAT experiment) you should probably get in the habit of opening up each of your functional volumes with fsledithd:

fsledithd f.nii

Don't do anything else. Just open it and then save it without making any modifications. When you return to the terminal you will see a message along the lines of:

++ WARNING: nifti_read_buffer(run4.nii):
  data bytes needed = 60817408
  data bytes input  = 52379648
  number missing    = 8437760 (set to 0)

What happened here is that fsledithd saw that there are supposed to be 256 volumes of data, but a smaller amount of data was found. So it went ahead and filled in all the missing bytes with 0. Now your f.nii file will be bigger, with all the missing volumes at the end filled with zeros.

Header Problems 2: Unsupported slice timing 5

Running preproc-sess on an existing dataset from the Booth lab, I ran into

nifti1Read(): unsupported slice timing pattern 5 in /home/chris/ubfs/cpmcnorg/openfmri/booth/FS_T2_501/bold/029/f.nii

Some of the .nii files have invalid information in the header. In the case of the slice_code field, valid values are 0,1,2,3, or 4:

#define NIFTI_SLICE_UNKNOWN  0
#define NIFTI_SLICE_SEQ_INC  1
#define NIFTI_SLICE_SEQ_DEC  2
#define NIFTI_SLICE_ALT_INC  3
#define NIFTI_SLICE_ALT_DEC  4

According to the NifTI header documentation, if the slice_code field nonzero, AND if slice_dim is nonzero, AND if slice_duration is positive, this value indicates the timing pattern of the slice acquisition (sequential or interleaving slices; incremental or decremental). Because this value is sometimes '0' in some of our older data, but '5' in some of the newer data, my working theory is that one of the pieces of software used to convert from DICOM to NifTI format (MRI Convert, a Windows program) inserts nonsensical default values in some of the header fields that are not used by all fMRI analysis packages. In any case, the set_TR script now sets the slice_time field to 0 at the same time that it modifies the TR field. Another program, fsledithd can be used to modify some (but not all) of the header fields, including the slice_code field:

fsledithd f.nii

This command would open up a default command-line text editor (e.g., nano) where fields and their values are listed, one per line. You would locate the line for slice_code and modify it so that it reads:

slice_code = '0'

Then save the changes and quit.

ERROR: 3dvolreg.afni & libxp.so.6

This error occurs on Ubuntu 16.04 due to the lack of libXp packages. To fix this, we simply need to install an older version of the needed packages. Get the correct package here. Download this file (somewhere, probably Downloads is easiest). Open the terminal and cd to the directory you downloaded the file in, then run

sudo dpkg --install <name of file>

You may need to get one of the End Bosses to run this as an admin.

niiRead(): error opening file /tmp/mkbrainmask*

You probably missed a step in matlab. Go back and make sure you dropped volumes, set TR, and extracted the parfiles. Make sure everything is in the right location and named properly.