Differences between revisions 15 and 16
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
[[FsFastTutorialV5.1_freeview|top]] | [[FsFastTutorialV5.1/FsFastDirStruct_freeview|previous (Directory Structure)]]| [[FsFastTutorialV5.1/FsFastFirstLevel_freeview|next (First Level Analysis)]]
<<TableOfContents>>
[[FsFastTutorialV5.1_freeview|top]] | [[FsFastTutorialV5.1/FsFastDirStruct_freeview|previous (Directory Structure)]]| [[FsFastTutorialV5.1/FsFastFirstLevel_freeview|next (First Level Analysis)]] <<TableOfContents>>
Line 5: Line 5:
Once the data have been arranged in the proper directory structure and
naming convention, they are ready to be preprocessed. Preprocessing includes
  1. Template Creation
  1. Brain Mask Creation
  1. Registration with FreeSurfer Anatomical
  1. Motion Correction
  1. Slice Timing Correction (if using)
  1. Spatial Normalization
  1. Masking
  1. Spatial Smoothing
Once the data have been arranged in the proper directory structure and naming convention, they are ready to be preprocessed. Preprocessing includes

1. Template Creation
 1. Brain Mask Creation
 1. Registration with FreeSurfer Anatomical
 1. Motion Correction
 1. Slice Timing Correction (if using)
 1. Spatial Normalization
 1. Masking
 1. Spatial Smoothing
Line 16: Line 17:
  * Left Cortical Hemisphere
  * Right Cortical Hemisphere
  * Subcortical Structures (Volume-based)
You will need to decide how much to smooth the data and whether you
want to do slice-timing correction. In this analysis, we will smooth
the data by 5mm Full-Width/Half-Max (FWHM) and correct for slice
timing. The slice-timing for this particular data set was 'Ascending',
meaning that the first slice was acquired first, the second slice was
acquired second, etc. To preprocess the data, run:

* Left Cortical Hemisphere
 * Right Cortical Hemisphere
 * Subcortical Structures (Volume-based)

You will need to decide how much to smooth the data and whether you want to do slice-timing correction. In this analysis, we will smooth the data by 5mm Full-Width/Half-Max (FWHM) and correct for slice timing. The slice-timing for this particular data set was 'Ascending', meaning that the first slice was acquired first, the second slice was acquired second, etc. To preprocess the data, run:
Line 31: Line 30:
This data has already been preprocessed, so it should just verify that
it is up-to-date, finishing in a few seconds. This command has several
arguments:
  * -s sess01 : indicates which session to preprocess
  * -fsd bold : indicate the functional subdirectory (FSD)
  * -stc up : slice-timing correction with ascending ('up') slice order
  * -surface fsaverage lhrh : indicates that data should be sampled to the left and right hemispheres of the 'fsaverage' subject
  * -mni305 : indicates that data should be sampled to the mni305 volume (2mm isotropic voxel size)
  * -fwhm 5 : smooth by 5mm FWHM after resampling (volume and surface separately)
  * -per-run : register each run separately
This command does a lot, and it can take quite a long time to run,
especially for many subjects. Look at the contents of one of the
run directories:
This data has already been preprocessed, so it should just verify that it is up-to-date, finishing in a few seconds. If the program runs for a while, just cancel it by typing Ctrl+C. You should already have the output data available to you and can proceed to the next step.

This command has several arguments:

* -s sess01 : indicates which session to preprocess
 * -fsd bold : indicate the functional subdirectory (FSD)
 * -stc up : slice-timing correction with ascending ('up') slice order
 * -surface fsaverage lhrh : indicates that data should be sampled to the left and right hemispheres of the 'fsaverage' subject
 * -mni305 : indicates that data should be sampled to the mni305 volume (2mm isotropic voxel size)
 * -fwhm 5 : smooth by 5mm FWHM after resampling (volume and surface separately)
 * -per-run : register each run separately

