#pragma section-numbers 1
[[Tutorials|Back to Tutorial Homepage]] | [[FsTutorial|Back to Course Homepage]] | [[MultiModalTutorialV6.0|Back to Multimodal Tutorial List]]

----
Other Multimodal Tutorials: [[MultiModalTutorialV6.0/MultiModalRegistration|Multimodal Registration]], [[MultiModalTutorialV6.0/FMRIGroupAnalysis|Surface-based Group fMRI Analysis]], [[FsTutorial/DiffusionV6.0|Diffusion and DTI Integration]]

----
{{{#!html
<h1>Individual fMRI Integration</h1>
}}}
----
The purpose of this tutorial is to get you acquainted with the concepts needed to perform fMRI integration in !FreeSurfer by interacting with the data from an individual subject. You will not learn how to perform fMRI analysis here; that knowledge is already assumed. This tutorial also does not assume any particular directory structure (as would happen in FS-FAST). This tutorial makes use of data from the Functional Biomedical Informatics Research Network (fBIRN).

<<TableOfContents(1)>>

= fMRI Basics =
In fMRI, stimuli are presented to a subject, which induces a BOLD hemodynamic response function (HRF) in certain areas of the brain. The analysis is performed by first using motion correction, then correlating each voxel's time course with the stimulus schedule convolved with an assumed HRF shape. The result is an estimate of the HRF amplitude for each condition at each voxel, contrasts of the HRF amplitudes of various conditions, the variance of this contrast, and some measure of the signficance (eg, p, t, F, or z) map. All these maps are aligned with the motion correction template (from the functional analysis), which should be used as the registration template.

For a tutorial in resting state analysis, click here: FsFastFunctionalConnectivityWalkthrough

= Preparations =
== If You're at an Organized Course ==
If you are taking one of the formally organized courses, everything has been set up for you on the provided laptop. The only thing you will need to do is run the following commands in ''every'' '''new''' terminal window (aka shell) you open throughout this  tutorial. Copy and paste the commands below to get started:

{{{
export SUBJECTS_DIR=$TUTORIAL_DATA/buckner_data/tutorial_subjs
cd $SUBJECTS_DIR/multimodal/fmri/fbirn-101
}}}
''To copy: Highlight the command in the box above, right click and select copy (or use keyboard shortcut Ctrl+c), then use the middle button of your mouse to click inside the terminal window to paste the command (or use keyboard shortcut Ctrl+Shift+v). Press enter to run the command.''

These two commands set the SUBJECTS_DIR variable to the directory where the data is stored and then navigates into the directory within the  SUBJECTS_DIR that you will use for this part of the tutorial. You can now skip ahead to the tutorial (below the gray line).

== If You're Not at an Organized Course ==
If you are '''NOT''' taking one of the formally organized courses, then to follow this exercise exactly be sure you've downloaded the [[FsTutorial/Data|tutorial data set]] before you begin. If you choose not to download the data set you can follow these instructions on your own data, but you will have to substitute your own specific paths and subject names. These are the commands that you need to run before getting started:

