dmriprep.utils.vectors module

Utilities to operate on diffusion gradients.

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

Bases: object

Data structure for DWI gradients.

property affineView on GitHub : Get the affine for RAS+/image-coordinates conversions.

property b0maskView on GitHub : Get a mask of low-b frames.

property bvalsView on GitHub : Get the N b-values.

property bvecsView on GitHub : Get the N x 3 list of bvecs.

property count_shellsView on GitHub : Count the number of volumes per b-value.

generate_rasb()View on GitHub : Compose RAS+B gradient table.

generate_vecval()View on GitHub : Compose a bvec/bval pair in image coordinates.

property gradientsView on GitHub : Get gradient table (rasb).

normalize()View on GitHub : Normalize (l2-norm) b-vectors.

property normalizedView on GitHub : Return whether b-vecs have been normalized.

property poleView on GitHub 

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()View on GitHub : Reorient the vectors based o a list of affine transforms.

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

dmriprep.utils.vectors.bvecs2ras(affine, bvecs, norm=True, bvec_norm_epsilon=0.2)View on GitHub 

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)View on GitHub 

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 otherwise.
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_mag=None, b_scale=True, raise_error=False)View on GitHub 

Normalize b-vectors and b-values.

The resulting b-vectors will be of unit length for the non-zero b-values. The resulting 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: Inconsistent bvals and bvecs (0, 1 low-b, respectively).

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

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

>>> int(norm_vals[0])
0
>>> int(norm_vals[1])
4000
>>> int(norm_vals[-2])
600
>>> int(norm_vals[-1])
3000

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

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