qsirecon (CBRAIN Tool Config ID: 7805)

• Container: docker://pennlinc/qsirecon:1.0.0

• Documentation: https://qsirecon.readthedocs.io/en/latest/

• Boutiques Descriptor: https://portal.cbrain.mcgill.ca/tool_configs/7805/boutiques_descriptor.json

• name: qsirecon

• description: QSIRecon builds post-processing workflows that produce many of the biologically-interesting dMRI derivatives used for hypothesis testing. The main goal of QSIRecon is to make the state-of-the-art methods available in Dipy, MRTrix, DSI Studio, PyAFQ and other software packages easy to apply on preprocessed dMRI data. QSIRecon is companion software for XCP-D, doing for dMRI what XCP-D does for BOLD.

External Requirements

These are file-based requirements, external to the pipeline, that must be satisfied for processing to occur. The “Argument IDs” field corresponds to input “id”s within the tool Boutiques Descriptor. “Value”s correspond to either specific configuration files (if there is a numeric value), or otherwise broader file types within CBRAIN (if the entry is text-based).

Argument ID	Flag	Value	Description
subject_dir	n/a	BidsSubject	Subject folder for BIDS (folders name should be sub-XXXXX).
qsiprep_subject_dir	n/a	QsiprepOutput	Subject folder for previous QSIPREP Outputs (folders name should be sub-XXXXX).
qsiprep_json	n/a	5460266	The json descriptor of the original qsiprep preprocessing derivatives.
fs_license_file	–fs-license-file	4323067	Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html

Ancestor Pipelines

This pipeline utilizes outputs from the following pipelines that are also ran in CBRAIN:

• qsiprep

Other Processing Settings

These additional settings cover everything outside of files that are used as inputs during processing. The settings cover numeric values, flags, outputs directories, and other settings that are used to configure processing.

Argument ID	Flag	Value	Description
output_dir_name	n/a	output	The name of the output for the outcomes of preprocessing and visual reports
output_resolution	–output-resolution	1.7	The isotropic voxel size in mm the data will be resampled to after preprocessing. If set to a lower value than the original voxel size, your data will be upsampled using BSpline interpolation.
recon_spec	–recon-spec	hbcd_scalar_maps	JSON file specifying a reconstruction pipeline to be run after preprocessing
report_output_level	–report-output-level	session	Where should the html reports be written? By default root will write them to the –output-dir. Other options will write them into their subject or session directory.
infant	–infant	True	Configure pipelines to process infant brains
derivatives_prefix	n/a		Folders to put before the pipeline specific folder. By default this will look like DataProvider/derivatives/PipelineName, where pipeline name is specific to the current pipeline. The provided string must end in /
verbose	-v	True	Increases log verbosity for each occurence (-vvv).

Pipeline Outputs

Following processing, a number of files and folders are identified as outputs that should be saved for future reference. In the following table the ‘Path Relative to Working Directory’ column specifies the location of files that should be saved (with ‘*’ denoting wildcards). The output location for these files in the final ‘DataProvider’ is specified in the ‘Path in Output Data Provider’ column. In the case of HBCD the [DERIVATIVES_PREFIX] entry is empty.

