fMRI process pipeline: fMRI preprocess steps and tools - CuiLabCIBR/utils GitHub Wiki
Notice: There are a lot resources to learn how to process fMRI data, so wo just describe how we process fMRI data in a standard way. If you don't familiar with fMRI data and those tools what we use, please refer follow links to learn some basic knowledge of fMRI data:
Principles of fMRI
this course from Dr. Martin Lindquist and Dr. Tor Wager in The Johns Hopkins University. You can get all basic and some advanced knowledges from this course about fMRI. However, considering the resting state fMRI comes from task fMRI, quite a part of this class is being taught task fMRI, so if you just want to learn resting fMRI data, you just need to learn module 1 to module 10b in Principles of fMRI Part 1 and module 10 to module 20.
FSL course
FSL is a great and powerful tools in neuroimage process field, which can be ran on Apple and PCs (both Linux, and Windows via a Virtual Machine), and is very easy to install. Most of the tools can be run both from the command line and as GUIs. I recommand you use Linux or Mac to install FSL, however, you can use FSL on Windows 10 by using WSL. WSL is very convenient for Windows users.
Much information on resting state fMRI research
There are many pitfalls in resting state fMRI analysis, to help guide reseacher through this jungle of rs-fMRI, OHBM walk us through all stages of a resting state experiment, which including: data quality, noise in rs-fMRI data, nuisance regression approach and How should rs-fMRI data be preprocessed.
Nipype
Nipype is an open-source tool for nueroimage process, which provides a uniform interface to existing neuroimaging software (e.g., ANTS, SPM, FSL, FreeSurfer, Camino, MRtrix, MNE, AFNI, Slicer) and facilitates interaction between these packages within a single workflow, eases the design of workflows within and between packages, and reduces the learning curve necessary to use different packages. For me, if you want to learn more tools about neuroimage, please walk on nipype directly, it would save your time. Here is a excellent tutorial:nipype_tutorial.
And some other useful tutorials for different tools are as follows:
the Questions and Answers in MRI
The BIDS standard structure aims to organise and describe neuroimaging data in a uniform way to simplify data sharing through the scientific community.To be honest, there are many useful Tutorials on what is BIDS and how to make your data organized in BIDS way. For simply understanding, we just introduce some basic rules in BIDS and give some useful example here.
Overall, these are the three main types of files you'll find in a BIDS dataset:
-
.json
files that containkey: value
metadata -
.tsv
files that contain tables of metadata - Raw data files (e.g.,
.jpg
files for images or.nii.gz
files for MRI data.)
Considering to understand the BIDS from a practical point of view, we use a example of MSC data to explain what is BIDS. MSC dataset is a free acess datast come froms the Midnight Scanning Club. Details of this dataset are more fully described in Gordon EM, Laumann TO, Gilmore AW, Newbold DJ, Greene DJ, Berg JJ, Ortega M, Hoyt-Drazen C, Gratton C, Sun H, et al. (2017). Precision Functional Mapping of Individual Human Brains. Neuron 95.
here is an example of MSC BIDS:
We can see that BIDS is a hierarchy structure, there are four main levels of the folder hierarchy, these are:
project(MSC_BIDS_example)/
└── subject(sub-MSC01)
└── session(ses-func01/ses-struct01)
└── datatype(fmap/func/anat)
let's see the files in those folder step by step. First, you should have some basic information for your own dataset, the dataset_description.json
decribe some key values including Name
, BIDVerision
, License
, Authors
, HowToAcknowledge
and other useful information of this project, the participants.json
and participants.tsv
describe some basic information of subject in this project, including gender
, age
, education_years
and other demography information, the phasediff.json
contains the information of phase encoding of MRI data, and T1w.json
, T2w.json
, task-glasslexical_bold.json
, task-memoryfaces_bold.json
, task-memoryscenes_bold.json
, task-memorywords_bold.json
, task-motor_bold.json
and task-rest_bold.json
named by their modality and contains the scanning parameters for all subjects. You should notice that if you use same parameter to scan all subject, you will just put one modality_name.json
file under the project(MSC_BIDS_example)/
folder for each modality, otherwise, you need to put the specific scanning information json file under datatype folder for each subject[ex:datatype(fmap/func/anat)]. If you want to do slice time for fmri data, you need to have the key: SliceTiming
in your task-*_bold.json
file.
Next, let's look at the subject folder. One folder per subject in the project dataset. Labels should be unique for each subject, and the name should be as sub-<subject label>
. All files under each subject folder should be only refer to this subject only. If you collected data from them on different days, you will need the folder which named by ses-<session label>
. It could be 'func' or 'struct'. If there is only a single session per subject, this level of the hierarchy could be omitted. Under the folder of sub-<subject label>
or ses-<subject label>
, that would be the data type folder. The BIDS sets different types of data. Must be one of: func
, dwi
, fmap
, anat
, meg
, eeg
, ieeg
, beh
, pet
. If you don't know the meaning of those types, please check this website bids-examples.
Finally , we need to name each file of participant tidy and organized. The filename of each file should describe some key information, for example:
subjects: sub-<subject label>
session: ses-<session label>
task: task-<task label>
modality: bold/T1w/T2w
file type: .nii.gz/.tsv/
You should notice that above information just a little part of BIDS, please refer the BIDS website to learn whole picture.
fMRIPrep is a functional magnetic resonance imaging (fMRI) data preprocessing pipeline that is designed to provide an easily accessible, state-of-the-art interface that is robust to variations in scan acquisition protocols and that requires minimal user input, while providing easily interpretable and comprehensive error and output reporting. It performs basic processing steps (coregistration, normalization, unwarping, noise component extraction, segmentation, skullstripping etc.) providing outputs that can be easily submitted to a variety of group level analyses, including task-based or resting-state fMRI, graph theory measures, surface or volume-based statistics, etc. As their Note, fMRIPrep performs minimal preprocessing. They difine the ‘minimal preprocessing’ as :
motion correctionx
brain extraction
bias field correction
field unwarping
normalization
If you want to do more preprocess on your data, fMRIPrep only offer follow choices: slice time
, ICA-AROMA
,
dummy-scans
and fd-spike-threshold
. For denoise process, you need to do it by yourself using nilearn or other tools such as nipype. However, there is a good tool is developed by the Satterthwaite lab at the University of Pennysilvania, which takes fMRIPRep outputs and then postprocess resting state fmri data. When we use the fMRIprep on our serve, we usually use such script to run it by singularity :
#!/bin/bash
#SBATCH -o /tmp_out_put_dir/job.%j.out #this file would save the running information of fMRIprep
#SBATCH -e /tmp_out_put_dir/job.%j.error.txt #this file would save the error during running of fMRIprep
#SBATCH -c 20 #how many cpus is used
#SBATCH --mem-per-cpu 8000 #how much memory is used for each cpu
#SBATCH -p lab_fat # which serve you use
module load singularity/3.7.0 #you should load singularity on your own account
#!/bin/bash
#User inputs:
bids_root_dir=/raw_BIDS_data_dir/ # such as /***/MSC_BIDS_example
bids_root_dir_output_wd4singularity=/project_tmp_file/HNU_WK # you should save all tmp files that the fmriprep produced
subj=$1 #get the subject name from input parameter
nthreads=40 #threads, number of cpu *2
mkdir $bids_root_dir/derivatives # save output from fMRIprep
mkdir $bids_root_dir_output_wd4singularity/derivatives # save tmp files from fMRIprep
#Run fmriprep
echo ""
echo "Running fmriprep on participant: sub-$subj"
echo ""
#Make fmriprep directory and participant directory in derivatives folder
if [ ! -d $bids_root_dir/derivatives/fmriprep ]; then
mkdir $bids_root_dir/derivatives/fmriprep
fi
if [ ! -d $bids_root_dir/derivatives/fmriprep/sub-${subj} ]; then
mkdir $bids_root_dir/derivatives/fmriprep/sub-${subj}
fi
if [ ! -d $bids_root_dir_output_wd4singularity/derivatives/fmriprep ]; then
mkdir $bids_root_dir_output_wd4singularity/derivatives/fmriprep
fi
if [ ! -d $bids_root_dir_output_wd4singularity/derivatives/fmriprep/sub-${subj} ]; then
mkdir $bids_root_dir_output_wd4singularity/derivatives/fmriprep/sub-${subj}
fi
#Run fmriprep
export SINGULARITYENV_TEMPLATEFLOW_HOME=/***/templateflow # this derictory refers to the TemplateFlow
unset PYTHONPATH; singularity run --cleanenv -B $bids_root_dir_output_wd4singularity/derivatives/fmriprep/sub-${subj}:/wd \
-B $bids_root_dir:/inputbids \
-B $bids_root_dir/derivatives/fmriprep/sub-${subj}:/output \
-B /freesurfer_license_dir/:/freesurfer_license \
/fmriprep_simg_folder/fmriprep-20.2.1.simg \
/inputbids /output participant\
--participant_label ${subj} \
-w /wd \
--nthreads $nthreads \
--omp-nthreads $nthreads \
--mem-mb 160000 \
--fs-license-file /freesurfer_license/license.txt \
--output-spaces T1w MNI152NLin6Asym:res-2 MNI152NLin2009cAsym:res-2 \ # Standard spaces you want to normalized into
--return-all-components \
--notrack --verbose \
--skip-bids-validation --debug all --stop-on-first-crash --use-syn-sdc --resource-monitor --cifti-output 91k # create the HCP fs_LR space file, 91k resolution
You should notice that you can't use network when excute the fMRIPrep by sbatch, so you need to download the [templateflow] (https://github.com/templateflow/templateflow) on serve firstly. Please refer to How do you use TemplateFlow in the absence of access to the Internet section to do it.
The output of fMRIprep would be look like bellow:
the fmriprep
folder contains all anat
and func
files that you need, and the freesurfer
folder contains all surface file produced by Freesurfer tool. The figures
folder contains useful information for quality control of preprocess. You may need to check them one by one. Let's look at the files in func
folder, because we are interested the fMRI data only.
the output files contains :
*-confounds_timeseries.tsv
, which used to regress nuisance out, what we need including csf
, whiter_matter
, global_signal
, trans_x
, trans_y
, trans_z
, rot_x
, rot_y
, and rot_z
.
*fsLR_den-91k_bold.dtseries.nii
, which is the CIFTI file of fmri data, it has been projected into the fs_LR space.
*_desc-preproc_bold.nii.gz
, which is the volume fMRI data, the space of this data is defined by space
parameter.
explaination of other files can be found in Outputs of fMRIPrep.
After you preprocessed the rest state fMRI data by fMRIprep, you need to do some post-denoise step on your data. However, there is no unified steps on how to denoise rs-fMRI data. There are many papers discuss this topic, we choose this paper Mitigating head motion artifact in functional connectivity MRI as refenrece to do post-denoise. And XCP-ABCD is developed by the lab of the author.
XCP-ABCD is easy to use because of the docker container. And the usage is similar to fMRIprep, let's see a script to understand how it goes.
#!/bin/bash
#SBATCH --nodes=1 # OpenMP requires a single node
#SBATCH -p lab_fat
#SBATCH --ntasks=1 # Run a single serial task
#SBATCH --cpus-per-task=20
#SBATCH --mem-per-cpu=8gb
#SBATCH --time=80:00:00 # Time limit hh:mm:ss
##### END OF JOB DEFINITION #####
module load singularity_xcp_abcd/0.0.4
singularity run -B /fmri_prep_out_dir/:/fmriprep \
-B /xcp_output_dir/:/out \
-B /home/.cache:/home/xcp_abcd/.cache \
-B /xcp_tmp_work_dir/:/work \
$IMG /fmriprep /out participant -w /work --participant_label $1 -p 36P --cifti --despike --lower-bpf 0.01 --upper-bpf 0.08 --smoothing 6
you need to notice that you should run the xcp_abcd on your account to download some template file on your home/.cache
folder and then run it by sbatch.
$1
would accept the first parameter as the sub-label
-p 36
means nuissance parameters to be selected by 36P see Ciric etal 2007
--cifti
means that you will process dtseries.nii
--despike
mean that the rs-fMRI data would be despiked by using AFNI 3d-spike
--lower-bpf
and --upper-bpf
set the lower cut-off frequency (Hz) and upper cut-off frequency (Hz) for the butterworth bandpass filter
--smoothing
mean that you would smooth the postprocessed output by 6 (fwhm)