|
Size: 6419
Comment:
|
← Revision 45 as of 2024-01-16 14:11:01 ⇥
Size: 7427
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| === work in progress... === == About == Walkthrough: How to use FsFast and [[http://surfer.nmr.mgh.harvard.edu/fswiki/fcseed-sess|fcseed-sess]] for functional connectivity analysis including example commands. |
This page describes how to perform seed-based functional connectivity (FC) analysis in FSFAST. The FC analysis is an extension of the task-based analysis for which there is much more documentation. These instructions mainly cover the details specific to FC analysis. The other steps are given minimal treatment under the understanding that many more details can be found in the task based analysis documentation as found in [[http://surfer.nmr.mgh.harvard.edu/pub/docs/freesurfer.fsfast.ppt|FS-FAST powerpoint]] and the [[http://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorial|FS-FAST tutorial]]. Steps 4, 5, and 6 are the only ones specific to FC analysis. |
| Line 5: | Line 4: |
| For general tips on using FsFast, download this [[http://surfer.nmr.mgh.harvard.edu/pub/docs/freesurfer.fsfast.ppt|FS-FAST powerpoint]] This walkthrough demonstrates how to run a functional connectivity analysis on resting state fMRI data. *STEP 1: Unpack Data into the FSFAST Hierarchy using [[https://surfer.nmr.mgh.harvard.edu/fswiki/unpacksdcmdir|unpacksdcmdir]] |
*STEP 1: Unpack Data into the FSFAST Hierarchy using dcmunpack (run with -help for more documentation): |
| Line 13: | Line 8: |
| unpacksdcmdir -src dicomdir/subject/ALLDICOMS -targ fcMRI_dir/subject -cfg subject_config.txt -fsfast -unpackerr | dcmunpack -src dicomdir -targ sessionid -fsfast -run 3 bold nii.gz f.nii.gz -run 4 bold nii.gz f.nii.gz |
| Line 17: | Line 12: |
| * Have all fMRI dicoms linked into "ALLDICOMS" directory * Arguement for "-targ" specifies output directory * subject_config.txt is a configuration text file you create (format below) * Use "-fsfast" to generate fsfast hierarchy subject_config.txt format: 28 bold nii f.nii 29 bold nii f.nii Col.1: scan acquisition number Col.2: output dir name will be created within "fcMRI_dir/subject" Col.3: output file format - this example is nifti format Col.4: output filename. In this example, 2 files will be created: . fcMRI_dir/subject/028/f.nii fcMRI_dir/subject/029/f.nii *QA Check after unpacking: * A - Check unpacked data (time points, # of slices ..etc) * B - Check FSFAST hierarchy in session folder *STEP 2: Reconstruction Anatomical data using [[https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all|recon-all]] Sample cmd: setenv SUBJECTS_DIR /path/to/recon_dir/ recon-all -s subject_dirname -all -i pathtoT1dicom_scan1.dcm -i pathtoT1dicom_scan2.dcm In this sample command... * set your SUBJECTS_DIR variable to your FreeSurfer subject recon directory * set the subject's directory name with "-s" ... the arguement you provide will become the directory name within $SUBJECTS_DIR * use "-i" to supply the dicoms to reconstruct. Use one "-i" per T1 acquisition. A. QA Check: * A - Check talairach transformation * B - Check skull strip, white matter & pial surface * C - Re-run "recon-all" if edits are made * D - Check hierarchy of reconstructed anatomical data B. Use FSFAST basic hierarch: |
* Have all fMRI dicoms for this subject in the dicomdir folder or subfolders under this folder * Arguement for "-targ" specifies output directory here called "sessionid". This should be unique to the subject (and visit if longitudinal). This is called the session folder. * -run 3 bold nii.gz f.nii.gz will unpack run 3 fmri to sessionid/bold/003/f.nii.gz * To get a list of runs, run dcmunpack -src dicomdir/subject/ALLDICOMS * Use "-fsfast" to generate fsfast hierarchy shown in the image below * The parent folder of the sessionid folder is called the "Project Folder" or "Project Directory". All the commands below should be run from the Project Folder. |
| Line 61: | Line 21: |
| C. Link to FreeSurfer anatomical analysis: Create "subjectname" text file in the session directory. Write in it the subject's recon directory name (as labeld in $SUBJECTS_DIR). D. Create a sessid file (text file with list of your sessions)in your Study DIR (optional) |
*STEP 2: Link to FreeSurfer anatomical analysis. This is done by creating a text file called sessionid/subjectname with the name of the FreeSurfer anatomical folder as created with recon-all and found in $SUBJECTS_DIR. |
| Line 67: | Line 25: |
| Sample cmd: | Sample command {{{preproc-sess -s sessionid -fwhm 5 -surface fsaverage lhrh -mni305-2mm}}} |
| Line 69: | Line 27: |
| preproc-sess -s <subjid> -fwhm <#> A. By default this will do motion correction, smoothing & brain masking B. Quality Check (plot-twf-sess) C.Examine additions to FSFAST hierarchy (in each run of bold dir): ||f.nii ||(Raw fMRI data) || |
By default this will do motion correction, masking, registration to the anatomical, sampling to the surface, and surface smoothing by 5mm as well as sampling to the mni305 with volume smoothing. The surface sampling is done onto the surface of the lh and rh hemispheres of fsaverage. The mni305 is only used for volume-based analysis of subcortical structures. Note that eventhough the time series data are sampled onto fsaverage, the FC seeds are derived from the indvidual anatomy as shown below using unsmoothed data. See the task-based analysis documentation for more information. |
| Line 80: | Line 30: |
||fmc.nii ||(Motion corrected-MC) || ||fmcsm5.nii ||(MC & smoothed) || ||fmc.mcdat ||(Text file with the MC parameters (AFNI)) || ||brain.mgz ||(Binary mask of the brain) || NOTE: you ''may'' need to convert the file "fmcpr.mgz" to fmcpr.nii using [[http://surfer.nmr.mgh.harvard.edu/fswiki/mri_convert|mri_convert]] Found in each bold scan dir. Sample cmd: mri_convert session/bold/002/fmcpr.mgz session/bold/002/fmcpr.nii mri_convert session/bold/003/fmcpr.mgz session/bold/003/fmcpr.nii *STEP 4: Use fcseed-config to record the parameters you wish to pass to your connectivity analysis. |
*STEP 4: Use fcseed-config to configure the parameters you wish to pass to your connectivity analysis. |
| Line 99: | Line 33: |
| fcseed-config -segid 1010 -fcname mean.L_Posteriorcingulate.dat -fsd bold -mean -cfg mean.L_Posteriorcingulate.config | {{{fcseed-config -segid 1010 -fcname L_Posteriorcingulate.dat -fsd bold -mean -rescale-global -cfg mean.L_Posteriorcingulate.config}}} |
| Line 101: | Line 35: |
| This example will use the FreeSurfer cortical segmentation for the left posterior cingulate (segID: 1010). For seed regions, we recommend generating the mean signal timecourse by using "-mean" | This example will use the FreeSurfer cortical segmentation for the left posterior cingulate (segID: 1010, see $FREESURFER_HOME/FreeSurferColorLUT.txt for more) as defined for this individual in aparc+aseg.mgz. For seed regions, we recommend generating the mean signal timecourse by using "-mean". Note that this does not perform any analysis, it just creates a text file with the configuration. You can include more -segid flags to include more regions (though it will create only one seed time course). NOTE: Once a config file is created it may be used for multiple sessions. The -rescale-global option will rescale the seed to be 100/GlobalMean where GlobalMean is computed from the mean over the brain mask. It is also possible to rescale based on the mean inside of the ROI with -rescale-local. Finally, one can specify -no-rescale to turn off rescaling entirely; this is not recommended, but this is the way FSFAST computed the seed for all versions up to and including 7.4.1. |
| Line 103: | Line 37: |
| *STEP 5: Pass the config text file to fcseed-sess to generate time-course information for your chosen seed region (or for nuisance variable signal). | If you want to split a Freesurfer parcellation into multiple seeds ("split parcellation"), follow the [[FsFastFunctionalConnectivityWalkthroughSplittingSeeds |additional steps here]] - and resume with step 4 on this page... |
| Line 105: | Line 39: |
| Sample cmd (mean seed region timecourse): | *STEP 5: Create the FC seed for an individual |
| Line 107: | Line 41: |
| fcseed-sess -s <session> -cfg mean.L_Posteriorcingulate.config | {{{fcseed-sess -s sessionid -cfg L_Posteriorcingulate.config}}} |
| Line 109: | Line 43: |
| Sample cmd (Principal component analysis for nuisance regressors): | This creates a file called L_Posteriorcingulate.dat in each resting state run. This will have a single time course in it *STEP 6: Create nuisance variables |
| Line 112: | Line 48: |
| . fcseed-config -wm -fcname wm.dat -fsd bold -pca -cfg wm.config . fcseed-sess -s <session> -cfg wm.config |
. fcseed-config -wm -fcname wm.dat -fsd bold -pca -cfg wm.config . fcseed-sess -s sessionid -cfg wm.config |
| Line 116: | Line 52: |
| . fcseed-config -vcsf -fcname vcsf.dat -fsd bold -mean -cfg vcsf.config . fcseed-sess -s <session> -cfg vcsf.config |
. fcseed-config -vcsf -fcname vcsf.dat -fsd bold -pca -cfg vcsf.config . fcseed-sess -s sessionid -cfg vcsf.config |
| Line 119: | Line 55: |
| *NOTE: Once a config file is created it may be used for multiple sessions | These commands will create wm.dat and vcsf.dat in for each resting state run. These are text files with multiple columns. Each column is a principle component. You will choose the number of components to use below. |
| Line 121: | Line 58: |
| *STEP 5: Use [[http://surfer.nmr.mgh.harvard.edu/fswiki/mkanalysis-sess|mkanalysis-sess]] to setup an analysis for your FC data | *STEP 7: Use [[http://surfer.nmr.mgh.harvard.edu/fswiki/mkanalysis-sess|mkanalysis-sess]] to configure an analysis for your FC data. Like the fcseed-config above, this is done once regardless of how many sessionds you have. |
| Line 123: | Line 60: |
| Sample cmd: | {{{mkanalysis-sess -analysis fc.lpccseed.surf.lh -surface fsaverage lh -fwhm 5 -notask -taskreg L_Posteriorcingulate.dat 1 -nuisreg vcsf.dat 5 -nuisreg wm.dat 5 -mcextreg -polyfit 5 -nskip 4 -fsd bold -TR <TR> }}} |
| Line 125: | Line 62: |
| mkanalysis-sess -a <analysisname> | This command does not perform any analysis; it just creates an analysis configuration called "fc.lpccseed.surf.lh". There will be a folder of this name with a text file called analysis.info. The analysis will be run on the left hemisphere of fsaverage smoothed by 5 mm (this was already performed in preprocessing above). The waveform in the file called mean.L_Posteriorcingulate.dat will be used as the "task regressor"; this is just the FC seed. There are five sets of nuisance variables: (1) the CSF from which the top 5 principle components will be used, (2) the white matter from which the top 5 principle components will be used, (3) motion correction parameters (-mcextreg), (4) 5th order polynomial, and (5) the first 4 time points will be discarded. If you with to perform global signal regression, add "-nuisreg global.waveform.dat 1". Specify the TR with the -TR flag (eg, TR 2 for 2 seconds). Note that separate mkanalysis-sess commands will need to be run for the righ hemisphere and for the mni305 volume-based analysis. |
| Line 127: | Line 64: |
| . -surface fsaverage <hemi> -notask -taskreg mean.L_Posteriorcingulate.dat 1 -nuisreg vcsfreg.dat 3 -nuisreg wmreg.dat 3 -nuisreg global.waveform.dat 1 -fwhm 5 -fsd bold -TR <TR> -mcextreg -polyfit 2 -nskip 4 | *STEP 8: Use [[http://surfer.nmr.mgh.harvard.edu/fswiki/selxavg3-sess|selxavg3-sess]] to run the subject-level analysis outlined by the above mkanalysis-sess cmd just as you would with a task-based analysis |
| Line 129: | Line 66: |
| *STEP 6: Use [[http://surfer.nmr.mgh.harvard.edu/fswiki/selxavg3-sess|selxavg3-sess]] to run the subject-level analysis outlined by the above mkanalysis-sess cmd. | {{{selxavg3-sess -s sessionid -a fc.lpccseed.surf.lh}}} |
| Line 131: | Line 68: |
| . selxavg3-sess -s <session> -a <analysisname> | This performs the voxel-wise time series analysis for the given session. This results in several files being generated in the session folder. These include |
| Line 133: | Line 70: |
| *STEP 7: Choose the contrast file (generated in each session's contrast directory) that you wish to analyze on a group level: | * ces.mgz - contrast effect size (contrast matrix * regression coef) * cesvar.mgz - variance of contrast effect size * sig.mgz - significance map (-log10(p)) * pcc.mgz - partial correlation coefficient map |
| Line 135: | Line 75: |
| # ces.mgz - contrast effect size (contrast matrix * regression coef) # cesvar.mgz - variance of contrast effect size # sig.mgz - significance map (-log10(p)) # pcc.mgz - partial correlation coefficient map |
*STEP 9: Group-level analysiss |
| Line 140: | Line 77: |
| *STEP 8: To continue with a group-level analysis, try one of the methods below: Method 1: *create fsgd file containing all sessions of interest *Concatenate contrast files using [[http://www.freesurfer.net/fswiki/mri_concat|mri_concat]] *Run group analysis using [[http://www.freesurfer.net/fswiki/mri_concat|mri_glmfit]] Should also be possible with: Method 2: *[[http://www.freesurfer.net/fswiki/Qdec|Qdec]] Should also be possible with: Method 3: *Concatenate with [[http://www.freesurfer.net/fswiki/isxconcat-sess|isxconcat-sess]] *Run group analysis using [[http://www.freesurfer.net/fswiki/mri_concat|mri_glmfit]] |
As with task-based analysis, you will run isxconcat-sess to create a "stack" of maps from each subject. If you want to use the correlation coefficient instead of the ces, specify -map pcc. Specify the contrast as L_Posteriorcingulate (or just use -all-contrasts). After that, you can perform the standard group FS group analysis. |
This page describes how to perform seed-based functional connectivity (FC) analysis in FSFAST. The FC analysis is an extension of the task-based analysis for which there is much more documentation. These instructions mainly cover the details specific to FC analysis. The other steps are given minimal treatment under the understanding that many more details can be found in the task based analysis documentation as found in FS-FAST powerpoint and the FS-FAST tutorial. Steps 4, 5, and 6 are the only ones specific to FC analysis.
*STEP 1: Unpack Data into the FSFAST Hierarchy using dcmunpack (run with -help for more documentation):
Sample cmd:
dcmunpack -src dicomdir -targ sessionid -fsfast -run 3 bold nii.gz f.nii.gz -run 4 bold nii.gz f.nii.gz
In this sample command...
- Have all fMRI dicoms for this subject in the dicomdir folder or subfolders under this folder
- Arguement for "-targ" specifies output directory here called "sessionid". This should be unique to the subject (and visit if longitudinal). This is called the session folder.
- -run 3 bold nii.gz f.nii.gz will unpack run 3 fmri to sessionid/bold/003/f.nii.gz
- To get a list of runs, run dcmunpack -src dicomdir/subject/ALLDICOMS
- Use "-fsfast" to generate fsfast hierarchy shown in the image below
- The parent folder of the sessionid folder is called the "Project Folder" or "Project Directory". All the commands below should be run from the Project Folder.
*STEP 2: Link to FreeSurfer anatomical analysis. This is done by creating a text file called sessionid/subjectname with the name of the FreeSurfer anatomical folder as created with recon-all and found in $SUBJECTS_DIR.
*STEP 3: Pre-process your bold data using preproc-sess preproc-sess
Sample command preproc-sess -s sessionid -fwhm 5 -surface fsaverage lhrh -mni305-2mm
By default this will do motion correction, masking, registration to the anatomical, sampling to the surface, and surface smoothing by 5mm as well as sampling to the mni305 with volume smoothing. The surface sampling is done onto the surface of the lh and rh hemispheres of fsaverage. The mni305 is only used for volume-based analysis of subcortical structures. Note that eventhough the time series data are sampled onto fsaverage, the FC seeds are derived from the indvidual anatomy as shown below using unsmoothed data. See the task-based analysis documentation for more information.
*STEP 4: Use fcseed-config to configure the parameters you wish to pass to your connectivity analysis.
Sample command: fcseed-config -segid 1010 -fcname L_Posteriorcingulate.dat -fsd bold -mean -rescale-global -cfg mean.L_Posteriorcingulate.config
This example will use the FreeSurfer cortical segmentation for the left posterior cingulate (segID: 1010, see $FREESURFER_HOME/FreeSurferColorLUT.txt for more) as defined for this individual in aparc+aseg.mgz. For seed regions, we recommend generating the mean signal timecourse by using "-mean". Note that this does not perform any analysis, it just creates a text file with the configuration. You can include more -segid flags to include more regions (though it will create only one seed time course). NOTE: Once a config file is created it may be used for multiple sessions. The -rescale-global option will rescale the seed to be 100/GlobalMean where GlobalMean is computed from the mean over the brain mask. It is also possible to rescale based on the mean inside of the ROI with -rescale-local. Finally, one can specify -no-rescale to turn off rescaling entirely; this is not recommended, but this is the way FSFAST computed the seed for all versions up to and including 7.4.1.
If you want to split a Freesurfer parcellation into multiple seeds ("split parcellation"), follow the additional steps here - and resume with step 4 on this page...
*STEP 5: Create the FC seed for an individual
fcseed-sess -s sessionid -cfg L_Posteriorcingulate.config
This creates a file called L_Posteriorcingulate.dat in each resting state run. This will have a single time course in it
*STEP 6: Create nuisance variables
for white matter:
- fcseed-config -wm -fcname wm.dat -fsd bold -pca -cfg wm.config
- fcseed-sess -s sessionid -cfg wm.config
for ventricles + CSF:
- fcseed-config -vcsf -fcname vcsf.dat -fsd bold -pca -cfg vcsf.config
- fcseed-sess -s sessionid -cfg vcsf.config
These commands will create wm.dat and vcsf.dat in for each resting state run. These are text files with multiple columns. Each column is a principle component. You will choose the number of components to use below.
*STEP 7: Use mkanalysis-sess to configure an analysis for your FC data. Like the fcseed-config above, this is done once regardless of how many sessionds you have.
mkanalysis-sess -analysis fc.lpccseed.surf.lh -surface fsaverage lh -fwhm 5 -notask -taskreg L_Posteriorcingulate.dat 1 -nuisreg vcsf.dat 5 -nuisreg wm.dat 5 -mcextreg -polyfit 5 -nskip 4 -fsd bold -TR <TR>
This command does not perform any analysis; it just creates an analysis configuration called "fc.lpccseed.surf.lh". There will be a folder of this name with a text file called analysis.info. The analysis will be run on the left hemisphere of fsaverage smoothed by 5 mm (this was already performed in preprocessing above). The waveform in the file called mean.L_Posteriorcingulate.dat will be used as the "task regressor"; this is just the FC seed. There are five sets of nuisance variables: (1) the CSF from which the top 5 principle components will be used, (2) the white matter from which the top 5 principle components will be used, (3) motion correction parameters (-mcextreg), (4) 5th order polynomial, and (5) the first 4 time points will be discarded. If you with to perform global signal regression, add "-nuisreg global.waveform.dat 1". Specify the TR with the -TR flag (eg, TR 2 for 2 seconds). Note that separate mkanalysis-sess commands will need to be run for the righ hemisphere and for the mni305 volume-based analysis.
*STEP 8: Use selxavg3-sess to run the subject-level analysis outlined by the above mkanalysis-sess cmd just as you would with a task-based analysis
selxavg3-sess -s sessionid -a fc.lpccseed.surf.lh
This performs the voxel-wise time series analysis for the given session. This results in several files being generated in the session folder. These include
- ces.mgz - contrast effect size (contrast matrix * regression coef)
- cesvar.mgz - variance of contrast effect size
- sig.mgz - significance map (-log10(p))
- pcc.mgz - partial correlation coefficient map
*STEP 9: Group-level analysiss
As with task-based analysis, you will run isxconcat-sess to create a "stack" of maps from each subject. If you want to use the correlation coefficient instead of the ces, specify -map pcc. Specify the contrast as L_Posteriorcingulate (or just use -all-contrasts). After that, you can perform the standard group FS group analysis.