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)

Map from MNI152 0.8mm space to DWI native space
 1# Subjects identification
 4# Map from MNI152 0.8mm to DWI space
 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
Map from DWI native space to MNI152 0.8mm
 1# Map from DWI space to MNI152 0.8mm
 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
From MNI152 to rsfMRI space
 1# Map from MNI152 0.8mm to rsfMRI space
 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
From rsfMRI to MNI152 space
 1# Map from rsfMRI space to MNI152 0.8mm
 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
From rsfMRI to nativepro space
 1# Map from rsfMRI space to nativepro 2mm
 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 inside out/freesurfer/. It’s up to you to keep the original freesurfer directory or erase it.

Usage example of -freesurfer_dir flag
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 or wb_command -metric-smoothing from workbench.

In the next examples we’ll use the subject sub-01 session ses-01:

20mm smoothing of the left hemisphere using freesurfer tools
 1 # OutDir is the directory with -Morphology outpus
 2 outDir=out/micapipe/sub-01/ses01/anat/surfaces/morphology
 4 # Declare the micapipe's freesurfer directory variable
 5 export SUBJECTS_DIR=out/freesurfer
 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"
20mm smoothing of the left hemisphere using WorkBench tools
 1MICAPIPE_DIR=<path to the micapipe repository>
 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"
 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
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:

Concatenates all rsfMRI runs and process the output
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
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
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 in mif format with bvals, bvecs, PhaseEncodingDirection and ReadoutTime encoded.

Usage example of -dwi_processed flag
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 given mif 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 using mrcat and mrconvert 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
 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/
 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 \
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 \
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
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 \
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.