Simulation

The package provides functions for simulations related IVIM, specifically

  • Simulation of noisy data given IVIM parameters (API)

  • Particle velocities according to the Langevin equation (API)

API

ivim.sim.noise(D_file: str, f_file: str, regime: str, bval_file: str, noise_sigma: float, outbase: str, S0_file: str | None = None, K_file: str | None = None, Dstar_file: str | None = None, v_file: str | None = None, cval_file: str | None = None, tau_file: str | None = None, delta_file: str | None = None, Delta_file: str | None = None, T_file: str | None = None, seq: str = 'monopolar', k_file: str | None = None)

Generate noisy data for the IVIM model at a given regime and noise level based on IVIM parameter maps.

Parameters:

  • D_file – path to nifti file with diffusion coefficients

  • f_file – path to nifti file with perfusion fractions

  • regime – IVIM regime to model: no (= sIVIM), diffusive (long encoding time) or ballistic (short encoding time)

  • bval_file – path to .bval file

  • noise_sigma – standard deviation of the noise at b = 0

  • outbase – string used to set the file path to out, e.g. ‘/folder/out’ gives ‘/folder/out.nii.gz’ etc.

  • S0_file – (optional) path to nifti file with signal at b = 0, if None S0 = 1

  • K_file – (optional) path to nifti file with kurtosis coefficients

  • Dstar_file – (optional) path to nifti file with pseudo diffusion coefficients

  • v_file – (optional) path to nifti file with velocities

  • cval_file – (optional) path to .cval file

  • tau_file – (optional) path to nifti file with correlation times

  • delta_file – (optional) path to .delta file

  • Delta_file – (optional) path to .Delta file

  • T_file – (optional) path to .T file

  • seq – (optional) pulse sequence used (monopolar or bipolar)

  • k_file – (optional) path to .k file

ivim.sim.langevin(sigma_v: float, tau: float, dt: float, m: int, n: int = 100) → ndarray[Any, dtype[float64]]

Simulation of random walks (velocities) in 3D according to the Langevin equation:

\[dv = -vdt/\tau + \sqrt{2\sigma^2_v/\tau}d\xi\]

where dv is the velocity increment occuring in the time dt, v is the current velocity, tau is the correlation time, \(\sigma_v\) is the standard deviation of velocities and \(d\xi\) is a Wiener process with autocorrelation \(\langle d\xi(t)d\xi(t')\rangle = \delta(t-t')dt\).

Parameters:

  • sigma_v – standard deviation of the velocities

  • tau – correlation time

  • dt – time step (should be substantially smaller than tau)

  • m – number of time steps

  • n – (optional) number of random walkers

Output:

v: velocities of the walkers (nxmx3 array)

Examples:

>>> sigma_v, tau, dt, m = 2, 100e-3, 1e-3, 1e3
>>> v = langevin(sigma_v, tau, dt, m, n = 100)