tessl/pypi-dipy

Comprehensive Python library for diffusion MRI analysis including tensor imaging, tractography, and visualization

—

Pending

Overview

Eval results

Files

Image Processing and Filtering

Name: tessl/pypi-dipy
Author: tessl

Denoising algorithms, filtering methods, and preprocessing tools for diffusion MRI data quality improvement. DIPY provides state-of-the-art methods for enhancing signal quality while preserving important diffusion information.

Capabilities

Denoising Algorithms

Advanced denoising methods specifically designed for diffusion MRI data.

def nlmeans(arr, sigma=None, mask=None, patch_radius=1, block_radius=5, rician=True, num_threads=None):
    """
    Non-local means denoising for diffusion MRI.
    
    Parameters:
        arr (array): 4D diffusion data (x, y, z, diffusion_directions)
        sigma (float): noise standard deviation (estimated if None)
        mask (array): binary mask for processing region
        patch_radius (int): radius of comparison patches
        block_radius (int): radius of search neighborhood  
        rician (bool): assume Rician noise distribution
        num_threads (int): number of parallel threads
        
    Returns:
        array: denoised diffusion data
    """

def localpca(arr, sigma=None, mask=None, patch_radius=2, pca_method='eig', tau_factor=2.3, return_sigma=False, out_dtype=None):
    """
    Local PCA-based denoising using Marchenko-Pastur distribution.
    
    Parameters:
        arr (array): 4D diffusion data
        sigma (float): noise level (auto-estimated if None)
        mask (array): processing mask
        patch_radius (int): local patch radius
        pca_method (str): PCA computation method ('eig', 'svd')
        tau_factor (float): threshold factor for eigenvalue cutoff
        return_sigma (bool): return estimated noise level
        out_dtype (dtype): output data type
        
    Returns:
        array or tuple: denoised data, optionally with sigma estimate
    """

def mppca(arr, mask=None, patch_radius=2, pca_method='eig', return_sigma=False, out_dtype=None):
    """
    Marchenko-Pastur PCA denoising.
    
    Parameters:
        arr (array): 4D diffusion data
        mask (array): binary mask
        patch_radius (int): patch size for local PCA
        pca_method (str): eigenvalue computation method
        return_sigma (bool): return noise estimate
        out_dtype (dtype): output data type
        
    Returns:
        array or tuple: denoised data and optional sigma
    """

def patch2self(data, bvals, patch_radius=0, model='ols', b0_threshold=50, alpha=1.0, verbose=False):
    """
    Patch2Self self-supervised denoising.
    
    Parameters:
        data (array): 4D diffusion data
        bvals (array): b-values for diffusion encoding
        patch_radius (int): spatial patch radius
        model (str): regression model ('ols', 'ridge', 'lasso')
        b0_threshold (float): threshold for b=0 identification
        alpha (float): regularization parameter
        verbose (bool): print progress information
        
    Returns:
        array: self-supervised denoised data
    """

Motion Correction

Algorithms for correcting subject motion during diffusion MRI acquisition.

def motion_correction(data, gtab, *, affine=None, b0_ref=0, pipeline=None, static_mask=None):
    """
    Motion correction for DWI datasets (inter-volume motion).
    
    Parameters:
        data (array/str): 4D DWI data or file path
        gtab (GradientTable): gradient table
        affine (array): voxel-to-world transformation
        b0_ref (int): reference B0 volume index
        pipeline (list): registration transformation sequence
        static_mask (array): mask for reference volume
        
    Returns:
        tuple: (corrected_img, affine_array) motion-corrected data and transforms
    """

def register_dwi_series(data, gtab, *, affine=None, b0_ref=0, pipeline=None, static_mask=None):
    """
    Register DWI series to mean B0 for motion correction.
    
    Parameters:
        data (array/str): DWI data
        gtab (GradientTable): gradient information
        affine (array): affine transformation
        b0_ref (int): reference B0 index
        pipeline (list): registration steps (['center_of_mass', 'translation', 'rigid', 'affine'])
        static_mask (array): processing mask
        
    Returns:
        tuple: (registered_img, transformation_matrices)
    """

Gibbs Ringing Removal

Methods for removing Gibbs ringing artifacts from MRI images.

def gibbs_removal(vol, slice_axis=2, n_points=3, num_processes=1):
    """
    Remove Gibbs ringing artifacts from MRI data.
    
    Parameters:
        vol (array): 3D or 4D MRI volume
        slice_axis (int): axis along which to apply correction
        n_points (int): number of oscillations to correct
        num_processes (int): parallel processing threads
        
    Returns:
        array: corrected volume with reduced Gibbs ringing
    """

Eddy Current Correction

Correction for eddy current-induced distortions in diffusion data.

def eddy_correct(dwi, gtab, *, ref_b0=0, num_threads=1, slice_drop_correction=True):
    """
    Eddy current correction for diffusion data.
    
    Parameters:
        dwi (array): 4D diffusion-weighted images
        gtab (GradientTable): gradient table
        ref_b0 (int): reference B0 volume
        num_threads (int): number of threads
        slice_drop_correction (bool): correct for slice dropouts
        
    Returns:
        array: eddy current corrected data
    """

Bias Field Correction

Methods for correcting intensity inhomogeneity (bias fields) in MRI.

def n4_bias_correction(data, mask=None, num_iterations=50, convergence_threshold=0.001, bspline_grid_resolution=(1, 1, 1)):
    """
    N4 bias field correction algorithm.
    
    Parameters:
        data (array): 3D or 4D image data
        mask (array): binary processing mask
        num_iterations (int): maximum iterations
        convergence_threshold (float): convergence criteria
        bspline_grid_resolution (tuple): B-spline knot spacing
        
    Returns:
        tuple: (corrected_data, bias_field) corrected image and estimated bias
    """

