nifreeze.testing.simulations module

Utilities for testing purposes.

nifreeze.testing.simulations.BOUNDS_2FIBERS_DOMINANT_VF1: tuple[float, float] = (0.1, 0.3)

Bounds for two-fiber \(\lambda_1\) volume fraction in the dominant configuration.

nifreeze.testing.simulations.BOUNDS_2FIBERS_NONDOMINANT_VF1: tuple[float, float] = (0.3, 0.7)

Bounds for two-fiber \(\lambda_1\) volume fraction in the non-dominant configuration.

nifreeze.testing.simulations.BOUNDS_3FIBERS_VF1: tuple[float, float] = (0.25, 0.3)

Bounds for three-fiber \(\lambda_1\) volume fraction.

nifreeze.testing.simulations.BOUNDS_3FIBERS_VF2: tuple[float, float] = (0.3, 0.35)

Bounds for three-fiber \(\lambda_2\) volume fraction.

nifreeze.testing.simulations.BOUNDS_LAMBDA1: tuple[float, float] = (0.0014, 0.0018)

Bounds for single-fiber \(\lambda_1\) volume fraction parameter.

nifreeze.testing.simulations.BOUNDS_LAMBDA23: tuple[float, float] = (0.0001, 0.0005)

Bounds for single-fiber \(\lambda_{2}\) and \(\lambda_{3}\) volume fraction parameters.

nifreeze.testing.simulations.add_b0(bvals: ndarray, bvecs: ndarray) → tuple[ndarray, ndarray]

Insert a b=0 at the front of the gradient table (b-values and b-vectors).

Parameters:

• bvals (ndarray) – Array of b-values.

• bvecs (ndarray) – Array of b-vectors.

Returns:

Updated gradient table (b-values, b-vectors) including a b=0.

Return type:

tuple

nifreeze.testing.simulations.compute_pet_noise_sd(scale_factor: float, c: ndarray, delta: ndarray, lambda_: float, t: ndarray) → ndarray

Compute PET signal noise standard deviation (SD).

Computes standard deviation values to be added to normally distributed noise in PET simulations following equation 7 in [1].

Parameters:

• scale_factor (float) – Scale factor controlling the level of noise.

• c (ndarray) – Noise-free simulated radioactivity at each time point.

• delta (ndarray) – Frame duration in seconds.

• lambda_ (float) – Radioisotope decay constant.

• t (obj:~numpy.ndarray) – Time at which the noise is to be generated.

Returns:

obj – The computed SD value.

Return type:

~numpy.ndarray

References

[1]

Masanori Ichise, Jeih-San Liow, Jian-Qiang Lu, Akihiro Takano, Kendra Model, Hiroshi Toyama, Tetsuya Suhara, Kazutoshi Suzuki, Robert B. Innis, and Richard E. Carson. Linearized reference tissue parametric imaging methods: application to [11c]dasb positron emission tomography studies of the serotonin transporter in human brain. Journal of Cerebral Blood Flow & Metabolism, 23(9):1096–1112, 2003. URL: https://doi.org/10.1097/01.WCB.0000085441.37552.CA, doi:10.1097/01.WCB.0000085441.37552.CA.

nifreeze.testing.simulations.create_diffusion_encoding_gradient_dirs(hsph_dirs: int, iterations: int = 5000, seed: int = 1234) → dipy.core.sphere.Sphere

Create the dMRI gradient-encoding directions.

Parameters:

• hsph_dirs (int) – Number of hemisphere directions.

• iterations (int, optional) – Number of iterations for charge dispersion.

• seed (int, optional) – Seed for the random number generator.

Returns:

A sphere with diffusion-encoding gradient directions.

Return type:

Sphere

nifreeze.testing.simulations.create_random_diffusivity_eigenvalues(size, rng)

Create DTI model diffusion tensor eigenvalues (\(\lambda_{1}, \lambda_{2}, \lambda_{3}\)) drawn from a uniform distribution.

It is assumed that \(\lambda_{2} = \lambda_{3}\) following [2].

References

[2] (1,2,3,4)