{{{
## bash
<source_freesurfer>
export TUTORIAL_DATA=<path_to_your_tutorial_data>
export SUBJECTS_DIR=$TUTORIAL_DATA/buckner_data/tutorial_subjs
cd $SUBJECTS_DIR/multimodal/fmri/fbirn-101

## tcsh
source $FREESURFER_HOME/SetUpFreeSurfer.csh
setenv TUTORIAL_DATA <path_to_your_tutorial_data>
setenv SUBJECTS_DIR $TUTORIAL_DATA/buckner_data/tutorial_subjs
cd $SUBJECTS_DIR/multimodal/fmri/fbirn-101
}}}
''Information on how to source [[https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurfer|FreeSurfer]] is located [[https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall#Setup+&+Configuration|here]]''.

If you are not using the tutorial data you should set your {{{SUBJECTS_DIR}}} to the directory in which the recon(s) of the subject(s) you will use for this tutorial are located.

--------
The directory you are currently in is one of 5 subjects from the fBIRN Phase I acquisition. The subjects are called fbirn-10?, where "?" is 1, 3, 4, 5, 6 (note that #2 is missing).  Each has a !FreeSurfer reconstruction by the name fbirn-anat-10?.v6 (anat is short for anatomical). This tutorial will only deal with subject fbirn-101 (but you can run the same commands on any of the subjects).

The data are the results from a sensorimotor paradigm (flashing checkerboard, audible tone, and finger tapping). The raw fMRI data was motion corrected but not smoothed. Each subject has four volumes (output from the fMRI analysis, which in this case, was done with FS-FAST):
||template.nii ||motion correction template (from functional analysis) ||
||ces.nii ||contrast effect size ||
||cesvar.nii ||variance of contrast effect size ||
||sig.nii ||signed significance of contrast (-log10(p)) ||




The contrast is the contrast between the ON and the OFF of the stimulus paradigm (i.e., a comparison against baseline). The sig.nii volume has signed -log10(p) values. So, if the p-value = .01, -log10(p) = 2. If the contrast was positive (i.e., ON>OFF), then the value would be +2, if negative (i.e., ON<OFF), then the value would be -2.

= Check Registration =
First (and always), check the registration (we learned how to register the functional volume and anatomical surfaces in the [[MultiModalTutorialV6.0/MultiModalRegistration|Registration Tutorial]] - in this case, register.lta is the output of that step). Note, this registration should already be good, so there is no need to make any modifications.

{{{
freeview -v $SUBJECTS_DIR/fbirn-anat-101.v6/mri/orig.mgz:visible=0 \
    template.nii:reg=register.lta -f \
    $SUBJECTS_DIR/fbirn-anat-101.v6/surf/lh.white \
    $SUBJECTS_DIR/fbirn-anat-101.v6/surf/rh.white \
    -viewport cor -transform-volume
}}}
After clicking on the template volume, use Alt+c to toggle between the template and the orig, using the surfaces as a guide to make sure they are aligned.

= View sig map on anatomical volume =
{{{
freeview -v $SUBJECTS_DIR/fbirn-anat-101.v6/mri/orig.mgz \
    $SUBJECTS_DIR/fbirn-anat-101.v6/mri/aparc+aseg.mgz:colormap=lut:opacity=0.2 \
    sig.nii:reg=register.lta:colormap=heat:heatscale=2,2,4 -colorscale \
    -viewport coronal
}}}
Note: This command will load this subject's anatomical data - orig.mgz - as well as the cortical and subcortical segmentations (all output from recon-all). We load the significance map (again, output from the fMRI analysis) and the registration file we created earlier so that the sig map is correctly overlaid on the anatomical data.

You can now scroll through this subject to see what areas of the brain show a significant value.

{{attachment:sigmap.jpg||width="419",height="380"}}

Notes:

 1. ON>OFF is red/yellow.
 1. ON<OFF is blue/cyan.
 1. Notice activation in motor, auditory, and visual regions.
 1. As you click on the volume loaded in freeview, you will see the value change next to "sig" in the Cursor and Mouse windows below the main viewing window. The value next to "aparc+aseg" will change as well.
 1. Note that the 'min' value to the left of the viewing window is given a value of 2. This refers to the minimum functional value of the voxels you want to be shown on the overlay (and since we loaded the sig map, the "functional value" in this case are the sig values of the voxels).
 1. Functional value is the -log 10(p-value) which makes the p-value here 0.01.
 1. Also note that areas that are not above threshold will still have non-zero functional values (seen if you hover over a voxel that does not have a red or blue sig voxel on it).
 1. The max value is really a saturation value, i.e. if the functional value is above the maximum (or below -max) the color does not change. That is why you will see voxels with values greater than 4 (or less than -4) that still have a red or blue sig voxel on it.

Things to do:

 1. You can make the overlay visible or not visible by checking/unchecking the box next to "sig" in the 'Volumes' list to the left of the main viewing window.
 1. To understand and experiment with this image further, try changing the ''Min'' and ''Max'' values in the sliders to the left, which are currently set at 2 and 4, respectively. You can either move the slider or enter a new value and hit Enter.

= View sig map on left hemisphere =
Before you can view the fMRI data on the (inflated) surface, you must resample the data onto the surface:

{{{
mri_vol2surf --mov sig.nii \
    --reg register.lta \
    --projfrac 0.5 --interp nearest \
    --hemi lh --o lh.sig.mgh
}}}
Notes:

 1. The "moveable" (--mov) is the signficance map (which is in line with the template.nii used for registration).
 1. "--projfrac 0.5" indicates that the significance should be sampled half way between the white and pial surfaces.
 1. "--interp nearest" means use nearest neighbor interpolation (this is better for significance maps as it reduces smoothing).

The output is lh.sig.mgh, which is the significance sampled onto the left hemisphere. It has the same size as any other surface overlay for this subject, eg, lh.thickness. To see it's dimensions, run:

{{{
mri_info lh.sig.mgh
}}}
You will see "dimensions: 164660 x 1 x 1", indicating that there are 164660 "columns", which is the number of vertices in the surface.

To actually view the significance sampled on the left hemisphere surface:

{{{
freeview -f $SUBJECTS_DIR/fbirn-anat-101.v6/surf/lh.inflated:annot=aparc.annot:annot_outline=1:overlay=lh.sig.mgh:overlay_threshold=2,5 \
    -viewport 3d
}}}
{{attachment:sigmaplh.jpg}}

{{attachment:sigmaplh_medial.jpg}}

As you click on the surface loaded in freeview, you will see the  value change next to "lh.sig.mgh" in the Cursor and Mouse window below the main  viewing window. The value next to  "aparc.annot" (which indicates which region of the cortex you're in) will change as well .

Things to Note:

 1. As mentioned in the previous section, the example we've considered here is the result from administering a sensorimotor task. The activation can be seen in the corresponding regions- Auditory cortex (Temporal lobe), Visual cortex (Occipital lobe), and Motor cortex (Parietal lobe).
 1. Click on a point on the surface and notice the label change.
 1. Change the min and max threshold values and notice how the overlay changes. To do this, click '''Configure''' in the sidebar. This brings up an interface which looks as follows. The min and max threshold values are currently set to 2 and 5, respectively.

{{attachment:configure_overlay_v6_menu.jpg||width="395",height="627"}}

= ROI Analysis without a Functional Constraint =
In this section, we will compute the average HRF contrast (ces) in some ROIs. First, we need to resample the ces.nii volume into the individual's anatomical space using {{{mri_vol2vol}}}. You cannot perform ROI analysis without first resampling your data into the individual's anatomic space.

{{{
mri_vol2vol --mov ces.nii \
    --reg register.lta \
    --fstarg --interp nearest \
    --o ces.anat.bb.mgh
}}}
Notes:

 1. "--fstarg" means to sample the data into the anatomical space
 1. Nearest-neighbor (--interp nearest) because we will average within each ROI so we do not want averaging from interpolation.

The output is ces.anat.bb.mgh. Look at its dimensions:

{{{
mri_info ces.anat.bb.mgh
}}}
Note that it is 256x256x256 with each voxel being 1mm isotropic. This is the same size as the !FreeSurfer anatomical.

Now run the segmentation statistics:

{{{
mri_segstats \
   --seg $SUBJECTS_DIR/fbirn-anat-101.v6/mri/aparc+aseg.mgz \
   --ctab $FREESURFER_HOME/FreeSurferColorLUT.txt \
   --id 1021 --id 1022 --id 1030  --id 17 \
   --i ces.anat.bb.mgh --sum ces.bb.stats
}}}
Notes:

 1. The subject's own aparc+aseg.mgz is used.
 1. Segmentation names (--id) come from the LUT. Click [[FsTutorial/AnatomicalROI/FreeSurferColorLUT|here]] to view the contents of the LUT file.
 1. A report on only 4 segmentations are requested (1021=ctx-lh-pericalcarine, 1022=ctx-lh-postcentral, 1030=ctx-lh-superiortemporal, and 17=Left-Hippocampus). The first three are related to the paradigm.
 1. The input is ces.anat.bb.mgh.

Look at the output ces.bb.stats in a text viewer (or click [[MultiModalTutorialV6.0/BBStats#ces.bb.stats|here]]). It has a format similar to the aseg.stats file in each subject's stats directory.  The "Mean" here is the average HRF amplitude in the given ROI in raw MR units (example: the average HRF amplitude in ctx-lh-pericalcarine is 107.7495, and the volume of the ctx-lh-pericalcarine segmentation is 2752.0.

= ROI Analysis with an Unsigned Functional Constraint =
In this section, we will compute the average HRF contrast (ces) in anatomical ROIs constrained by unsigned (positive or negative) functional activation. First, we need to resample the sig.nii volume into the  individual's anatomical space. As a reminder: You cannot perform ROI analysis without first resampling your data into the individual's anatomic space.

{{{
mri_vol2vol --mov sig.nii \
    --reg register.lta \
    --fstarg --interp nearest \
    --o sig.anat.bb.mgh
}}}
Notes:

 1. "--fstarg" means to sample the data into the anatomical space.
 1. Nearest-neighbor (--interp nearest) because this is a significance volume.

Now run the segmentation statistics with the functional constraint:

{{{
mri_segstats \
   --seg $SUBJECTS_DIR/fbirn-anat-101.v6/mri/aparc+aseg.mgz \
   --ctab $FREESURFER_HOME/FreeSurferColorLUT.txt \
   --id 1021 --id 1022 --id 1030  --id 17 \
   --i ces.anat.bb.mgh --sum ces.abs-masked.bb.stats \
   --mask sig.anat.bb.mgh --maskthresh 2 --masksign abs
}}}
Notes:

 1. The mask is the signficance map.
 1. The threshold is 2 (p<.01).
 1. "--masksign abs" means to use any voxel that exceeds threshold regardless of its sign.

Look at the output ces.abs-masked.bb.stats in a text viewer (or click [[MultiModalTutorialV6.0/BBStats#ces.abs-masked.bb.stats|here]]). The "Mean" for ctx-lh-pericalcarine is now 182.5064, an increase of 69.4%. This increase is due to the voxels with no signal being excluded from the ROI average. The volume is now 1530.0 mm3, meaning that 55.6% (1530.0/2752.0) of the ROI is above threshold.

= ROI Analysis with a Positive Functional Constraint =
In this section, we will compute the average HRF contrast (ces) in anatomical ROIs constrained by positive functional activation only. Run the segmentation statistics with the functional constraint, below. You do not need to run {{{mri_vol2vol}}} if you did this in the previous section (ROI Analysis with an Unsigned Functional Constraint).

{{{
mri_vol2vol --mov sig.nii \
    --reg register.lta \
    --fstarg --interp nearest \
    --o sig.anat.bb.mgh
}}}
{{{
mri_segstats \
   --seg $SUBJECTS_DIR/fbirn-anat-101.v6/mri/aparc+aseg.mgz \
   --ctab $FREESURFER_HOME/FreeSurferColorLUT.txt \
   --id 1021 --id 1022 --id 1030  --id 17 \
   --i ces.anat.bb.mgh --sum ces.pos-masked.bb.stats \
   --mask sig.anat.bb.mgh --maskthresh 2 --masksign pos
}}}
Notes:

 1. "--masksign pos" means to use any voxel that exceeds threshold and has a positive sign.

Look at the output ces.pos-masked.bb.stats in a text viewer (or click [[MultiModalTutorialV6.0/BBStats#ces.pos-masked.bb.stats|here]]). The "Mean" for ctx-lh-pericalcarine is now 200.5127, an increase of nearly 10% over the unsigned case. The increase is because some of the voxels in the unsigned case are negative, reducing the ROI average. Note that the volume has also dropped to 1422.0 mm3 because the negative voxels have been removed. Note: in this case the Mean will always be positive because we have constrained it that way!

----
= Summary =
By the end of this exercise, you should know how to:
 * View significance maps on the anatomical volume
 * View significance maps on the inflated surface
 * Run the ROI analysis using mri_segstats without functional constraints, with an unsigned functional constraint, and with a positive functional constraint

----
= Quiz =
You can test your knowledge of this tutorial by [[https://forms.gle/tDXibsNs4DS5fnPk7|clicking here]] for a quiz!

-----

----
Other Multimodal Tutorials: [[MultiModalTutorialV6.0/MultiModalRegistration|Multimodal Registration]], [[MultiModalTutorialV6.0/FMRIGroupAnalysis|Surface-based Group fMRI Analysis]], [[FsTutorial/DiffusionV6.0|Diffusion and DTI Integration]]

[[Tutorials|Back to Tutorial Homepage]] | [[FsTutorial|Back to Course Homepage]] | [[MultiModalTutorialV6.0|Back to Multimodal Tutorial List]]