qsiprep.workflows.dwi package

Pre-processing q-space Image workflows

Orchestrating the dwi-preprocessing workflow

qsiprep.workflows.dwi.base.init_dwi_preproc_wf(scan_groups, t2w_sdc, output_prefix, source_file, anatomical_template) → LiterateWorkflow[source]

This workflow controls the dwi preprocessing stages of qsiprep.

(Source code)

Parameters:

  • scan_groups (list of dicts) – List of dicts grouping files by PE-dir

  • t2w_sdc (bool) – Include T2w scans in distortion correction

  • output_prefix (str) – beginning of the output file name (eg ‘sub-1_buds-j’)

  • source_file (str) – The file name template used for derivatives

Inputs:

  • t1_preproc – Bias-corrected structural template image

  • t1_brain – Skull-stripped t1_preproc

  • t1_mask – Mask of the skull-stripped template image

  • t1_output_grid – Image to write out DWIs aligned to t1

  • t1_seg – Segmentation of preprocessed structural image, including gray-matter (GM), white-matter (WM) and cerebrospinal fluid (CSF)

  • t1_2_mni_forward_transform – ANTs-compatible affine-and-warp transform file

  • t1_2_mni_reverse_transform – ANTs-compatible affine-and-warp transform file (inverse)

  • subjects_dir – FreeSurfer SUBJECTS_DIR

  • subject_id – FreeSurfer subject ID

  • dwi_sampling_grid – A NIfTI1 file with the grid spacing and FoV to resample the DWIs

Outputs:

  • dwi_t1 – dwi series, resampled to T1w space

  • dwi_mask_t1 – dwi series mask in T1w space

  • bvals_t1 – bvalues of the dwi series

  • bvecs_t1 – bvecs after aligning to the T1w and resampling

  • local_bvecs_t1 – voxelwise bvecs accounting for local displacements

  • gradient_table_t1 – MRTrix-style gradient table

  • dwi_mni – dwi series, resampled to template space

  • dwi_mask_mni – dwi series mask in template space

  • bvals_mni – bvalues of the dwi series

  • bvecs_mni – bvecs after aligning to the T1w and resampling

  • local_bvecs_mni – voxelwise bvecs accounting for local displacements

  • gradient_table_mni – MRTrix-style gradient table

  • confounds_file – estimated motion parameters and zipper scores

  • raw_qc_file – DSI Studio QC file for the raw data

  • raw_concatenated – concatenated raw images for a qc report

  • carpetplot_data – path to a file containing carpetplot data

See also

Utility workflows

qsiprep.workflows.dwi.util.init_dwi_reference_wf(dwi_file=None, name='dwi_reference_wf', gen_report=False, source_file=None, desc='initial')[source]

Create dwiref reference image.

If register_t2, a skull-stripped T1w image is downsampled to the resolution of the b=0 input image and registered to it.

(Source code)

Parameters:

  • dwi_file (str, optional) – A b=0 image Default is None.

  • name (str) – Name of workflow (default: dwi_reference_wf)

  • gen_report (bool, optional) – Whether a mask report node should be appended in the end. Default is False.

  • source_file (str, optional) – Source file for the mask report. Default is None.

  • desc (str, optional) – Description of the dwi reference image. Default is initial.

Inputs:

  • b0_template – the b0 template used as the motion correction reference

  • t1_brain – skull-stripped T1w image from the same subject

  • t1_mask – mask image for t1_brain

  • wm_seg – white matter segmentation from the T1w image

Outputs:

  • raw_ref_image – Reference image to which dwi series is motion corrected

  • ref_image – Contrast-enhanced reference image

  • ref_image_brain – Skull-stripped reference image

  • dwi_mask – Skull-stripping (rough) mask of reference image

  • validation_report – HTML reportlet indicating whether dwi_file had a valid affine

See also

  • init_enhance_and_skullstrip_wf()

Head motion correction

qsiprep.workflows.dwi.hmc.init_dwi_hmc_wf(source_file, num_model_iterations=2, mem_gb=3, name='dwi_hmc_wf')[source]