Erick Jorge Canales-Rodríguez, Jon Haitz Legarreta, Marco Pizzolato, Gaëtan Rensonnet, Gabriel Girard, Jonathan Rafael Patiño, Muhamed Barakovic, David Romascano, Yasser Alemán-Gómez, Joaquim Radua, Edith Pomarol-Clotet, Raymond Salvador, Jean-Philippe Thiran, and Alessandro Daducci. Sparse wars: a survey and comparative study of spherical deconvolution algorithms for diffusion MRI. NeuroImage, 184():140–160, 01 2019. URL: https://www.sciencedirect.com/science/article/abs/pii/S1053811918307699, doi:10.1016/j.neuroimage.2018.08.071.

nifreeze.testing.simulations.create_random_polar_angles(size, rng)

Create polar angles drawn from a uniform distribution.

nifreeze.testing.simulations.create_random_polar_coordinates(hsph_dirs: int, seed: int = 1234) → tuple[ndarray, ndarray]

Create random polar coordinates.

Parameters:

• hsph_dirs (int) – Number of hemisphere directions.

• seed (int, optional) – Seed for the random number generator.

Returns:

Theta and Phi values of polar coordinates.

Return type:

tuple

nifreeze.testing.simulations.create_single_fiber_evecs(theta: float = 0, phi: float = 0) → ndarray

Create eigenvectors for a simulated fiber given the polar coordinates of its principal axis.

Parameters:

• theta (float) – Theta coordinate

• phi (float) – Phi coordinate

Returns:

Eigenvectors for a single fiber.

Return type:

ndarray

nifreeze.testing.simulations.create_single_shell_gradient_table(hsph_dirs: int, bval_shell: float, iterations: int = 5000) → dipy.core.gradients.GradientTable

Create a single-shell gradient table.

Parameters:

• hsph_dirs (int) – Number of hemisphere directions.

• bval_shell (float) – Shell b-value.

• iterations (int, optional) – Number of iterations for charge dispersion.

Returns:

The gradient table for the single-shell.

Return type:

GradientTable

nifreeze.testing.simulations.create_three_fiber_random_volume_fractions(size, rng)

Create fiber volume fractions drawn from a uniform distribution for a three-fiber configuration.

Volume fractions are assumed to be:

\begin{align*} f1 &\sim U(0.25, 0.3) \\ f2 &\sim U(0.3, 0.35) \\ f3 &= 1 - (f1 + f2) \end{align*}

following [2].

References

nifreeze.testing.simulations.create_two_fiber_dominant_random_volume_fractions(size, rng)

Create fiber volume fractions drawn from a uniform distribution for a two-fiber configuration with a dominant fiber.

Volume fractions are assumed to be:

\begin{align*} f1 &\sim U(0.1, 0.3) \\ f2 &= 1 - f1 \end{align*}

following [2].

References

nifreeze.testing.simulations.create_two_fiber_nondominant_random_volume_fractions(size, rng)

Create fiber volume fractions drawn from a uniform distribution for a two-fiber configuration with non-dominant fibers.

Volume fractions are assumed to be:

\begin{align*} f1 &\sim U(0.3, 0.7) \\ f2 &= 1 - f1 \end{align*}

following [2].

References

nifreeze.testing.simulations.get_query_vectors(gtab: dipy.core.gradients.GradientTable, train_mask: ndarray) → tuple[ndarray, ndarray]

Get the diffusion-encoding gradient vectors for estimation from the gradient table.

Get the diffusion-encoding gradient vectors where the signal is to be estimated from the gradient table and the training mask: the vectors of interest are those that are masked in the training mask. b0 values are excluded.

Parameters:

• gtab (GradientTable) – Gradient table.

• train_mask (ndarray) – Mask for selecting training vectors.

Returns:

Gradient vectors and indices for estimation.

Return type:

tuple

nifreeze.testing.simulations.group_values(values, group_size)

nifreeze.testing.simulations.serialize_dmri(dwi_data, gtab, dwi_data_fname, bval_data_fname, bvec_data_fname, affine: ndarray | None = None)

Serialize dMRI data.

Parameters:

• dwi_data (ndarray) – DWI data.

• gtab (gradient_table) – Gradient table.

• dwi_data_fname (str) – Filename of NIfTI file to save the DWI signal.

• bval_data_fname (str) – Filename of NIfTI file to save the diffusion-encoding gradient b-vals.

• bvec_data_fname (str) – Filename of NIfTI file to save the diffusion-encoding gradient b-vecs.

