dmriprep.utils.vectors module¶

Utilities to operate on diffusion gradients.

class dmriprep.utils.vectors.DiffusionGradientTable(b0_threshold=50, b_scale=True, bvals=None, bvec_norm_epsilon=0.1, bvecs=None, dwi_file=None, raise_inconsistent=False, rasb_file=None, transforms=None)¶

Bases: object

Data structure for DWI gradients.

property affine¶: Get the affine for RAS+/image-coordinates conversions.

property b0mask¶: Get a mask of low-b frames.

property bvals¶: Get the N b-values.

property bvecs¶: Get the N x 3 list of bvecs.

generate_rasb()¶: Compose RAS+B gradient table.

generate_vecval()¶: Compose a bvec/bval pair in image coordinates.

property gradients¶: Get gradient table (rasb).

normalize()¶: Normalize (l2-norm) b-vectors.

property normalized¶: Return whether b-vecs have been normalized.

property pole¶

Check whether the b-vectors cover a full or just half a shell.

If pole is all-zeros then the b-vectors cover a full sphere.

reorient_rasb()¶: Reorient the vectors based o a list of affine transforms.

to_filename(filename, filetype='rasb')¶: Write files (RASB, bvecs/bvals) to a given path.

dmriprep.utils.vectors.b0mask_from_data(dwi_file, mask_file, z_thres=3.0)¶

Evaluate B0 locations relative to mean signal variation.

Standardizes (z-score) the average DWI signal within mask and threshold. This is a data-driven way of estimating which volumes in the DWI dataset are really encoding low-b acquisitions.

Parameters

dwi_file (str) – File path to the diffusion-weighted image series.
mask_file (str) – File path to a mask corresponding to the DWI file.
z_thres (float) – The z-value to consider a volume as a low-b orientation.

dmriprep.utils.vectors.bvecs2ras(affine, bvecs, norm=True, bvec_norm_epsilon=0.2)¶

Convert b-vectors given in image coordinates to RAS+.

Examples

>>> bvecs2ras(2.0 * np.eye(3), [(1.0, 0.0, 0.0), (-1.0, 0.0, 0.0)]).tolist()
[[1.0, 0.0, 0.0], [-1.0, 0.0, 0.0]]

>>> affine = np.eye(4)
>>> affine[0, 0] *= -1.0  # Make it LAS
>>> bvecs2ras(affine, [(1.0, 0.0, 0.0), (-1.0, 0.0, 0.0)]).tolist()
[[-1.0, 0.0, 0.0], [1.0, 0.0, 0.0]]

>>> affine = np.eye(3)
>>> affine[:2, :2] *= -1.0  # Make it LPS
>>> bvecs2ras(affine, [(1.0, 0.0, 0.0), (-1.0, 0.0, 0.0)]).tolist()
[[-1.0, 0.0, 0.0], [1.0, 0.0, 0.0]]

>>> affine[:2, :2] = [[0.0, 1.0], [1.0, 0.0]]  # Make it ARS
>>> bvecs2ras(affine, [(1.0, 0.0, 0.0), (-1.0, 0.0, 0.0)]).tolist()
[[0.0, 1.0, 0.0], [0.0, -1.0, 0.0]]

>>> bvecs2ras(affine, [(0.0, 0.0, 0.0)]).tolist()
[[0.0, 0.0, 0.0]]

>>> bvecs2ras(2.0 * np.eye(3), [(1.0, 0.0, 0.0), (-1.0, 0.0, 0.0)],
...           norm=False).tolist()
[[2.0, 0.0, 0.0], [-2.0, 0.0, 0.0]]

dmriprep.utils.vectors.calculate_pole(bvecs, bvec_norm_epsilon=0.1)¶

Check whether the b-vecs cover a hemisphere, and if so, calculate the pole.

Parameters: bvecs (numpy.ndarray) – 2D numpy array with shape (N, 3) where N is the number of points. All points must lie on the unit sphere.
Returns: pole – A zero-vector if bvecs covers the full sphere, and the unit vector locating the hemisphere pole othewise.
Return type: numpy.ndarray

Examples

>>> bvecs = [(1.0, 0.0, 0.0), (-1.0, 0.0, 0.0),
...          (0.0, 1.0, 0.0), (0.0, -1.0, 0.0),
...          (0.0, 0.0, 1.0)]  # Just half a sphere
>>> calculate_pole(bvecs).tolist()
[0.0, 0.0, 1.0]

>>> bvecs += [(0.0, 0.0, -1.0)]  # Make it a full-sphere
>>> calculate_pole(bvecs).tolist()
[0.0, 0.0, 0.0]

References

https://rstudio-pubs-static.s3.amazonaws.com/27121_a22e51b47c544980bad594d5e0bb2d04.html

dmriprep.utils.vectors.normalize_gradients(bvecs, bvals, b0_threshold=50, bvec_norm_epsilon=0.1, b_scale=True, raise_error=False)¶

Normalize b-vectors and b-values.

The resulting b-vectors will be of unit length for the non-zero b-values. The resultinb b-values will be normalized by the square of the corresponding vector amplitude.

Parameters

bvecs (m x n 2d array) – Raw b-vectors array.
bvals (1d array) – Raw b-values float array.
b0_threshold (float) – Gradient threshold below which volumes and vectors are considered B0’s.

Returns

bvecs (m x n 2d array) – Unit-normed b-vectors array.
bvals (1d int array) – Vector amplitude square normed b-values array.

Examples

>>> bvecs = np.vstack((np.zeros(3), 2.0 * np.eye(3), -0.8 * np.eye(3), np.ones(3)))
>>> bvals = np.array([1000] * bvecs.shape[0])
>>> normalize_gradients(bvecs, bvals, 50, raise_error=True)
Traceback (most recent call last):
ValueError:

>>> bvals[0] = 0.0
>>> norm_vecs, norm_vals = normalize_gradients(bvecs, bvals)
>>> np.all(norm_vecs[0] == 0)
True

>>> norm_vecs[1, ...].tolist()
[1.0, 0.0, 0.0]

>>> norm_vals[0]
0
>>> norm_vals[1]
4000
>>> norm_vals[-2]
600
>>> norm_vals[-1]
3000

>>> norm_vecs, norm_vals = normalize_gradients(bvecs, bvals, b_scale=False)
>>> norm_vals[0]
0
>>> np.all(norm_vals[1:] == 1000)
True

dmriprep.utils.vectors.rasb_dwi_length_check(dwi_file, rasb_file)¶: Check the number of encoding vectors and number of orientations in the DWI file.