[FSL] [TitleIndex] [WordIndex] 

Contents

  1. Introduction
  2. User Guide

    Contents

    1. Segmentation using FIRST
      1. run_first_all
      2. first_roi_slicesdir
    2. General Advice and Workflow
    3. Vertex Analysis (with NEW features in v5.0.0)
      1. concat_bvars
      2. randomise
      3. General Advice and Workflow
        1. Getting started:
        2. Create a design matrix:
        3. Running vertex analysis
        4. Output of vertex analysis
        5. Other common design matrices
      4. Viewing results
    4. Volumetric Analysis
    5. Models
    6. Advanced Usage
      1. Registration
      2. Segmentation
    7. Boundary Correction
      1. first_boundary_corr
      2. first_mult_bcorr
    8. Surface-based Vertex Analysis
      1. Viewing surface outputs
      2. surface_fdr
      3. General Advice and Workflow
        1. Running vertex analysis:
        2. Output of vertex analysis:
        3. Running Multiple Comparison Correction:
        4. Other common design matrices:
    9. first_utils
    10. Labels

Segmentation using FIRST

The simplest way to perform segmentation using FIRST is to use the run_first_all script which segments all the subcortical structures, producing mesh and volumetric outputs (applying boundary correction). It uses default settings for each structure which have been optimised empirically.

run_first_all

and if there are no errors then you will see no output, otherwise you will see what errors have occured.

first_roi_slicesdir

first_roi_slicesdir is a script to generate summary images, in a webpage format, for the segmentation outputs. It is very useful for checking the quality of segmentations, especially when there are many subjects. It runs the script slicesdir on a region of interest (ROI) defined by a set of label images (e.g. output of FIRST). A set of temporary ROI images are created and then slicesdir is then run on those.

Usage: first_roi_slicesdir <list of t1_images> <list of label_images>

Example: first_roi_slicesdir *_t1.nii.gz *_all_fast_firstseg.nii.gz

General Advice and Workflow

Below is a recommendation for running FIRST in a systematic way. While it is only a recommendation, you may find that organizing your data in a different way than suggested below leads to complications further down the road, especially when moving files.