Perform head motion correction and susceptibility distortion correction.

This workflow uses antsRegistration and an iteratively updated signal model to perform motion correction.

Parameters

hmc_transform: ‘Rigid’ or ‘Affine’

How many degrees of freedom to incorporate into motion correction

hmc_model: ‘3dSHORE’, ‘none’ , ‘tensor’ or ‘SH’

Which model to use for generating signal predictions for hmc. ‘3dSHORE’ requires multiple b-values, ‘none’ will only use b0 images for motion correction, ‘tensor’ uses a tensor model for signal predictions for hmc, and ‘SH’ uses spherical harmonics (not implemented yet).

hmc_align_to: ‘first’ or ‘iterative’

Which volume should be used to determine the motion-corrected space?

source_file: str

Path to one of the original dwi files (used for reportlets)

rpe_b0: str

Path to a reverse phase encoding image to be used for 3dQWarp’s TOPUP-style correction

num_model_iterations: int

If hmc_model is '3dSHORE' or 'SH' determines the number of times the model is updated and motion correction is estimated. Default: 2.

Inputs

dwi_files: list

List of single-volume files across all DWI series

b0_indices: list

Indexes into dwi_files that correspond to b=0 volumes

bvecs: list

List of paths to single-line bvec files

bvals: list

List of paths to single-line bval files

b0_images: list

List of single b=0 volumes

original_files: list

List of the files from which each DWI volume came from.

Outputs

final_template: str

Path to the mean of the coregistered b0 images

forward_transforms: list

List of ITK transforms that motion-correct the images in dwi_files

noise_free_dwis: list

Model-predicted images reverse-transformed into alignment with dwi_files

cnr_image: str

If hmc_model is ‘none’ this is the tsnr of the b=0 images. Otherwise it is the model fit divided by the model error in each voxel.

optimization_data: str

CSV file tracking the motion estimates across shoreline iterations

qsiprep.workflows.dwi.hmc.init_dwi_model_hmc_wf(num_iters=2, name='dwi_model_hmc_wf')[source]

Create a model-based hmc workflow.

(Source code)

Parameters:

num_iters (int) – the number of times the model will be updated with transformed data

Inputs:

  • dwi_files – list of 3d dwi files

  • b0_indices – list of which indices in dwi_files are b0 images

  • initial_transforms – list of b0-based transforms from dwis to the b0 template

  • warped_b0_images – list of aligned b0 images

  • b0_mask – mask of containing brain voxels

  • bvecs – list of bvec files corresponding to dwi_files

  • bvals – list of bval files corresponding to dwi_files

Outputs:

  • hmc_transforms – list of transforms, one per file in dwi_files

  • model_predicted_images (list) – Model-predicted images reverse-transformed into alignment with dwi_files

  • cnr_image (str) – If hmc_model is ‘none’ this is the tsnr of the b=0 images. Otherwise it is the model fit divided by the model error in each voxel.

  • optimization_data (str) – CSV file tracking the motion estimates across shoreline iterations

Implementing the FSL preprocessing workflow

qsiprep.workflows.dwi.fsl.init_fsl_hmc_wf(scan_groups, source_file, t2w_sdc, dwi_metadata=None, slice_quality='outlier_n_sqr_stdev_map', name='fsl_hmc_wf')[source]

This workflow controls the dwi preprocessing stages using FSL tools.

I couldn’t get this to work reliably unless everything was oriented in LAS+ before going to TOPUP and eddy. For this reason, if TOPUP is going to be used (for an epi fieldmap or an RPE series) or there is no fieldmap correction, operations occurring before eddy are done in LAS+. The fieldcoefs are applied during eddy’s run and the corrected series comes out. This is finally converted to LPS+ and sent to the rest of the pipeline.

If a GRE fieldmap is available, the correction is applied to eddy’s outputs after they have been converted back to LPS+.

Finally, if SyN is chosen, it is applied to the LPS+ converted, eddy-resampled data.

Parameters

scan_groups: dict

dictionary with fieldmaps and warp space information for the dwis

impute_slice_threshold: float

