estimators

estimators ¶

IVIM parameter estimation algorithms.

This module implements various fitting strategies for IVIM parameters, including segmented fitting and full bi-exponential fitting.

Output parameter maps: - D: diffusion coefficient in mm^2/s - D*: pseudo-diffusion coefficient in mm^2/s - f: perfusion fraction, dimensionless

GPU/CPU agnostic using the xp array module pattern. Uses the shared LevenbergMarquardtFitter via BoundIVIMModel binding.

References

.. [1] Federau C et al. (2012). Quantitative measurement of brain perfusion with intravoxel incoherent motion MR imaging. Radiology 265(3):874-881. .. [2] Lemke A et al. (2011). Toward an optimal distribution of b values for intravoxel incoherent motion imaging. Magn Reson Imaging 29(6):766-776. .. [3] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [4] Dickie BR et al. MRM 2024. doi:10.1002/mrm.30101

FittingMethod ¶

Bases: Enum

IVIM fitting methods.

IVIMFitParams `dataclass` ¶

IVIMFitParams(
    method=SEGMENTED,
    b_threshold=200.0,
    max_iterations=500,
    tolerance=1e-06,
    bounds=None,
    bayesian_params=None,
)

Parameters for IVIM fitting.

ATTRIBUTE	DESCRIPTION
`method`	Fitting method to use. TYPE: `FittingMethod`
`b_threshold`	b-value threshold for segmented fitting (s/mm²). b-values above this are used for D estimation. TYPE: `float`
`max_iterations`	Maximum iterations for optimization. TYPE: `int`
`tolerance`	Convergence tolerance. TYPE: `float`
`bounds`	Custom parameter bounds. TYPE: `dict \| None`
`bayesian_params`	Bayesian-specific parameters (prior_std, noise_std, compute_uncertainty). Only used when `method` is `FittingMethod.BAYESIAN`. TYPE: `dict \| None`

IVIMFitResult `dataclass` ¶

IVIMFitResult(
    d_map,
    d_star_map,
    f_map,
    s0_map,
    quality_mask,
    r_squared=None,
    fitting_stats=dict(),
)

Result of IVIM fitting.

ATTRIBUTE	DESCRIPTION
`d_map`	Diffusion coefficient (D) map in mm^2/s. TYPE: `ParameterMap`
`d_star_map`	Pseudo-diffusion coefficient (D) map in mm^2/s. TYPE:* `ParameterMap`
`f_map`	Perfusion fraction (f) map, dimensionless. TYPE: `ParameterMap`
`s0_map`	S0 (b=0 signal) map in arbitrary units. TYPE: `ParameterMap`
`quality_mask`	Mask of successfully fitted voxels. TYPE: `NDArray[bool_]`
`r_squared`	Goodness of fit (R^2) map. TYPE: `NDArray[floating] \| None`
`fitting_stats`	Fitting statistics. TYPE: `dict[str, Any]`

fit_ivim ¶

fit_ivim(
    signal,
    b_values,
    mask=None,
    params=None,
    method=None,
    progress_callback=None,
)

Fit IVIM model to DWI data.

PARAMETER	DESCRIPTION
`signal`	DWI signal data, shape (..., n_b_values). Last dimension corresponds to b-values. TYPE: `NDArray[floating]`
`b_values`	b-values in s/mm². TYPE: `NDArray[floating]`
`mask`	Brain/tissue mask. TYPE: `NDArray[bool_] \| None` DEFAULT: `None`
`params`	Fitting parameters. TYPE: `IVIMFitParams \| None` DEFAULT: `None`
`method`	Fitting method. If provided, overrides params.method. TYPE: `FittingMethod \| None` DEFAULT: `None`
`progress_callback`	Progress callback function. TYPE: `Callable[[float], None] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`IVIMFitResult`	Fitted parameter maps.

Examples:

>>> import numpy as np
>>> from osipy.ivim import fit_ivim
>>> signal = np.random.rand(64, 64, 10, 8) * 1000
>>> b_values = np.array([0, 10, 20, 50, 100, 200, 400, 800])
>>> result = fit_ivim(signal, b_values)