cat *.logs/*.e*

which will show no output if there are no errors. Once you've verified that there are no errors, then you can most easily check the results from a group of subjects using the relevant slicesdir tools.

${FSLDIR}/bin/slicesdir -p ${FSLDIR}/data/standard/MNI152_T1_1mm.nii.gz *_to_std_sub.nii.gz

This command creates a directory called "slicesdir" which will contain a webpage output of the summary results for each subject's registration. Note that if the registration stage failed then the model fitting will not work, even though run_first_all will continue to run and generate output. Therefore it is critical to check the registration results.

On the webpage, each subject's registered image (*_to_std_sub.nii.gz) will be displayed in sagittal, coronal, and axial views, with a red outline showing the edges from MNI152_T1_1mm standard brain. Open this webpage in any web browser.

When assessing the registrations, pay particular attention to the sub-cortical structures. It does not matter if the cortex does not always align well, particularly where there are large ventricles, as it is the alignment of the sub-cortical structures which is important for the segmentation.

Firstly, fix any registration errors (see below for first_flirt and various options available) and re-run the segmentation using the new registration. After that the segmentation output can be inspected. This can be done using first_roi_slicesdir which generates a similar webpage, but this time showing the segmentations.

If there are any problems, you can try different segmentation options (e.g. number of modes, boundary correction method, etc.) using the individual tools described in the Advanced Usage section.

Vertex Analysis (with NEW features in v5.0.0)

Internally the vertex locations from each subject (at a corresponding anatomical point) are projected onto the surface normal of the average shape (of this particular cohort). The projections are scalar values, allowing them to be processed by univariate statistical methods (e.g. randomise). It is these projection values that are stored in the 4D file (one image per subject) and they represent the signed, perpendicular distance from the average surface, where a positive value is outside the surface and a negative value is inside. A mask file (covering the vertices on the surface of the average shape) is also output.

first_utils --vertexAnalysis --usebvars -i concatenated_bvars -d design.mat -o output_basename [--useReconNative --useRigidAlign ] [--useReconMNI] [--usePCAfilter -n number_of_modes]

concat_bvars

concat_bvars is used to concatenate the ".bvars" files across subjects. All subjects should be created using the same model and concat_bvars will keep track of the number of subjects that the final, concatenated file contains. Usage:

concat_bvars output_name.bvars [list of ".bvars" files]

Example:

concat_bvars L_Hipp_all.bvars con*_L_Hipp_first.bvars dis*_L_Hipp_first.bvars

randomise

randomise is used to calculate the statistics from the 4D image output. This requires design matrix, t-contrast and f-contrast files to be specified. These can be created by the Glm GUI.

Example:

randomise -i con1_dis2_L_Hipp.nii.gz -m con1_dis2_L_Hipp_mask.nii.gz -o con1_dis2_L_Hipp_rand -d con1_dis2.mat -t con1_dis2.con -f con1_dis2.fts --fonly -D -F 3

Here the -d, -t, and -f specify the files containing the design matrix, t-contrast(s) and f-contrast(s). The -D option demeans the data (and design matrix - you can ignore the warning about the design having a non-zero mean, as this will be removed internally and give correct outputs). The -F 3 option does cluster-based multiple-comparison-correction (with an arbitrary threshold of 3, which is only an example here) but could be substituted with any other valid multiple-comparison-correction option such as --T2, -x, -S. See the randomise documentation for more information on available options.

The --fonly option is included so that only the F-statistic is calculated and used by randomise for inference. This is then equally sensitive to changes in either direction (e.g., growth or atrophy). To determine which direction the change is in there are two possible approaches: (i) omit this option and look at the t-contrast results (carefully taking into account the signs used in both the design matrix EVs and the contrast) or; (ii) more simply, just look at the signs of the individual data points in the 4D input file. The second option is generally easier and is quite simply done with FSLView, by loading the corrected p-value output from randomise (the f-statistic result, having kept the --fonly option) then adding the 4D input file and using the "timeseries" option in FSLView to see the values from the 4D input file at boundary locations where there was a statistically significant change.

General Advice and Workflow

This section covers some general recommendations for running vertex analysis. The following is not prescriptive but may be helpful, especially to new users or those less familiar with unix-style commands and environments.

Getting started:

To begin with you need to generate segmentations of all the structure of interest in all subjects (see the segmentation section). Note that it is the bvars files, which correspond directly to the surface representations, which will be needed and the volumetric representation from FIRST (e.g. run_first_all) is not used. Hence it does not matter what boundary correction was used or whether one or more structures were segmented.

One the segmentations are done, concatenate all of the bvars files for the structure you are going to run vertex-wise stats on. For example if you are looking for differences in the left hippocampus, and assuming your output bvar files are named con*_L_Hipp_first.bvars and dis*_L_Hipp_first.bvars, do
concat_bvars con_to_dis_L_Hipp.bvars con*_L_Hipp_first.bvars dis*_L_Hipp_first.bvars

This command will create a bvars file called con_to_dis_L_Hipp.bvars that contains the bvars (mode paramters) of the segmentation of the left hippocampus from each subject in the order con01-con10, followed by dis01-dis10.

Create a design matrix:

This is easiest done by using the "Higher-level" mode of the Glm gui. However, the design matrices are treated slightly differently by FIRST compared with FEAT. The main difference is that FIRST does not model separate group variances and so ignores the "Group" column in the Glm gui. Another difference is that only F-tests are needed, since we look for any change in vertex position. Therefore it is necessary to set up a least one F-contrast, which needs T-contrasts to be set up (since that is how F-contrasts are specified). For more details about this see the FEAT documention.

For this example, imagine you are simply interested in finding a difference in shape between the two groups "con" and "dis". Your design matrix would simply be an EV with 10 negative ones followed by 10 positive ones. That is: 

-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
1
1
1
1
1
1
1
1
1
1

Create this design (using the Glm GUI) and specify both a single T-contrast and single F-contrast, and then save them in files named con1_dis2 (choose the name con1_dis2 in the "Save" dialog of the Glm GUI - it will produce con1_dis2.mat, con1_dis2.con and con1_dis2.fts). Note that because the concatenated bvars files was created in the order "con", then "dis", in your design matrix group 1 is the "con" group and group 2 is the "dis" group.

You are now ready to run vertex_analysis. Note that for this example, the --useReconNative option will be used. This carries out vertex analysis in native space, along with the --useRigidAlign option. The --useReconMNI option may also be used to carry out vertex analysis, it will do it in the MNI standard space instead, which normalises for brain size. It is difficult to say which will be more sensitive to changes in shape, and so it may be interesting to try both the --useReconNative and the --useReconMNI options. Also note that the --useScale option will not be used. Without the --useScale option, changes in both local shape and size can be found in shape analysis. This type of finding can be interpreted, for example, as local atrophy. With the --useScale option, overall changes in size are lost.

Create a new directory (e.g. called shape_analysis) within the current main directory. This will be where the results of shape analysis are saved. For example, mkdir shape_analysis

Running vertex analysis

Run first_utils giving it the combined bvars file and the design matrix. For example:

first_utils --vertexAnalysis --usebvars -i con_to_dis_L_Hipp.bvars -d con1_dis2.mat -o shape_analysis/con1_dis2_L_Hipp --useReconNative --useRigidAlign -v >& shape_analysis/con1_dis2_L_Hipp_output.txt

Run randomise using the output 4D image (containing projections of the vertex displacements per subject) and the mask image, together with the design matrix and contrast files. For example:

randomise -i con1_dis2_L_Hipp.nii.gz -m con1_dis2_L_Hipp_mask.nii.gz -o con1_dis2_L_Hipp_rand -d con1_dis2.mat -t con1_dis2.con -f con1_dis2.fts --fonly -D -F 3

Note that the option -F 3 is only one of several multiple-comparison-correction options available, and this is just an example, not a standard recommendation.

Output of vertex analysis

In the same way as in FSLVBM and TBSS, randomise is used to generate the statistics. The output of most interest is the probability that is corrected for multiple comparisons. This will contain corrp in the filename. The values within this file contain 1-p values, such that p=0.05 corresponds to a value of 0.95, and so displaying all values over 0.95 with FSLView will show the significant areas. For more information about how to view these results refer to the documentation for randomise, FSLVBM or TBSS.

Other common design matrices

Correlation

For correlation only (no group difference) you can create a design matrix with one column (EV) where each row contains the value of the correlating measure for each subject in the same order as the subject's bvars (in the concatenated bvars file). For example, to correlate age with shape, the design matrix would contain one EV, which would be a single column where each row has the age of each subject in the same order as the concatenated bvars file. If you have not removed the mean from the age values (i.e. demeaned them), then randomise will do it for you, although it will print a warning to this effect (which you can ignore).

Interpretting the results of a correlation: the values in the p-value images will give the probability of a zero correlation (the null hypothesis) at each vertex. You can also do correlation with a covariate (see below). This gives you the same type of output statistics, but accounting for the covariates/confounds.

Covariate

To add a covariate to a group difference study, simple add a second column to the group difference design matrix. This second column should contain the demeaned scores (for each subject in the same order as the concatenated bavrs file) of the measure you wish to use as a covariate; for example, age. If you want to model different correlations in the different groups then you need a separate (demeaned) EV of scores per group. This is the same as any standard GLM analysis, as are the contrasts, except that the final contrast of interest should always be made into an F-contrast (if it is not naturally one already) in order to do a two-sided test. See other documentation on GLM and modelling for more information.

Viewing results

Results from randomise can be viewed in the standard orthographic viewer in FSLView (viewing orthogonal slices). To distinguish the direction of the changes see the description in the section on randomise above.

first3Dview.png

Alternatively, it is possible to view the results as a 3D rendering (as shown in the image here), by using the script first3Dview (download this here, as it is not part of FSL currently). Simply unzip the script into the standard $FSLDIR/bin directory, or into a local directory (where you will run it from). Once you have done this, you need to follow these instructions:

Volumetric Analysis

Currently, to perform volumetric analysis it is necessary to determine the label number of the structure of interest and use fslstats to measure the volume. Other software (e.g. SPSS or MATLAB) needs to be used to analyse the volume measurements.

To find the label number, load the output_name_*_firstseg.nii.gz image into FSLView, click on a voxel in the structure of interest and the label number will be the number in the Intensity box. Alternatively, you can find the number from the CMA standard labels.

Once you have the label number you can measure the volume using fslstats with the threshold options to select out just the single label number (by using -l and -u with -/+0.5 from the desired label number). For example, if the label number is 17 (Left Hippocampus) then you can use the following command:

fslstats output_name_all_fast_firstseg -l 16.5 -u 17.5 -V where the first number of the output is the number of voxels and the second is the volume in mm3.

Models

Advanced Usage

The following sections detail the more fundamental commands that the script run_first_all calls. If problems are encountered when running run_first_all, it is recommended that each of the individual stages described below be run separately in order to identify and fix the problem.

Registration

FIRST segmentation requires firstly that you run first_flirt to find the affine transformation to standard space, and secondly that you run run_first to segment a single structure (re-running it for each further structure that you require). These are both run by run_first_all which also produces a summary segmentation image for all structures.

Please note, if the registration stage fails then the models fitting will not work, despite the fact that run_first_all continues to run and may produce outputs.

first_flirt should be used on whole-head (non-betted) images. Although it is generally discouraged, the flag -b will allow first_flirt to also be used on brain extracted data.

first_flirt con01 con01_to_std_sub

This command uses the T1-weighted image con01.nii.gz as the input and will generate the registered (con01_to_std_sub.nii.gz) and the transformation matrix (con01_to_std_sub.mat).

You should verify that the registrations were successful prior to further processing (e.g. using ${FSLDIR}/bin/slicesdir -p ${FSLDIR}/data/standard/MNI152_T1_1mm.nii.gz *_to_std_sub.nii.gz). When assessing the registration, pay attention to the sub-cortical structures. Note that the cortex may not always align well, particularly where there are large ventricles.

Segmentation

where image_xfm_output_list.txt may look like, 

subject_1_t1     subject_1_t1_to_mni.mat     subject_1
subject_2_t1     subject_2_t1_to_mni.mat     subject_2
subject_3_t1     subject_3_t1_to_mni.mat     subject_3

By using the above command, FIRST would fit L_Thal_05mm.bmv to subject_1, subject_2, and subject_3. The output would be a nifti image, .bvars and .vtk output files, with the base names subject_1_L_Thal_n40, subject_2_L_Thal_n40, and subject_3_L_Thal_n40 respectively.

Boundary Correction

first_boundary_corr

This program is used for the classification of the boundary voxels in the volumetric output for a single structure. It takes the segmentation image output by run_first and classifies the boundary voxels as belonging to the structure or not. The output volume will have only a single label.

Usage:

first_boundary_corr -s segmented_image -i intensity_image -b method -o output_name

For the models contained in ${FSLDIR}/data/first/models_336_bin/05mm/, all boundary voxels are considered as belonging to the structure, and hence none is the appropriate correction method. This is done automatically by run_first_all.

first_mult_bcorr

This program is used to correct overlapping segmentations after boundary correction has been run on each structure independently. It requires the combined corrected and uncorrected segmentations (as separate 4D files) in addition to the original T1-weigthed image. This is called automatically by run_first.

Usage: first_mult_bcorr -i t1_image -c 4D_corrected_labels -u 4D_uncorrected_labels -o output_name

Any voxel labeled by two or more structures is re-classified as belonging to only one structure. This is based on how similar the intensity is to the intensity distributions of the interior voxels for the competing structures. However, if one structure labels the voxel as an interior voxel and the other labels it as a boundary voxel it will be classified as belonging to the interior of the former structure, regardless of its intensity.

Surface-based Vertex Analysis

This is the old method of vertex analysis, invoked using --surfaceout in first_utils, that is based on multivariate statistics, but is not recommended due to restrictions in the design matrices, contrasts and multiple-comparison-correction method. When using this option be aware that although it will also generate image outputs, the images outputs do not use the design matrix or do any statistical testing. It is only the multivariate statistics, as shown on the surface outputs, that use the design matrix.

Note: for more complicated design matrices, with multiple EVs, each EV is tested in turn (with an implicit contrast that is one for that EV and zero for all others). A separate test is run for each such contrast, so that N results are generated when there are N EVs. Also, the constant EV is always implicitly added and user-specified EVs are demeaned. The contrast never includes the constant EV.

Viewing surface outputs

The slider in the mesh controls panel in FSLVIEW will allow you to deform the mesh between the group means. The surface colouring is the multivariate F statistic (based on Pillai's Trace). The length of the vectors and the statistics are not linearly related - the former is dependent only on the mean difference between groups while the latter is a statistic that takes the variances into account.

For surface-based output the only available method of multiple-comparison-correction uses False Discovery Rate (FDR) correction via the utility surface_fdr.

surface_fdr

Usage:

surface_fdr input.vtk

Outputs:

Will create files input_Fthresh.vtk and input_pvals.vtk and some small image files (which can be ignored). The first mesh output, input_Fthresh.vtk is a mesh containing the thresholded F statistics; that is, those that survive the FDR thresholding. The second mesh output, input_pvals.vtk is a mesh containing the uncorrected p-values. The utility will also output the FDR threshold (as a p-value) when running. This FDR threshold can be used to threshold this p-value mesh to create the same significant areas as in the thresholded F-statistic mesh output.

Note that for surface output, as of FSL4.1.3, all surface files generated by vertex analysis contain the relevant Degrees Of Freedom and bvars files contain registration matrices (and are now in a binary format). Also, as substantial improvements in the sensitivity of the statistics were made between FSL4.1.2 and FSL4.1.3, it is recommended and necessary to re-run previous vertex analyses with the newer version of FIRST and not attempt to combine with outputs generated by previous versions.

General Advice and Workflow

To begin with, run the same steps as described above for Getting Started and Create a Design Matrix.

Note that in this mode FIRST will demean the design matrix and performs its own contrasts, therefore it is not necessary to set up contrasts in the Glm gui (they will be ignored) and it is not necessary to demean your EVs (FIRST will do this automatically) or include a constant EV (FIRST will do this too).

Running vertex analysis:

first_utils --vertexAnalysis --surfaceout --usebvars -i con_to_dis_L_Hipp.bvars -d con1_dis2.mat -o shape_analysis/con1_dis2_L_Hipp --useReconNative --useRigidAlign -v >& shape_analysis/con1_dis2_L_Hipp_output.txt

Note that the -v option displays the details of certain calculations to the command line and the >& option captures this output into a file (here called con1_dis2_L_Hipp_output.txt). This output may be useful to save.

Output of vertex analysis:

In the shape_analysis directory there will be a file called con1_dis2_L_Hipp1.vtk. This is the 3D mesh displaying the results of vertex analysis (the number 1 represents the first EV tested - in this case the only one). Open FSLView and add a standard brain. Start the 3D viewer and turn off the standard brain (this was simply added to get the 3D viewer started). Click the add mesh button and open the con1_dis2_L_Hipp1.vtk file. A 3D surface of the hippocampus will open with the uncorrected F stats for the difference between groups displayed at each vertex on the surface. Something like this (initially without the vectors, but see below):

vertexana.png

The colour bar indicates the statistic values; an increase from red to blue is going from a lower to higher statistical significance. Note that the colours only indicate where any difference between groups was found, not the direction of this difference. The vectors (little arrows shown on the surface) indicate the direction of change. Open the mesh properties window. Scale the vectors by a value of 2 to 5 for better visualization. These vectors point from the mean surface of whatever subjects corresponded to a value of 0 or less in the design matrix (demeaned EV1) to the mean surface of others subjects. In this case controls were given a value of 0 and diseased a value of 1. Therefore FIRST would have demeaned this design matrix so that controls had a value of -0.5 and diseased had a valued of +0.5. These vectors therefore point from the mean surface of control group (viewed by sliding the mesh slider to position 0) to the mean surface of diseased group (viewed by sliding the mesh slider to position 1). In this case, if the vector points inward at a given vertex, then that means that that vertex on the mean control surface moves inward to reach the same vertex on the mean diseased surface. For example, on the side of the hippocampus in the image above you can see a large patch of blue with vectors pointing inward. These vectors indicate that the direction of difference is such that the diseased hippocampus is smaller/thinner here than in the control group, consistent with local atrophy. Note that the vectors give direction while the colours indicate the statistical strength of the difference in any direction.

Running Multiple Comparison Correction:

Following this you should correct for multiple comparisons to get corrected statistics. Do this with:

surface_fdr con1_dis2_L_Hipp1.vtk

This generates an output called con1_dis2_L_Hipp1_Fthresh.vtk which you can then view in FSLView, in the same way as above, and only shows non-zero statistics where they survived the FDR multiple comparison correction. Note that an FDR threshold of zero means that no vertices have survived multiple comparison correction.

Other common design matrices:

Correlation

For correlation only (no group difference) you can create a design matrix with one column (EV) where each row contains the value of the correlating measure for each subject in the same order as the subject's bvars (in the concatenated bvars file). For example, to correlate age with shape, the design matrix would contain one EV, which would be a single column where each row has the age of each subject in the same order as the concatenated bvars file. There is no need to demean the age values, as FIRST will demean them for you.

Interpretting the results of a correlation: the colours on the surface of the mesh will display the strength of the correlation at each vertex, while the vectors will display the direction of the correlation. Surface 0 on the slider is the mean surface for all of the subjects younger than the mean age, while surface 1 on the slider is the mean surface for all of the subjects older than the mean age. The vectors point from surface 0 to surface 1, which is from the younger group to the older.

You can also do correlation with a covariate (see below). This gives you statistics as explained above (but accounting for the other EVs) but the interpretation of the vectors will no longer be the same as that described above, but will instead depend only on the groupings defined by the first column of the design matrix (EV1).

Covariate

To add a covariate to a group difference study, simple add a second column to the design matrix for the group difference. This second column should contain the raw scores (for each subject in the same order as the concatenated bavrs file) of the measure you wish to use as a covariate; for example, age. Vertex analysis will now produced two vtk files, with one file called output_name1.vtk, showing the areas of group difference after accounting for the covariate. The file called output_name2.vtk, on the other hand, will show the areas that correlate with the covariate (e.g. age) after accounting for group difference.

Note that the mean surfaces and vectors will be the same in each case (although vectors only show at vertices where the statistics were significant, and these statistics will vary) since the mean surfaces and vectors are always defined by the grouping in the first column of the design matrix (EV1), with the first group being all values below the mean and the second group being all values above the mean.

first_utils

This command can be used to fill meshes, as well as for running vertex analysis.

first_utils --meshToVol -m mesh.vtk -i t1_image.nii.gz -l fill_value -o output_name

Labels

10 Left-Thalamus-Proper 40
11 Left-Caudate 30
12 Left-Putamen 40
13 Left-Pallidum 40
16 Brain-Stem /4th Ventricle 40
17 Left-Hippocampus 30
18 Left-Amygdala 50
26 Left-Accumbens-area 50
49 Right-Thalamus-Proper 40
50 Right-Caudate 30
51 Right-Putamen 40
52 Right-Pallidum 40
53 Right-Hippocampus 30
54 Right-Amygdala 50
58 Right-Accumbens-area 50

2014-07-08 15:33