threshold for a slice to be replaced with imputed values. Overrides the parameter in eddy_config if set to a number > 0.

pepolar_methodstr

Either ‘DRBUDDI’, ‘TOPUP’ or ‘DRBUDDI+TOPUP’. The method for SDC when EPI fieldmaps are used.

eddy_config: str

Path to a JSON file containing settings for the call to eddy.

Inputs

dwi_file: str

DWI series. Possibly concatenated, denoised, etc

bvec_file: str

bvec file

bval_file: str

bval file

json_file: str

path to sidecar json file for dwi_file

b0_indices: list

Indexes into dwi_files that correspond to b=0 volumes

b0_images: list

List of single b=0 volumes

original_files: list

List of the files from which each DWI volume came. One per original file

t1_brain: str

Skull stripped T1w image

t1_mask: str

mask for t1_brain

Resampling workflows

qsiprep.workflows.dwi.resampling.init_dwi_trans_wf(source_file, mem_gb, template='ACPC', name='dwi_trans_wf', use_compression=True, write_local_bvecs=False, write_reports=True, concatenate=True, doing_topup=False)[source]

This workflow samples dwi images to the output_grid in a “single shot” from the original DWI series.

(Source code)

Parameters

templatestr

Name of template targeted by template output space

mem_gbfloat

Size of DWI file in GB

omp_nthreadsint

Maximum number of threads an individual process may use

namestr

Name of workflow (default: dwi_trans_wf)

use_compressionbool

Save registered DWI series as .nii.gz

use_fieldwarpbool

Include SDC warp in single-shot transform from DWI to MNI

output_resolutionfloat

Voxel size in mm for the output data

to_mnibool

Include warps to MNI

write_local_bvecsbool

if true, local bvec niftis are written

Inputs

itk_b0_to_t1

Affine transform from ref_bold_brain to T1 space (ITK format)

t1_2_mni_forward_transform

ANTs-compatible affine-and-warp transform file

dwi_files

Individual 3D volumes, not motion corrected

cnr_map

Contrast to noise map from model-based hmc

fieldmap_hz

Fieldmap in Hz. Only written out if TOPUP was used.

bval_files

individual bval files

bvec_files

one-lined bvec files

b0_ref_image

b0 template for the dwi series

b0_indices

List of indices that contain a b0 image

dwi_mask

Skull-stripping mask of reference image

name_source

DWI series NIfTI file Used to recover original information lost during processing

hmc_xforms

List of affine transforms aligning each volume to ref_image in ITK format

fieldwarps

a DFM in ITK format

output_grid

File defining the output space

t1_mask

Brain mask from the t1w

Outputs

dwi_resampled

DWI series, resampled to template space. One file if concatenate, otherwise a list of files

dwi_ref_resampled

Reference, contrast-enhanced summary of the DWI series, resampled to template space

dwi_mask_resampled

DWI series mask in template space

cnr_map_resampled

Contrast to noise map resampled

bvals

bvals file for the DWI series

rotated_bvecs

bvecs rotated for transforms to output_grid

local_bvecs

NIfTI file containing the bvec rotation matrix (due to transforms) in each voxel. Includes rotations introduced by warpingdenoisin

Calculate dwi confounds

qsiprep.workflows.dwi.confounds.init_dwi_confs_wf()[source]

This workflow calculates confounds for a dwi series, and aggregates them into a TSV file, for use as nuisance regressors in a GLM.

The following confounds are calculated, with column headings in parentheses:

  1. Framewise displacement, based on head-motion parameters (framewise_displacement)

  2. Estimated head-motion parameters, in mm and rad (trans_x, trans_y, trans_z, rot_x, rot_y, rot_z)

../_images/qsiprep-workflows-dwi-5.png

(Source code, png, svg, pdf)

Inputs:

  • sliceqc_file – dwi image, after the prescribed corrections (STC, HMC and SDC) when available.

  • motion_params – spm motion params

Outputs:

  • confounds_file – TSV of all aggregated confounds

  • rois_report – Reportlet visualizing white-matter/CSF mask used for aCompCor, the ROI for tCompCor and the dwi brain mask.

Submodules