dwitools module

clabtoolkit.dwitools.delete_dwi_volumes(in_image, bvec_file=None, bval_file=None, out_image=None, bvals_to_delete=None, vols_to_delete=None)[source]

… (docstring unchanged) …

clabtoolkit.dwitools.get_b0s(dwi_img, b0s_img, bval_file=None, bval_thresh=0)[source]

Extract B0 volumes from a DWI image and save them as a separate NIfTI file.

Parameters:

dwi_img (str) – Path to the input DWI image file.
b0s_img (str) – Path to the output B0 image file.
bval_file (str, optional) – Path to the bval file. If None, it will assume the bval file is in the same directory as the DWI file with the same name but with the .bval extension. The bval file is used to identify the B0 volumes in the DWI image.
bval_thresh (int, optional) – Threshold for identifying B0 volumes. Default is 0. Volumes with b-values below this threshold will be considered B0 volumes.

Returns:

b0s_img (str) – Path to the output B0 image file.
b0_vols (List[int]) – List of indices of the B0 volumes extracted from the DWI image.

Raises:

FileNotFoundError – If the input DWI image file or the bval file does not exist.
ValueError – If the output path for the B0 image file does not exist.

Return type:

str

Examples

>>> dwi_img = 'path/to/dwi_image.nii.gz'
>>> b0s_img = 'path/to/b0_image.nii.gz'
>>> bval_file = 'path/to/bvals.bval'
>>> b0s_img, b0_vols = get_b0s(dwi_img, b0s_img, bval_file)
>>> print(f"B0 image saved at: {b0s_img}")
>>> print(f"B0 volumes indices: {b0_vols}")

>>> b0s_img, b0_vols = get_b0s(dwi_img, b0s_img, bval_file, bval_thresh=10)
>>> print(f"B0 image saved at: {b0s_img}")
>>> print(f"B0 volumes indices: {b0_vols}")
>>> All the volumes with b-values below 10 will be considered B0 volumes.

>>> b0s_img, b0_vols = get_b0s(dwi_img, b0s_img)
>>> print(f"B0 image saved at: {b0s_img}")
>>> print(f"B0 volumes indices: {b0_vols}")
>>> The bval file will be assumed to be in the same directory as the DWI file with the same name but with the .bval extension.

clabtoolkit.dwitools.maps_from_tensor_eigenvalues(eigvals, out_basename, dtmaps=['all'], overwrite=False)[source]

Compute scalar maps derived from diffusion tensor eigenvalues.

Eigenvalues can be supplied either as a single 4D NIfTI image (volumes ordered as λ1, λ2, λ3 along the 4th axis) or as a list/tuple of three separate 3D NIfTI files [l1_path, l2_path, l3_path].

Division-by-zero voxels are handled safely: whenever the denominator is zero the result at that voxel is set to 0.

Parameters:

eigvals (str or list/tuple of str) – Path to a 4D eigenvalue NIfTI image or a list/tuple of three paths to the individual eigenvalue volumes [λ1, λ2, λ3].
out_basename (str) – Full path prefix for the output files. The map tag and .nii.gz extension are appended automatically (e.g. /path/sub-01_desc-DTI → /path/sub-01_desc-DTI_FA.nii.gz).

dtmaps (list of str, optional) –

Scalar maps to compute. Use ['all'] (default) to compute every supported map. Supported tags (case-insensitive):

Tag	Description
`AD`	Axial Diffusivity (λ1)
`RD`	Radial Diffusivity ((λ2 + λ3) / 2)
`MD`	Mean Diffusivity ((λ1 + λ2 + λ3) / 3)
`FA`	Fractional Anisotropy
`CL`	Linear Anisotropy Coefficient
`CP`	Planar Anisotropy Coefficient
`CS`	Spherical Anisotropy Coefficient
`VF`	Volume Fraction
`GA`	Geodesic Anisotropy
`RA`	Relative Anisotropy

overwrite (bool, optional) – If True, recompute and overwrite existing output files. Default is False.

Returns:

Dictionary mapping each requested tag to the path of the saved NIfTI file, or to an empty string if the file could not be created.

Return type:

dict

Raises:

ValueError – If eigvals is not a str, list, or tuple; or if a list/tuple does not contain exactly three elements.
FileNotFoundError – If any of the supplied eigenvalue paths do not exist.

Examples

