FreeSurfer Tutorial #7: The FSGD File¶
Before starting this tutorial, create a directory called
FS within the
Cannabis directory. The
FS directory should contain all of the directories that have been generated by recon-all. Either run the recon-all commands from that directory, or move them into the FS directory with the
So far we have reviewed the basic commands of FreeSurfer: recon-all and freeview. Recon-all creates a series of volumes and surfaces from a T1-weighted anatomical image, and quantifies the amount of grey matter thickness and volume in different regions of the brain. The cortical regions are called parcellations, and the sub-cortical regions are called segmentations. For example, the left superior frontal gyrus is a parcellation delineated by the Desikan-Killiany atlas, and structural measurements are calculated in that region for each subject. The right amygdala, on the other hand, is a segmentation; because the sub-cortical regions are not inflated into a surface, they only contain measurements of grey matter volume, not thickness.
At this point, you may be thinking about how to compare structural measurements between groups and how to represent those differences on the surface of the brain. The procedure is similar to fMRI analysis: Just as we compare voxels in fMRI, we compare vertices in FreeSurfer. If the vertices are in a common space such as MNI, we can calculate differences in grey matter thickness at a particular vertex and test whether that difference is significant. This generates statistical maps that we can overlay on a template brain as a surface map.
The template brain that we use, which was mentioned in passing in the earlier tutorials, is called
fsaverage. It is an average of 40 subjects that were combined using the spherical averaging technique described in Fischl et al., 1999. The coordinates of this brain are used as a standardized space for the rest of the brains which are normalized to the fsaverage template.
Organizing the Directories¶
First, we will copy the fsaverage template into our current directory. Navigate to the Cannabis directory which contains all of the subjects (i.e.,
Cannabis/FS), and then type:
cp -R $FREESURFER_HOME/subjects/fsaverage .
to copy the fsaverage template. When that is done, set the SUBJECTS_DIR variable to the current directory by typing
export SUBJECTS_DIR=`pwd`. This will place the output of any recon-all or group analysis commands into the current directory:
setenv SUBJECTS_DIR `pwd`
The backticks which bookend
pwd will display the absolute path to the current directory; in other words, it will replace
`pwd` with whatever the output is of typing the command
pwd. This kind of shorthand will be useful, so practice it whenever you have the chance.
We will also create two directories called
Contrasts, which will contain the text files needed to run our analysis:
mkdir FSGD Contrasts
Creating the FSGD File¶
The Cannabis dataset comes with a file called
participants.tsv that contains labels and covariates for each subject: Group, gender, age, onset of cannabis use, and so on. To create a FreeSurfer Group Descriptor (FSGD) file, we will extract those covariates or group labels that we are interested in and format them in a way that FreeSurfer understands. The FSGD file will both contain the covariates that we want to contrast, and a separate contrast file will indicate which covariates to contrast and which weights to assign to them.
To keep our files organized, copy the participants.tsv file into the FSGD directory, and rename it
cp ../particpants.tsv FSGD/CannabisStudy.tsv.
Now, open the file
CannabisStudy.tsv in Excel. We will reformat it into an FSGD file, which is organized in such a way that can be understood by the group analysis commands we will run later. In the first column, type the following four lines:
GroupDescriptorFile 1 Title CannabisStudy Class HC Class CB
These lines are called header lines, since they are needed at the top, or head, of the document and indicate the format of the FSGD file. The first line,
GroupDescriptorFile 1, indicates that the file is in FSGD format; you will need this first line in any FSGD file that you create. The second line,
Title CannabisStudy, will prepend the string “CannabisStudy” to the directories which store the results of your analyses. The next two lines,
Class HC and
Class CB, indicate that the subject name next to a column containing the string HC belongs to the HC group, and that the subject name next to a column containing the string CB belongs to the CB group. For example, after our header lines, we may see something like this:
Input sub-202 HC Input sub-206 HC Input sub-207 HC Input sub-101 CB Input sub-103 CB Input sub-104 CB
The first column,
Input, signalizes that this row contains a subject; the next column,
sub-104, specifies the subject name (which should correspond to the subject directories in the Cannabis folder); and the last column,
HB, indicates which group that subject belongs to. In this case, subjects 202, 206, and 207 belong to the HC group, and subjects 101, 103, and 104 belong to the CB group. Our goal is to contrast the structural measurements between the groups, which we will do in the next chapter. Later on, you will see how to add as many covariates as you like - one for each column. These covariates will be selected from the
For now, save the spreadsheet as a Tab Delimited Text file by clicking on
File -> Save As, and selecting “Tab Delimited Text” from the File Format field. This will create a file called
CannabisStudy.txt. Make sure this is saved into the FSGD directory. Then open a Terminal, navigate to the FSGD directory, and type the following:
tr '\r' '\n' < CannabisStudy.txt > CannabisStudy.fsgd
This will remove any DOS carriage returns, which Unix cannot interpret, and replaces them with newline characters. This will prevent any errors when using the FSGD file with FreeSurfer commands.
Although we are not discussing covariates yet, be aware that many researchers choose to include estimated total intracranial volume (eTIV) as a covariate when comparing groups. See the note in this page under the section “Modifying the FSGD File”.
Creating the Contrast file¶
Our next step is to create a contrast file that specifies the contrast weights for each regressor in our model. The “Class” variables that we specified in the FSGD file are group regressors: One for the Cannabis group, and one for the Control group. Since we have only two regressors, we only need to specify two contrast weights.
To specify these weights, navigate to the
Contrasts directory and then type:
echo "1 -1" > HC-CB.mtx
This enters the string
1 -1 into a file labeled
.mxt stands for “matrix”, as in, “contrast matrix”; in more complicated designs, the contrast file can be any size M x N matrix.) The label of the contrast file can be anything you choose; in this example, we have chosen a label that is compact and easy to understand.
Now create another contrast file for the opposite contrast, namely:
echo "-1 1" > CB-HC.mtx
Which will create a contrast file subtracting the Control group from the Cannabis group.
Now that we have created the files necessary for a group analysis, the next step is to run the group analysis itself. Before you proceed, try the following exercises to test your understanding of what you just read.
- If you wanted to create a contrast representing the average effect across groups, what contrast weights would you use? What would be a good label for the contrast file?
- When analyzing an open-access dataset designed to compare Old and Young groups, you come across this FSGD file:
GroupDescriptorFile 1 Title MyStudy Class Old Class Young Input sub-101 HighAge Input sub-102 HighAge Input sub-103 HighAge Input sub-201 LowAge Input sub-202 LowAge Input sub-203 LowAge
What is wrong with this file? Which parts would you change? (Hint: One section you must change for the analysis to run without FreeSurfer throwing any errors; another section can be changed to better describe the analysis.)