Input Data for QSIRecon

Raw BIDS dMRI should not be used and will not work. Instead, gather data processed by QSIPrep or UKBioBank. The directory containing the sub-* directories (if from QSIPrep) or the directory with the numerals/underscores per subject if UKBB will be the first argument to QSIRecon.

Using Data from QSIPrep

QSIPrep outputs will work as inputs for QSIRecon as-is, aside from some when some specific options were selected for preprocessing.

Important

QSIRecon endeavors to maintain compatibility with QSIPrep outputs from the same release series. We cannot guarantee that QSIPrep outputs from different releases will work with QSIRecon.

QSIPrep and QSIRecon follow a matched release schedule, with major (i.e., backwards-incompatible) releases made at the same time. Minor and patch releases may be made independently.

If --anat-modality none was used

If --anat-modality none was used, there will be no preprocessed T1w data in the QSIRecon results. Instead the DWI images have been aligned to AC-PC as closely as possible (likely imperfectly). In this case, the FreeSurfer skull-stripped brain.mgz is rigidly registered to dwiref of each preprocessed DWI. The FreeSurfer brain mask is resampled to the grid of the DWI.

If structural connectivity is calculated during the reconstruction workflow (or any atlases are specified with the --atlases parameter), the coregistered-to-DWI brain.mgz image will be normalized to the MNI152NLin2009cAsym template using antsRegistration. The reverse transform is used to get parcellations aligned to the DWI.

Using Data Preprocessed by Other Pipelines

Many open datasets are provided in minimally preprocessed form. Most of these have a bespoke processing pipeline and in many cases these pipelines are very similar to QSIRecon. Instead of preprocessing these from scratch, you can run reconstruction workflows on the minimally preprocessed data by specifying the pipeline that was used for preprocessing.

UK BioBank Preprocessed Data

To use the UK BioBank preprocessed dMRI data, specify --input-type ukb. Note that the transforms to/from MNI space are not able to be used at this time. This means that a new spatial normalization will have to be estimated in order to use any of the workflows that require one. Also note that only DSI_Studio recon-specs have been tested for UKB inputs.

HCP Young Adult Preprocessed Data

To use minimally preprocessed dMRI data from HCP-YA specify --input-type hcpya. Note that the transforms to/from MNI space are not able to be used at this time. Please note that if you have the HCPYA dataset from datalad (https://github.com/datalad-datasets/human-connectome-project-openaccess) then you should datalad get relevant subject data before running QSIRecon, and be mindful about how you mount the directory in Docker/Apptainer.

Anatomical Data for Reconstruction Workflows

Some reconstruction workflows require additional anatomical data to work properly. This table shows which reconstruction workflows depend on the availibility of anatomical data:

Option	Req. T1w	Req. FreeSurfer	Req. SDC
mrtrix_multishell_msmt_ACT-hsvs	Yes	Yes	Yes
mrtrix_multishell_msmt_ACT-fast	Yes	No	Yes
mrtrix_multishell_msmt_noACT	No	No	No
mrtrix_singleshell_ss3t_ACT-hsvs	Yes	Yes	No
mrtrix_singleshell_ss3t_ACT-fast	Yes	No	No
mrtrix_singleshell_ss3t_noACT	Yes	No	No
pyafq_tractometry	No	No	No
pyafq_input_trk	No	No	No
amico_noddi	No	No	No
dsi_studio_gqi	No	No	Recommended
dipy_mapmri	No	No	Recommended
dipy_3dshore	No	No	Recommended
csdsi_3dshore	No	No	Recommended
reorient_fslstd	No	No	No

Including FreeSurfer Data

Suppose you ran FreeSurfer on your data (e.g. as part of fmriprep). You can specify the directory containing freesurfer outputs with the --fs-subjects-dir flag. If you have:

derivatives/freesurfer/sub-x
derivatives/freesurfer/sub-y
derivatives/freesurfer/sub-z

and (for example) processed data from QSIPrep:

derivatives/qsiprep/sub-x
derivatives/qsiprep/sub-y
derivatives/qsiprep/sub-z

You can run:

apptainer run \
    --containall \
    --writable-tmpfs \
    -B "${PWD}" \
    -B "${FREESURFER_HOME}/license.txt":/license.txt \
    "${PWD}/derivatives/qsiprep" \
    "${PWD}/derivatives/qsirecon" \
    participant \
    -w "${PWD}/work" \
    --nthreads 8 \
    --omp-nthreads 8 \
    --fs-license-file /license.txt \
    --recon-spec mrtrix_multishell_msmt_ACT-hsvs \
    --fs-subjects-dir "${PWD}/derivatives/freesurfer" \
    -v -v

This will read the FreeSurfer data, align it to the QSIPrep results and use it for subsequent reconstruction steps.

How FreeSurfer Data is Included

If a T1w image is available in the input data the brain.mgz image from freesurfer is registered to the appropriate T1w image. The transform from freesurfer native space into alignment with the qsirecon outputs is achieved by converting brain.mgz into NIfTI format and adjusting the affine matrix such that the images are aligned in world coordinates. This prevents an extra interpolation.