>>> # 4D eigenvalue image
>>> maps = compute_scalar_maps_from_tensor(
...     "sub-01_eigvals.nii.gz",
...     "out/sub-01",
...     dtmaps=["FA", "MD"],
... )

>>> # Three separate eigenvalue files
>>> maps = compute_scalar_maps_from_tensor(
...     ["sub-01_l1.nii.gz", "sub-01_l2.nii.gz", "sub-01_l3.nii.gz"],
...     "out/sub-01",
...     dtmaps=["all"],
... )

class clabtoolkit.dwitools.DiffusionScheme[source]

Bases: object

__init__()[source]

classmethod from_bvec_bval_files(bvec_file, bval_file)[source]

classmethod from_bvec_bval_arrays(bvecs, bvals)[source]

classmethod from_bmatrix_file(bmat_file)[source]

classmethod from_bmatrix_array(bmat)[source]: bmat shape: (N, 6) with: [Bxx, Byy, Bzz, Bxy, Bxz, Byz]

plot(show=True, use_notebook=False, radius=10.0, colormap='jet', toroid_radius=None, toroid_alpha=0.3, b0_thresh=10.0, show_colorbar=True, show_axes=True, show_opposite_dirs=True)[source]

The dwitools module provides tools for diffusion-weighted imaging (DWI) data: volume management, b-value and gradient direction handling, and tensor-derived map generation.

Note

Tractogram handling lives in tracttools module, not here. Streamline loading, clustering, format conversion (trk2tck / tck2trk) and visualization are all provided by clabtoolkit.tracttools.

Key Features

DWI volume manipulation and removal by index or b-value
B0 volume extraction
Acquisition scheme handling from bvec/bval or b-matrix sources
Gradient direction visualization
Tensor eigenvalue to scalar map conversion (FA, MD, and related maps)

Main Classes

DiffusionScheme

Represents a diffusion acquisition scheme, built through class-method constructors rather than direct instantiation.

Key Methods: - from_bvec_bval_files(): Build a scheme from bvec and bval files - from_bvec_bval_arrays(): Build a scheme from bvec and bval arrays - from_bmatrix_file(): Build a scheme from a b-matrix file - from_bmatrix_array(): Build a scheme from a b-matrix array - plot(): Visualize the gradient directions on a sphere

Main Functions

Volume Management

delete_dwi_volumes(): Remove DWI volumes by volume index or by b-value
get_b0s(): Extract b=0 volumes from a DWI dataset

Tensor Maps

maps_from_tensor_eigenvalues(): Derive scalar maps from tensor eigenvalues

Common Usage Examples

DWI volume manipulation:

from clabtoolkit.dwitools import delete_dwi_volumes

# Remove specific volumes, keeping the bvec/bval files in sync
delete_dwi_volumes(
    in_image="dwi.nii.gz",
    bvec_file="dwi.bvec",
    bval_file="dwi.bval",
    vols_to_delete=[0, 5, 10],
    out_image="cleaned_dwi.nii.gz"
)

# Or remove every volume acquired at a given b-value
delete_dwi_volumes(
    in_image="dwi.nii.gz",
    bvec_file="dwi.bvec",
    bval_file="dwi.bval",
    bvals_to_delete=[3000],
    out_image="cleaned_dwi.nii.gz"
)

Working with b-values:

from clabtoolkit.dwitools import get_b0s

# Extract the b=0 volumes into their own image
b0s_img, b0_vols = get_b0s(
    dwi_img="dwi.nii.gz",
    b0s_img="dwi_b0s.nii.gz",
    bval_file="dwi.bval",
    bval_thresh=50
)
print(f"Found {len(b0_vols)} b0 volumes")

Inspecting an acquisition scheme:

from clabtoolkit.dwitools import DiffusionScheme

# Build the scheme from the gradient files
scheme = DiffusionScheme.from_bvec_bval_files(
    bvec_file="dwi.bvec",
    bval_file="dwi.bval"
)

# Visualize the gradient directions
scheme.plot(show=True)

# A scheme can also be built from a b-matrix
scheme = DiffusionScheme.from_bmatrix_file("dwi.bmat")

Tensor-derived maps:

from clabtoolkit.dwitools import maps_from_tensor_eigenvalues

# Generate scalar maps from tensor eigenvalues
maps = maps_from_tensor_eigenvalues(
    eigvals="dti_eigenvalues.nii.gz",
    out_basename="/path/to/output/sub-01_dti",
    dtmaps=["all"],
    overwrite=True
)
print(maps)  # dict mapping each map tag to its saved path