qsiprep.workflows.dwi package

Pre-processing q-space Image workflows.

Pre-processing q-space Image workflows

Orchestrating the dwi-preprocessing workflow.

Orchestrating the dwi-preprocessing workflow

qsiprep.workflows.dwi.base.init_dwi_preproc_wf(unit, t2w_sdc, output_prefix, source_file, anatomical_template, do_biascorr=True) → LiterateWorkflow[source]

Build a workflow that runs the dwi preprocessing stages of qsiprep.

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

(Source code, png, svg, pdf)

Parameters:

  • unit (PreprocUnit) – The DWI series to correct together and the fieldmap that corrects them

  • 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

  • anatomical_template (str) – Name of the anatomical template (e.g., 'MNI152NLin2009cAsym'), passed to the SHORELine head motion and distortion correction workflow for fieldmap-less SDC.

  • do_biascorr (bool, optional) – Whether bias correction is applied to the DWI data; used for the methods boilerplate and provenance. Default is True.

Inputs:

  • dwi_files – the unit’s member series, conformed and denoised, one per file in unit.dwi_files and in the same order (see init_dwi_series_denoise_wf())

  • bval_files – bvals of each series

  • bvec_files – conformed bvecs of each series

  • raw_dwi_files – the member series, conformed but not denoised

  • noise_images – noise image of each series

  • denoising_confounds – denoising confounds of each series

  • validation_reports – conformation report of each series

  • 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)

  • to_template_affine_transform – Full affine to the anatomical template that AC-PC alignment was extracted from (consumed by the SynB0 generation workflow)

  • acpc_inv_transform – Inverse of the AC-PC rigid transform

  • 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.

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, optional) – 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.

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]

Build a workflow that performs head motion and susceptibility distortion correction.

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

The transform and signal model come from the hmc_transform and shoreline_model workflow settings, set by --shoreline-config.

Parameters:

  • source_file (str) – Path to one of the original dwi files (used for reportlets)

  • num_model_iterations (int, optional) – Number of SHORELine model-based iterations, used when the model is ‘3dshore’ or ‘tensor’ (ignored for ‘none’). Default: 2.

  • mem_gb (float, optional) – Estimated memory usage. Default: 3.

  • name (str, optional) – Name of the workflow. Default: ‘dwi_hmc_wf’.

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 shoreline_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, optional) – the number of times the model will be updated with transformed data

  • name (str, optional) – Name of workflow (default: dwi_model_hmc_wf)

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 shoreline_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.

Implementing the FSL preprocessing workflow

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

Build a workflow that runs 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:

  • unit (PreprocUnit) – the DWI series to correct together and the fieldmap that corrects them

  • source_file (str) – Path to the source DWI file (used for report and derivative naming).

  • t2w_sdc (bool) – Whether a T2w image is available for distortion correction (used for DRBUDDI’s multi-modal registration).

  • slice_quality (str, optional) – Name of the eddy output that is sent to outputnode.slice_quality and outputnode.hmc_optimization_data. Default is 'outlier_n_sqr_stdev_map'.

  • name (str, optional) – Name of workflow (default: fsl_hmc_wf)

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.

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, pe_axis=None, weight_fieldwarps=True, sdc_warp_source=None, sdc_pe_dir=None, sdc_readout_time=None)[source]

Build a workflow that resamples dwi images to the output grid in a single shot.

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

(Source code)

Parameters:

  • source_file (str) – Source DWI file used to name the resampled b=0 reference reports.

  • mem_gb (float) – Size of DWI file in GB

  • template (str, optional) – Name of template targeted by template output space

  • name (str, optional) – Name of workflow (default: dwi_trans_wf)

  • use_compression (bool, optional) – Save registered DWI series as .nii.gz

  • write_local_bvecs (bool, optional) – if true, local bvec niftis are written

  • write_reports (bool, optional) – Whether the resampled b=0 reference workflow writes its mask report.

  • concatenate (bool, optional) – Whether to merge the resampled volumes into a single 4D series (and compute the resampled b=0 reference and QC). If False, the list of resampled volumes is sent to outputnode.dwi_resampled.

  • doing_topup (bool, optional) – Whether TOPUP was used, in which case inputnode.fieldmap_hz is resampled to the output grid.

  • pe_axis (int or None, optional) – Voxel axis of the phase-encoding direction, used to compute Jacobian weights whenever a displacement field is supplied.

  • weight_fieldwarps (bool, optional) – Whether the susceptibility displacement field is included in the Jacobian weights. False leaves it unmodulated.

  • sdc_warp_source (str or None, optional) – Where the SDC displacement field written on the output grid comes from: 'fieldwarp', 'topup', 'gre_in_eddy' or 'topup+drbuddi' (see sdc_warp_source()). If None, no SDC displacement field is written.

  • sdc_pe_dir (str or None, optional) – Phase-encoding direction used to rebuild the displacement field from a fieldmap in Hz.

  • sdc_readout_time (float or None, optional) – Total readout time used to rebuild the displacement field from a fieldmap in Hz.

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

  • gradwarp_field – a gradient nonlinearity displacement field in native DWI space, or undefined if no gradwarp correction is being applied

  • 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.

Calculate dwi confounds

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

Build a workflow that calculates confounds for a dwi series.

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