• affine (ndarray, optional) – Affine matrix. If None an identity affine matrix is used.

nifreeze.testing.simulations.serialize_dwi(dwi_data, dwi_data_fname, affine: ndarray | None = None)

Serialize DWI data.

Parameters:

• dwi_data (ndarray) – DWI data.

• dwi_data_fname (str) – Filename of NIfTI file to save the DWI signal.

• affine (ndarray, optional) – Affine matrix. If None an identity affine matrix is used.

nifreeze.testing.simulations.serialize_gtab(gtab, bval_data_fname, bvec_data_fname)

Serialize dMRI gradient-encoding table data into a pair of b-vals and b-vecs files.

Parameters:

• gtab (gradient_table) – Gradient table.

• bval_data_fname (str) – Filename of NIfTI file to save the diffusion-encoding gradient b-vals.

• bvec_data_fname (str) – Filename of NIfTI file to save the diffusion-encoding gradient b-vecs.

nifreeze.testing.simulations.simulate_multifiber_voxels(S0, hsph_dirs, bval_shell=1000, snr=20, n_voxels=1, seed=None)

Create a DWI signal with multiple tensors.

nifreeze.testing.simulations.simulate_one_fiber_multivoxel(gtab, S0, snr, n_voxels, rng, evals=None)

Create a single-fiber multi-voxel DWI signal.

nifreeze.testing.simulations.simulate_three_fiber_multivoxel(gtab, S0, snr, n_voxels, rng)

Create three-fiber multi-voxel DWI signal.

nifreeze.testing.simulations.simulate_two_fiber_multivoxel(gtab, S0, snr, n_voxels, rng, dominant)

Create two-fiber multi-voxel DWI signal.

nifreeze.testing.simulations.simulate_voxels(S0, hsph_dirs, bval_shell=1000, snr=20, n_voxels=1, evals=None, seed=None)

nifreeze.testing.simulations.single_fiber_voxel(gtab, S0, evals, rng, theta=0, phi=0, snr=20)

nifreeze.testing.simulations.srtm(x: ndarray, t: ndarray, cr: ndarray, cri: ndarray, dt: ndarray, nr: int) → tuple[ndarray, ndarray]

Simplified Reference Tissue Model (SRTM) simulation with partial derivatives.

SRTM estimates brain receptor binding potentials useful in PET simulation studies.

The model was proposed in [3], and this implementation is based on [4].

Parameters:

• x (ndarray, shape (3,)) – Model parameters: [R1, k2, BP]

• t (ndarray, shape (nr,)) – Mid-times (kept for API parity; not used directly in the original code)

• cr (ndarray, shape (nr,)) – Reference region TAC

• cri (ndarray, shape (nr,)) – Integral of reference TAC over frames (must match what MATLAB ‘cri’ represents)

• dt (ndarray, shape (nr,)) – Frame durations / time steps used by the solver

• nr (int) – Number of time points (should equal len(cr))

Returns:

• CT (ndarray, shape (nr,)) – Simulated tissue TAC

• DT (ndarray, shape (nr, 3)) – Partial derivatives [dCT/dR1, dCT/dk2, dCT/dBP] as columns

Notes

This code is translation from the simSRTM_1_0_0.m MATLAB script available on GitHub and the Human Emotion Systems Laboratory of the Turku PET Centre GitLab

A description of the model is also available at the Turku PET Centre website

References

[3]

Adriaan A. Lammertsma and Susan P. Hume. Simplified reference tissue model for pet receptor studies. NeuroImage, 4(3):153–158, 12 1996. URL: https://www.sciencedirect.com/science/article/pii/S105381199690066X, doi:https://doi.org/10.1006/nimg.1996.0066.

[4]

Tomi Karjalainen, Jouni Tuisku, Severi Santavirta, Tatu Kantonen, Marco Bucci, Lauri Tuominen, Jussi Hirvonen, Jarmo Hietala, Juha O. Rinne, and Lauri Nummenmaa. Magia: robust automated image processing and kinetic modeling toolbox for pet neuroinformatics. Frontiers in Neuroinformatics, 02 2020. URL: https://www.frontiersin.org/journals/neuroinformatics/articles/10.3389/fninf.2020.00003, doi:10.3389/fninf.2020.00003.