src.wrappers package

Submodules

src.wrappers.OsipiBase module

class src.wrappers.OsipiBase.OsipiBase(bvalues=None, thresholds=None, bounds=None, initial_guess=None, algorithm=None, **kwargs)

Bases: object

Comprehensive base class for OSIPI IVIM fitting algorithms.

The OsipiBase class defines a standardized framework for fitting intravoxel incoherent motion (IVIM) models to diffusion-weighted MRI data. It manages common attributes such as b-values, parameter bounds, thresholds, and initial guesses; provides requirement-checking utilities; and offers convenience methods for voxel-wise or full-volume fitting. Subclasses can implement algorithm-specific behavior while inheriting these shared tools.

Parameters

bvaluesarray-like, optional

Diffusion b-values (s/mm²) matching the last dimension of the input data.

thresholdsarray-like, optional

Thresholds used by specific algorithms (e.g., signal cutoffs).

boundsarray-like, optional

Parameter bounds for constrained optimization.

initial_guessarray-like, optional

Initial parameter estimates for the IVIM fit.

algorithmstr, optional

Name of an algorithm module in src/standardized to load dynamically. If supplied, the instance is immediately converted to that algorithm’s subclass via osipi_initiate_algorithm().

**kwargs

Additional keyword arguments forwarded to the selected algorithm’s initializer if algorithm is provided.

Attributes

bvalues, thresholds, bounds, initial_guessnp.ndarray or None

Core fitting inputs stored as arrays when provided.

use_bounds, use_initial_guessbool

Flags controlling whether bounds and initial guesses are applied.

deep_learning, supervised, stochasticbool

Indicators for the algorithm type; subclasses may set these.

result_keyslist of str, optional

Names of the output parameters (e.g., [“f”, “Dp”, “D”]).

required_bvalues, required_thresholds, required_bounds, required_bounds_optional, required_initial_guess, required_initial_guess_optional : various, optional

Optional attributes used by requirement-checking helpers.

Key Methods

osipi_initiate_algorithm(algorithm, **kwargs)

Dynamically replace the current instance with the specified algorithm subclass.

osipi_fit(data, bvalues=None, njobs=1, **kwargs)

Voxel-wise IVIM fitting with optional parallel processing and automatic signal normalization.

osipi_fit_full_volume(data, bvalues=None, **kwargs)

Full-volume fitting for algorithms that support it.

osipi_print_requirements()

Display algorithm requirements such as needed b-values or bounds.

osipi_accepted_dimensions(), osipi_accepts_dimension(dim)

Query acceptable input dimensionalities.

osipi_check_required_*()

Validate that provided inputs meet algorithm requirements.

osipi_simple_bias_and_RMSE_test(SNR, bvalues, f, Dstar, D, noise_realizations)

Monte-Carlo bias/RMSE evaluation of the current fitting method.

D_and_Ds_swap(results)

Ensure consistency of D and D* estimates by swapping if necessary.

Notes

• This class is typically used as a base or as a dynamic loader for a specific algorithm implementation.

• Parallel voxel-wise fitting uses joblib.

• Subclasses must implement algorithm-specific methods such as ivim_fit() or ivim_fit_full_volume().

Examples

# Dynamic algorithm loading model = OsipiBase(bvalues=[0, 50, 200, 800],

algorithm=”MyAlgorithm”)

# Voxel-wise fitting results = base.osipi_fit(dwi_data, njobs=4) f_map = results[“f”]

D_and_Ds_swap(results)

initialize()

Placeholder for subclass initialization

osipi_accepted_dimensions()

The array of accepted dimensions e.g. (1D, 2D, 3D, 4D, 5D, 6D) (True, True, False, False, False, False)

osipi_accepts_dimension(dim)

Query if the selection dimension is fittable

osipi_author()

Author identification

osipi_check_required_bounds()

Checks if input bounds fulfil the algorithm requirements

osipi_check_required_bvalues()

Minimum number of b-values required

osipi_check_required_initial_guess()

Checks if input initial guess fulfil the algorithm requirements

osipi_check_required_thresholds()

Checks if the number of input thresholds fulfil the algorithm requirements

osipi_fit(data, bvalues=None, njobs=1, **kwargs)

Fit multi-b-value diffusion MRI data using the IVIM model.

This function normalizes the input signal to the minimum b-value and fits each voxel’s signal to the IVIM model to estimate parameters such as perfusion fraction (f), pseudo-diffusion coefficient (D*), and tissue diffusion coefficient (D). Fits can be computed in parallel across voxels using multiple jobs.

