FAQ
Table of Contents
Registration issues
- Q: How do I register a volume from rsfMRI or DWI space to MNI152 and vice-versa?
A: although micapipe calculates all the necessary transformation matrices and warp fields to register from any native space to MNI152, this procedure is not implemented at any point in the pipeline.
Using the following information you should be able to register between any spaces using ANTs. The paths are relative to the subject directory (e.g.
out/micapipe/sub-01/ses-01
)1# Subjects identification 2subjectID=sub-01_ses-01 3 4# Map from MNI152 0.8mm to DWI space 5Input=file_in_space-MNI152_0.8mm.nii.gz 6Output=file_from_MNI152_0.8mm_in_space-dwi.nii.gz 7 8antsApplyTransforms -d 3 -i ${Input} \ 9 -r dwi/${subjectID}_space-dwi_desc-b0.nii.gz \ 10 -n GenericLabel \ # Interpolation! 11 -t xfm/${subjectID}_space-dwi_from-dwi_to-dwi_mode-image_desc-SyN_1Warp.nii.gz \ 12 -t xfm/${subjectID}_space-dwi_from-dwi_to-dwi_mode-image_desc-SyN_0GenericAffine.mat \ 13 -t [xfm/${subjectID}_space-dwi_from-dwi_to-nativepro_mode-image_desc-0GenericAffine.mat,1] \ 14 -t [xfm/${subjectID}_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_0GenericAffine.mat,1] \ 15 -t xfm/${subjectID}_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_1InverseWarp.nii.gz \ 16 -o ${Output} -v
1# Map from DWI space to MNI152 0.8mm 2Input=file_in_space-dwi.nii.gz 3Output=file_from_dwi_in_space-MNI152_0.8mm.nii.gz 4 5antsApplyTransforms -d 3 -i ${Input} \ 6 -r ${MICAPIPE_DIR}/MNI152Volumes/MNI152_T1_0.8mm_brain.nii.gz \ 7 -n GenericLabel \ 8 -t xfm/${subjectID}_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_1Warp.nii.gz \ 9 -t xfm/${subjectID}_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_0GenericAffine.mat \ 10 -t xfm/${subjectID}_space-dwi_from-dwi_to-nativepro_mode-image_desc-0GenericAffine.mat \ 11 -t [xfm/${subjectID}_space-dwi_from-dwi_to-dwi_mode-image_desc-SyN_0GenericAffine.mat,1] \ 12 -t xfm/${subjectID}_space-dwi_from-dwi_to-dwi_mode-image_desc-SyN_1Warp.nii.gz \ 13 -o ${Output} -v 14}
1# Map from MNI152 0.8mm to rsfMRI space 2Input=file_in_space-MNI152_0.8mm.nii.gz 3Output=file_from_MNI152_0.8mm_in_space-rsfMRI.nii.gz 4 5antsApplyTransforms -d 3 \ 6 -i ${Input} \ 7 -r func/volumetric/${subjectID}_space-rsfmri_desc-singleecho_brain.nii.gz \ 8 -t xfm/${subjectID}_rsfmri_from-nativepro_rsfmri_to-rsfmri_mode-image_desc-SyN_1Warp.nii.gz \ 9 -t xfm/${subjectID}_rsfmri_from-nativepro_rsfmri_to-rsfmri_mode-image_desc-SyN_0GenericAffine.mat \ 10 -t [xfm/${subjectID}_rsfmri_from-rsfmri_to-nativepro_mode-image_desc-affine_0GenericAffine.mat,1] \ 11 -t [xfm/${subjectID}_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_0GenericAffine.mat,1] \ 12 -t xfm/${subjectID}_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_1InverseWarp.nii.gz \ 13 -o ${Output} -v
1# Map from rsfMRI space to MNI152 0.8mm 2Input=file_in_space-rsfMRI.nii.gz 3Output=file_from_rsfMRI_in_space-MNI152_0.8mm.nii.gz 4 5antsApplyTransforms -d 3 \ 6 -i func/volumetric/${subjectID}_space-rsfmri_desc-singleecho_brain.nii.gz \ 7 -r ${MICAPIPE_DIR}/MNI152Volumes/MNI152_T1_0.8mm_brain.nii.gz \ 8 -t xfm/${subjectID}_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_1Warp.nii.gz \ 9 -t xfm/${subjectID}_from-nativepro_brain_to-MNI152_0.8mm_mode-image_desc-SyN_0GenericAffine.mat \ 10 -t xfm/${subjectID}_rsfmri_from-rsfmri_to-nativepro_mode-image_desc-affine_0GenericAffine.mat \ 11 -t [xfm/${subjectID}_rsfmri_from-nativepro_rsfmri_to-rsfmri_mode-image_desc-SyN_0GenericAffine.mat,1] \ 12 -t xfm/${subjectID}_rsfmri_from-nativepro_rsfmri_to-rsfmri_mode-image_desc-SyN_1InverseWarp.nii.gz \ 13 -o ${Output} -v -u int
1# Map from rsfMRI space to nativepro 2mm 2Input=file_in_space-rsfMRI.nii.gz 3Output=file_from_rsfMRI_in_space-nativepro_2mm.nii.gz 4 5antsApplyTransforms -d 3 \ 6 -i func/volumetric/${subjectID}_space-rsfmri_desc-singleecho_brain.nii.gz \ 7 -r ${MICAPIPE_DIR}/MNI152Volumes/MNI152_T1_2mm_brain.nii.gz \ 8 -t xfm/${subjectID}_rsfmri_from-rsfmri_to-nativepro_mode-image_desc-affine_0GenericAffine.mat \ 9 -t [xfm/${subjectID}_rsfmri_from-nativepro_rsfmri_to-rsfmri_mode-image_desc-SyN_0GenericAffine.mat,1] \ 10 -t xfm/${subjectID}_rsfmri_from-nativepro_rsfmri_to-rsfmri_mode-image_desc-SyN_1InverseWarp.nii.gz \ 11 -o ${Output} -v -u int
Surface issues
- Q: What if my database already has quality checked Freesurfer outputs?
A: If you have an already processed and QC-ed freesurfer directory remember to use the flag
-freesurfer_dir
when you run the pipeline!! It will make a copy of your data with a compatible naming insideout/freesurfer/
. It’s up to you to keep the original freesurfer directory or erase it.1 # Run micapipe 2 mica-pipe -bids rawdata -out derivatives -sub 01 \ 3 -proc_surf -freesurfer_dir <path_to_my_subject_freesurfer_dir> \
- Q: How do I modify the smoothing on the surfaces?
A: By default micapipe
-Morphology
only applies a smoothing of 10mm over the surfaces. If you need a different FWHM you can use either:mri_surf2surf
from freesurfer orwb_command -metric-smoothing
from workbench.In the next examples we’ll use the subject
sub-01
sessionses-01
:1 # OutDir is the directory with -Morphology outpus 2 outDir=out/micapipe/sub-01/ses01/anat/surfaces/morphology 3 4 # Declare the micapipe's freesurfer directory variable 5 export SUBJECTS_DIR=out/freesurfer 6 7 mri_surf2surf --hemi lh \ 8 --fwhm-trg 20 \ 9 --srcsubject sub-01_ses01 \ 10 --srcsurfval "${outDir}/sub-01_ses01_space-fsnative_desc-lh_thickness.mgh" \ 11 --trgsubject fsaverage5 \ 12 --trgsurfval "${outDir}/sub-01_ses01_space-fsaverage5_desc-lh_thickness_20mm.mgh" 13 "${outDir}/lh_curv_20mm_c69-32k.func.gii"
1MICAPIPE_DIR=<path to the micapipe repository> 2 3# For WorkBench the first step is to convent the mgh surface file to GIFTI 4 mri_convert "${outDir}/sub-01_ses01_space-conte69-32k_desc-lh_thickness.mgh" "/tmp/lh_curv_c69-32k_thickness.func.gii" 5 6 wb_command -metric-smoothing \ 7 "${MICAPIPE_DIR}/surfaces/fsaverage.L.midthickness_orig.32k_fs_LR.surf.gii" \ 8 "/tmp/lh_curv_c69-32k_thickness.func.gii" \ 9 20 \ 10 "/tmp/lh_curv_20mm_c69-32k.func.gii" # This is the 20 mm FWHM surface 11 12 # Convert from GIFTI back to MGH 13 mri_convert "/tmp/lh_curv_10mm_c69-32k.func.gii" "${outDir}/sub-01_ses01_space-conte69-32k_desc-lh_thickness_20mm.mgh"
Resting state issues
- Q: How do I process multiple rsfMRI If I have different runs in the same session?
A: Right now the pipeline does not manage multiple runs on the same session. We recommend to concatenate all the runs into one file and process it. Using
mrcat
from MRtrix3 for example:1 # Inside the func directory contatenate all the runs 2 mrcat sub-01_task-rest_run-1_bold.nii.gz sub-01_task-rest_run-2_bold.nii.gz sub-01_task-rest_desc-cat_bold.nii.gz 3 4 # Copy the json file from run-1 5 cp sub-01_task-rest_run-1_bold.json sub-01_task-rest_desc-cat_bold.json 6 7 # Run micapipe and specify the name of the concatenated rsfmri 8 mica-pipe -bids rawdata -out derivatives -sub 01 \ 9 -proc_rsfmri -mainScanStr task-rest_desc-cat_bold \
- Q: Can I process multi-echo rsfMRI acquisition with micapipe?
A: Although is planned to be included in a future release, right now micapipe cannot handle in any way multi-echo acquisitions.
- Q: How do I train an ICA-FIX
RData
file? A: The default processing of rsfMRI was optimized with the MICs dataset. Thus, we generated a custom training file in order to use FIX with our dataset. If you want to use FIX to clean the noisy components from your rsfMRI time series, we recommend to train your own weights file using FSL-FIX instructions
- Q: What if I already have rsfMRI processed data? (eg. from fmriPREP)
A: Unfortunately, due to the multiple nested steps which take place inside
proc_rsfmri
is not possible to use an already processed rsfMRI volume. If you are thrilled to develop its implementation, please help us!- Q: Why does micapipe not apply slice timing correction in rsfMRI processing?
A: micapipe was optimized for multi-band acquisitions, which do not require slice timing correction.
- Q: If my database has the field maps instead of the reverse phase encoding acquisition of rsfMRI and DWI, can micapipe use them for the geometric distortion correction?
A: The usage of field maps is not implemented in micapipe. However you could apply the field map based correction to their correspondent images and then run micapipe, choosing the fieldmap-based corrected images to process.
DWI issues
- Q: What if I already have DWI processed data?
A: If you have your DWI already processed and you don’t want to run this step again. you can use the flag
-dwi_processed
to the processed DWI, it must be inmif
format with bvals, bvecs, PhaseEncodingDirection and ReadoutTime encoded.1 # Run micapipe 2 mica-pipe -bids rawdata -out derivatives -sub 01 \ 3 -proc_dwi -dwi_processed <path>/dwi_preprocessed.mif \
- Q: Can I save the tractogram (tck file) generated in
-SC
? A: Yes, you need to use the flag
-keep_tck
to keep the connectome generated by the pipeline, which is erased by default.- Q: Does
micapipe
compress the tractogram (tck file) generated in-SC
when they are saved with-keep_tck
? A: No, by default, our pipeline does not save the tractograms or compress them after connectome calculations (
-SC
). The main reason is storage and computational time, which is a significant issue even when compression is used (for 10 million streamlines, uncompressed/compressed tractograms are ~14G/3G per case). When running the pipeline, it is possible to keep tractograms (optional argument-keep_tck
), but it’s up to the final user to compress them. We included a short tutorial regarding this issue in the section How to downsample a tractogram- Q: My dataset contains multiple and separated DWI shells, can I process them individually or should I merge them before
-proc_dwi
? A: The default behavior of micapipe is to use all the dwi shells provided and perform a rigid registration before concatenating them. While we found this step to increase robustness of our processing for some cases in the MICs dataset, applying a rotation prior to invoking
dwipreproc
(which runs eddy/topup and thus also corrects for motion within a givenmif
file) may increase data interpolation between shells. If the user wants to avoid this rigid registration between shells is possible to concatenate the shells prior processing and call the resulting file with their corresponding updated json, bvecs and bval files. We recommend usingmrcat
andmrconvert
to perform this step.If the user wants to process only an individual shell from a dataset acquisition is also possible using the flag
-dwi_main
to select only one DWI nifti file.Processing multiple shells with default parameters
1# Path relative to main MICs rawdata directory 2sub_id="sub-HC001/ses-01/dwi/sub-HC001_ses-01" 3 4# Processing command 5micapipe -sub HC001 -ses 01 -proc_dwi \ 6 -bids . \ 7 -out ../derivatives \ 8 -dwi_main ${sub_id}_acq-b2000-91_dir-AP_dwi.nii.gz,${sub_id}_acq-b700-41_dir-AP_dwi.nii.gz \ 9 -dwi_rpe ${sub_id}_dir-PA_dwi.nii.gz \ 10 -dwi_acq multi-shell
Processing a single shell
1# Processing command 2micapipe -sub HC001 -ses 01 -proc_dwi \ 3 -bids . \ 4 -out ../derivatives \ 5 -dwi_main ${sub_id}_acq-b700-41_dir-AP_dwi.nii.gz \ 6 -dwi_rpe ${sub_id}_dir-PA_dwi.nii.gz \ 7 -dwi_acq shell-b700
Concatenating shells before processing with micapipe
1# From the subject's DWI directory 2cd sub-HC001/ses-01/dwi/ 3sub="sub-HC001_ses-01" 4 5# Convert each shell to mif to store the associated bvecs, bvals and json files 6# Shell b2000 7mrconvert -json_import ${sub}_acq-b2000-91_dir-AP_dwi.json \ 8-fslgrad ${sub}_acq-b2000-91_dir-AP_dwi.bvec ${sub}_acq-b2000-91_dir-AP_dwi.bval \ 9${sub}_acq-b2000-91_dir-AP_dwi.nii.gz \ 10${sub}_acq-b2000-91_dir-AP_dwi.mif 11 12# Shell b700 13mrconvert -json_import ${sub}_acq-b700-41_dir-AP_dwi.json \ 14-fslgrad ${sub}_acq-b700-41_dir-AP_dwi.bvec ${sub}_acq-b700-41_dir-AP_dwi.bval \ 15${sub}_acq-b700-41_dir-AP_dwi.nii.gz \ 16${sub}_acq-b700-41_dir-AP_dwi.mif 17 18# Concatenate shells and export bvec, bval and json files 19mrcat ${sub}_acq-b2000-91_dir-AP_dwi.mif ${sub}_acq-b700-41_dir-AP_dwi.mif ${sub}_acq-MultiShell_dir-AP_dwi.mif 20 21# Convert mif to nifti 22mrconvert -export_grad_fsl ${sub}_acq-MultiShell_dir-AP_dwi.bvec ${sub}_acq-MultiShell_dir-AP_dwi.bval \ 23-json_export ${sub}_acq-MultiShell_dir-AP_dwi.json \ 24${sub}_acq-MultiShell_dir-AP_dwi.mif \ 25${sub}_acq-MultiShell_dir-AP_dwi.nii.gz 26 27# Processing command 28micapipe -sub HC001 -ses 01 -proc_dwi \ 29-bids \ 30-out \ 31-dwi_main ${sub}_acq-MultiShell_dir-AP_dwi.nii.gz \ 32-dwi_rpe ${sub}_dir-PA_dwi.nii.gz 33-dwi_acq MultiShell
Parcellation issues
- Q: Can I use a different cortical / subcortical / cerebellar atlas not included in the micapipe?
A: At the present moment this feature is not included. If you wan’t to help us implementing this new feature you are very welcome.