asldro.utils package

Submodules

asldro.utils.example_resampling module

asldro.utils.filter_validation module

asldro.utils.general module

General utilities

asldro.utils.general.generate_random_numbers(specification: dict, shape=None, rng=None) → numpy.ndarray

Generates a set of numbers according to the prescribed distributions, returning them as a list

Parameters

  • specification (dict) –

    The distribution to use to generate the parameters:

    • ’gaussian’ - normal distribution with mean and standard deviation

    • ’uniform’ - rectangular distribution with min and max values

    • ’mean’ - mean value of the distribution (gaussian only)

    • ’sd’ - standard deviation of the distribution (gaussian only)

    • ’min’ - minimum value of the distribution (uniform only)

    • ’max’ - maximum value of the distribution (uniform only)

  • shape (int or tuple of ints) – length of the list to return

  • rng ([type], optional) – The random number generator to use, defaults to None

Returns

List of the generated numbers

Return type

list

asldro.utils.general.map_dict(input_dict: Mapping[str, Any], io_map: Mapping[str, str], io_map_optional: bool = False) → Dict[str, str]

Maps a dictionary onto a new dictionary by changing some/all of the keys.

Parameters

  • input_dict – The input dictionary

  • io_map –

    The dictionary used to perform the mapping. All keys and values must be strings. For example:

    {
    "one": "two",
    "three": "four"
}

    will map inputs keys of “one” to “two” AND “three” to “four”.

  • io_map_optional – If this is False, a KeyError will be raised if the keys in the io_map are not found in the input_dict.

Raises

KeyError – if keys required in the mapping are not found in the input_dict

Returns

the remapped dictionary

asldro.utils.general.splitext(path)

The normal os.path.splitext treats path/example.tar.gz as having a filepath of path/example.tar with a .gz extension - this fixes it

asldro.utils.generate_numeric_function module

Functions to generate arrays of mathematical function values

asldro.utils.generate_numeric_function.generate_circular_function_array(func, xx: numpy.ndarray, yy: numpy.ndarray, zz: numpy.ndarray, array_size: int, array_angular_increment: Union[float, int], func_params: dict, array_origin: Union[numpy.ndarray, list, tuple] = 0.0, 0.0, 0.0) → numpy.ndarray

Produces a superposition of the supplied function in a circular array. The circular array’s axis is about the z axis.

Parameters

  • func (function) – The function to use to generate the circular array. This should accept arrays of x, y and z values of the entire domain to generate the function (i.e. 3d), as generated by np.meshgrid. It must also accept the argument ‘’loc’’, which is the origin of the function, and theta, which is the angle in degrees to rotate the function (mathematically) about an axis parallel to z that runs through loc. An example function is generate_point_function().

  • xx (np.ndarray) – Array of x-coordinates, generate by meshgrid. Can be sparse.

  • yy (np.ndarray) – Array of y-coordinates, generate by meshgrid. Can be sparse.

  • zz (np.ndarray) – Array of z-coordinates, generate by meshgrid. Can be sparse.

  • array_size (int) – The number of instances of func in the array.

  • array_angular_increment (Union[float, int]) – The amount, in degrees, to increment the function each step.

  • func_params (dict) –

    A dictionary of function parameters. Must have entries:

    • ’loc’: np.ndarray, list or tuple length 3, \([x_0, y_0, z_0]\) values.

  • array_origin (Union[np.ndarray, list, tuple], optional) – The origin of the circular array, \([x_{a,0}, y_{a,0}, z_{a,0}]\), defaults to (0.0, 0.0, 0.0)

Raises

  • KeyError – If argument func_params does not have an entry ‘loc’.

  • ValueError – If value of func_params[‘loc’] is not a np.ndarray, list or tuple.

  • ValueError – If value of func_params[‘loc’] is not 1D and of lenght 3

Returns

An array, comprising the function output arrayed at each position, normalised so that its maximum value is 1.0

