qsiprep.workflows.dwi.hmc module

Head motion correction

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

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

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

qsiprep.workflows.dwi.hmc.first_image(image_list)

qsiprep.workflows.dwi.hmc.init_b0_hmc_wf(align_to=None, transform=None, boilerplate=True, name='b0_hmc_wf', prioritize_omp=False) → LiterateWorkflow

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

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

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

qsiprep.workflows.dwi.hmc.init_hmc_model_iteration_wf(name='hmc_model_iter0')

Create a model-based hmc registration iteration workflow.

This workflow takes an initial set of transforms, applies them to the original data, and builds a signal model out of the transformed images.

The original images are then registered to the model-generated target images. Included in the outputs are the transforms and optionally the noise-free images in original (non-aligned) space.

(Source code)

Parameters:

• name (str) – name of the workflow

• Inputs –

  original_dwi_files

  list of 3d dwi files, no b0’s

  bvals

  list of bval files corresponding to original_dwi_files

  approx_aligned_dwi_files

  dwi files that have been registered through a shoreline iteration

  approx_aligned_bvecs

  list of bvec files corresponding to approx_aligned_dwi_files

  b0_indices

  list of which indices in dwi_files are b0 images

  initial_transforms

  list of transforms from a previous registration

  b0_mask

  mask of containing brain voxels

  b0_mean

  mean of the aligned b0 images

• **Outputs** –

  hmc_transforms

  list of transforms, one per file in dwi_files

  rotated_bvecs

  rotated bvec matrix

qsiprep.workflows.dwi.hmc.linear_alignment_workflow(transform='Rigid', iternum=0, omp_nthreads=1)

Takes a template image and a set of input images, does a linear alignment to the template and updates it with the inverse of the average affine transform to the new template

Returns a workflow