Detrending FreeSurfer Data

Over the course of a run, there can be a linear drift in the signal in different regions of the brain. There are many possible causes for this that have nothing to do with any interesting aspect of your data -- in other words, this linear drift is a nuisance artifact. The second step is to remove this signal drift from the data because it can introduce spurious correlations between two unrelated time series. You can see this for yourself in a quick experiment you could whip up in Excel: take two vectors of 100 randomly generated numbers (e.g., randbetween(1,99)). They should be uncorrelated. Now add 1, 2, 3, ... , 99, 100 to the values in each vector. This simulates a linear trend in the data. You shouldn't be surprised to find that the two vectors are now highly and positively correlated!

A script has been written called detrend.sh that removes the linear trend in your BOLD data:

detrend.sh

#!/bin/bash
USAGE="Usage: detrend.sh filepattern surf sub1 ... subN"
if [ "$#" == "0" ]; then
	echo "$USAGE"
	exit 1
fi
 
#first parameter is the filepattern for the .nii.gz time series to be detrended, up to the hemisphere indicator
#e.g., fmcpr.sm6.$surf.?h.nii.gz would use fmcpr.sm6.[self|fsaverage] as the filepattern
filepat="$1"
shift

#second parameter should be specified either as self or fsaverage
surf="$1"
shift

#after the shift command, all the arguments are shifted down one place and the first two arguments 
#(the filepattern and surface) 
#fall off the list. The remaining arguments should be subject_ids
subs=( "$@" );
hemis=( "lh" "rh" );

for sub in "${subs[@]}"; do
   source_dir=${SUBJECTS_DIR}/${sub}/bold
   echo ${source_dir}
   if [ ! -d ${source_dir} ]; then
       #The subject_id does not exist
       echo "${source_dir} does not exist!"
   else
	cd ${source_dir}
	readarray -t runs < runs
	for r in "${runs[@]}"; do
		if [ -n "${r}" ]; then
		#the -n test makes sure that the run number is not an empty string
		#caused by a trailing newline in the runs file
			for hemi in "${hemis[@]}"; do
				cd ${source_dir}/${r}
				pwd
       			#subject_id does exist. Detrend
				if [ "${surf}" = "self" ]; then

					SURFTOUSE=${sub}
				else
					SURFTOUSE=fsaverage
				fi
               		mri_glmfit --y ${source_dir}/${r}/${filepat}.${surf}.${hemi}.nii.gz \
       			--glmdir ${source_dir}/${r}/${hemi}.detrend \
				--qa --save-yhat --eres-save \
				--surf ${SURFTOUSE} ${hemi}
				mv ${source_dir}/${r}/${hemi}.detrend/eres.mgh ${source_dir}/${r}/${filepat}.${hemi}.mgh
       		done
		fi
	done
   fi
done

Running the Script

Before running this script, you will need to create a text file called 'runs' in the bold/ directory for each subject's dataset, e.g.,

• FS_T1_501/
  • bold/
    • runs
    • 005/
    • 006/

The runs file simply lists each run folder on its own line:

005
006

The detrend.sh script uses this file to determine the folders containing the data to be detrended. Assuming all your subject folders have the same run folders to detrend, you would detrend multiple subjects using detrend.sh, specifying a file pattern for the source data (i.e., the name of the preprocessed files generated by FS-FAST, omitting anything after the '?h' hemisphere identifier), followed by a list of subject IDs:

detrend.sh fmcpr.sm6.self FS_T1_501 FS_T2_501 FS_T1_505 FS_T2_505

The gist is that it calls the mri_glmfit function and saves the residuals after the linear trend has been removed from the data. Multiple files are generated in ?h.detrend/ directories in each run directory. The detrended data is subsequently copied back to the run directory as a new file called ${filepat}.?h.mgh, where ${filepat} is whatever file pattern you provided to the script (note that the source data are .nii.gz files, whereas the detrended data are .mgh files).

A handy shortcut exists if you happen to have a subjects file in $SUBJECTS_DIR:

FILEPATTERN=fmcpr.sm6.self
detrend.sh $FILEPATTERN `cat subjects`

This will execute the detrend.sh script on all the subjects listed in the subjects text file. I just figured this out today.