This command does a lot, and it can take quite a long time to run, especially for many subjects. Look at the contents of one of the run directories:
Line 48: Line 48:
  * fmcpr.up.sm5.fsaverage.lh.nii.gz - Left hemisphere of fsaverage
  * fmcpr.up.sm5.fsaverage.rh.nii.gz = Right hemisphere of fsaverage
  * fmcpr.sm5.mni305.2mm.nii.gz - Volume of fsaverage (MNI305 space) - for subcortical analyses
These are time series data, and their names indicate what has been
performed on them:
  * fmcpr - motion correction, per-run
  * up - slice-timing correction using ascending
  * sm5 - smoothed by 5mm FWHM (after resampling)
  * fsaverage.lh - sampled on the surface of fsaverage left hemi
  * fsaverage.rh - sampled on the surface of fsaverage right hemi
  * mni305.2mm - sampled in the fsaverage (MNI305) volume at 2mm isotropic
{{attachment:fsfast.dirstruct.after-preproc.jpg|dirstruct|width=350}}

To learn more, see [[FsFastTutorialV5.1/FsFastPreProc_freeview#PreprocessingDetails|Preprocessing Details]] below.

* fmcpr.up.sm5.fsaverage.lh.nii.gz - Left hemisphere of fsaverage
 * fmcpr.up.sm5.fsaverage.rh.nii.gz = Right hemisphere of fsaverage
 * fmcpr.sm5.mni305.2mm.nii.gz - Volume of fsaverage (MNI305 space) - for subcortical analyses

These are time series data, and their names indicate what has been performed on them:

* fmcpr - motion correction, per-run
 * up - slice-timing correction using ascending
 * sm5 - smoothed by 5mm FWHM (after resampling)
 * fsaverage.lh - sampled on the surface of fsaverage left hemi
 * fsaverage.rh - sampled on the surface of fsaverage right hemi
 * mni305.2mm - sampled in the fsaverage (MNI305) volume at 2mm isotropic

{{attachment:fsfast.dirstruct.after-preproc.jpg|dirstruct|width="350"}}

To learn more, see [[#PreprocessingDetails|Preprocessing Details]] below.
Line 65: Line 69:
Line 68: Line 73:
'''NOTE: A proper installation of [[http://www.gnuplot.info/|gnuplot]] is required for this command to work.''' The output of this command is shown below. This gives the vector motion at each time point for each run. Note
that it is always positive because this is a magnitude. It is also 0
at the middle time point because the middle time point is used as the
reference.

{{attachment:plot-twf-sess.png||plot-twf-sess}}

There are no rules for how much motion is too much motion. Generally
speaking, sudden motions are the worst as are task-related motion.
'''NOTE: A proper installation of [[http://www.gnuplot.info/|gnuplot]] is required for this command to work.''' The output of this command is shown below. This gives the vector motion at each time point for each run. Note that it is always positive because this is a magnitude. It is also 0 at the middle time point because the middle time point is used as the reference.

{{attachment:plot-twf-sess.png}}

There are no rules for how much motion is too much motion. Generally speaking, sudden motions are the worst as are task-related motion.
Line 80: Line 81:
Line 84: Line 86:
Line 95: Line 98:
Line 96: Line 100:
  * Functional and structural are not the same subject (subjectname file is wrong)
  * The functional is left-right reversed
  * The initialization failed (happens sometimes with partial Field-of-View)

* Functional and structural are not the same subject (subjectname file is wrong)
 * The functional is left-right reversed
 * The initialization failed (happens sometimes with partial Field-of-View)
Line 100: Line 106:
Line 103: Line 110:
{{attachment:tkregister.gif|tkregister|width=200}} {{attachment:tkregister.gif|tkregister|width="200"}}
Line 107: Line 115:
If you want to learn more about using tkregister or freeview see [[FsTutorial/MultiModalRegistration_freeview| Multimodal Tutorial]].
If you want to learn more about using tkregister or freeview see [[FsTutorial/MultiModalRegistration_freeview|Multimodal Tutorial]].
Line 109: Line 119:
  * What would the preproc-sess command be to analyze session sess02? [[FsFastTutorialV5.1/StudyAnswers#PreProcSess02|Answer]]
  * What would the preproc-sess command be to smooth by 7mm FWHM? [[FsFastTutorialV5.1/StudyAnswers#PreProcFWHM7|Answer]]
  * What would the preproc-sess command be to analyze data in a functional subdirectory called 'rest'? [[FsFastTutorialV5.1/StudyAnswers#PreProcRest|Answer]]
  * What would the preproc-sess command be if you did not want to use slice-timing correction? [[FsFastTutorialV5.1/StudyAnswers#PreProcSTC|Answer]]
 * What would the preproc-sess command be to analyze session sess02? [[FsFastTutorialV5.1/StudyAnswers#PreProcSess02|Answer]]
 * What would the preproc-sess command be to smooth by 7mm FWHM? [[FsFastTutorialV5.1/StudyAnswers#PreProcFWHM7|Answer]]
 * What would the preproc-sess command be to analyze data in a functional subdirectory called 'rest'? [[FsFastTutorialV5.1/StudyAnswers#PreProcRest|Answer]]
 * What would the preproc-sess command be if you did not want to use slice-timing correction? [[FsFastTutorialV5.1/StudyAnswers#PreProcSTC|Answer]]
Line 114: Line 125:
Line 115: Line 127:
You do NOT need to perform the steps below to understand the rest of the tutorial. This is provided to allow you to understand the inner workings of FSFAST Preprocessing better.
Go back into one of the run directories and see what preproc-sess creates. To do this,
You do NOT need to perform the steps below to understand the rest of the tutorial. This is provided to allow you to understand the inner workings of FSFAST Preprocessing better. Go back into one of the run directories and see what preproc-sess creates. To do this,
Line 121: Line 133:
This directory previously held only f.nii.gz, workmem.par, and
wmfir.par before preprocessing. Now there are a lot of files, each
indicative of a different preprocessing stage. Now type
This directory previously held only f.nii.gz, workmem.par, and wmfir.par before preprocessing. Now there are a lot of files, each indicative of a different preprocessing stage. Now type
Line 127: Line 138:
This command sorts the files by creation time with the oldest at the
top and the newest at the bottom. The preprocessing is progressive,
meaning that the output of one stage is the input to the next.
This command sorts the files by creation time with the oldest at the top and the newest at the bottom. The preprocessing is progressive, meaning that the output of one stage is the input to the next.
Line 131: Line 141:
This stage creates template.nii.gz (and template.log). This is the
middle time point from the raw functional data (f.nii.gz). This is
the reference used to motion correct and register the functionals
for this run to the anatomical. It is also used to create masks of the
brain.
This stage creates template.nii.gz (and template.log). This is the middle time point from the raw functional data (f.nii.gz). This is the reference used to motion correct and register the functionals for this run to the anatomical. It is also used to create masks of the brain.
Line 137: Line 144:
Line 138: Line 146:
The masks for this run are stored in the 'masks' directory. Run 'ls
-ltr masks'. You will see a file called 'brain.nii.gz'. This is a
binary mask created using the FSL BET program. There is also a file
called 'brain.e3.nii.gz' which is the mask eroded by three
voxels. These have the same dimensions as the template. View the masks
with:
The masks for this run are stored in the 'masks' directory. Run 'ls -ltr masks'. You will see a file called 'brain.nii.gz'. This is a binary mask created using the FSL BET program. There is also a file called 'brain.e3.nii.gz' which is the mask eroded by three voxels. These have the same dimensions as the template. View the masks with:
Line 150: Line 154:

You can play with the opacity of the mask by moving the opacity slider or entering a new value less than 1 and hitting enter.
The brain.nii.gz is used to constrain voxel-wise operations. The
eroded mask (brain.e3.nii.gz) is used to compute the mean functional
value used for intensity normalization and global mean time
course. There are other masks there that we will get to later.
You can play with the opacity of the mask by moving the opacity slider or entering a new value less than 1 and hitting enter.  The brain.nii.gz is used to constrain voxel-wise operations. The eroded mask (brain.e3.nii.gz) is used to compute the mean functional value used for intensity normalization and global mean time course. There are other masks there that we will get to later.
Line 157: Line 157:
By default, FSFAST will scale the intensities of all voxels and time
points to help assure that they are of the same value across runs,
sessions, and subjects. It does this by dividing by the mean across
all voxels and time points inside the brain.e3.nii.gz mask, then
multiplying by 100. This value is stored in global.meanval.dat. This
is a simple text file which you can view. At this point, this value is
stored and used later. A waveform is also constructed of the mean at
each time point (text file global.waveform.dat). This can be used as a
nuisance regressor.
By default, FSFAST will scale the intensities of all voxels and time points to help assure that they are of the same value across runs, sessions, and subjects. It does this by dividing by the mean across all voxels and time points inside the brain.e3.nii.gz mask, then multiplying by 100. This value is stored in global.meanval.dat. This is a simple text file which you can view. At this point, this value is stored and used later. A waveform is also constructed of the mean at each time point (text file global.waveform.dat). This can be used as a nuisance regressor.
Line 167: Line 160:
Line 168: Line 162:
The next six files (init.register.dof6.dat, register.dof6.dat,
register.dof6.dat.mincost, register.dof6.dat.sum,
register.dof6.dat.log, register.dof6.dat.param) deal with the
registration from the functional to the same-subject FreeSurfer
anatomical. There are only two files here that are really
important: register.dof6.dat and register.dof6.dat.mincost.
The next six files (init.register.dof6.dat, register.dof6.dat, register.dof6.dat.mincost, register.dof6.dat.sum, register.dof6.dat.log, register.dof6.dat.param) deal with the registration from the functional to the same-subject FreeSurfer anatomical. There are only two files here that are really important: register.dof6.dat and register.dof6.dat.mincost.
Line 176: Line 166:
     the quality of the registration.
The registration is will be revisited below when we talk about Quality
Assurance
  . the quality of the registration.

The registration is will be revisited below when we talk about Quality Assurance
Line 180: Line 171:
The motion correction stage produces these files: fmcpr.mat.aff12.1D,
fmcpr.nii.gz, mcprextreg, mcdat2extreg.log, fmcpr.nii.gz.mclog,
fmcpr.mcdat. There are only three important file here:
  * fmcpr.nii.gz -- this is the motion corrected functional data. It has the same size and dimension as the raw functional data.
  * fmcpr.mcdat - text file of the amount of motion at each time point. This is important for Quality Assurance (see below).
  * mcprextreg - text file of the motion correction parameters assembled into an orthogonalized matrix that can be used as nuisance regressors
  * Verify that fmcpr.nii.gz has the same dimension as f.nii.gz using mri_info.
The motion correction stage produces these files: fmcpr.mat.aff12.1D, fmcpr.nii.gz, mcprextreg, mcdat2extreg.log, fmcpr.nii.gz.mclog, fmcpr.mcdat. There are only three important file here:

* fmcpr.nii.gz -- this is the motion corrected functional data. It has the same size and dimension as the raw functional data.
 * fmcpr.mcdat - text file of the amount of motion at each time point. This is important for Quality Assurance (see below).
 * mcprextreg - text file of the motion correction parameters assembled into an orthogonalized matrix that can be used as nuisance regressors
 * Verify that fmcpr.nii.gz has the same dimension as f.nii.gz using mri_info.
Line 188: Line 179:
Slice-timing correction compensates for the fact that each of the 30
slices was acquired separately over the course of 2 sec. It does this
by interpolating between time points to align each slice to the time
of the middle of the TR. The file created with this is fmcpr.up.nii.gz
(and fmcpr.up.nii.gz.log).
  * Verify that fmcpr.up.nii.gz has the same dimension as f.nii.gz using mri_info.
Slice-timing correction compensates for the fact that each of the 30 slices was acquired separately over the course of 2 sec. It does this by interpolating between time points to align each slice to the time of the middle of the TR. The file created with this is fmcpr.up.nii.gz (and fmcpr.up.nii.gz.log).

 * Verify that
fmcpr.up.nii.gz has the same dimension as f.nii.gz using mri_info.
Line 195: Line 184:
At this point, the functional data has stayed in the 'native
functional space', ie, 64x64x30, 3.4x3.4x5mm3. Now it will be sampled
into the 'Common Space'. The Common Space is a geometry where all
subjects are in voxel-for-voxel registration. There are three such
spaces in FSFAST:
  * Left hemisphere of fsaverage (fmcpr.up.sm5.fsaverage.lh.nii.gz)
  * Right hemisphere of fsaverage (fmcpr.up.sm5.fsaverage.rh.nii.gz)
  * Volume of fsaverage (MNI305 space) - for subcortical analyses (fmcpr.sm5.mni305.2mm.nii.gz)
Each of these is the entire 4D functional data set resampled into the
common space. The spatial smoothing is performed after
resampling. Surface-based (2D) smoothing is used for the surfaces; 3D
for the volumes.
Check the dimensions of the MNI305 space volume:
At this point, the functional data has stayed in the 'native functional space', ie, 64x64x30, 3.4x3.4x5mm3. Now it will be sampled into the 'Common Space'. The Common Space is a geometry where all subjects are in voxel-for-voxel registration. There are three such spaces in FSFAST:

* Left hemisphere of fsaverage (fmcpr.up.sm5.fsaverage.lh.nii.gz)
 * Right hemisphere of fsaverage (fmcpr.up.sm5.fsaverage.rh.nii.gz)
 * Volume of fsaverage (MNI305 space) - for subcortical analyses (fmcpr.sm5.mni305.2mm.nii.gz)

Each of these is the entire 4D functional data set resampled into the common space. The spatial smoothing is performed after resampling. Surface-based (2D) smoothing is used for the surfaces; 3D for the volumes. Check the dimensions of the MNI305 space volume:
Line 212: Line 196:
The dimension will be '76 76 93 142' meaning that there are 76
columns, 76 rows, 93 slices but still 142 time points (same as the raw
data). The resolution will be '2.0 2.0 2.0 2000' meaning that each
voxel is 2mm in size and the TR is still 2 sec. The transformation
to this space is based on the 12DOF talairach.xfm created during the
FreeSurfer reconstruction.
Check the dimensions of the Left Hemisphere 'volume':
The dimension will be '76 76 93 142' meaning that there are 76 columns, 76 rows, 93 slices but still 142 time points (same as the raw data). The resolution will be '2.0 2.0 2.0 2000' meaning that each voxel is 2mm in size and the TR is still 2 sec. The transformation to this space is based on the 12DOF talairach.xfm created during the FreeSurfer reconstruction. Check the dimensions of the Left Hemisphere 'volume':
Line 223: Line 202:
The dimension is '163842 1 1 142'. This 'volume' has 163842 'columns',
1 'row', and 1 'slice' (still 142 time points). You are probably
confused right now. That's ok, it's natural. At this point the notion
of a 'volume' has been lost. Each 'voxel' is actually a vertex (of
which there are 163842 in the left hemisphere of fsaverage). Storing
it in a NIFTI 'volume' is just a convenience.
The 'resolution' is '1.0 1.0 1.0 2000'. The values for the first 3
dimensions are meaningless because there are no columns, rows, or
slices on the surface so the distances between them are
meaningless. The last value indicates the time between frames and is
still accurate (2 sec).
The transformation to this space is based on the surface-based
intersubject registration created during the FreeSurfer
reconstruction.<<BR>>
[[FsFastTutorialV5.1_freeview|top]] | [[FsFastTutorialV5.1/FsFastDirStruct_freeview|previous (Directory Structure)]]| [[FsFastTutorialV5.1/FsFastFirstLevel_freeview|next (First Level Analysis)]]
The dimension is '163842 1 1 142'. This 'volume' has 163842 'columns', 1 'row', and 1 'slice' (still 142 time points). You are probably confused right now. That's ok, it's natural. At this point the notion of a 'volume' has been lost. Each 'voxel' is actually a vertex (of which there are 163842 in the left hemisphere of fsaverage). Storing it in a NIFTI 'volume' is just a convenience. The 'resolution' is '1.0 1.0 1.0 2000'. The values for the first 3 dimensions are meaningless because there are no columns, rows, or slices on the surface so the distances between them are meaningless. The last value indicates the time between frames and is still accurate (2 sec). The transformation to this space is based on the surface-based intersubject registration created during the FreeSurfer reconstruction.<<BR>> [[FsFastTutorialV5.1_freeview|top]] | [[FsFastTutorialV5.1/FsFastDirStruct_freeview|previous (Directory Structure)]]| [[FsFastTutorialV5.1/FsFastFirstLevel_freeview|next (First Level Analysis)]]

top | previous (Directory Structure)| next (First Level Analysis)

1. Introduction to FSFAST Preprocessing

Once the data have been arranged in the proper directory structure and naming convention, they are ready to be preprocessed. Preprocessing includes

  1. Template Creation
  2. Brain Mask Creation
  3. Registration with FreeSurfer Anatomical

  4. Motion Correction
  5. Slice Timing Correction (if using)
  6. Spatial Normalization
  7. Masking
  8. Spatial Smoothing

In FS-FAST, it is assumed that each data set will be analyzed in three normalization spaces:

  • Left Cortical Hemisphere
  • Right Cortical Hemisphere
  • Subcortical Structures (Volume-based)

You will need to decide how much to smooth the data and whether you want to do slice-timing correction. In this analysis, we will smooth the data by 5mm Full-Width/Half-Max (FWHM) and correct for slice timing. The slice-timing for this particular data set was 'Ascending', meaning that the first slice was acquired first, the second slice was acquired second, etc. To preprocess the data, run:

export SUBJECTS_DIR=$TUTORIAL_DATA/fsfast-tutorial.subjects
cd $TUTORIAL_DATA/fsfast-functional

preproc-sess -s sess01 -fsd bold -stc up -surface fsaverage lhrh -mni305 -fwhm 5 -per-run

This data has already been preprocessed, so it should just verify that it is up-to-date, finishing in a few seconds. If the program runs for a while, just cancel it by typing Ctrl+C. You should already have the output data available to you and can proceed to the next step.

This command has several arguments:

  • -s sess01 : indicates which session to preprocess
  • -fsd bold : indicate the functional subdirectory (FSD)
  • -stc up : slice-timing correction with ascending ('up') slice order
  • -surface fsaverage lhrh : indicates that data should be sampled to the left and right hemispheres of the 'fsaverage' subject
  • -mni305 : indicates that data should be sampled to the mni305 volume (2mm isotropic voxel size)
  • -fwhm 5 : smooth by 5mm FWHM after resampling (volume and surface separately)
  • -per-run : register each run separately

This command does a lot, and it can take quite a long time to run, especially for many subjects. Look at the contents of one of the run directories:

ls $TUTORIAL_DATA/fsfast-functional/sess01/bold/001

You will see many files there, but there are three important ones:

  • fmcpr.up.sm5.fsaverage.lh.nii.gz - Left hemisphere of fsaverage
  • fmcpr.up.sm5.fsaverage.rh.nii.gz = Right hemisphere of fsaverage
  • fmcpr.sm5.mni305.2mm.nii.gz - Volume of fsaverage (MNI305 space) - for subcortical analyses

These are time series data, and their names indicate what has been performed on them:

  • fmcpr - motion correction, per-run
  • up - slice-timing correction using ascending
  • sm5 - smoothed by 5mm FWHM (after resampling)
  • fsaverage.lh - sampled on the surface of fsaverage left hemi
  • fsaverage.rh - sampled on the surface of fsaverage right hemi
  • mni305.2mm - sampled in the fsaverage (MNI305) volume at 2mm isotropic

dirstruct

To learn more, see Preprocessing Details below.

2. Quality Assurance

2.1. Motion Correction

The motion plots can be viewed with:

plot-twf-sess -s sess01 -fsd bold -mc

NOTE: A proper installation of gnuplot is required for this command to work. The output of this command is shown below. This gives the vector motion at each time point for each run. Note that it is always positive because this is a magnitude. It is also 0 at the middle time point because the middle time point is used as the reference.

plot-twf-sess.png

There are no rules for how much motion is too much motion. Generally speaking, sudden motions are the worst as are task-related motion.

2.2. Functional-Anatomical Cross-modal Registration

You can get a summary of registration quality using the following command:

tkregister-sess -s sess01 -s sess02 -s sess03 -fsd bold -per-run -bbr-sum

This prints out a value for each run for each session:

sess01     001    0.5740
sess01     002    0.5796
sess01     003    0.5832
sess01     004    0.5747
sess02     001    0.5159
sess03     001    0.6021
  • The first column is the Session ID
  • The second columnn is the Run inside the Session
  • The third value is the QA value. It will be between 0 and 1, with 0 being perfect and 1 being terrible.

Actual values depend upon exactly how you have acquired your data. Generally, anything over 0.8 indicates that something is probably wrong, such as:

  • Functional and structural are not the same subject (subjectname file is wrong)
  • The functional is left-right reversed
  • The initialization failed (happens sometimes with partial Field-of-View)

You can view registrations using the following command:

tkregister-sess -s sess02 -fsd bold -per-run

tkregister

  • This will display the registration for each of the runs in tkregister2.
  • For now, simply glance at the registration and verify that it looks good
  • Quit out of tkregister.

If you want to learn more about using tkregister or freeview see Multimodal Tutorial.

3. Study Questions

  • What would the preproc-sess command be to analyze session sess02? Answer

  • What would the preproc-sess command be to smooth by 7mm FWHM? Answer

  • What would the preproc-sess command be to analyze data in a functional subdirectory called 'rest'? Answer

  • What would the preproc-sess command be if you did not want to use slice-timing correction? Answer

4. Preprocessing Details (Skip or defer to the end for FreeSurfer Course)

You do NOT need to perform the steps below to understand the rest of the tutorial. This is provided to allow you to understand the inner workings of FSFAST Preprocessing better. Go back into one of the run directories and see what preproc-sess creates. To do this,

cd $TUTORIAL_DATA/fsfast-functional/sess01/bold/001
ls

This directory previously held only f.nii.gz, workmem.par, and wmfir.par before preprocessing. Now there are a lot of files, each indicative of a different preprocessing stage. Now type

ls -ltr

This command sorts the files by creation time with the oldest at the top and the newest at the bottom. The preprocessing is progressive, meaning that the output of one stage is the input to the next.

4.1. Template

This stage creates template.nii.gz (and template.log). This is the middle time point from the raw functional data (f.nii.gz). This is the reference used to motion correct and register the functionals for this run to the anatomical. It is also used to create masks of the brain.

  • Verify that it has the same dimension and resolution as the raw data using mri_info.

4.2. Masking

The masks for this run are stored in the 'masks' directory. Run 'ls -ltr masks'. You will see a file called 'brain.nii.gz'. This is a binary mask created using the FSL BET program. There is also a file called 'brain.e3.nii.gz' which is the mask eroded by three voxels. These have the same dimensions as the template. View the masks with:

freeview -v template.nii.gz masks/brain.nii.gz:colormap=heat -viewport coronal

freeview -v template.nii.gz masks/brain.e3.nii.gz:colormap=heat -viewport coronal

You can play with the opacity of the mask by moving the opacity slider or entering a new value less than 1 and hitting enter. The brain.nii.gz is used to constrain voxel-wise operations. The eroded mask (brain.e3.nii.gz) is used to compute the mean functional value used for intensity normalization and global mean time course. There are other masks there that we will get to later.

4.3. Intensity Normalization and Global Mean Time Course

By default, FSFAST will scale the intensities of all voxels and time points to help assure that they are of the same value across runs, sessions, and subjects. It does this by dividing by the mean across all voxels and time points inside the brain.e3.nii.gz mask, then multiplying by 100. This value is stored in global.meanval.dat. This is a simple text file which you can view. At this point, this value is stored and used later. A waveform is also constructed of the mean at each time point (text file global.waveform.dat). This can be used as a nuisance regressor.

  • What are the global means for runs 1, 2, 3, and 4?

4.4. Functional-Anatomical Cross-modal Registration

The next six files (init.register.dof6.dat, register.dof6.dat, register.dof6.dat.mincost, register.dof6.dat.sum, register.dof6.dat.log, register.dof6.dat.param) deal with the registration from the functional to the same-subject FreeSurfer anatomical. There are only two files here that are really important: register.dof6.dat and register.dof6.dat.mincost.

  • register.dof6.dat - is a text file that contains the registration matrix.
  • register.dof6.mincost - is a text file that contains a measure of
    • the quality of the registration.

The registration is will be revisited below when we talk about Quality Assurance

4.5. Motion Correction (MC)

The motion correction stage produces these files: fmcpr.mat.aff12.1D, fmcpr.nii.gz, mcprextreg, mcdat2extreg.log, fmcpr.nii.gz.mclog, fmcpr.mcdat. There are only three important file here:

  • fmcpr.nii.gz -- this is the motion corrected functional data. It has the same size and dimension as the raw functional data.
  • fmcpr.mcdat - text file of the amount of motion at each time point. This is important for Quality Assurance (see below).
  • mcprextreg - text file of the motion correction parameters assembled into an orthogonalized matrix that can be used as nuisance regressors
  • Verify that fmcpr.nii.gz has the same dimension as f.nii.gz using mri_info.

4.6. Slice-Timing Correction (STC)

Slice-timing correction compensates for the fact that each of the 30 slices was acquired separately over the course of 2 sec. It does this by interpolating between time points to align each slice to the time of the middle of the TR. The file created with this is fmcpr.up.nii.gz (and fmcpr.up.nii.gz.log).

  • Verify that fmcpr.up.nii.gz has the same dimension as f.nii.gz using mri_info.

4.7. Resampling to Common Spaces and Spatial Smoothing

At this point, the functional data has stayed in the 'native functional space', ie, 64x64x30, 3.4x3.4x5mm3. Now it will be sampled into the 'Common Space'. The Common Space is a geometry where all subjects are in voxel-for-voxel registration. There are three such spaces in FSFAST:

  • Left hemisphere of fsaverage (fmcpr.up.sm5.fsaverage.lh.nii.gz)
  • Right hemisphere of fsaverage (fmcpr.up.sm5.fsaverage.rh.nii.gz)
  • Volume of fsaverage (MNI305 space) - for subcortical analyses (fmcpr.sm5.mni305.2mm.nii.gz)

Each of these is the entire 4D functional data set resampled into the common space. The spatial smoothing is performed after resampling. Surface-based (2D) smoothing is used for the surfaces; 3D for the volumes. Check the dimensions of the MNI305 space volume:

mri_info --dim fmcpr.up.sm5.mni305.2mm.nii.gz
mri_info --res fmcpr.up.sm5.mni305.2mm.nii.gz

The dimension will be '76 76 93 142' meaning that there are 76 columns, 76 rows, 93 slices but still 142 time points (same as the raw data). The resolution will be '2.0 2.0 2.0 2000' meaning that each voxel is 2mm in size and the TR is still 2 sec. The transformation to this space is based on the 12DOF talairach.xfm created during the FreeSurfer reconstruction. Check the dimensions of the Left Hemisphere 'volume':

mri_info --dim fmcpr.up.sm5.fsaverage.lh.nii.gz
mri_info --res fmcpr.up.sm5.fsaverage.lh.nii.gz

The dimension is '163842 1 1 142'. This 'volume' has 163842 'columns', 1 'row', and 1 'slice' (still 142 time points). You are probably confused right now. That's ok, it's natural. At this point the notion of a 'volume' has been lost. Each 'voxel' is actually a vertex (of which there are 163842 in the left hemisphere of fsaverage). Storing it in a NIFTI 'volume' is just a convenience. The 'resolution' is '1.0 1.0 1.0 2000'. The values for the first 3 dimensions are meaningless because there are no columns, rows, or slices on the surface so the distances between them are meaningless. The last value indicates the time between frames and is still accurate (2 sec). The transformation to this space is based on the surface-based intersubject registration created during the FreeSurfer reconstruction.
top | previous (Directory Structure)| next (First Level Analysis)

FsFastTutorialV5.1/FsFastPreProc_freeview (last edited 2016-04-28 14:31:58 by ZekeKaufman)