Return type

np.ndarray

asldro.utils.generate_numeric_function.generate_gaussian_function(xx: numpy.ndarray, yy: numpy.ndarray, zz: numpy.ndarray, loc: Union[tuple, list, numpy.ndarray] = numpy.zeros, fwhm: Union[tuple, list, numpy.ndarray] = numpy.ones, theta: float = 0.0) → numpy.ndarray

Generates a 3-dimensional gaussian function. Can be used with generate_circular_function_array().

Parameters

  • xx (np.ndarray) – Array of x-coordinates, generate by meshgrid. Can be sparse.

  • yy (np.ndarray) – Array of y-coordinates, generate by meshgrid. Can be sparse.

  • zz (np.ndarray) – Array of z-coordinates, generate by meshgrid. Can be sparse.

  • loc (Union[tuple, list, np.ndarray], optional) – origin of the gaussian, \([x_0, y_0, z_0]\), defaults to np.zeros((3,))

  • fwhm (Union[tuple, list, np.ndarray], optional) – full-width-half-maximum of the gaussian, \([\text{fwhm}_x, \text{fwhm}_y, \text{fwhm}_z]\), defaults to np.ones((3,))

  • theta (float, optional) – polar rotation of the gaussian (about an axis parallel to z at the gaussian origin), degrees, defaults to 0.0

Raises

  • ValueError – If xx, yy, and zz do not all have shapes that permit broadcasting

  • ValueError – If loc is not 1D and of length 3

  • ValueError – If fwhm is not 1D and of length 3

  • ValueError – If any entry in fwhm is < 0.0

Returns

An array with shape the result of broadcasting xx, yy, and zz, values given by the 3D gaussian function.

Return type

np.ndarray

Equation

The gaussian is generated according to:

\[\begin{split}&f(x,y,z) = e^{-(a(x-x_0)^2+ 2b(x-x_0)(y-y_0)+c(y-y_0)^2+d(z-z_0)^2)}\\ \text{where,}\\ &a=\frac{\cos^2\theta}{2\sigma^2_x}+\frac{\sin^2\theta}{2\sigma^2_y}\\ &b=-\frac{\sin 2\theta}{4\sigma^2_x}+\frac{\sin 2\theta}{4\sigma^2_y}\\ &c=\frac{\sin^2\theta}{2\sigma^2_x}+\frac{\cos^2\theta}{2\sigma^2_y}\\ &d=\frac{1}{2\sigma^2_z}\\ &\sigma_{a}=\frac{\text{fwhm}_a}{2\sqrt{2\ln 2}}\end{split}\]
asldro.utils.generate_numeric_function.generate_point_function(xx: numpy.ndarray, yy: numpy.ndarray, zz: numpy.ndarray, loc: Union[tuple, list, numpy.ndarray] = numpy.zeros) → numpy.ndarray

Generates an array where the element closest to the location defined by loc is 1.0. If loc is out of bounds then no point is created. Can be used with generate_circular_function_array().

Parameters

  • xx (np.ndarray) – Array of x-coordinates, generate by meshgrid. Can be sparse.

  • yy (np.ndarray) – Array of y-coordinates, generate by meshgrid. Can be sparse.

  • zz (np.ndarray) – Array of z-coordinates, generate by meshgrid. Can be sparse.

  • loc (Union[tuple, list, np.ndarray], optional) – location of the point, \([x_0, y_0, z_0]\), defaults to np.zeros((3,))

Returns

An array with shape the result of broadcasting xx, yy, and zz, where the element closes to the location defined by loc is 1.0, other elements are 0.0. If loc is out of bounds all elements are 0.0.

Return type

np.ndarray

asldro.utils.resampling module

Utility Functions for the ASL DRO

asldro.utils.resampling.rot_x_mat(theta: float) → numpy.ndarray

creates a 4x4 affine performing rotations about x

Parameters

theta (float) – angle to rotate about x in degrees

