Installation and Usage Instructions - SPMIC-UoN/BRC_Pipeline GitHub Wiki
- Release notes
- Prerequisities
- Installation
- Structure of the output folders
- Running the BRC Pipelines for different modalities
The BRC Pipelines have the following software requirements:
-
A 64-bit Linux Operating System
-
The FSL version 6.0.6 (www.fmrib.ox.ac.uk/fsl) installed and configuration file properly sourced.
-
FreeSurfer version 7.1.0 (https://surfer.nmr.mgh.harvard.edu/)
-
Matlab (we used 2018a but it should all work with previous versions)
- For MATLAB, you will need the official MATLAB toolboxes:
- Statistics
- Bioinformatics
- Signal Processing
-
SPM version 12 (https://www.fil.ion.ucl.ac.uk/spm/software/spm12/)
-
Cuda version 8.0
-
The FSL version 5.0.11 (www.fmrib.ox.ac.uk/fsl) installed and configuration file properly sourced. Some parts of the fMRI preprocessing pipeline need FSL version 5.0.11. The pipeline has been tested using FSL 6.0.5.
-
Convert3D Medical Image Processing Tool (https://sourceforge.net/projects/c3d/)
NOTE: We already have installed the latest version of the pipeline on the University of Nottingham's High-Performance Cluster. If you have access to that cluster, you can skip the following installation steps. You just need to load the module of the BRC Pipeline using the following command:
module load brc-pipelines-img
The installation procedure is as follows:
-
Install the listed prerequisites first.
-
Create a directory in which you want the BRC Pipeline to be installed and then go to that folder, e.g.
$ mkdir ~/Scripts $ cd ~/Scripts -
Download the BRC Pipeline project files using the following command:
$ git clone https://github.com/SPMIC-UoN/BRC_Pipeline -
This will create a directory containing the HCP Pipelines, e.g.
$ cd ~/BRC_Pipeline $ ls -F BRC_IDP_extraction/ BRC_diffusion_pipeline/ BRC_func_group_analysis/ BRC_structural_pipeline/ BRC_functional_pipeline/ BRC_perfusion_pipeline/ global/ README.md SetUpBRCPipeline.sh Show_version.sh product.txt version.txt -
In order to make the scripts executable, the following command must be called in the
~/BRC_Pipelinedirectory:$ find . -name "*.sh" -exec chmod 755 {} \; -
All of the environment variables used in the BRC Pipeline are set in the
SetUpBRCPipeline.shscript. TheSetUpBRCPipeline.shscript assumes that you have:- properly installed FSL
- set the FSLDIR environment variable (you can modify
SetUpBRCPipeline.shto correctly set up the FSLDIR) - sourced the FSL configuration script
- properly installed FreeSurfer
- set the FREESURFER_HOME environment variable (you can modify
SetUpBRCPipeline.shto correctly set up the FREESURFER_HOME) - sourced the FreeSurfer setup script
If you want to run the BRC Pipeline via a high-performance cluster (HPC), then you need to set
CLUSTER_MODEvariable in theSetUpBRCPipeline.shscript. Then, most of the softwares like FSL and FreeSurfer will be configured, automatically. Also, in theSetUpBRCPipeline.shscript you need to set up specific environment variables for the BRC Pipeline. You may need to update the setting of theSetUpBRCPipeline.shvariables to reflect where you have installed the 'FSL', 'Freesurfer', 'MATLAB', 'SPM', 'Cuda', 'DVARS', and 'BRC Pipeline', respectively. These environment variables are as follows:If you are running the pipeline on HPC:
$ export CLUSTER_MODE="YES" #TO BE MODIFIED BY USER, "YES"/"NO"If you are running the pipeline on servers or PCs:
$ export CLUSTER_MODE="NO" #TO BE MODIFIED BY USER, "YES"/"NO" $ export FSLDIR="/Path/to/fsl (e.g., /usr/local/fsl)" #TO BE MODIFIED BY USER $ export FREESURFER_HOME="/Path/to/freesurfer (e.g., /usr/local/freesurfer)" #TO BE MODIFIED BY USER $ export MATLABpath="/Path/to/Matlab (e.g., /usr/local/matlab/R2017a/bin)" #TO BE MODIFIED BY USER $ export FSLDIR_5_0_11="/Path/to/fsl 5.0.11 (e.g., /usr/local/fsl-5.0.11)" #TO BE MODIFIED BY USER $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:"/Path/to/Cuda (e.g., /usr/local/cuda/lib64)" #TO BE MODIFIED BY USERIn addition, you need to specify the path of the following items:
$ export SPMpath="/Path/to/SPM (e.g., /usr/local/spm12)" #TO BE MODIFIED BY USER $ export DVARSpath="/Path/to/DVARS (e.g., /usr/local/DVARS)" #TO BE MODIFIED BY USER $ export ANTSPATH="/Path/to/ANTs (e.g., "/usr/local/ANTs/ants-2.1.0-redhat/" #TO BE MODIFIED BY USER $ export C3DPATH="/Path/to/C3D (e.g., "/usr/local/c3d/bin" #TO BE MODIFIED BY USER $ export BRCDIR="/Path/to/BRC Pipeline (e.g., ${HOME}/Scripts/BRC_Pipeline)" #TO BE MODIFIED BY USER -
To set all of the environment variables used in the BRC Pipeline appropriately, you need to carry out some configuration by hand. How you do this will depend on what shell you are using. In BASH shell, User shell setup is stored in a file called
.bash_profilein your home folder (e.g.,~/.bash_profile). You need to edit (or create) this file and add the following line:$ source ${HOME}/Scripts/BRC_Pipeline/SetUpBRCPipeline.shPlease change
${HOME}/Scripts/BRC_Pipeline/SetUpBRCPipeline.shto a directory path you have installed the BRC Pipeline.NOTE: Already, the pipeline has been installed in the internal clusters of the University of Nottingham. Therefore, the internal users just need to add
/usr/local/BRC_Pipeline-<VERSION NUMBER>/SetUpBRCPipeline.shto their.bash_profile. -
To make it easier for people who work with the pipeline at the University of Nottingham, we have saved SetUpBRCPipeline.sh files that are ready to be used in our internal clusters such as Chilli, Pepper, and HPC (Augusta). These files are saved in the following directory:
/BRC_Pipeline/global/examples/
The structure of the pipeline is designed in such a way that in the study folder, the analyzed data of each subject is saved in a folder that its name is the subject ID of that subject. Then the raw data of each modality will be saved in the raw folder and all the analyzed files will be saved in the analysis folder. The general structure of the output files is demonstrated here:
The current version of BRC pipeline can cover the preprocessing of the following modalities:
The Structural preprocessing is the first step for the processing of data for each subject. Structural preprocessing is subdivided into 2 parts: T1w-MRI preprocessing and T2w-MRI (if available). The preprocessing pipeline contains:
- Bias-filed correction
- Skull stripping
- Tissue segmentation (GM, WM, and CSF)
- Subcortical segmentation
- Registration (linear/non-linear) to standard space
- Multimodal tissue segmentation
- FreeSurfer analysis
- FastSurfer analysis
- Quality control
The schematic of the structural pipeline is described in the following image: 
The usage of struc_preproc.sh is as follows:
struc_preproc.sh <arguments>
-
Compulsory arguments (You MUST set all of):
--input <path> Full path of the input T1w image (for one image only) --path <path> Output path --subject <subject name> Output directory is a subject name folder in output path directory -
Optional arguments (You may optionally specify one or more of):
--t2 <path> Full path of the input T2W image (for processing of T2 data) --freesurfer Turn on Freesurfer processing pipeline --fastsurfer Turn on Fastsurfer processing pipeline --subseg Turn on subcortical segmentation by FIRST --qc Turn on quality control of T1 data --noreg Turn off steps that do registration to standard (FLIRT and FNIRT) --noseg Turn off the step that does tissue-type segmentation (FAST) --nocrop Turn off the step that does automated cropping --nodefacing Turn off the step that does automated brain defacing --regtype <method> The registration method for the registration of structural data to the standard space 1: Linear, 2: Linear + Non-linear (FNIRT in FSL) (default value). Here, the linear transformation is used as an initialization step for the Non-linear registration 3: Linear + Non-linear (ANTs). --t2lesion <path> Full path of the input labeled lesion mask in T2 native space --fbet <value> Fractional intensity threshold in FSL BET (0 <-> 1); default=0.5. FSL BET is used as an initialisation step for the final brain extraction algorithm. If the default value didn't work (it works in most of the cases), you have this option to give it as an input into the pipeline. --help help
Diffusion preprocessing depends on the outputs generated by Structural preprocessing. So diffusion preprocessing should not be attempted on data sets for which structural preprocessing is not yet complete. The output path and subject name of the Diffusion preprocessing must be exactly the same as the path and subject name used for the preprocessing of the anatomical MRI of that subject. The preprocessing pipeline contains:
- Skull stripping
- Eddy current correction
- EPI distortion correction
- Motion correction (between/within the volume)
- Registration (linear/non-linear) to anatomical/standard space
- Microstructure maps
- Quality control
The schematic of the structural pipeline is described in the following image: 
The usage of dMRI_preproc.sh is as follows:
dMRI_preproc.sh <arguments>
-
Compulsory arguments (You MUST set all of):
--input <path> dataLR(AP)1@dataLR(AP)[email protected](AP)N, filenames of input images (For input filenames, if for a LR/RL (AP/PA) pair one of the two files are missing set the entry to EMPTY) --path <path> output directory. Please provide absolute path --subject <subject name> output directory is a subject name folder in output path directory --echospacing <value> EchoSpacing should be in Sec --pe_dir <value> Phase Encoding Direction 1 for LR/RL, 2 for AP/PA -
Optional arguments (You may optionally specify one or more of):
--input_2 <path> dataRL(PA)1@dataRL(PA)[email protected](PA)N, filenames of input images (reverse phase encoding direction), Set to NONE if not available (default) --slspec <path> Specifies a .json file (created by your DICOM->niftii conversion software) that describes how the slices/multi-band-groups were acquired. This file is necessary when using the slice-to-vol movement correction --slice2vol If one wants to do slice-to-volome motion correction --cm_flag <value> CombineMatchedFlag 2 for including in the output all volumes uncombined (default), 1 for including in the output and combine only volumes where both LR/RL (or AP/PA) pairs have been acquired, 0 for including (uncombined) single volumes as well --p_im <value> ParallelImaging_Factor, In-plane parallel imaging factor 1 for No_Parallel_Imagin --movebysusceptibility By setting this option, eddy attempts to estimate how the susceptibility-induced field changes when the subject moves in the scanner This option activates '--estimate_move_by_susceptibility' in EDDY This option is available for FSL 6 onwards --hires This option will increase the time limits and the required memory for the processing of high-resolution data --dtimaxshell <value> Select the maximum shell value to calculate the DTI model. Default: 1500 --skip_preproc By adding this option, the pipeline skip eunning pre-processing steps. NOTE: user can add --qc, --reg, --tbss, --noddi, --dki, --wmti, and --alps as the input(s) of the pipeline --qc Turn on steps that do quality control of dMRI data --reg Turn on steps that do registration to standard (FLIRT and FNIRT) --tbss Turn on steps that run TBSS analysis. --noddi Turn on steps that run NODDI analysis. NOTE: requires multi-shell data. NOTE: The pipeline always generates the DTI model maps. --dki Turn on steps that generates microsctructural maps using diffusion kurtosis model. NOTE: requires multi-shell data. --wmti Turn on steps that generates microsctructural maps using white matter tract integrity model. NOTE: requires multi-shell data. --alps Turn on steps that compute the diffusion along perivascular spaces (ALPS) metric. --mppca Perform denoising using Marcenko-Pastur PCA. Default: No denoising --use_topup <path> If one wants to skip the TOPUP step of the pipeline and use the previously prepared folder. Please provide absolute path. --help help
Perfusion preprocessing depends on the outputs generated by Structural preprocessing. So perfusion preprocessing should not be attempted on data sets for which structural preprocessing is not yet complete. It requires a difference and calibration image from single TI pseudo-continuous arterial spin labelling (does not work with other types of perfusion data). The output path and subject name of the Perfusion preprocessing must be exactly the same as the path and subject name used for the preprocessing of the anatomical MRI of that subject. The preprocessing pipeline contains:
- Single TI partial volume correction based on Modified Partial Least Trimmed Squares (MLTS)
- Registration to anatomical/standard space
The usage of ASL_preproc.sh is as follows:
ASL_preproc.sh <arguments>
-
Compulsory arguments (You MUST set one or more of):
--input_pwi <path> full path of the filename of difference (perfusion-weighted) image --input_m0 <path> full path of the filename of calibration (M0) image --path <path> output directory --subject <subject name> output directory is a subject name folder in input image directory -
Optional arguments (You may optionally specify one or more of):
--tr Repetition time (TR) of calibration data (default 3.2 sec) --ti Inversion time (TI) of calibration data (default 3.0 sec) --bolus Bolus (labelling) duration (default 1) --cgain Relative gain between calibration and ASL image (default 1) --pvcmethod <method> Partial volume correction method on quantified CBF map Values: MLTS and NONE (default) --name <folder name> Output folder name of the functional analysis pipeline. Default: aslMRI --help help
Functional preprocessing depends on the outputs generated by Structural preprocessing. So functional preprocessing should not be attempted on data sets for which structural preprocessing is not yet complete. The output path and subject name of the Functional preprocessing must be exactly the same as the path and subject name used for the preprocessing of the anatomical MRI of that subject. The preprocessing pipeline contains:
- EPI distortion correction
- Estimated
- Measured
- Motion correction
- Between volume
- Within volume
- Intensity normalization
- Slice timing correction
- Temporal filtering
- Physiological noise removal
- Automatic
- Measured regressors
- Quality control
- Registration to anatomical/standard space
- Static functional connectivity
- Dynamic functional connectivity
The schematic of the functional preprocessing pipeline is described in the following image: 
The usage of dMRI_preproc.sh is as follows:
fMRI_preproc.sh <arguments>
-
Compulsory arguments (You MUST set all of):
--input <path> full path of the filename of fMRI image --path <path> output directory --subject <subject name> output directory is a subject name folder in input image directory -
Optional arguments (You may optionally specify one or more of):
--mctype <Type> Motion correction method. MCFLIRT: between volumes (default), and EDDY: within/between volumes MCFLIRT6: between volumes with 6 degrees of freedom (default), MCFLIRT12: between volumes with 12 degrees of freedom, EDDY: within/between volumes --dcmethod <method> Susceptibility distortion correction method (required for accurate processing) Values: TOPUP, SiemensFieldMap (same as FIELDMAP), GeneralElectricFieldMap, and NONE (default) --fmriscout <path> A single band reference image (SBRef) is recommended if available. Set to NONE if not available (default) Set to NONE if you want to use the first volume of the timeseries for motion correction --slice2vol If one wants to do slice-to-volome motion correction --slspec <path> Specifies a .json file (created by your DICOM->niftii conversion software) that describes how the slices/multi-band-groups were acquired. This file is necessary when using the slice-to-vol movement correction --fmapmag <path> Expects 4D Magnitude volume with two 3D volumes (differing echo times). Set to NONE (default) if using TOPUP --fmapphase <path> Expects a 3D Phase difference volume (Siemens style). Set to NONE (default) if using TOPUP --fmapgeneralelectric Path to General Electric style B0 fieldmap with two volumes 1. field map in degrees 2. magnitude Set to 'NONE' (default) if not using 'GeneralElectricFieldMap' as the value for the DistortionCorrection variable --echodiff <value> Set to NONE if using TOPUP --SEPhaseNeg <path> For the SE field map volume with a 'negative' phase encoding direction (the same direction of fMRI data) Set to NONE if using regular FIELDMAP --SEPhasePos <path> For the SE field map volume with a 'positive' phase encoding direction (the opposite direction of fMRI data) Set to NONE if using regular FIELDMAP --echospacing <value> Effective Echo Spacing of spin echo field map acquisitions (in sec) NOTE: The pipeline expects you to have used the same phase encoding axis and echo spacing in the fMRI data as in the SE field map acquisitions. Otherwise, you need to specify the fMRI Echo spacing using --echospacing_fMRI --unwarpdir <direction> Based on Phase Encoding Direction: PA: 'y', AP: 'y-', RL: 'x', and LR: 'x- --biascorrection <method> Receive coil bias field correction method Values: NONE (default), or SEBASED (Spin-Echo Based) SEBASED calculates bias field from spin echo images (which requires TOPUP distortion correction) --intensitynorm If one wants to do intensity normalization --stcmethod <method> Slice timing correction method 0: NONE (default value), 1: (SPM) If the slices were acquired with interleaved order (0, 2, 4 ... 1, 3, 5 ...), 2: (SPM) If slices were acquired with forward order (0, 1, 2, ...), 3: (SPM) If slices were acquired with backward order (n, n-1, n-2, ...), 4: (FSL) If slices were acquired from the bottom of the brain, 5: (FSL) If slices were acquired from the top of the brain to the bottom, 6: (FSL) If the slices were acquired with interleaved order (0, 2, 4 ... 1, 3, 5 ...), 7: (FSL) If slices were not acquired in regular order you will need to use a slice order file or a slice timings file. If a slice order file is to be used, create a text file with a single number on each line, where the first line states which slice was acquired first, the second line states which slice was acquired second, etc. The first slice is numbered 1 not 0. The file path should be specified using --slstiming 8: (FSL) If a slice timings file is to be used, put one value (ie for each slice) on each line of a text file. The units are in TRs, with 0.5 correspondings to no shift. Therefore a sensible range of values will be between 0 and 1. The file path should be specified using --slstiming --slstiming <path> file path of a single-column custom interleave order/timing file --fwhm <value> Spatial size (sigma, i.e., half-width) of smoothing, in mm. Set to 0 (default) for no spatial smooting --noaroma disable ICA-AROMA for Artifact/Physiological Noise Removal --fmrires <value> Target final resolution of fMRI data in mm (default is 2 mm) --tempfilter <value> Non-zero value of this option means that one wants to do temporal filtering with High pass filter curoff <value> in Sec the default value is 0, means No Temporal Filtering --echospacing_fMRI <value> Echo Spacing of fMRI image (in sec) --name <folder name> Output folder name of the functional analysis pipeline. Default: rfMRI --noqc Turn off quality control of fMRI data --clean Delete all intermediate files --delvolumes <value> Delete a number of volumes from the start of the fMRI 4D data --printcom use 'echo' for just printing everything and not running the commands (default is to run) --help help
Functional connectivity and network analysis depend on the outputs generated by Structural and Functional preprocessing. So the analysis pipeline should not be attempted on data sets for which structural and functional preprocessing is not yet complete.
The network analysis contains:
- Functional connectivity analysis
- Anatomical/functional atlas-based
- ICA-based
- Association type
- Covariance
- Amplitude
- Full correlation
- Partial correlation
- Simple
- L1-norm
- L2-norm
- Cross-subject group analysis
- Group ICA
The usage of fmri_group_analysis.sh is as follows:
fmri_group_analysis.sh <arguments>
-
Compulsory arguments (You MUST set all of):
--in <path> List of all subject IDs their 4D datasets are preprocessed and are in the standard-space --indir <path> Input directory full path. All of the input list subjects must be in this directory --outdir <path> Output directory full path for group analysis --parcellation <atlas> Type of parcellation used to extract ROIs: FS_DKA: This atlas is known as the 'Desikan-Killiany' cortical atlas in FreeSurfer. This atlas is in the functional native space. FS_DA: This atlas is known as the 'Destrieux' cortical atlas in FreeSurfer. This atlas is in the functional native space. AAL: This atlas is known as AAL 'Automated Anatomical Labeling' atlas This atlas is in the standard MNI152 space and contains 116 ROIs. SHEN: a functional atlas that covering both cortical and sub-cortical brain regions This atlas is in the standard MNI152 space and contains 268 ROIs. MELODIC: Multivariate Exploratory Linear Optimized Decomposition into Independent Components By choosing this option you have to specify --approach, --dim options. NONE: a user defined atlas which can be used as an input using --inatlas option. Also, the label maps should be specified using --labels option. --fmrires <value> Data resolution of fMRI data and ATLAS in mm --tr <value> Repetition time in sec -
Optional arguments (You may optionally specify one or more of):
--labels <path> List of the label values that you want to extract their time series (default all labels in the ATLAS) --corrtype <method> Type of assosiation estimation: COV: covariance (non-normalised 'correlation') AMP: only use nodes' amplitude CORR: full correlation (diagonal is set to zero) (default) RCORR: full correlation after regressing out global mean timecourse PCORR: partial correlation. If a lambda parameter is given as the --regval option, 'PCORR' will change to L1-norm regularised partial correlation with lambda= <--regval value> RPCORR: partial correlation using L2-norm Ridge Regression (aka Tikhonov) The rho parameter is given by --regval option --regval <value> Regularization value used for 'PCORR' (default is 0) and 'RPCORR' (default is 0.1) --varnorm <value> Temporal variance normalisation to apply 0 = none (default) 1 = normalise whole subject stddev 2 = normalise each separate timeseries from each subject --groupdiffs do cross-subject GLM on a set of network matrices, giving uncorrected and corrected (1-p) values assuming you already specified the corresponding group for each subject in a column next to each subject name (e.g., 1 for the 1st group and 2 for the 2nd group) in --in option input file --approach <method> Approach for multi-session/subject data: concat: temporally-concatenated group-ICA using MIGP (default) tica: tensor-ICA --dim <value> Dimensionality reduction into #num dimensions (default: automatic estimation) --inatlas <path> User defined atlas which can be used for parcellation --gmroi Add the MNI152 GM mask to the list of ROIs for calculating the functional connections --nofr2z Do not apply Fisher's r-to-Z transformation for the calculation of FC. Default: convert from r to z --help help
- Mnet_{correlation method}.txt:
- Simple average group-level analysis to look at the mean network matrix across all subjects
- Znet_{correlation method}.txt:
- The results of a simple one-group t-test across subjects as Z values
- netmats_{correlation method}.txt:
- Is a network matrix for each subject (the vectorized version of a matrix) based on the specified association method. These values are Z values
IDP extraction pipeline depends on the outputs generated by the Structural (T1/T2) and diffusion preprocessing pipelines. So if the pipeline does not find the desired data in the folder where the data is supposed to be stored, the output values will be NaN for the features related to that data. The current version of the pipeline extracts the IDPs related to the following processed data:
- T1 alignment to standard space
- T2 alignment to T1
- Tissue/head size volumes
- Subcortical gray matter volumes
- Cortical grey matter volumes
- T2 FLAIR white matter hyperintensity
- WM tract microstructural features for FA, MD, MO, L1, L2, L3, ICVF, ISOVF, and DOI.
The usage of idp_extract.sh is as follows:
idp_extract.sh <arguments>
-
Compulsory arguments (You MUST set all of):
--in <path> A list of subject IDs that are pre-processed --indir <path> The full path of the input directory. All of the IDs that are in the input list MUST have a pre-processed folder in this direcory --outdir <path> The full path of the output directory to save the output files