ID	Path Relative to Working Directory	Path in Output DataProvider	Description
recon_dir	[QSIRECON_OUTPUT_DIR]/[SUBJECT_DIR]	[DERIVATIVES_PREFIX]qsirecon	This is the directory where the QSIRECON outputs are to be stored.
recon_dir_dipydki	[QSIRECON_OUTPUT_DIR]/derivatives/qsirecon-DIPYDKI/[SUBJECT_DIR]	[DERIVATIVES_PREFIX]qsirecon-DIPYDKI	This is the directory where the QSIRECON DIPYKI outputs are to be stored.
recon_html_dipydki	[QSIRECON_OUTPUT_DIR]/derivatives/qsirecon-DIPYDKI/[SUBJECT_DIR]*html	[DERIVATIVES_PREFIX]qsirecon-DIPYDKI	This is the directory where the QSIRECON DIPYKI outputs are to be stored.
recon_dir_dsistudio	[QSIRECON_OUTPUT_DIR]/derivatives/qsirecon-DSIStudio/[SUBJECT_DIR]	[DERIVATIVES_PREFIX]qsirecon-DSIStudio	This is the directory where the QSIRECON DSIStudio outputs are to be stored.
recon_html_dsistudio	[QSIRECON_OUTPUT_DIR]/derivatives/qsirecon-DSIStudio/[SUBJECT_DIR]*html	[DERIVATIVES_PREFIX]qsirecon-DSIStudio	This is the directory where the QSIRECON DSIStudio outputs are to be stored.
recon_dir_tortoise_mapmri	[QSIRECON_OUTPUT_DIR]/derivatives/qsirecon-TORTOISE_model-MAPMRI/[SUBJECT_DIR]	[DERIVATIVES_PREFIX]qsirecon-TORTOISE_model-MAPMRI	This is the directory where the QSIRECON TORTOISE MAPMRI outputs are to be stored.
recon_html_tortoise_mapmri	[QSIRECON_OUTPUT_DIR]/derivatives/qsirecon-TORTOISE_model-MAPMRI/[SUBJECT_DIR]*html	[DERIVATIVES_PREFIX]qsirecon-TORTOISE_model-MAPMRI	This is the directory where the QSIRECON TORTOISE MAPMRI outputs are to be stored.
recon_dir_tortoise_tensor	[QSIRECON_OUTPUT_DIR]/derivatives/qsirecon-TORTOISE_model-tensor/[SUBJECT_DIR]	[DERIVATIVES_PREFIX]qsirecon-TORTOISE_model-tensor	This is the directory where the QSIRECON TORTOISE Tensor outputs are to be stored.
recon_html_tortoise_tensor	[QSIRECON_OUTPUT_DIR]/derivatives/qsirecon-TORTOISE_model-tensor/[SUBJECT_DIR]*html	[DERIVATIVES_PREFIX]qsirecon-TORTOISE_model-tensor	This is the directory where the QSIRECON TORTOISE Tensor outputs are to be stored.

Command Line Template

The following code-snippet highlights how the tool is referenced on the command-line. The code being displayed is executed within the tool’s container. Some of the directives may describe file manipulations to prepare for processing, and other directives will describe the primary processing command. At the time of processing, the text in brackets will be replaced by text that has been provided to configure processing.

true [SUBJECT_DIR]; true [DERIVATIVES_PREFIX]; qsirecon [QSIPREP_DIR] [QSIRECON_OUTPUT_DIR] participant -v --work-dir "$PWD"/work [SESSION_ID] [FS_LICENSE_FILE] [BIDS_FILTER_FILE] [RECON_SPEC] [fs_subjects_dir] [report_output_level] --omp-nthreads 8 --n-cpus 8 --stop-on-first-crash [USE_PLUGIN] [INFANT] [BOILERPLATE] [VERBOSE] [B0_THRESHOLD] [OUTPUT_RESOLUTION] [REPORTS_ONLY] [WRITE_GRAPH] [SLOPPY]

File Selection For Processing

The first step of selecting a candidate for processing is determining whether the right files are present. In HBCD processing, pipelines are always run on one session worth of data at a time. With that in mind, we (mostly) query the contents of a subject’s session folder to determine if processing should occur and also which files should be included in processing. For every pipeline there will be at least one requirement group that determines what files are needed for processing to occur. Within a requirement group, there may be criteria that address multiple file (or modality) types, which are known as ‘File Groups’. For processing to occur, the minumum number of files surviving all Included/Excluded terms for a given ‘File Group’ must be satisfied.

To allow for more flexible selection of files for processing, there are often multiple ‘Requirement Groups’. The contents of each ‘File Group’ across ‘Requirement Groups’ must be the same, but which ‘File Groups’ are defined can be different. If multiple ‘Requirement Groups’ are present for the current pipeline, there will be multiple tables in this section. Only one ‘Requirement Group’ needs to be satisfied for processing to occur. If one requirement group is satisfied, then files from all ‘File Groups’ will be included in processing.

