qsiprep.interfaces.gradients module

Handle merging and splitting of DSI files.

class qsiprep.interfaces.gradients.CombineMotions(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

• ref_file (a pathlike object or string representing an existing file) – Fixed Image.

• transform_files (a list of items which are a pathlike object or string representing an existing file) – Transform files from hmc.

Outputs:

• motion_file (a pathlike object or string representing an existing file)

• spm_motion_file (a pathlike object or string representing an existing file)

class qsiprep.interfaces.gradients.ComposeSDCWarp(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Express the SDC displacement field on the output (ACPC) grid.

The susceptibility warp is estimated in the corrected DWI frame. Writing it to derivatives means re-expressing it on the ACPC output grid as a transform, so its displacement vectors are rotated into ACPC world coordinates – a scalar image resample would move the values but leave the vectors pointing along the DWI axes.

With A the DWI-frame-to-ACPC transform (the inverse of to_template_transforms) and W the SDC warp, the field on the ACPC grid is the conjugation A o W o A^-1: at an ACPC point it pulls back to the DWI frame, applies W, and pushes forward, so a uniform DWI-frame displacement d becomes R d where R is A’s rotation. antsApplyTransforms composes, first-applied-first, to_template_transforms (ACPC->DWI = A^-1), then W, then the inverse of to_template_transforms (A); -o [field, 1] writes the composite as a displacement field on the reference grid. Affine stages are inverted on the fly; a non-linear stage (a non-default intramodal-template warp) is inverted numerically first.

Several sdc_warps make W their composition, applied to a point in the order given: for TOPUP+DRBUDDI, DRBUDDI’s refinement carries a corrected point into the TOPUP-corrected series, and TOPUP’s field carries it on to the distorted data.

Mandatory Inputs:

• reference_image (a pathlike object or string representing an existing file) – The output (ACPC) grid.

• sdc_warps (a list of items which are a pathlike object or string representing an existing file) – The SDC (susceptibility) displacement fields for volume 0, in the order a corrected point passes through them on its way back to the distorted data (e.g. DRBUDDI deformation_FINV alone, or DRBUDDI refinement then TOPUP).

• to_template_transforms (a list of items which are a pathlike object or string representing an existing file or ‘identity’) – ANTs-ordered transforms carrying the corrected DWI frame to the output (ACPC) grid (ComposeTransforms.sdc_warp_transforms).

Outputs:

sdc_warp_to_template (a pathlike object or string representing an existing file) – The SDC displacement field, on the output (ACPC) grid.

class qsiprep.interfaces.gradients.ComposeTransforms(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

• dwi_files (a list of items which are a pathlike object or string representing an existing file) – List of dwi files.

• reference_image (a pathlike object or string representing an existing file) – Output grid.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• b0_to_dwiref_transforms (a list of items which are a pathlike object or string representing an existing file) – List of transforms to register the b=0 to the dwiref.

• copy_dtype (a boolean) – Copy dtype from inputs to outputs. (Nipype default value: False)

• default_value (a float) – Maps to a command-line argument: --default-value %g. (Nipype default value: 0.0)

• dimension (2 or 3 or 4) – This option forces the image to be treated as a specified-dimensional image. If not specified, antsWarp tries to infer the dimensionality from the input image. Maps to a command-line argument: --dimensionality %d.

• dwiref_to_t1_affine (a pathlike object or string representing an existing file) – Affine from the dwiref to t1.

• dwiref_to_t1_warp (a pathlike object or string representing an existing file) – Warp from the dwiref to t1.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• fieldwarps (a list of items which are a pathlike object or string representing an existing file) – SDC unwarping transform.

• float (a boolean) – Use float instead of double for computations. Maps to a command-line argument: --float %d. (Nipype default value: False)

• gradwarp (a list of items which are a pathlike object or string representing an existing file) – Gradient nonlinearity displacement field, in native DWI space.

• hmc_affines (a list of items which are a pathlike object or string representing an existing file) – Head motion correction affines.

• hmcsdc_dwi_ref_to_t1w_affine (a pathlike object or string representing an existing file) – Affine from dwi ref to t1w.

• input_image (a pathlike object or string representing a file)

• input_image_type (0 or 1 or 2 or 3) – Option specifying the input image type of scalar (default), vector, tensor, or time series. Maps to a command-line argument: --input-image-type %d.

• interpolation (‘Linear’ or ‘NearestNeighbor’ or ‘CosineWindowedSinc’ or ‘WelchWindowedSinc’ or ‘HammingWindowedSinc’ or ‘LanczosWindowedSinc’ or ‘MultiLabel’ or ‘Gaussian’ or ‘BSpline’ or ‘GenericLabel’) – Maps to a command-line argument: %s. (Nipype default value: Linear)

• interpolation_parameters (a tuple of the form: (an integer) or a tuple of the form: (a float, a float) or a tuple of the form: (a string))

• invert_transform_flags (a list of items which are a boolean)

• num_threads (an integer) – Number of parallel processes. (Nipype default value: 1)

• out_postfix (a string) – Postfix that is appended to all output files (default = _trans). (Nipype default value: _trans)

• output_image (a string) – Output file name. Maps to a command-line argument: --output %s.

• print_out_composite_warp_file (a boolean) – Output a composite warp file instead of a transformed image. Requires inputs: output_image.

• save_cmd (a boolean) – Write a log of command lines that were applied. (Nipype default value: True)

• t1_2_mni_forward_transform (a list of items which are a pathlike object or string representing an existing file) – Composite (h5) transform to mni.

• transforms (a pathlike object or string representing a file)

Outputs:

• log_cmdline (a pathlike object or string representing a file) – A list of command lines used to apply transforms.

• out_affines (a list of items which are a pathlike object or string representing an existing file) – Composed affine-only transforms to output_grid.

• out_warps (a list of items which are a pathlike object or string representing an existing file) – Composed all transforms to output_grid.

• sdc_warp_transforms (a list of items which are a pathlike object or string representing an existing file or ‘identity’) – ANTs-ordered transforms that move the SDC displacement field from the corrected DWI frame to the output (ACPC) grid, for volume 0.

• transform_lists (a list of items which are a list of items which are a pathlike object or string representing an existing file) – Lists of transforms for each image.

class qsiprep.interfaces.gradients.ExtractB0s(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Extract a b0 series and a mean b0 from a dwi series.

Mandatory Inputs:

dwi_series (a pathlike object or string representing an existing file)

Optional Inputs:

• b0_indices (a list of items which are any value)

• b0_threshold (an integer) – (Nipype default value: 50)

• bval_file (a pathlike object or string representing an existing file)

Outputs:

• b0_average (a pathlike object or string representing an existing file)

• b0_series (a pathlike object or string representing an existing file)

class qsiprep.interfaces.gradients.GradientRotation(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Reorient gradients according to transforms.

Mandatory Inputs:

• bval_files (a list of items which are a pathlike object or string representing an existing file) – List of split bval files.

• bvec_files (a list of items which are a pathlike object or string representing an existing file) – List of split bvec files, must correspond to a non-oblique image/reference frame.

Optional Inputs:

• affine_transforms (a list of items which are a pathlike object or string representing an existing file) – ITK affine transforms.

• original_images (a list of items which are a pathlike object or string representing an existing file) – NIfTI images corresponding to bvals, bvecs.

Outputs:

• bvals (a pathlike object or string representing an existing file)

• bvecs (a pathlike object or string representing an existing file)

• log_cmdline (a pathlike object or string representing an existing file)

class qsiprep.interfaces.gradients.LocalGradientRotation(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

bval_files (a list of items which are a pathlike object or string representing an existing file) – List of split bval files.

Optional Inputs:

• affine_transforms (a list of items which are a pathlike object or string representing an existing file) – ITK affine transforms.

• bvec_files (a list of items which are a pathlike object or string representing an existing file) – List of split bvec files.

• mask_image (a pathlike object or string representing an existing file) – Brain mask in the output space.

• original_images (a list of items which are a pathlike object or string representing an existing file) – NIfTI images corresponding to bvals, bvecs.

• warp_transforms (a list of items which are a pathlike object or string representing an existing file) – Warps.

Outputs:

• local_bvecs (a pathlike object or string representing an existing file)

• log_cmdline (a pathlike object or string representing an existing file)

class qsiprep.interfaces.gradients.MatchTransforms(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

• b0_indices (a list of items which are any value)

• dwi_files (a list of items which are a pathlike object or string representing an existing file)

• transforms (a list of items which are a pathlike object or string representing an existing file)

Outputs:

transforms (a list of items which are a pathlike object or string representing an existing file)

class qsiprep.interfaces.gradients.RemoveDuplicates(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

• bval_file (a pathlike object or string representing an existing file)

• bvec_file (a pathlike object or string representing an existing file)

• dwi_file (a pathlike object or string representing an existing file)

Optional Inputs:

• distance_cutoff (a float) – (Nipype default value: 5.0)

• expected_directions (an integer)

• local_bvec_file (a pathlike object or string representing an existing file)

Outputs:

• bval_file (a pathlike object or string representing an existing file)

• bvec_file (a pathlike object or string representing an existing file)

• dwi_file (a pathlike object or string representing an existing file)

• local_bvec_file (a pathlike object or string representing an existing file)

class qsiprep.interfaces.gradients.SliceQC(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Optional Inputs:

• ideal_image_files (a list of items which are a pathlike object or string representing an existing file) – Model-based images.

• impute_slice_threshold (a float) – Threshold for using imputed data in a slice.

• mask_image (a pathlike object or string representing an existing file) – Brain mask.

• min_slice_size_percentile (a float) – Slices bigger than this percentile are candidates for imputation. (Nipype default value: 10.0)

• uncorrected_dwi_files (a list of items which are a pathlike object or string representing an existing file) – Uncorrected dwi files.

Outputs:

• imputed_images (a list of items which are a pathlike object or string representing an existing file) – Dwi files with imputed slices.

• slice_stats (a pathlike object or string representing an existing file) – Npy file with the slice-by-TR error matrix.

qsiprep.interfaces.gradients.aattp_rotate_vec(orig_vec, transform, runtime)

qsiprep.interfaces.gradients.bvec_rotation(ortho_bvecs, transforms, output_file, runtime)

Rotate bvecs using antsApplyTransformsToPoints and antsTransformInfo.

Parameters:

• ortho_bvecs (np.ndarray of shape (n, 3)) – bvecs relative to a non-oblique output volume

• transforms (list) – List of transform files that will be applied to the vectors

• output_file (str) – Path to write the new bvec file

• runtime (runtime object) – Nipype node runtime object

qsiprep.interfaces.gradients.compose_affines(reference_image, affine_list, output_file)

Use antsApplyTransforms to get a single affine from multiple affines.

qsiprep.interfaces.gradients.concatenate_bvals(bval_list, out_file)

Create an FSL-style bvals file from split bval files.

qsiprep.interfaces.gradients.concatenate_bvecs(input_files)

Create Dipy-style gradient array (3-columns) from bvec files.

qsiprep.interfaces.gradients.create_tensor_image(mask_img, direction, prefix)

Create an ANTs tensor image with the tensor for direction in every mask voxel.

Set intent as NIFTI_INTENT_SYMMATRIX (1005), [dxx, dxy, dyy, dxz, dyz, dzz] are the components info from here https://github.com/ANTsX/ANTs/wiki/Importing-diffusion-tensor-data-from-other-software

qsiprep.interfaces.gradients.get_fsl_motion_params(itk_file, ref_file, working_dir)

qsiprep.interfaces.gradients.get_ras_motion_params(itk_file, ref_file)

Decompose a per-volume rigid transform into RAS+ motion parameters.

Mirror of get_fsl_motion_params(), but the translation (mm) and rotation (rotation-vector radians) are expressed in the scanner-independent RAS+ world frame instead of FSL’s radiological frame. eddy/SHORELine report FSL and DIFFPREP reports LPS; decomposing every backend’s transform in RAS removes those per-backend axis flips, so the exported motion is directly comparable to RAS-defined ground truth regardless of grid orientation.

qsiprep.interfaces.gradients.get_vector_nii(data, affine, header)

qsiprep.interfaces.gradients.local_bvec_rotation(original_bvecs, warp_transforms, mask_image, runtime, output_fname)

Create a vector in each voxel that accounts for nonlinear warps.

qsiprep.interfaces.gradients.match_transforms(dwi_files, transforms, b0_indices)

qsiprep.interfaces.gradients.reorient_tensor_image(tensor_image, warp_file, mask_img, prefix, output_fname)

qsiprep.interfaces.gradients.write_concatenated_fsl_gradients(bval_files, bvec_files, out_prefix)