Noise Estimation

Methods for estimating noise characteristics in diffusion MRI data.

def estimate_sigma(arr, disable_background_masking=False, N=0):
    """
    Estimate noise standard deviation in DWI data.
    
    Parameters:
        arr (array): 4D diffusion data or 3D single volume
        disable_background_masking (bool): disable automatic background detection
        N (int): number of coils for Rician correction
        
    Returns:
        float or array: estimated noise standard deviation
    """

def piesno(data, N=1, alpha=0.01, l=100, itermax=100, eps=1e-5, return_mask=False):
    """
    Probabilistic Identification and Estimation of Noise (PIESNO).
    
    Parameters:
        data (array): diffusion MRI data
        N (int): number of receiver coils
        alpha (float): probability of false detection
        l (int): number of background voxels to select
        itermax (int): maximum iterations
        eps (float): convergence tolerance
        return_mask (bool): return background mask
        
    Returns:
        float or tuple: noise standard deviation, optionally with mask
    """

Gradient Non-linearity Correction

Correction for gradient non-linearities in diffusion encoding.

def gradient_nonlinearity_correction(dwi, gtab, grad_dev=None, scanner='siemens'):
    """
    Correct for gradient non-linearity effects.
    
    Parameters:
        dwi (array): diffusion-weighted images
        gtab (GradientTable): gradient table
        grad_dev (array): gradient deviation tensor field
        scanner (str): scanner manufacturer
        
    Returns:
        array: corrected diffusion data
    """

Signal Drift Correction

Methods for correcting signal drift during long acquisitions.

def signal_drift_correction(data, gtab, *, b0_threshold=50, method='linear'):
    """
    Correct for signal drift over acquisition time.
    
    Parameters:
        data (array): 4D diffusion data
        gtab (GradientTable): gradient table with acquisition timing
        b0_threshold (float): threshold for b=0 identification
        method (str): drift correction method ('linear', 'polynomial')
        
    Returns:
        array: drift-corrected diffusion data
    """

Usage Examples

# Comprehensive preprocessing pipeline
from dipy.denoise import localpca, nlmeans, patch2self
from dipy.denoise.gibbs import gibbs_removal
from dipy.denoise.noise_estimate import estimate_sigma, piesno
from dipy.align import motion_correction
from dipy.data import read_stanford_hardi
import numpy as np

# Load example data
img, gtab = read_stanford_hardi()
data = img.get_fdata()

print(f"Original data shape: {data.shape}")

# Step 1: Gibbs ringing removal
print("Removing Gibbs ringing artifacts...")
data_gibbs = gibbs_removal(data, slice_axis=2)

# Step 2: Noise estimation
print("Estimating noise level...")
sigma = estimate_sigma(data_gibbs)
print(f"Estimated noise sigma: {sigma:.4f}")

# Alternative: PIESNO noise estimation
sigma_piesno, mask = piesno(data_gibbs, N=1, return_mask=True)
print(f"PIESNO sigma estimate: {sigma_piesno:.4f}")

# Step 3: Denoising with MP-PCA
print("Applying MP-PCA denoising...")
from dipy.denoise import mppca
data_denoised = mppca(data_gibbs, patch_radius=2)

# Alternative: Non-local means denoising
data_nlm = nlmeans(data_gibbs, sigma=sigma, patch_radius=1, block_radius=2)

# Alternative: Patch2Self denoising
data_p2s = patch2self(data_gibbs, gtab.bvals, patch_radius=0, model='ols')

# Step 4: Motion correction
print("Applying motion correction...")
data_corrected, transforms = motion_correction(data_denoised, gtab)

print(f"Applied {transforms.shape[-1]} motion correction transforms")

# Check improvement in data quality
original_std = np.std(data[data > 0])
denoised_std = np.std(data_corrected.get_fdata()[data_corrected.get_fdata() > 0])
print(f"Noise reduction: {original_std:.4f} -> {denoised_std:.4f}")

# Advanced denoising comparison
print("\nComparing denoising methods...")

# Local PCA with return sigma
data_lpca, sigma_lpca = localpca(data_gibbs, patch_radius=2, return_sigma=True)
print(f"Local PCA estimated sigma: {sigma_lpca:.4f}")

# Non-local means with mask
mask = data_gibbs[..., 0] > np.percentile(data_gibbs[..., 0], 50)
data_nlm_masked = nlmeans(data_gibbs, mask=mask, patch_radius=1, 
                         block_radius=3, rician=True)

# Save results for comparison
from dipy.io.image import save_nifti

save_nifti('data_original.nii.gz', data, img.affine)
save_nifti('data_denoised.nii.gz', data_denoised, img.affine)
save_nifti('data_motion_corrected.nii.gz', data_corrected.get_fdata(), 
           data_corrected.affine)

print("Preprocessing pipeline completed successfully!")

# Noise estimation in practice
print("\nNoise estimation methods comparison:")

# Background-based estimation
sigma_bg = estimate_sigma(data, disable_background_masking=False)

# Manual background masking
background_mask = data[..., 0] < np.percentile(data[..., 0], 10)
sigma_manual = np.std(data[background_mask, :])

print(f"Auto background sigma: {sigma_bg:.4f}")
print(f"Manual background sigma: {sigma_manual:.4f}")
print(f"PIESNO sigma: {sigma_piesno:.4f}")

Install with Tessl CLI