Returns

4x4 affine for rotating about x

Return type

np.array

asldro.utils.resampling.rot_y_mat(theta: float) → numpy.ndarray

creates a 4x4 affine performing rotations about y

Parameters

theta (float) – angle to rotate about y in degrees

Returns

4x4 affine for rotating about y

Return type

np.array

asldro.utils.resampling.rot_z_mat(theta: float) → numpy.ndarray

creates a 4x4 affine performing rotations about z

Parameters

theta (float) – angle to rotate about z in degrees

Returns

4x4 affine for rotating about z

Return type

np.array

asldro.utils.resampling.scale_mat(scale: Union[Tuple[float, float, float], numpy.ndarray]) → numpy.ndarray

Creates a 4x4 affine performing scaling

Parameters

vector (Tuple[float, float, float]) – describes (sx, sy, sz) scaling factors

Returns

4x4 affine for scaling

Return type

np.array

asldro.utils.resampling.transform_resample_affine(image: Union[nibabel.Nifti1Image, nibabel.Nifti2Image, asldro.containers.image.BaseImageContainer], translation: Tuple[float, float, float], rotation: Tuple[float, float, float], rotation_origin: Tuple[float, float, float], target_shape: Tuple[int, int, int]) → Tuple[numpy.ndarray, numpy.ndarray]

Calculates the affine matrices that transform and resample an image in world-space. Note that while an image (NIFTI or BaseImageContainer derived) is accepted an an argument, the image is not acutally resampled.

Parameters

  • image (Union[nib.Nifti1Image, nib.Nifti2Image, BaseImageContainer]) – The input image

  • translation (Tuple[float, float, float]) – vector to translate in the image by in world space

  • rotation (Tuple[float, float, float]) – angles to rotate the object by in world space

  • rotation_origin (Tuple[float, float, float]) – coordinates for the centre point of rotation in world space

  • target_shape (Tuple[int, int, int]) – target shape for the resampled image

Returns

[target_affine_with_motion, target_affine_no_motion]. target_affine_with_motion is the affine to supply to a resampling function. After resampling theresampled image’s affine should be set to to target_affine_no_motion so that it only has the image formation (scaling) operation performed (not the motion)

Return type

Tuple[np.array, np.array]

asldro.utils.resampling.transform_resample_image(image: Union[nibabel.Nifti1Image, nibabel.Nifti2Image, asldro.containers.image.BaseImageContainer], translation: Tuple[float, float, float], rotation: Tuple[float, float, float], rotation_origin: Tuple[float, float, float], target_shape: Tuple[int, int, int]) → Tuple[Union[nibabel.Nifti2Image, nibabel.Nifti2Image], numpy.ndarray]

Transforms and resamples a nibabel NIFTI image in world-space

Parameters

  • image (Union[nib.Nifti1Image, nib.Nifti2Image]) – The input image

  • translation (Tuple[float, float, float]) – vector to translate in the image by in world space

  • rotation (Tuple[float, float, float]) – angles to rotate the object by in world space

  • rotation_origin (Tuple[float, float, float]) – coordinates for the centre point of rotation in world space

  • target_shape (Tuple[int, int, int]) – target shape for the resampled image

Returns

[resampled_image, target_affine]. resampled_image is the input image with the transformation and resampling applied. target_affine is the affine that was used to resample the image. Note resampled_image has an affine that only corresponds to voxel scaling and not motion, i.e. the image FOV is the same as the input image FOV.

Return type

Tuple[Union[nib.Nifti2Image, nib.Nifti2Image], np.array]

asldro.utils.resampling.translate_mat(translation: Union[Tuple[float, float, float], numpy.ndarray]) → numpy.ndarray

Creates a 4x4 affine performing translations

Parameters

vector (Tuple[float, float, float]) – describes (x, y, z) to translate along respective axes

Returns

4x4 affine for translation

Return type

np.array

Module contents