1 #pragma section-numbers off
   2 
   3 [wiki:Self:FreeSurferWiki top] | [wiki:Self:Tutorials previous]
   4 
   5 This tutorial steps you through the analysis of an fMRI data set with
   6 the FreeSurfer Functional Analysis Stream (FSFAST), from organizing
   7 the data to group analysis.
   8 
   9 [[TableOfContents]]
  10 
  11 = Tutorial Data Description =
  12 
  13 The data being analyzed is part of the fBIRN Phase I data set. There
  14 are 5 subjects, each scanned twice at each of 10 sites. The data in
  15 the tutorial is the data collected at the MGH site. The task is a
  16 simple sensory motor blocked design experiment. During each task block
  17 the subject was shown a flashing checkerboard and presented with an
  18 auditory tone. During this time, the subject was asked to press
  19 bottons with both hands. The task blocks alternated with fixation
  20 blocks during which the subject stared at a fixation cross but
  21 performed no other task. Each block type was 15 sec long. Each run
  22 started with a fixation block followed by 8 pairs of task and fixation
  23 blocks (and so ends with a fixation block) for a total run duration of
  24 255 sec. The TR was 3 sec, so there were 85 time points. This task was
  25 performed 4 times in each visit.Anatomicals were also collected and
  26 analyzed in FreeSurfer for each of these subjects.
  27 
  28 = Getting and Organizing the Tutorial =
  29 
  30 The tutorial requires about 10G of space. Find a location for this
  31 data, download or copy the tarfile from XXX. Untar it with:
  32 
  33 tar xvfz fsfast-tutorial.tar.gz 
  34 
  35 This will create a directory called fsfast-tutorial. You can now
  36 delete the tar file. cd fsfast-tutorial. It will be assumed that you
  37 are in this directory (or subdirectory there of) throughout the
  38 tutorial. This directory will have five folders:
  39 
  40  * fb1-raw - raw fMRI data
  41  * fb1-raw-study - raw data origanized as an FSFAST study but unanalyzed
  42  * fb1-preproc-study - The same data preprocessed.
  43  * fb1-analysis-study - The same data analyzed
  44  * subjects - FreeSurfer reconstruction of anatomical data (plus the fsaverage subject).
  45 
  46 If you look (ls) in fb1-raw, you will see that there are 20 NIFTI data sets with names like f.mgh-10X.1-rYYY.nii. These are the 20 fMRI runs mentioned above. X indicates the subjects number (1, 3, 4, 5, 6), and YYY indicates the run number. The sensory-motor task happend to be runs 3, 5, 7, and 10.
  47 
  48 = Quick Visualization Tutorial (tkmedit/tksurfer) =
  49 
  50 The purpose of this tutorial is to familarize you with how to use
  51 FreeSurfer volume viewer (tkmedit) and surface viewer (tksurfer) in
  52 the context of viewing functional data.You should already know how to
  53 use tkmedit and tksurfer otherwise. See the pages below for a more
  54 detailed handling of tkmedit and tksurfer.
  55 
  56 == tkmedit ==
  57  * [wiki:Self:TkMeditGuide_2fTkMeditGeneralUsage_2fTkMeditInterface Interface] [[BR]]
  58  * [wiki:Self:FsTutorial/TkmeditGeneralUsage General usage] [[BR]]
  59  * [wiki:Self:FsTutorial/TkmeditWorkingWithData Working with data] [[BR]]
  60  * [wiki:Self:FsTutorial/TkmeditReference Quick reference] [[BR]]
  61 
  62 == tksufer ==
  63 
  64  * [wiki:Self:TkSurferGuide_2fTkSurferGeneralUsage_2fTkSurferInterface Interface] [[BR]]
  65  * [wiki:Self:FsTutorial/TksurferGeneralUsage General usage] [[BR]]
  66  * [wiki:Self:FsTutorial/TksurferWorkingWithData Working with data] [[BR]]
  67  * [wiki:Self:FsTutorial/TksurferReference Quick reference] [[BR]]
  68 
  69 == Viewing a single functional overlay in the volume ==
  70 
  71 cd into the study with all the analyzed data:
  72 {{{
  73 cd fb1-analysis-study
  74 }}}
  75 Run tkmedit-sess (this is an FSFAST wrapper for tkmedit):
  76 {{{
  77 tkmedit-sess -s mgh-101.v1 -a sm-gamma-fwhm5 -c odd-v-0 -aparc+aseg
  78 }}}
  79 Don't worry about what all the arguments mean, this part is only about visualization.This command will bring up two windows, one with a brain image the other a control panel.
  80 
  81 attachment:tkm-101-gam-cor.2-4.gif
  82 attachment:tkm-101-toolswindow.gif
  83 
  84 The brain image is the FreeSurfer anatomical for this subject. The
  85 slightly pale colors on the anatomical indicate the FreeSurfer
  86 automatic segmentation. The bright red/yellow/blue are super-threshold
  87 voxels in the functional overlay. As you click on different points,
  88 you will see the "Functional value" field in the Tools window change
  89 as well as the "Sgmtn label".Note that areas that are not above
  90 threshold will still have non-zero functional values. The
  91 interpretation of the value depepends on what is being viewed. This is
  92 a significance map, so the value is -log10(pvalue)*sign (ie, for a
  93 pvalue = .01, the functional value will be +2). The sign is a
  94 functional direction. The red/yellow are postive, and the blue are
  95 negative. As a functional value gets more positive, its color will
  96 change from red to yellow. As it gets more negative, it will change
  97 from blue to cyan.[[BR]]
  98 
  99 Toggle the functional overlay on and off by hitting the button with
 100 the red/yellow blob in the Tools window (it's in the top row - if you
 101 mouse over it, you'll see a "Show Overlay" tooltip.)[[BR]]
 102 
 103 Configure the functional overlay by clicking on "View..." in the Tools
 104 window, then "Configure->Functional Overlay...". You should see the
 105 following interface:
 106 
 107 attachment:tkm-101-config-funcoverlay.gif
 108 
 109 The thresholds are currently set at 2 (Min) and 4 (max). The Min
 110 threshold is the minimum absolute value needed for a voxel to show an
 111 overlay color. The maximum is the value beyond which the voxel will
 112 stop changing color. Try changing these values, then hit the Apply
 113 button to see their effect.[[BR]]
 114 
 115 So, what's all that activation OUTSIDE of the brain. Can't have that!
 116 Try hitting View->Mask Functional Overlay to Aux button. There, now
 117 isn't that better? And why is it so blockly? There are big voxels in
 118 functional data, but if you'd like to pretend otherwise, try hitting
 119 the "Trilinear" button on the Configure Functional Overlay window.
 120 
 121 == Viewing multiple functional overlays and time courses in the volume ==
 122 Run tkmedit-sess (this is an FSFAST wrapper for tkmedit):
 123 {{{
 124 tkmedit-sess -s mgh-101.v1 -a sm-fir-fwhm5 -c 1v0 -aparc+aseg
 125 }}}
 126 
 127 This will bring up the two windows as you saw before (the brain image
 128 window will have a different overlay). It will also bring up a window
 129 called "Time Course". Click anywhere in the volume, and you will see a
 130 time course associated with that voxel similar to the one below.
 131 
 132 attachment:tkm-101-fir.gif
 133 
 134 The meaning of the time course depends upon the nature of the time
 135 course loaded. In this case it is the hemodynamic response to the task
 136 block averaged over all blocks over all runs (this is an "FIR"
 137 model). The horizontal axis is time (0 means the onset of the
 138 block). You can visualize the values of any multi-frame data set in
 139 this way (it does not have to be a "time" course).[[BR]]
 140 
 141 Notice that there is not much activation in the functional
 142 overlay. This is good! You are looking at an overlay that corresponds
 143 3 seconds prior to stimulus onset, so there should be no
 144 activation. To see the other time points, bring up the functional
 145 overlay configuration window (View->Configure->Functional
 146 Overlay). Notice that the "Time Point" field now has a range of 0-8
 147 indiating the 9 time points in the Time Course window. If you hit the
 148 + button next to "Time Point" then hit Apply, you will see the overlay
 149 change. You will also see a vertical dashed line in the Time Course
 150 window. You are now looking the map associated with the time between 0
 151 and 3 sec after stimulus onset. Keep hitting the +/Apply buttons to
 152 see different time points. You can hit the "|>" button to start a
 153 movie of the activation (then "[]" to stop it).
 154 
 155 == Viewing a single functional overlay on the surface ==
 156 
 157 To view the same data on the surface run:
 158 
 159 {{{
 160 tksurfer-sess -s mgh-101.1 -a sm-gamma-fwhm5 -c odd-v-0 -hemi lh
 161 }}}
 162 
 163 Again you will see two windows, "Tksurfer Tools" and a surface image window.
 164 
 165 = Assembling the Data in the FSFAST Hiearchy =
 166 
 167 == The Project (or Study) Directory ==
 168 == Create a Session ==
 169 == Create a Stimulus Schedule (Paradigm File) ==
 170 == Link to the FreeSurfer Anatomical Recontruction ==
 171 == Create a SessionID File ==
 172 
 173 = Preprocessing of fMRI Data (preproc-sess) =
 174 == What preprocessing stages do you want to run? ==
 175 
 176 There are up to seven types of preprocessing that are run on fMRI
 177 data: 1. brain masking, 2. motion correction (MC), 3. slice-timing
 178 correction (STC), 4. B0 distortion correction, 5. spatial smoothing,
 179 6. resampling to common space, and 7. intensity normalization. Not all
 180 packages run all of these seven, and they are not always run in the
 181 same order, and some stages are sometimes run as post-processing. In
 182 FSFAST, we can run 1. MC, 2. STC (optional), 3. smoothing, and
 183 4. intensity normalization. We create a brain mask, but we do not mask
 184 the functional data.
 185 
 186 == Run preprocessing ==
 187 
 188 To run MC and spatial smoothing by 5 mm FWHM along with brain mask creation on one session run:
 189 
 190 {{{
 191 cd fb1-raw-study
 192 preproc-sess -s mgh-101.1 -fwhm 5
 193 }}}
 194 
 195 Note that this has already been done with all subjects in the
 196 fb1-preproc-study directory. To preprocess all of the session, you
 197 would run "preproc-sess -sf sessid -fwhm 5". Also note that if
 198 preprocessing as already been performed on a session, it will
 199 automatically skip it and move on to the next (unless you add -force
 200 to the command-line).
 201 
 202 == Examine additions to hierachy ==
 203 
 204 {{{
 205 ls mgh-101.1/bold/003
 206 ls mgh-101.1/bold/masks
 207 }}}
 208 
 209 You will see f.nii (the raw data), fmc.nii (motion corrected), and
 210 fmcsm5.nii (motion corrected and smoothed). In addition you will see
 211 fmc.mcdat; this is a text file with the motion correctionwill
 212 parameters (translations and rotations) as created by AFNI. You will
 213 also see mcextreg.bhdr. This is a binary file with the orthogonalized
 214 motion correction parameters which can later be used as nuisance
 215 regressors when analyzing the data. These files will exist in each of
 216 the runs (ie, 005, 007, 010). You will see a brain.nii volume in the
 217 masks folder. This is a binary mask of the brain as found by FSL's BET
 218 program. The functional data themselves are not masked.[[BR]]
 219 
 220 To view the translation components, run
 221 {{{
 222 plot-twf-sess -s mgh-101.1 -mc
 223 }}}
 224 This will bring up a plot with the translations for each of the runs.
 225 
 226 = Function-Structure Registration =
 227 
 228 In order to render the functional results on the anatomical background
 229 as well as to map the functional results into a common space for group
 230 analysis, it is necessary to register/align the functional volume with
 231 a structral volume. In FSFAST, we first register to the same-subject
 232 FreeSurfer anatomical with a 6 DOF registration. We then map the
 233 functional to Talairach/MNI305/fsaverage space by concatenating the
 234 within-subject function/structure registration with the Talairach
 235 registration (talariach.xfm) created when the subject was
 236 reconstructed. For mapping to surface-based space, we concatenate the
 237 within-subject function/structure registration with the surface-based
 238 registration. Since we are only dealing with the functional analysis
 239 here, we will just consider the within-subject function/structure
 240 registration. 
 241 
 242 == View unregistered (tkregister-sess) ==
 243 
 244 Run the following command to see how the functional and structrual are
 245 aligned prior to performing any automatic registration.
 246 
 247 {{{
 248 cd fb1-preproc-sess
 249 tkregister-sess -s mgh-101.1 -regheader
 250 }}}
 251 Hit the compare button.
 252 
 253 == Run automatic registration (fslregister-sess) ==
 254 {{{
 255 cd fb1-preproc-sess
 256 fslregister-sess -s mgh-101.1
 257 }}}
 258 When this command is complete, you will see a register.dat file in
 259 mgh-101.1/bold. This is the only change. The functional data are not
 260 resampled! 
 261 
 262 == Check automatic registration (tkregister-sess) ==
 263 {{{
 264 cd fb1-preproc-sess
 265 tkregister-sess -s mgh-101.1 -regheader
 266 }}}
 267 Hit the compare button.
 268 
 269 == Check talairach registration ==
 270 {{{
 271 tkregister2 --s fbph1-101 --fstal --surf
 272 }}}
 273 
 274 = First-Level Analysis =
 275 
 276 The First-Level Analysis (FLA) consists of setting up models of the
 277 task-related and nuisance components. The FLA is done in two
 278 stages. In the first stage, the FLA is configured (with
 279 mkanalysis-sess). This is done once regardless of how many data sets
 280 you have (you do not even need to have any data to run the
 281 configuration). In the second stage, you actualy perform the analysis
 282 with selxavg3-sess by passing it the configuration and the session
 283 that you want to analyze. selxavg3-sess customizes the analysis for
 284 that session based on what it finds in the hierarchy, builds the
 285 design matrix, and performs the analysis. Breaking the FLA up into
 286 these two stages assures that all sessions are analyzed in the same
 287 way. 
 288 
 289 == Configure Analysis and Contrasts I: Gamma HRF Model  ==
 290 
 291 Configuring the FLA is performed with mkanalysis-sess. When you run:
 292 {{{
 293 cd fb1-preproc-study
 294 mkanalysis-sess -gui
 295 }}}
 296 
 297 You will see the following window:
 298 attachment:mkana-startup.gif
 299 
 300 You will use this window to specify the input of the analysis, the
 301 hemodynamic response model, contrasts, and nuisance regressors. The
 302 red fields are field that you must enter before you can save the
 303 analysis.  There is a lot going on with this GUI, so we'll break it
 304 down. Note that many of the components have "tooltips" that will show
 305 when you pause the mouse pointer over them.
 306 
 307 In the upper left corner is a panel called "FS-FAST Hiearchy". The
 308 "Func Stem" is the input to the analysis. You should specify the
 309 output from the preprocessing. For this excercise, we are going to use
 310 the motion corrected and 5mm smoothed data. This functional volume is
 311 called fmcsm5.nii in the hiearchy which makes its stem "fmcsm5" (ie,
 312 just strip off the nii). Enter "fmcsm5" into the field. When you hit
 313 return, it changes from red to white. Next, enter the TR (sec). For
 314 this experiment it was 3 sec. This will be checked against the TR
 315 found in the input nifti file. Leave INorm checked.
 316 
 317 Turn your attention to the "Noise and Nuisance Variables" panel. Low
 318 frequency noise so prevelant in fMRI is compensated for in a
 319 combination of three ways. Drift components are modeled with
 320 polynomial regressors. The order can be adjusted, but leave it at 2
 321 for now. The motion correction parameters can be used as regressors by
 322 checking the "MC Regressors" box (do so now). Finally, the remaining noise is
 323 modeled as time-invariant linear AR1 process when the "Temporal
 324 Whitening" box is checked (leave it so). There is one additionaly way
 325 to compensate for noise through the use of a "Time Point Exlucde
 326 File", but we will not consider that here.
 327 
 328 You will specify the model of the task-related signal in the "Event
 329 Related/Block Design" panel (leave that box checked). Choose the
 330 number of conditions by clicking on the "NConditions" slider. This is
 331 the number of TASK conditions (do not include the Null/Fixation
 332 condition). In this example, we have two conditions (Odd and Even), so
 333 adjust this to 2. To the right of this is the "Paradigm File". Enter
 334 "sensory-motor.par". Note that the number of task conditions in the
 335 paradigm file must match that specified with "NConditions". Below, you
 336 will specify the Hemodynamic Response Model. There are three choices:
 337 Gamma, SPM HRF, and FIR. Choose Gamma for now. If you hit the "Plot"
 338 button it will show the Gamma and SPM HRF. As you change the Gamma
 339 paraters (Delay, Dispersion (Tau), and Exponent (Alpha)), the Gamma
 340 plot will change. Make sure that they are at Delay=2.25, Tau=1.25, and
 341 Alpha=2.
 342 
 343 At this point, you have specified the model of the BOLD signal
 344 including HRF, nuisance, and noise. The GUI should look like the image
 345 below:
 346 
 347 attachment:mkana-gamma-precon.gif
 348 
 349 Now you are ready to specify contrasts. A contrast is an instantiation
 350 of a hypothesis and is represented by a contrast matrix (ie, a linear
 351 summation of the regression coefficients). Contrasts are managed
 352 through a separate GUI accessed through the "Contrast" list box. When
 353 you click on "Add Contrast", you will see the following screen:
 354 
 355 attachment:mkcon-gam-startup.gif
 356 
 357 There are several things going on here, but the most important is the
 358 list of condtitions in the middle of the GUI (ie, "Condition 1",
 359 "Condition 2") will green, red, and black radio buttons. Green
 360 indicates an "active" condition; red means a "control" condition, and
 361 black means to ignore the condition in the contrast. Active conditions
 362 are given a weight of +1; controls are given -1; ignores get 0. The
 363 weight is given to the right of the buttons.  All contrasts are
 364 implicitly computed against the Null or Fixation condition. If you
 365 want to test the null hypothesis that Condition 1 is no different than
 366 the Null condition, then you would make Condition 1 active and ignore
 367 the rest. To test the null hypothesis that Condition 1 is no different
 368 than Condition 2, then you would make Condition 1 active and Condition
 369 2 control. 
 370 
 371 For this exercise, we are going to test four NULL hypotheses:
 372 
 373  * Odd == Fixation (odd-v-0)
 374  * Even == Fixation (even-v-0)
 375  * Odd == Even (odd-v-even)
 376  * Odd+Even == Fixation (odd-+even)
 377 
 378 The last one tests whether the average of the responses to odd and
 379 even are different than fixation. Remember that, according to the
 380 Paradigm File, Condition 1 is Odd, and Condition 2 is Even.  When "Add
 381 Contrast" is clicked, "Condition 1" will be active and Condition 2
 382 will be ignored. This corresponds to our first contrast, so there is
 383 nothing we need to do except give the contrast a name. You should give
 384 your contrasts meaningful but terse names. Specify "odd-v-0" for this
 385 contrast. Hit the "Done/Save" button.  You will now see "odd-v-0"
 386 appear in the Contrast list box in the mkanalyiss GUI.
 387 
 388 Click on "Add Contrast" again to bring up the contrast GUI
 389 again. This time, click on the green button next to Condition 2 (see
 390 its weight change from 0 to 1). Then click on the black button next
 391 to Condition 1 (see weight change from 1 to 0). Change the name to
 392 "even-v-0", then click Done/Save. "even-v-0" will appear in the list
 393 box.
 394 
 395 Click on "Add Contrast" again, and click the red button next to
 396 Condition 2 (see its weight change from 0 to -1).  Change the name to
 397 "odd-v-even", then click Done/Save.
 398 
 399 Click on "Add Contrast" one more time, and click the green button next to
 400 Condition 2 (see its weight change from 0 to +1).  Change the name to
 401 "odd+even", then click Done/Save.
 402 
 403 You can go back and view and/or edit an contrast by clicking on it in
 404 the list box.
 405 
 406 The last thing you have to do is to give your analysis a name. Like
 407 the contrasts, it should be terse but descriptive (it cannot have any
 408 spaces or blanks). Specify "sm-gamma-fwhm5" (sm = sensory-motor, gamma
 409 = Gamma HRF, and fwhm5 for the input). The interface should now look
 410 like:
 411 
 412 attachment:mkana-gamma-done.gif
 413 
 414 Hit the "Save" button, then "Quit".
 415 
 416 After you hit Quit, control will be returned to the shell that you ran
 417 mkanalysis-sess from. If you type "ls", you will see a new folder
 418 called "sm-gamma-fwhm5". If you "ls sm-gamma-fwhm5", you will see
 419 analysis.info, analysis.cfg, odd-v-0.mat, even-v-0.mat,
 420 odd-v-even.mat, odd+even.mat. Your configuration is stored in these
 421 files. You can browse/edit your configuration by running:
 422 
 423 {{{
 424 mkanalysis-sess -gui -analysis sm-gamma-fwhm5
 425 }}}
 426 
 427 == Configure Analysis and Contrasts II: FIR HRF Model  ==
 428 
 429 Now we are going to use a Finit Impulse Response (FIR) to model the
 430 hemodynamic response. The FIR does not make any assumptions about the
 431 shape of the HRF but is also less interpretable. Again, run
 432 
 433 {{{
 434 cd fb1-preproc-study
 435 mkanalysis-sess -gui
 436 }}}
 437 
 438 Set the Func Stem, TR, NConditions, and Paradigm File as above, but
 439 now click on the "FIR" checkbox. This will enable the "Total Time
 440 Window", "PreStim", and "TER" entry boxes. The Time Window is the
 441 window within which we will estimate the HRF. Given that the task is
 442 15 sec long and the rest is 15 sec, let's choose 27 sec. The PreStim
 443 is the amount of time before stimulus onset to start estimating the
 444 HRF. A non-zero PreStim gives us an idea of what the baseline is at
 445 stimulus onset. Set it to 6. 
 446 
 447 Setup the same contrasts as you did above, then name the analysis
 448 "sm-fir-fwhm5", hit Save, then Quit.
 449 
 450 == Analyze First Level (selxavg3-sess) ==
 451 
 452 You are now ready to analyze some data! Note that the fully analyzed
 453 data (along with correctly configured analyses) can be found in
 454 fb1-analysis-study. To analyze the data for session mgh-101.1 with the
 455 sm-gamma-fwhm5 analysis, run:
 456 
 457 {{{
 458 cd fb1-preproc-study
 459 selxavg3-sess -s mgh-101.1 -analysis sm-gamma-fwhm5
 460 }}}
 461 
 462 Note that if you want to analyze all the sessions, you can run
 463 "selxavg3-sess -sf sessid -analysis sm-gamma-fwhm5".
 464 
 465 To analyze the data for session mgh-101.1 with the sm-fir-fwhm5
 466 analysis, run:
 467 {{{
 468 cd fb1-preproc-study
 469 selxavg3-sess -s mgh-101.1 -analysis sm-fir-fwhm5
 470 }}}
 471 
 472 == Examine additions to the hierarchy ==
 473 
 474 {{{
 475 ls mgh-101.1/bold
 476 ls mgh-101.1/bold/sm-gamma-fwhm5
 477 ls mgh-101.1/bold/sm-gamma-fwhm5/odd-v-0
 478 }}}
 479 
 480 == Visualize ==
 481 
 482 === Volume-based visualization (tkmedit-sess) ===
 483 
 484 View the result of the Gamma HRF analysis on the FreeSurfer anatomical
 485 volume for mgh-101.1 with:
 486 {{{
 487 cd fb1-analysis-study
 488 tkmedit-sess -s mgh-101.1 -aparc+aseg -analysis sm-gamma-fwhm5 \
 489   -c odd-v-0 -c even-v-0 -c odd+even -c odd-v-even 
 490 }}}
 491 When you configure the functional overlay with
 492 View->Configure->Functional Overlay, you will see that there are 4
 493 "Time Points". Each point is different contrast (ie, 0 is odd-v-0, 1
 494 is even-v-0, etc). Scroll through each one.
 495 
 496 View the result of the HRF HRF analysis for mgh-101.1 with:
 497 {{{
 498 cd fb1-analysis-study
 499 tkmedit-sess -s mgh-101.1 -aparc+aseg -analysis sm-fir-fwhm5 -c odd-v-0 
 500 }}}
 501 Here we view only one contrast at a time because each contrast has
 502 multiple time points for each point in the time window. Note that
 503 there is less activation than the Gamma HRF. When you click on a
 504 point, you will see the HRF for both Condition 1 (Odd) and Condition 2
 505 (Even) blocks.
 506 
 507 Finally, view the overlay maps from the Gamma with the HRF from the FIR:
 508 {{{
 509 cd fb1-analysis-study
 510 tkmedit-sess -s mgh-101.1 -aparc+aseg -analysis sm-fir-fwhm5 \
 511   -mapanalysis sm-gamma-fwhm5 -c odd-v-0 -c even-v-0 -c odd+even -c odd-v-even 
 512 }}}
 513 When you configure the overlay, you will see that there are 4 "Time
 514 Points" -- these correspond to the 4 contrasts from the Gamma analysis.
 515 
 516 === Surface-based visualization (tksurfer-sess) ===
 517 View the result of the Gamma HRF analysis on the FreeSurfer anatomical
 518 surface for mgh-101.1 with:
 519 {{{
 520 cd fb1-analysis-study
 521 tksurfer-sess -hemi lh -aparc -s mgh-101.1 -analysis sm-gamma-fwhm5 \
 522   -c odd-v-0 -c even-v-0 -c odd+even -c odd-v-even
 523 }}}
 524 Note that the command-line is nearly identical to that of tkmedit
 525 above. The difference is that the hemisphere is specified ("-hemi
 526 lh"), and "-aparc+aseg" is replaced with "-aparc" to load the
 527 surface-based segmentation.
 528 
 529 = Higher-Level (Group) Analysis =
 530 
 531 Higher-Level is where you make inferences about the population that
 532 your subjects are drawn from. It is a bit confusing at times because
 533 both use GLMs, so at both levels you are constructing design matrices,
 534 contrasts, etc. Traditionally, fMRI group analysis has been done in a
 535 standard volume space (ie, Talairaach/MNI152/MNI305). With FreeSurfer,
 536 we also have the option to analyze group data in the surface
 537 space. Volume-based analyses are done in MNI305 space (which is the
 538 same as the fsaverage subject).
 539 
 540 == Assemble the Data (isxconcat-sess) ==
 541 
 542 The first step in the group analysis is to "assemble" the data. This
 543 means creating a single 4D file with where the 4th "time" dimension is
 544 actual all the subjects concatenated together in a common space. There is a
 545 different command, depending upon whether the common space is volume-
 546 or surface-based.
 547 
 548 For the next exercises, we will work in the fb1-analysis-study directory
 549 {{{
 550 cd fb1-analysis-study
 551 }}}
 552 
 553 
 554 === Volume-based (MNI305/fsaverage) ===
 555 
 556 To run the volume-based concatenation, run the command below. Note
 557 that the data from this command already exist in the
 558 group-sm-gamma-fwhm5-tut directory.
 559 
 560 {{{
 561 isxconcat-sess -sf sessid -a sm-gamma-fwhm5 -c odd-v-0 -o group-analysis
 562 }}}
 563 
 564 This command will go through each session in the sessid file, find the
 565 odd-v-0 contrast in the sm-gamma-fwhm5 analysis, use the register.dat
 566 for that session to resample to MNI305/fsaverage space. These are all
 567 concatenated together and saved in
 568 group-analysis/sm-gamma-fwhm5/odd-v-0/tal.ces.nii file. In addition, several
 569 other files are created. To see them, 
 570 
 571 {{{
 572 ls group-analysis-tut/sm-gamma-fwhm5
 573 cat group-analysis-tut/sm-gamma-fwhm5/sessid
 574 cat group-analysis-tut/sm-gamma-fwhm5/ffxdof.dat
 575 }}}
 576 
 577 In the output directory, you will see a series of files that start
 578 with "tal". tal.h-offset.nii is a stack where each "time point" is the
 579 mean functional image of each subject sampled in the MNI305 space. 
 580 tal.masks.nii are the binary masks for all the subjects, and 
 581 tal.snr.nii are the functional SNR maps from each
 582 subject. tal.mask.nii is a single binary mask made from the
 583 intersection of the individuals. ffxdof is the fixed-effects DOF
 584 across all subjects. sessid.txt is the list of sessions, the
 585 corresponding freesurfer subject name, and the DOF contributed by each
 586 subject. 
 587 
 588 You will also see some files that being with "lh". These are the same
 589 thing in the surface-based space.
 590 
 591 Now look in the directory for odd-v-0 the contrast
 592 {{{
 593 cd fb1-analysis-study
 594 ls group-sm-gamma-fwhm5-tut/odd-v-0
 595 }}}
 596 
 597 You will see tal.ces.nii. These are the contrast maps for eaah of the
 598 subjects, and tal.cesvar.nii are the variance of the contrast for each
 599 subject (ie, the square of the standard error). This variance is
 600 needed for fixed-effects and weighted random-effects analysis. You'll
 601 also see a bunch of directories that start with "glm". Ignore those
 602 for a moment.
 603 
 604 ==== Quality Assurance ====
 605 
 606 There are three important quality assurance steps that can be perfomed
 607 here. First, view the mean funcitonals to make sure that all are
 608 registered together properly. To do this run,
 609 
 610 {{{
 611 tkregister2 --s fsaverage --surf \
 612   --mov group-sm-gamma-fwhm5-tut/tal.h-offset.nii \
 613   --regheader --check-reg
 614 }}}
 615 The image window will show the MNI305 brain. Hit the "Compare" button
 616 to show the average functional of the first session. Click in the
 617 image window, then hit the 'a' key. Each time you hit the 'a' key, it
 618 will advance to the next subject.
 619 
 620 The next QA step is to check the individual masks. This can be done
 621 with:
 622 {{{
 623 tkmedit fsaverage orig.mgz \
 624   -overlay group-sm-gamma-fwhm5-tut/tal.masks.nii -fthresh 0.5
 625 }}}
 626 The threshold of 0.5 is appropriate because these masks are binary 
 627 (ie 0-1). When you View->Configure->Functional Overlay, you will see 
 628 that there are 5 "Time Points" (0-4) corresponding to the 5 subjects. 
 629 Advance through each one to assure that the masks are in the proper place.
 630 
 631 The final step is to look at the functional SNR maps with
 632 {{{
 633 tkmedit fsaverage orig.mgz \
 634   -overlay group-sm-gamma-fwhm5-tut/tal.snr.nii \
 635   -timecourse group-sm-gamma-fwhm5-tut/tal.snr.nii \
 636   -fthresh 50 -fmax 250
 637 }}}
 638 Again, when you View->Configure->Functional Overlay, you will see 
 639 that there are 5 "Time Points" (0-4) corresponding to the 5 subjects. 
 640 Advance through each one to assure that the SNR maps are
 641 "consistent". When you click on a voxel, you will see the SNR for each
 642 subject plotted in the "Time Course" window. The actual value of the
 643 FSNR will vary depending upon how much smoothing you've done and the
 644 details of the acquisition. You are looking for outliers here.
 645 
 646 ==== Group Analysis ====
 647 
 648 ===== Random Effects (RFx, OLS) =====
 649 {{{
 650 cd group-sm-gamma-fwhm5-tut/odd-v-0
 651 mri_glmfit --y tal.ces.nii --osgm \
 652   --glmdir glm.rfx.tal.ces 
 653 tkmedit fsaverage orig.mgz -overlay glm.rfx.tal.ces/osgm/sig.mgh
 654 }}}
 655 
 656 ===== Weighted Random Effects (WRFx, WLS) =====
 657 {{{
 658 cd group-sm-gamma-fwhm5-tut/odd-v-0
 659 mri_glmfit --y tal.ces.nii --osgm --wls tal.cesvar.nii\
 660   --glmdir glm.wrfx.tal.ces
 661 tkmedit fsaverage orig.mgz -overlay glm.rfx.tal.ces/osgm/sig.mgh
 662 }}}
 663 
 664 ===== Fixed Effects (FFx) =====
 665 {{{
 666 cd group-sm-gamma-fwhm5-tut/odd-v-0
 667 mri_glmfit --y tal.ces.nii --osgm --yffxvar tal.cesvar.nii 1570 \
 668   --glmdir glm.ffx.tal.ces 
 669 }}}
 670 
 671 ===== Output and visualization =====
 672 {{{
 673 cd group-sm-gamma-fwhm5-tut/odd-v-0
 674 mri_concat glm.rfx.tal.ces/osgm/sig.mgh \
 675            glm.wrfx.tal.ces/osgm/sig.mgh \
 676            glm.ffx.tal.ces/osgm/sig.mgh \
 677            --o all.sig.nii
 678 tkmedit fsaverage orig.mgz -aux brain.mgz -bc-main-fsavg \
 679    -overlay all.sig.nii -fthresh 2 -fmax 4
 680 }}}
 681 
 682 ===== Cluster Analysis =====
 683 {{{
 684 cd group-sm-gamma-fwhm5-tut/odd-v-0
 685 mri_volcluster --in sig.mgh \
 686   --fwhm 4.041332 --thmin 2 --mask ../mask.mgh\
 687   --fsaverage --cwpvalthresh .1 \
 688   --sum sumcluster.dat --ocn ocn.cluster.mgh \
 689   --cwsig cwsig.cluster.mgh 
 690 mri_volcluster --fwhmdat ../fwhm.dat --in sig.mgh --sum cluster.sum
 691 --thmin 2 --out sig.cluster.nii --ocn ocn.cluster.nii --cwsig
 692 cwsig.cluster.nii --mask ../mask.mgh --maskthresh .5 --fsaverage
 693 
 694 }}}
 695 
 696 
 697 === Surface-based ===
 698 
 699 
 700 
 701 = FsFast Tutorial SlideShow =
 702 
 703 [[Navigation(slideshow)]]
 704 
 705  * ["/000 Frontmatter"]
 706  * ["/300 Download data"]
 707  * ["/400 Get familiar with sessions format"]
 708  * ["/500 Make a directory for your study"]
 709  * ["/600 Make paradigm files for your experiment"]
 710  * ["/700 Motion correct the data"]
 711  * ["/800 Normalize signal intensity"]
 712  * ["/900 Set up session-level analysis"]
 713  * ["/905 Average session-level data by condition"]
 714  * ["/910 Define an omnibus contrast"]
 715  * ["/920 Compute statistical maps of the omnibus contrast"]
 716  * ["/930 Run functional and structural registration"]
 717  * ["/940 Visualization"]