Reference#

disimpy.gradients#

This module contains code for creating and manipulating gradient arrays.

Gradient arrays are numpy.ndarray instances with shape (number of measurements, number of time points, 3). Gradient array elements are floats representing the gradient magnitude in SI units (T/m).

disimpy.gradients.calc_b(gradient, dt)#

Calculate b-values of the gradient array.

Parameters:

  • gradient (numpy.ndarray) – Gradient array with shape (n of measurements, n of time points, 3).

  • dt (float) – Duration of a time step in gradient array.

Returns:

b – b-values.

Return type:

numpy.ndarray

disimpy.gradients.calc_q(gradient, dt)#

Calculate the q-vector array corresponding to the gradient array.

Parameters:

  • gradient (numpy.ndarray) – Gradient array with shape (n of measurements, n of time points, 3).

  • dt (float) – Duration of a time step in the gradient array.

Returns:

q – q-vector array.

Return type:

numpy.ndarray

disimpy.gradients.interpolate_gradient(gradient, dt, n_t)#

Interpolate the gradient array to have n_t time points.

Parameters:

  • gradient (numpy.ndarray) – Gradient array with shape (n of measurements, n of time points, 3).

  • dt (float) – Duration of a time step in the gradient array.

  • n_t (int) – The number of time points in the gradient array after interpolation.

Returns:

  • interp_g (numpy.ndarray) – Interpolated gradient array.

  • dt (float) – Duration of a time step in the interpolated gradient array.

disimpy.gradients.load_camino_scheme_file(path)#

Generate a gradient array from a Camino general waveform scheme file. All waveforms must have the same number of steps and the same time step duration. For details, see http://camino.cs.ucl.ac.uk/index.php?n=Tutorials.GenwaveTutorial.

Parameters:

path (str) – Path to the Camino scheme file.

Returns:

  • gradient (numpy.ndarray) – Gradient array.

  • dt (float) – Duration of a time step in the gradient array.

disimpy.gradients.pgse(delta, DELTA, n_t, bvals, bvecs)#

Generate a pulsed gradient spin echo gradient array.

Parameters:

  • delta (float) – Diffusion encoding time.

  • DELTA (float) – Diffusion time.

  • n_t (int) – The number of time points in the generated gradient array.

  • bvals (float or numpy.ndarray) – b-value or an array of b-values.

  • bvecs (numpy.ndarray) – b-vector or array of b-vectors.

Returns:

  • gradient (numpy.ndarray) – Gradient array.

  • dt (float) – Duration of a time step in the gradient array.

disimpy.gradients.rotate_gradient(gradient, Rs)#

Rotate the gradient array of each measurement according to the corresponding rotation matrix.

Parameters:

  • gradient (numpy.ndarray) – Gradient array with shape (n of measurements, n of time points, 3).

  • Rs (numpy.ndarray) – Rotation matrix array with shape (n of measurements, 3, 3).

Returns:

g – Rotated gradient array.

Return type:

numpy.ndarray

disimpy.gradients.set_b(gradient, dt, b)#

Scale the gradient array magnitude to correspond to given b-values.

Parameters:

  • gradient (numpy.ndarray) – Gradient array with shape (n of measurements, n of time points, 3).

  • dt (float) – Duration of a time step in gradient array.

  • b (float or numpy.ndarray) – b-value or an array of b-values with length equal to n of measurements.

Returns:

scaled_g – Scaled gradient array.

Return type:

numpy.ndarray

disimpy.simulations#

This module contains code for running diffusion-weighted MR simulations.

disimpy.simulations.add_noise_to_data(data, sigma, seed=None)#

Add Rician noise to data.

Parameters:

  • data (numpy.ndarray) – Array containing the data.

  • sigma (float) – Standard deviation of noise in each channel.

  • seed (int, optional) – Seed for pseudorandom number generation.

Returns:

noisy_data – Noisy data.

Return type:

numpy.ndarray

disimpy.simulations.simulation(n_walkers, diffusivity, gradient, dt, substrate, seed=123, traj=None, final_pos=False, all_signals=False, quiet=False, cuda_bs=128, max_iter=1000, epsilon=1e-13)#

Simulate a diffusion-weighted MR experiment and generate signal. For a detailed tutorial, please see https://disimpy.readthedocs.io/en/latest/tutorial.html.

Parameters:

  • n_walkers (int) – Number of random walkers.

  • diffusivity (float) – Diffusivity in SI units (m^2/s).

  • gradient (numpy.ndarray) – Floating-point array of shape (number of measurements, number of time points, 3). Array elements represent the gradient magnitude at a time point along an axis in SI units (T/m).

  • dt (float) – Duration of a time step in the gradient array in SI units (s).

  • substrate (disimpy.substrates._Substrate) – Substrate object containing information about the simulated microstructure.

  • seed (int, optional) – Seed for pseudorandom number generation.

  • traj (str, optional) – Path of a file in which to save the simulated random walker trajectories. The file can become very large! Every line represents a time point. Every line contains the positions as follows: walker_1_x walker_1_y walker_1_z walker_2_x walker_2_y walker_2_z…

  • final_pos (bool, optional) – If True, the signal and the final positions of the random walkers are returned as a tuple.

  • all_signals (bool, optional) – If True, the signal from each random walker is returned instead of the total signal.

  • quiet (bool, optional) – If True, updates on the progress of the simulation are not printed.

  • cuda_bs (int, optional) – The size of the one-dimensional CUDA thread block.

  • max_iter (int, optional) – The maximum number of iterations allowed in the algorithm that checks if a random walker collides with a surface during a time step.

  • epsilon (float, optional) – The amount by which a random walker is moved away from the surface after a collision to avoid placing it in the surface.

