tessl/pypi-dipy
Comprehensive Python library for diffusion MRI analysis including tensor imaging, tractography, and visualization
—
Pending
signal-reconstruction.mddocs/
Signal Reconstruction Models
Model-based analysis of diffusion MRI signals including diffusion tensor imaging (DTI), diffusion kurtosis imaging (DKI), constrained spherical deconvolution (CSD), and advanced microstructure models. All models follow a consistent Model/Fit interface pattern.
Capabilities
Diffusion Tensor Imaging (DTI)
Classical diffusion tensor model for estimating water diffusion properties and deriving standard diffusion metrics.
class TensorModel:
"""Diffusion tensor imaging model."""
def __init__(self, gtab, fit_method='WLS', return_S0_hat=False):
"""
Initialize tensor model.
Parameters:
gtab (GradientTable): gradient table
fit_method (str): fitting method ('WLS', 'OLS', 'NLLS')
return_S0_hat (bool): return S0 estimates
"""
def fit(self, data, mask=None):
"""
Fit tensor model to data.
Parameters:
data (array): diffusion data (4D)
mask (array): binary mask for fitting
Returns:
TensorFit: fitted tensor results
"""
class TensorFit:
"""Fitted diffusion tensor results."""
@property
def fa(self):
"""array: fractional anisotropy (0-1)"""
@property
def adc(self):
"""array: apparent diffusion coefficient"""
@property
def md(self):
"""array: mean diffusivity"""
@property
def ad(self):
"""array: axial diffusivity"""
@property
def rd(self):
"""array: radial diffusivity"""
@property
def eigenvals(self):
"""array: tensor eigenvalues"""
@property
def eigenvecs(self):
"""array: tensor eigenvectors"""
def predict(self, gtab=None, S0=1):
"""
Predict signal from fitted tensor.
Parameters:
gtab (GradientTable): gradient table for prediction
S0 (float): baseline signal
Returns:
array: predicted diffusion signal
"""Diffusion Kurtosis Imaging (DKI)
Extended tensor model that captures non-Gaussian diffusion effects through the kurtosis tensor.
class DiffusionKurtosisModel:
"""Diffusion kurtosis imaging model."""
def __init__(self, gtab, fit_method='WLS'):
"""
Initialize DKI model.
Parameters:
gtab (GradientTable): gradient table (requires multiple b-shells)
fit_method (str): fitting method
"""
def fit(self, data, mask=None):
"""
Fit DKI model to data.
Parameters:
data (array): multi-shell diffusion data
mask (array): binary mask
Returns:
DiffusionKurtosisFit: kurtosis fit results
"""
class DiffusionKurtosisFit:
"""Fitted diffusion kurtosis results."""
@property
def mk(self):
"""array: mean kurtosis"""
@property
def ak(self):
"""array: axial kurtosis"""
@property
def rk(self):
"""array: radial kurtosis"""
@property
def kfa(self):
"""array: kurtosis fractional anisotropy"""Constrained Spherical Deconvolution (CSD)
Advanced model for resolving crossing fibers by deconvolving the fiber orientation distribution function.
class ConstrainedSphericalDeconvModel:
"""Constrained spherical deconvolution model."""
def __init__(self, gtab, response, sh_order=8):
"""
Initialize CSD model.
Parameters:
gtab (GradientTable): gradient table
response (tuple): response function (eigenvals, S0)
sh_order (int): spherical harmonics order
"""
def fit(self, data, mask=None):
"""
Fit CSD model to data.
Parameters:
data (array): diffusion data
mask (array): binary mask
Returns:
CsdFit: CSD fit results
"""
def auto_response_ssst(gtab, data, roi_radii=10, fa_thr=0.7):
"""
Automatic single-shell, single-tissue response function estimation.
Parameters:
gtab (GradientTable): gradient table
data (array): diffusion data
roi_radii (int): ROI radius in voxels
fa_thr (float): FA threshold for response estimation
Returns:
tuple: (response, ratio, S0) response function parameters
"""MAP-MRI (Mean Apparent Propagator MRI)
Advanced model using continuous basis functions to represent the diffusion propagator.
class MapmriModel:
"""MAP-MRI reconstruction model."""
def __init__(self, gtab, radial_order=6, laplacian_regularization=True):
"""
Initialize MAP-MRI model.
Parameters:
gtab (GradientTable): gradient table
radial_order (int): radial basis order
laplacian_regularization (bool): use Laplacian regularization
"""
def fit(self, data, mask=None):
"""
Fit MAP-MRI model.
Parameters:
data (array): diffusion data
mask (array): binary mask
Returns:
MapmriFit: MAP-MRI fit results
"""IVIM (Intravoxel Incoherent Motion)
Bi-exponential model separating diffusion and perfusion effects in diffusion MRI.
class IvimModel:
"""IVIM signal model."""
def __init__(self, gtab, split_b=400, bounds=None):
"""
Initialize IVIM model.
Parameters:
gtab (GradientTable): gradient table with low b-values
split_b (float): b-value threshold for bi-exponential fitting
bounds (tuple): parameter bounds for fitting
"""
def fit(self, data, mask=None):
"""
Fit IVIM model.
Parameters:
data (array): diffusion data with low b-values
mask (array): binary mask
Returns:
IvimFit: IVIM fit results
"""
class IvimFit:
"""IVIM fit results."""
@property
def perfusion_fraction(self):
"""array: perfusion fraction (f)"""
@property
def D_star(self):
"""array: pseudo-diffusion coefficient"""
@property
def D(self):
"""array: true diffusion coefficient"""Multi-Shell Multi-Tissue CSD
Extension of CSD for multi-shell data with multiple tissue types.
class MultiShellMultiTissueModel:
"""Multi-shell, multi-tissue CSD model."""
def __init__(self, gtab, response, sh_order=8):
"""
Initialize MSMT-CSD model.
Parameters:
gtab (GradientTable): multi-shell gradient table
response (list): response functions for each tissue type
sh_order (int): spherical harmonics order
"""Usage Examples
# DTI analysis workflow
from dipy.reconst.dti import TensorModel
from dipy.data import read_stanford_hardi
import numpy as np
# Load data
img, gtab = read_stanford_hardi()
data = img.get_fdata()
# Fit tensor model
tenmodel = TensorModel(gtab)
tenfit = tenmodel.fit(data)
# Extract metrics
fa = tenfit.fa
md = tenfit.md
eigenvals = tenfit.eigenvals
print(f"Mean FA: {np.mean(fa[fa > 0]):.3f}")
print(f"Mean MD: {np.mean(md[md > 0]):.6f}")
# CSD for fiber orientation
from dipy.reconst.csdeconv import ConstrainedSphericalDeconvModel, auto_response_ssst
# Estimate response function
response, ratio = auto_response_ssst(gtab, data)
# Fit CSD model
csd_model = ConstrainedSphericalDeconvModel(gtab, response)
csd_fit = csd_model.fit(data)
# IVIM analysis
from dipy.reconst.ivim import IvimModel
# For IVIM, need data with low b-values
ivim_model = IvimModel(gtab)
ivim_fit = ivim_model.fit(data)
f = ivim_fit.perfusion_fraction
D = ivim_fit.D
D_star = ivim_fit.D_starInstall with Tessl CLI
npx tessl i tessl/pypi-dipy