Beyond the files that are chosen from this procedure, other associated files defined via the table here will also be included in processing.

Requirement Group: qsirecon_1

File Group	How Many To Keep	Term	Included (True)/Excluded (False)
DWI_AP	1	dwi.nii.gz	True
		dir-AP	True
DWI_PA	1	dwi.nii.gz	True
		dir-PA	True
T2	1	T2w.nii.gz	True
		rec-undistorted	False
		acq-svslocalizer	False
		acq-mrsLoc	False
		_QALAS.nii.gz	False
scans.tsv	All	scans.tsv	True
sessions.tsv	All	sessions.tsv	True

Requirement Group: qsirecon_2

File Group	How Many To Keep	Term	Included (True)/Excluded (False)
DWI_AP	1	dwi.nii.gz	True
		dir-AP	True
DWI_PA	1	dwi.nii.gz	True
		dir-PA	True
T1	1	T1w.nii.gz	True
		rec-undistorted	False
		acq-svslocalizer	False
		acq-mrsLoc	False
		_QALAS.nii.gz	False
T2	1	T2w.nii.gz	True
		rec-undistorted	False
		acq-svslocalizer	False
		acq-mrsLoc	False
		_QALAS.nii.gz	False
scans.tsv	All	scans.tsv	True
sessions.tsv	All	sessions.tsv	True

Quality Control Selection Information

The previous section of this page highlighted how to look at a file’s name to determine whether it may belong to a specific ‘File Group’ (such as T2w images) that are needed for processing. Beyond this, it is often necessary to look at some QC criteria to determine whether a file should be included in processing. This section defines the QC criteria that is used to evaluate specific images. These QC criteria always operate on one file group at a time. If a file group uses QC criteria to select images, at least one table will be displayed below. Depending on the context, these criteria will be used to exclude certain images from processing, to find the best available image(s) within a specific category, or to exclude a session from processing. If sorting is the goal, the first row will be considered the most important criteria. In certain cases, not all images will have ratings for a specific QC field. In this case, a backup table (which will be displayed after the first table if available), will be used for that file group.

File Group: DWI_AP

Processing will look for best 1 file(s) to keep using the following criteria(s).

scans.tsv Field	Operator	Value
QC	equals	1
part_of_a_pair	equals	1
QU_cutoff	less_than	10000
QU_sus	less_than	10000
QU_line	less_than	10000
ngood_frames	greater_than	0
line_mean_score	less_than	10000
tSNR_b0	greater_than	0

scans.tsv Field	Operator	Value
QC	equals	1
part_of_a_pair	equals	1
ngood_frames	greater_than	0
line_mean_score	less_than	10000
tSNR_b0	greater_than	0

File Group: DWI_PA

Processing will look for best 1 file(s) to keep using the following criteria(s).

scans.tsv Field	Operator	Value
QC	equals	1
part_of_a_pair	equals	1
QU_cutoff	less_than	10000
QU_sus	less_than	10000
QU_line	less_than	10000
ngood_frames	greater_than	0
line_mean_score	less_than	10000
tSNR_b0	greater_than	0

scans.tsv Field	Operator	Value
QC	equals	1
part_of_a_pair	equals	1
ngood_frames	greater_than	0
line_mean_score	less_than	10000
tSNR_b0	greater_than	0

File Group: T2

Processing will look for best 1 file(s) to keep using the following criteria(s).

scans.tsv Field	Operator	Value
QC	equals	1
QU_motion	less_than	2.01
aqc_motion	less_than	10000
brain_SNR	greater_than	-1000

scans.tsv Field	Operator	Value
QC	equals	1
aqc_motion	less_than	10000
brain_SNR	greater_than	-1000

File Group: T1

Processing will look for best 1 file(s) to keep using the following criteria(s).

scans.tsv Field	Operator	Value
QC	equals	1
QU_motion	less_than	2.01
aqc_motion	less_than	10000
brain_SNR	greater_than	-1000

scans.tsv Field	Operator	Value
QC	equals	1
aqc_motion	less_than	10000
brain_SNR	greater_than	-1000