diff --git a/README.md b/README.md
index b3815e5..1e9e676 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,27 @@
(Working in progress...) \
-Last updated: 06-Oct-2020
+Last updated: 2021-11-16
- [Introduction](#introduction)
- - [Dependency](#dependency)
+ - [Dependency](#dependency)
- [Preparations](#preparations)
- - [Setup global environment](#setup-global-environment)
- - [Create files for FreeSurfer](#create-files-for-freesurfer)
+ - [Setup global environment](#setup-global-environment)
+ - [Create files needed for FreeSurfer](#create-files-needed-for-freesurfer)
- [Pre-processing](#pre-processing)
- - [FreeSurfer](#freesurfer)
- - [HCP pipeline](#hcp-pipeline)
- - [Project volumetric data to surface data](#project-volumetric-data-to-surface-data)
+ - [FreeSurfer](#freesurfer)
- [First-level analysis](#first-level-analysis)
- - [Configure analysis, contrasts and perform the analysis](#configure-analysis-contrasts-and-perform-the-analysis)
- - [Draw labels based on contrast](#draw-labels-based-on-contrast)
+ - [Configure analysis, contrasts and perform the analysis](#configure-analysis-contrasts-and-perform-the-analysis)
+ - [Draw labels based on contrast](#draw-labels-based-on-contrast)
- [Group level analysis](#group-level-analysis)
- - [1. Group level analysis on fsaverage](#1-group-level-analysis-on-fsaverage)
- - [2. Univariate analysis of ROIs on self surface](#2-univariate-analysis-of-rois-on-self-surface)
- - [3. Classification/decoding with CoSMoMVPA](#3-classificationdecoding-with-cosmomvpa)
- - [4. Searchlight with CoSMoMVPA](#4-searchlight-with-cosmomvpa)
- - [Some suggestion for these analyses (or notes for myself)](#some-suggestion-for-these-analyses-or-notes-for-myself)
+ - [1. Group level analysis on fsaverage](#1-group-level-analysis-on-fsaverage)
+ - [2. Univariate analysis of ROIs on self surface](#2-univariate-analysis-of-rois-on-self-surface)
+ - [3. Classification/decoding with CoSMoMVPA](#3-classificationdecoding-with-cosmomvpa)
+ - [4. Searchlight with CoSMoMVPA](#4-searchlight-with-cosmomvpa)
+ - [Some suggestion for these analyses (or notes for myself)](#some-suggestion-for-these-analyses-or-notes-for-myself)
- [Data visualization](#data-visualization)
- - [Quality assurance of recon-all results](#quality-assurance-of-recon-all-results)
- - [Check other results](#check-other-results)
+ - [Quality assurance of recon-all results](#quality-assurance-of-recon-all-results)
+ - [Check other results](#check-other-results)
- [How-to](#how-to)
- [Future work](#future-work)
- [Q&A](#qa)
@@ -35,64 +33,67 @@ Last updated: 06-Oct-2020
These Matlab functions mainly call [FreeSurfer](https://surfer.nmr.mgh.harvard.edu/) commands to analyze fMRI data on the surface, perform multivariate pattern analysis (MVPA) with [CoSMoMVPA](http://www.cosmomvpa.org/) toolbox, and visualize results with [FreeView](https://surfer.nmr.mgh.harvard.edu/fswiki/FreeviewGuide/FreeviewIntroduction) and codes based on [Dr. Kendrick Kay](https://github.com/kendrickkay)'s work.
+Now some wrappers for BIDS, fMRIPrep, and HCPPipeline are also included.
+
**Note**:
-1. These functions are only tested in Mac, but have not been tested in Linux.
-2. These functions are built based on FreeSurfer 6.0, and therefore some may fail when previous FreeSurfer versions are loaded.
-3. Some default parameters in the functions were set based on our data acquisition protocol, they may not be appropriate for other protocols.
+1. These functions were only tested in Mac.
+2. These functions were built based on FreeSurfer 6.0, and therefore some may fail when earlier FreeSurfer versions are loaded (it seems to work on later versions).
+3. Some default parameters in the functions were set according to our data acquisition protocol, they may not be appropriate for others.
## Dependency
-The following software and toolboxes should be installed properly before using the current toolbox. Also, it is assumed that the user understands [the FS-FAST directory structure](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV6.0/FsFastDirStruct) and the general steps (and commands) for performing fMRI data analysis in [FS-Fast](http://freesurfer.net/fswiki/FsFastTutorialV6.0).
+The following software and toolboxes should be installed properly before using this toolbox. Also, it is assumed that the user understands [the FS-FAST directory structure](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV6.0/FsFastDirStruct) and the general steps (and commands) for performing fMRI data analysis in [FS-Fast](http://freesurfer.net/fswiki/FsFastTutorialV6.0).
- [FreeSurfer](https://surfer.nmr.mgh.harvard.edu/);
- [NIfTI_20140122](https://www.mathworks.com/matlabcentral/fileexchange/8797-tools-for-nifti-and-analyze-image);
- [CoSMoMVPA](http://www.cosmomvpa.org/) (for running multivariate pattern analysis);
- [knkutils](https://github.com/kendrickkay/knkutils.git) and [cvncode](https://github.com/kendrickkay/cvncode.git) (for visualizations in Matlab).
+Check [here (to be added)]() for a full list of dependended toolboxs.
+
# Preparations
## Setup global environment
-As most of the functions in this toolbox call FreeSurfer commands which are linux commands, the path to FreeSurfer needs to be added to the global environment `$PATH`. In addition, the matlab/ folder in FreeSurfer (`$FREESURFER_HOME/matlab/`) also needs to be added to Matlab path. These setups can be accomplished in two ways. Once this setup is finished, the functions in this folder should work.
+As most of the functions in this toolbox call FreeSurfer commands which are linux commands, the path to FreeSurfer needs to be added to the global environment `$PATH`. In addition, the matlab/ folder in FreeSurfer (`$FREESURFER_HOME/matlab/`) also needs to be added to Matlab path. These can be set up in two ways.
- **Method 1**:
1. Start a new terminal;
2. Set all the necessary global environment variables (e.g., `$FREESURFER_HOME`, `$SUBJECTS_DIR` and `$FUNCTIONALS_DIR`) and set up FreeSurfer (the instruction is available on the [FreeSurfer website](https://surfer.nmr.mgh.harvard.edu/fswiki/DownloadAndInstall#Setup.26Configuration));
- 3. Start Matlab in the *same* terminal by running `path-to-matlab-folder/bin/matlab` in the terminal. [You also can add the `path-to-matlab-folder/bin` to `$PATH` by following [this instruction](https://apple.stackexchange.com/questions/358687/right-way-to-add-paths-to-path-in-mojave) and run `matlab` in the terminal].
+ 3. Start Matlab in the *same* terminal by running `path-to-matlab-folder/bin/matlab` in the terminal. [You may also add the `path-to-matlab-folder/bin` to `$PATH` by following [this instruction](https://apple.stackexchange.com/questions/358687/right-way-to-add-paths-to-path-in-mojave) and run `matlab` in the terminal].
- **Method 2**:
- 1. Start Matlab and make sure you added all folders of this toolbox to the Matlab `path`;
- 2. Run `fs_setup('path-to-freesurfer-home');` to set `'path-to-freesurfer-home'` as `$FREESURFER_HOME` and add necessary paths to `$PATH`;
- 3. Run `fs_subjdir('path-to-subjects-dir');` to set `'path-to-subjects-dir'` as `$SUBJECTS_DIR`;
+ 1. Start Matlab and add all subdirectory of this toolbox to the Matlab `path`;
+ 2. Run `fs_setup('path/to/freesurfer/home');` to set `'path/to/freesurfer/home'` as `$FREESURFER_HOME` and add necessary paths to `$PATH`;
+ 3. Run `fs_subjdir('path/to/subjects/dir');` to set `'path/to/subjects/dir'` as `$SUBJECTS_DIR`;
-## Create files for FreeSurfer
+## Create files needed for FreeSurfer
Make sure the following files have been created properly (at least before running the general linear model (GLM) in FreeSurfer).
- create [paradigm files (parfiles)](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastParadigmFile);
- - run files (if needed): txt files containing the name of runs (folders); you should have different files for localizer and main runs;
- - subjectname: a txt file containing the subject name in `$SUBJECTS_DIR`; this links the functional data folder and the structural data folder for that subject.
- - sessFile: a txt file containing the list of session names in that folder.
-
- [More information about the session folder](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV5.1/FsFastDirStruct_freeview).
+ - run files (if needed): txt files containing the name of runs (folders) in a column. For example, you should have different run files for localizer and main runs.
+ - subjectname: a txt file containing the subject name in `$SUBJECTS_DIR`; this links the functional data folder and the structural data folder for that subject (more see [here](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV6.0/FsFastDirStruct#TheSUBJECTSDIRand.27subjectname.27File)).
+ - sessID Files: a txt file containing the list of session names in that folder (more see [here](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV6.0/FsFastDirStruct#SpecifyingMultipleSessionstoAnalyze.28SessIDFiles.29)).
# Pre-processing
-Data can be pre-processed with FreeSurfer or [workbench](https://www.humanconnectome.org/software/connectome-workbench) (i.e., HCP pipeline). After pre-processing, there should be one folder consisting the functional data and a separate folder consisting structural data (i.e., the `recon-all` results).
+Data can be pre-processed by FreeSurfer, [fMRIPrep](https://fmriprep.org/en/stable/) or [HCPpipeline](https://github.com/Washington-University/HCPpipelines). After pre-processing, there should be one folder consisting the functional data and a separate folder consisting structural data (i.e., the `recon-all` results).
## FreeSurfer
-- Structure Data
- - `system('recon-all -s subjCode -i path/to/T1/image -all')`;
- - (or) `fs_recon()`.
-- Functional data
- - (e.g.) `system('preproc-sess -sf sessFile -fsd bold -surface self lhrh -mni305 -fwhm 0 -per-run -force')`;
- - (or) `fs_preproc()`.
-
-## HCP pipeline
-Please check [the HCP website](https://www.humanconnectome.org/) or [this paper](https://www.sciencedirect.com/science/article/pii/S1053811913005053?via%3Dihub) for more information about the pre-processing.
-
-To further analyze the pre-processed data obtained from HCP, we need to re-arrange the files to [the FS-FAST directory structure](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV6.0/FsFastDirStruct). `fs_hcp_preproc()` can help.
-
-## Project volumetric data to surface data
-To project preprocessed functional data in volumes to fsaverage or self surface: `fs_projsess()`.
+In terminal:
+```shell
+# structure
+recon-all -s subjCode -i path/to/T1/image -T2 path/to/T2/image -all
+
+# functional
+preproc-sess -sf sessFile -fsd bold -surface self lhrh -mni305 -fwhm 0 -per-run -force
+```
+
+In Matlab:
-For quality assurance, please check [here](#check-recon-all-results).
+```matlab
+% structure
+fs_recon()
+% functional
+fs_preproc()
+```
# First-level analysis
@@ -102,7 +103,7 @@ Steps | functions
1.Configure analyses | `fs_mkanalysis()`
2.Configure contrasts | `fs_mkcontrast()`
3.Perform the analysis | `fs_selxavg3()`
-More information on configuring analyses and contrasts can be found [here](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV5.1/FsFastFirstLevel_freeview).
+More information on configuring analyses and contrasts can be found [here](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV6.0/FsFastFirstLevel).
## Draw labels based on contrast
After performing the first level analysis, you may want to create ROI label files based on the contrast. Please check [How to draw ROI on surface?](documents/draw_surface_roi.md)
@@ -111,7 +112,7 @@ After performing the first level analysis, you may want to create ROI label file
# Group level analysis
## 1. Group level analysis on fsaverage
-More information can be found [here](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV5.1/FsFastGroupLevel_freeview).
+More information can be found [here](https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV6.0/FsFastGroupLevelPerm).
Steps | functions
-- | --
1.Concatenate first level results | `fs_isxconcat()`
@@ -141,6 +142,7 @@ Visualize nifty files: [ITK-SNAP](http://www.itksnap.org/pmwiki/pmwiki.php).
Visualize surface data: FreeView or functions based on [knkutils](https://github.com/kendrickkay/knkutils.git) and [cvncode](https://github.com/kendrickkay/cvncode.git).
## Quality assurance of recon-all results
+To check the recon-all results, use `fv_checkrecon('subjcode')`.
To check both the volumetric and surface data, use `fv_checkreg()`.
To check the volumetric data only, run `fv_vol('', subjCode)` .
To check the surface data only, run `fv_surf('', 'inflated')` and then select which participants to be displayed in FreeView.