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]

Remove specific volumes from DWI image. If no volumes are specified, the function will remove the last B0s of the DWI image.

Parameters:

  • in_image (str) – Path to the diffusion weighted image file.

  • bvec_file (str, optional) – Path to the bvec file. If None, it will assume the bvec file is in the same directory as the DWI file with the same name but with the .bvec extension.

  • 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.

  • out_image (str, optional) – Path to the output file. If None, it will assume the output file is in the same directory as the DWI file with the same name but with the .nii.gz extension. The original file will be overwritten if the output file is not specified.

  • bvals_to_delete (int, list, optional) –

    List of bvals to delete. If None, it will assume the bvals to delete are the last B0s of the DWI image. Some conditions could be used to delete the volumes.

    For example:

    1. If you want to delete all the volumes with bval = 0, you can use: bvals_to_delete = [0]

    2. If you want to delete all the volumes with b-values higher than 1000, you can use: bvals_to_delete = [bvals > 1000] or bvals_to_delete = [bvals >= 1000] if you want to include the 1000 bvals.

    3. If you want to delete all the volumes with b-values between 1000 and 3000 you can use: bvals_to_delete = [1000 < bvals < 3000] or bvals_to_delete = [1000 <= bvals < 3000] if you want to include the 1000 but not the 3000 bvals.

    For more complex conditions, you can see the function get_indices_by_condition. Included in the clabtoolkit.misctools module.

  • vols_to_delete (int, list, optional) –

    Indices of the volumes to delete. If None, it will assume the volumes to delete are the last B0s of the DWI image. Some conditions could be used to delete the volumes.

    For example:
    1. If you want to delete the first 3 volumes, you can use:

      vols_to_delete = [0, 1, 2]

    2. If you want to delete the volumes from 0 to 10, you can use:

      vols_to_delete = [0:10] or vols_to_delete = [0-10]

    3. If you want to delete the volumes from 0 to 10 and 20 to 30, you can use:

      vols_to_delete = [0:10, 20:30] or vols_to_delete = [0-10, 20-30]

    4. If you want to delete the volumes from 0 to 10 and the volumes 40 and 60, you can use:

      vols_to_delete = [0:10, 40, 60] or vols_to_delete = [0-10, 40, 60] or vols_to_delete = [‘0-10, 40, 60’], etc

    For more complex conditions, you can see the function build_indices. Included in the clabtoolkit.misctools module.

    If both bvals_to_delete and vols_to_delete are specified, the function will remove the volumes with the bvals specified and the volumes specified in the vols_to_delete list. The function will unify all the indices in a single list and remove the volumes from the DWI image.

Returns:

  • out_image (str) – Path to the diffusion weighted image file.

  • out_bvecs_file (str) – Path to the bvec file. If None, it will assume the bvec file is in the same directory as the DWI file with the same name but with the .bvec extension.

  • out_bvals_file (str) – 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.

  • vols2rem (list) – List of volumes removed.

Return type:

str

Notes

IMPORTANT: The function will overwrite the original DWI file if the output file is not specified. IMPORTANT: The function will overwrite the original bvec and bval files if the output file is not specified. IMPORTANT: The function will remove the last B0s of the DWI image if no volumes are specified.

Examples

>>> delete_volumes('dwi.nii.gz') # will remove the last B0s. The original file will be overwritten.

>>> delete_volumes('dwi.nii.gz', out_image='dwi_clean.nii.gz') # will remove the last B0s and save the output in dwi_clean.nii.gz

>>> delete_volumes('dwi.nii.gz', vols_to_delete=[0, 1, 2]) # will remove the first 3 volumes

>>> delete_volumes('dwi.nii.gz', bvec_file='dwi.bvec', bval_file='dwi.bval') # will remove the last B0s and it will assume the bvec and bval files are in the same directory as the DWI file.

>>> delete_volumes('dwi.nii.gz', bvec_file='dwi.bvec', bval_file='dwi.bval', bvals_to_delete= [3000, "bvals >=5000"], out_image='dwi_clean.nii.gz') # will remove the volumes with bvals equal to 3000 and equal or higher than 5000.
    The output will be saved in in dwi_clean.nii.gz
    IMPORTANT: the b-values file dwi.bval should be in the same directory as the DWI file.
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 specialized tools for diffusion-weighted imaging (DWI) analysis, tractography processing, and white matter analysis.

Key Features

  • DWI volume manipulation and quality control

  • Tractography file processing (.trk, .tck formats)

  • B-value and gradient direction management

  • Bundle analysis and clustering

  • DTI and advanced diffusion modeling support

  • Integration with DIPY and MRtrix workflows

Main Functions

Volume Management

  • delete_dwi_volumes(): Remove specific DWI volumes based on indices or b-values

  • get_b0s(): Extract b=0 volumes from DWI data

Tractography Processing

  • tck2trk(): Convert TCK format to TRK format

  • trk2tck(): Convert TRK format to TCK format

  • concatenate_tractograms(): Concatenate multiple tractogram files

  • resample_streamlines(): Resample streamlines in tractograms

  • resample_tractogram(): Resample entire tractogram

  • compute_tractogram_centroids(): Compute centroids of tractogram streamlines

  • create_trackvis_colored_trk(): Create colored TRK files for TrackVis

  • extract_cluster_by_id(): Extract specific cluster from tractogram

  • explore_trk(): Explore TRK file properties

  • interpolate_on_tractogram(): Interpolate data on tractogram

Main Classes

TRKExplorer

Class for exploring and analyzing TRK tractogram files.

Common Usage Examples

DWI volume manipulation:

from clabtoolkit.dwitools import delete_dwi_volumes

# Remove specific volumes from DWI dataset
delete_dwi_volumes(
    dwi_file="dwi.nii.gz",
    bval_file="dwi.bval",
    bvec_file="dwi.bvec",
    volumes_to_delete=[0, 5, 10],  # Remove specific volumes
    output_prefix="cleaned_dwi"
)

Working with b-values:

# Extract b=0 volumes
b0_indices = get_b0s(
    bval_file="dwi.bval",
    tolerance=50
)

Tractography format conversion:

# Convert between tractography formats
tck2trk(
    input_tck="tractography.tck",
    output_trk="tractography.trk",
    reference="dwi.nii.gz"
)

# Explore tractography file
explorer = TRKExplorer("tractography.trk")
summary = explorer.explore()
print(f"Number of streamlines: {summary['n_streamlines']}")

# Concatenate multiple tractograms
concatenate_tractograms(
    input_files=["tract1.trk", "tract2.trk"],
    output_file="combined.trk"
)