Parameters

datanp.ndarray

Multi-dimensional array containing the signal intensities. The last dimension must correspond to the b-values (diffusion weightings).

bvaluesarray-like, optional

Array of b-values corresponding to the last dimension of data. If not provided, the method uses self.bvalues set during object initialization.

njobsint, optional, default=1

Number of parallel jobs to use for voxel-wise fitting. If njobs > 1, the fitting will be distributed across multiple processes. -1 will use all available cpus

**kwargsdict, optional

Additional keyword arguments to be passed to the underlying ivim_fit function.

Returns

resultsdict of np.ndarray

Dictionary containing voxel-wise parameter maps. Keys are parameter names (“f”, “D”, “Dp”), and values are arrays with the same shape as data excluding the last dimension.

Notes

• The signal is normalized to the minimum b-value before fitting.

• Handles NaN values by returning zeros for all parameters in those voxels.

• Parallelization is handled using joblib’s Parallel and delayed.

• If self.result_keys is defined, it determines the output parameter names; otherwise, the default keys are [“f”, “Dp”, “D”].

• The method swaps D and D* values after fitting using self.D_and_Ds_swap to maintain consistency.

Example

>>> results = instance.osipi_fit(data, bvalues=[0, 50, 200, 800], njobs=4)
>>> f_map = results['f']
>>> D_map = results['D']

osipi_fit_full_volume(data, bvalues=None, **kwargs)

Fit an entire volume of multi-b-value diffusion MRI data in a single call using the IVIM model.

Unlike osipi_fit, which processes one voxel at a time, this method sends the full volume to the fitting algorithm. This can be more efficient for algorithms that support full-volume fitting.

Parameters

datanp.ndarray

2D (data x b-values), 3D (single slice), or 4D (multi-slice) diffusion-weighted imaging (DWI) data. The last dimension must correspond to the b-values.

bvaluesarray-like, optional

Array of b-values corresponding to the last dimension of data. If not provided, the method uses self.bvalues set during object initialization.

**kwargsdict, optional

Additional keyword arguments to be passed to ivim_fit_full_volume.

Returns

resultsdict of np.ndarray or bool

Dictionary containing parametric maps for each IVIM parameter (keys from self.result_keys, or defaults [“f”, “Dp”, “D”]). Each value is an array matching the spatial dimensions of data. Returns False if full-volume fitting is not supported by the algorithm.

Notes

• This method does not normalize the input signal to the minimum b-value, unlike osipi_fit.

Example

# Standard usage: results = instance.osipi_fit_full_volume(data, bvalues=[0, 50, 200, 800]) f_map = results[‘f’] D_map = results[‘D’] Dp_map = results[‘Dp’]

# If the algorithm does not support full-volume fitting: results = instance.osipi_fit_full_volume(data) if results is False:

print(“Full-volume fitting not supported.”)

osipi_initiate_algorithm(algorithm, **kwargs)

Turns the class into a specified one by the input. This method can be used instead of specifically importing that class and initiating it.

WIP: Add args and kwargs!

Args:

algorithm (string): The name of the algorithm, should be the same as the file in the src/standardized folder without the .py extension.

osipi_print_requirements()

Prints the requirements of the algorithm. Attributes that are currently checked for are: required_bvalues (int):

The lowest number of b-values required.

required_thresholds (array-like)

1D array-like of two ints [least number of b-value thresholds, most number of b-value_thresholds].

required_bounds (bool):

Whether bounds are required or not.

required_bounds_optional (bool):

Whether bounds are optional or not

required_initial_guess (bool):

Whether an initial guess is required or not.

required_initial_guess_optional (bool):

Whether an initial guess is optional or not.

osipi_simple_bias_and_RMSE_test(SNR, bvalues, f, Dstar, D, noise_realizations=100)

src.wrappers.ivim_fit module

src.wrappers.ivim_fit.ivim_fit(authors=None, signals=None, bvalues=None, data=None, initial_guess=None, bounds=None)

wrapper function to use OSIPI code contributions for IVIM fit :param author: str, can be one of [] :param signals: numpy array containing signal intensities :param bvalues: numpy array containing corresponding b-values :param data: object containing signals and bvalues :param initial_guess: list of initial parameter estimates :param bounds: list containing list of lower parameter bounds and list of upper parameter bounds :return: numpy array of shape (signals.size, 4) with the D, Dp, f, S0 per voxel.

Module contents