Returns:

signal – Simulated signals.

Return type:

numpy.ndarray

disimpy.substrates#

This module contains code for creating substrate objects.

Substrate objects are used for storing information about the simulated microstructure.

disimpy.substrates.cylinder(radius, orientation)#

Return a substrate object for simulating diffusion in an infinite cylinder.

Parameters:

  • radius (float) – Radius of the cylinder.

  • orientation (numpy.ndarray) – Floating-point arrray with shape (3,) defining the orientation of the cylinder.

Returns:

substrate – Substrate object.

Return type:

disimpy.substrates._Substrate

disimpy.substrates.ellipsoid(semiaxes, R=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]))#

Return a substrate object for simulating diffusion in an ellipsoid.

Parameters:

  • semiaxes (numpy.ndarray) – Floating-point array with shape (3,) containing the semiaxes of the axis-aligned ellipsoid.

  • R (numpy.ndarray, optional) – Floating-point array with shape (3, 3) containing the rotation matrix that is applied to the axis-aligned ellipsoid before the simulation.

Returns:

substrate – Substrate object.

Return type:

disimpy.substrates._Substrate

disimpy.substrates.free()#

Return a substrate object for simulating free diffusion.

Returns:

substrate

Return type:

disimpy.substrates._Substrate

disimpy.substrates.mesh(vertices, faces, periodic, padding=array([0., 0., 0.]), init_pos='uniform', n_sv=array([50, 50, 50]), quiet=False, perm_prob=0)#

Return a substrate object for simulating diffusion restricted by a triangular mesh. The size of the simulated voxel is equal to the axis- aligned bounding box of the triangles plus padding. The triangles are shifted so that the lower corner of the simulated voxel is at the origin.

Parameters:

  • vertices (numpy.ndarray) – Floating-point array with shape (number of vertices, 3) containing the vertices of the triangular mesh.

  • faces (numpy ndarray) – Integer array with shape (number of triangles, 3) containing the vertex indices of the points of the triangles.

  • periodic (bool, optional) – If True, periodic boundary conditions are used, i.e., the random walkers leaving the simulated voxel encounter infinitely repeating copies of the simulated voxel. If False, the boundaries of the simulated voxel are an impermeable surface.

  • padding (np.ndarray, optional) – Floating-point array with shape (3,) defining how much empty space there is between the axis-aligned bounding box of the triangles and the boundaries of the simulated voxel on both sides along each axis.

  • init_pos (numpy.ndarray or str, optional) – Floating-point array with shape (number of random walkers, 3) defining the initial position of the random walkers within the simulated voxel or one of the following strings: ‘uniform’, ‘intra’, or ‘extra’. If ‘uniform’, the initial positions are sampled from a uniform distribution over the simulated voxel. If ‘intra’, the initial positions are sampled from a uniform distribution inside the surface defined by the triangular mesh. If ‘extra’, the initial positions are sampled from a uniform distribution over the simulated voxel excluding the volume inside the surface defined by the triangular mesh. Note that the triangles must define a closed surface if ‘intra’ or ‘extra’ is used.

  • n_sv (np.ndarray, optional) – Integer array with shape (3,) controlling the number of subvoxels into which the simulated voxel is divided to accelerate the collision check algorithm.

  • quiet (bool, optional) – If True, updates on computation progress are not printed.

  • perm_prob (float, optional) – Probability that a spin passes through a triangle.

Returns:

substrate – Substrate object.

Return type:

disimpy.substrates._Substrate

disimpy.substrates.sphere(radius)#

Return a substrate object for simulating diffusion in a sphere.

Parameters:

radius (float) – Radius of the sphere.

Returns:

substrate

Return type:

disimpy.substrates._Substrate

disimpy.utils#

This module contains general useful functions.

disimpy.utils.show_mesh(substrate, seed=123)#

Visualize a triangular mesh with random triangle colours.

Parameters:

  • substrate (disimpy.substrates._Substrate) – Substrate object containing the triangular mesh.

  • seed (int, optional) – Seed for pseudorandom number generation.

Return type:

None

disimpy.utils.show_traj(traj_file)#

Plot walker trajectories saved in a trajectories file.

Parameters:

traj_file (str) – Path of a trajectories file where every line represents a time point and every line contains the positions as follows: walker_1_x walker_1_y walker_1_z walker_2_x walker_2_y walker_2_z…

Return type:

None

disimpy.utils.vec2vec_rotmat(v, k)#

Return a rotation matrix defining a rotation that aligns v with k.

Parameters:

  • v (numpy.ndarray) – 1D array with length 3.

  • k (numpy.ndarray) – 1D array with length 3.

Returns:

R – 3 by 3 rotation matrix.

Return type:

numpy.ndarray