direct.common package

direct.common package#

Submodules#

direct.common.subsample module#

DIRECT samplers module.

This module contains classes for creating sub-sampling masks. The masks are used to sample k-space data in MRI reconstruction. The masks are created by selecting a subset of samples from the input k-space data.

class direct.common.subsample.BaseMaskFunc(accelerations, center_fractions=None, uniform_range=True, mode=MaskFuncMode.STATIC)[source][source]#

Bases: object

BaseMaskFunc is the base class to create a sub-sampling mask of a given shape.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling_mask. An acceleration of 4 retains 25% of the k-space, the method is given by mask_type. Has to be the same length as center_fractions if uniform_range is not True.
center_fractionsUnion[list[float], tuple[float, …]], optional: Fraction of low-frequency columns (float < 1.0) or number of low-frequence columns (integer) to be retained. If multiple values are provided, then one of these numbers is chosen uniformly each time. If uniform_range is True, then two values should be given. Default: None.
uniform_rangebool: If True then an acceleration will be uniformly sampled between the two values. Default: False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

choose_acceleration()[source][source]#

Chooses an acceleration and center fraction.

Returns:

Union[Number, tuple[Number, Number]]: Acceleration and center fraction.

Raises:

NotImplementedError: If uniform range is not yet implemented.

Return type:

Union[float, int, tuple[Union[float, int], Union[float, int]]]

abstract mask_func(*args, **kwargs)[source][source]#

Abstract methot to create a sub-sampling mask.

Returns:

torch.Tensor: Sampling mask.

Raises:

NotImplementedError

Return type:

Tensor

class direct.common.subsample.CIRCUSMaskFunc(subsampling_scheme, accelerations, center_fractions=None, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: BaseMaskFunc

Implementation of Cartesian undersampling (radial or spiral) using CIRCUS as shown in [1].

It creates radial or spiral masks for Cartesian acquired data on a grid.

Parameters:

subsampling_schemeCIRCUSSamplingMode: The subsampling scheme to use. Can be either CIRCUSSamplingMode.CIRCUS_RADIAL or CIRCUSSamplingMode.CIRCUS_SPIRAL.
accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]], optional: Fraction (< 1.0) of low-frequency samples to be retained. If None, it will calculate the acs mask based on the maximum masked disk in the generated mask (with a tolerance).Default: None.
uniform_rangebool: If True then an acceleration will be uniformly sampled between the two values. Default: False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

References

[1]

Liu J, Saloner D. Accelerated MRI with CIRcular Cartesian UnderSampling (CIRCUS): a variable density Cartesian sampling strategy for compressed sensing and parallel imaging. Quant Imaging Med Surg. 2014 Feb;4(1):57-67. doi: 10.3978/j.issn.2223-4292.2014.02.01. PMID: 24649436; PMCID: PMC3947985.

static circular_centered_mask(mask, eps=0.1)[source][source]#

Finds the maximum (masked) disk in mask given a tolerance.

Parameters:

masktorch.Tensor: The mask.
epsfloat, optional: Tolerance for the disk radius. The disk radius is increased until the ratio of the disk area to the intersection area is greater than 1 + eps. Default: 0.1

Returns:

torch.Tensor: _description_

Return type:

Tensor

circus_radial_mask(shape, acceleration)[source][source]#

Implements CIRCUS radial undersampling.

Parameters:

shapetuple[int, int]: Shape of the mask.
accelerationNumber: The acceleration factor.

Returns:

torch.Tensor: The radial mask.

Return type:

Tensor

circus_spiral_mask(shape, acceleration)[source][source]#

Implements CIRCUS spiral undersampling.

Parameters:

shapetuple[int, int]: Shape of the mask.
accelerationNumber: The acceleration factor.

Returns:

torch.Tensor: The spiral mask.

Return type:

Tensor

static get_square_ordered_idxs(square_side_size, square_id)[source][source]#

Returns ordered (clockwise) indices of a sub-square of a square matrix.

Parameters:

square_side_sizeint: Square side size. Dim of array.
square_idint: Number of sub-square. Can be 0, …, square_side_size // 2.

Returns:

ordered_idxslist of tuples.: Indices of each point that belongs to the square_id-th sub-square starting from top-left point clockwise.

Return type:

tuple[tuple, ...]

mask_func(shape, return_acs=False, seed=None)[source][source]#

Produces CIRCUSMaskFunc sampling masks.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

masktorch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.CIRCUSSamplingMode(value)[source][source]#

Bases: DirectEnum

Enumeration of CIRCUS sampling modes.

CIRCUS sampling modes are radial and spiral.

CIRCUS_RADIAL = 'circus-radial'#

CIRCUS_SPIRAL = 'circus-spiral'#

class direct.common.subsample.CalgaryCampinasMaskFunc(accelerations, **kwargs)[source][source]#

Bases: BaseMaskFunc

Implementation of Calgary-Campinas sampling mask function.

Samples are drawn from pre-computed masks provided by the challenge. The masks are available for accelerations of 5 and 10. The masks are available for shapes of \(218 \times 170/174/180\). The masks are downloaded from the challenge website and cached locally. The masks are loaded based on the shape of the input k-space data. The masks are randomly selected from the available masks for the given shape. The masks are broadcasted to the shape of the input k-space data. The autocalibration signal region is generated as a circular mask centered in the k-space with a radius of 18.

For more information, please refer to the challenge website [1].

Parameters:

accelerationsUnion[list[int], tuple[int, …]]: Amount of under-sampling_mask. An acceleration of 4 retains 25% of the k-space, the method is given by mask_type. Has to be the same length as center_fractions if uniform_range is not True.

Raises:

ValueError: If the acceleration is not 5 or 10.

References

[1]

https://sites.google.com/view/calgary-campinas-dataset/mr-reconstruction-challenge?authuser=0

BASE_URL = 'https://s3.aiforoncology.nl/direct-project/calgary_campinas_masks/'#

MASK_MD5S = {'R10_218x170.npy': '6e1511c33dcfc4a960f526252676f7c3', 'R10_218x174.npy': '78fe23ae5eed2d3a8ff3ec128388dcc9', 'R10_218x180.npy': '5039a6c19ac2aa3472a94e4b015e5228', 'R5_218x170.npy': '6599715103cf3d71d6e87d09f865e7da', 'R5_218x174.npy': '5bd27d2da3bf1e78ad1b65c9b5e4b621', 'R5_218x180.npy': '717b51f3155c3a64cfaaddadbe90791d'}#

static circular_centered_mask(shape, radius)[source][source]#

Creates a circular centered mask.

Parameters:

shapetuple[int, int]: Shape of the mask as a two-dim tuple.
radiusint: Radius of the circular mask.

Returns:

np.ndarray: The circular mask.

Return type:

ndarray

mask_func(shape, return_acs=False, seed=None)[source][source]#

Downloads and loads pre-computed Poisson masks.

Currently supports shapes of \(218 \times 170/174/180\) and acceleration factors of 5 or 10.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

masktorch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.CartesianEquispacedMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: EquispacedMaskFunc

Cartesian equispaced vertical line mask function.

Similar to FastMRIEquispacedMaskFunc, but instead of center fraction (center_fractions) representing the fraction of center lines to the original size, here, it represents the actual number of center lines.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling_mask. An acceleration of 4 retains 25% of the k-space, the method is given by mask_type. Has to be the same length as center_fractions if uniform_range is not True.
center_fractionsUnion[list[int], tuple[int, …]]: Number of low-frequence (center) columns to be retained.
uniform_rangebool: If True then an acceleration will be uniformly sampled between the two values. Default: False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

class direct.common.subsample.CartesianMagicMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: MagicMaskFunc

Cartesian equispaced mask function as implemented in [1].

Similar to FastMRIMagicMaskFunc, but instead of center fraction (center_fractions) representing the fraction of center lines to the original size, here, it represents the actual number of center lines.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling_mask. An acceleration of 4 retains 25% of the k-space, the method is given by mask_type. Has to be the same length as center_fractions if uniform_range is not True.
center_fractionsUnion[list[int], tuple[int, …]]: Number of low-frequence (center) columns to be retained.
uniform_rangebool: If True then an acceleration will be uniformly sampled between the two values. Default: False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

References

[1]

Defazio, Aaron. “Offset Sampling Improves Deep Learning Based Accelerated MRI Reconstructions by Exploiting Symmetry.” ArXiv:1912.01101 [Cs, Eess], Feb. 2020. arXiv.org, http://arxiv.org/abs/1912.01101.

class direct.common.subsample.CartesianRandomMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: RandomMaskFunc

Cartesian random vertical line mask function.

Similar to FastMRIRandomMaskFunc, but instead of center fraction (center_fractions) representing the fraction of center lines to the original size, here, it represents the actual number of center lines.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling_mask. An acceleration of 4 retains 25% of the k-space, the method is given by mask_type. Has to be the same length as center_fractions if uniform_range is not True.
center_fractionsUnion[list[int], tuple[int, …]]: Number of low-frequence (center) columns to be retained.
uniform_rangebool: If True then an acceleration will be uniformly sampled between the two values. Default: False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

class direct.common.subsample.CartesianVerticalMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: BaseMaskFunc

CartesianVerticalMaskFunc is the base class to create vertical Cartesian sub-sampling masks.

This is the base class of Cartesian and FastMRI mask functions. The difference between Cartesian and FastMRI mask functions is that the former uses the number of center lines to be retained, while the latter uses the fraction of center lines to be retained.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction of low-frequency columns (float < 1.0) or number of low-frequence columns (integer) to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

static center_mask_func(num_cols, num_low_freqs)[source][source]#

Creates the ACS (center) mask.

Parameters:

num_colsint: Number of center columns/lines.
num_low_freqsint: Number of low-frequency columns/lines.

Returns:

np.ndarray: ACS (center) mask.

Return type:

ndarray

class direct.common.subsample.EquispacedMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: CartesianVerticalMaskFunc

Equispaced vertical line mask function.

EquispacedMaskFunc creates a sub-sampling mask of given shape. The mask selects a subset of columns from the input k-space data. If the k-space data has N columns, the mask picks out:

\(N_{\text{low freqs}} = (N \times \text{center_fraction})\) columns in the center corresponding to low-frequencies if center_fraction < 1.0, or \(N_{\text{low freqs}} = \text{center_fraction}\) if center_fraction >= 1 and is integer.

The other columns are selected with equal spacing at a proportion that reaches the desired acceleration rate taking into consideration the number of low frequencies. This ensures that the expected number of columns selected is equal to \(\frac{N}{\text{acceleration}}\).

It is possible to use multiple center_fractions and accelerations, in which case one possible (center_fraction, acceleration) is chosen uniformly at random each time the EquispacedMaskFunc object is called.

Note that this function may not give equispaced samples (documented in facebookresearch/fastMRI#54), which will require modifications to standard GRAPPA approaches. Nonetheless, this aspect of the function has been preserved to match the public multicoil data.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[Number], tuple[Number, …]]: If < 1.0 this corresponds to the fraction of low-frequency columns to be retained. If >= 1 (integer) this corresponds to the exact number of low-frequency columns to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

mask_func(shape, return_acs=False, seed=None)[source][source]#

Creates an vertical equispaced vertical line mask.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

masktorch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.FastMRIEquispacedMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: EquispacedMaskFunc

Equispaced vertical line mask function.

FastMRIEquispacedMaskFunc creates a sub-sampling mask of given shape. The mask selects a subset of columns from the input k-space data. If the k-space data has N columns, the mask picks out:

\(N_{\text{low freqs}} = (N \times \text{center_fraction})\) columns in the center corresponding to low-frequencies.

The other columns are selected with equal spacing at a proportion that reaches the desired acceleration rate taking into consideration the number of low frequencies. This ensures that the expected number of columns selected is equal to \(\frac{N}{\text{acceleration}}\).

It is possible to use multiple center_fractions and accelerations, in which case one possible (center_fraction, acceleration) is chosen uniformly at random each time the EquispacedMaskFunc object is called.

Note that this function may not give equispaced samples (documented in facebookresearch/fastMRI#54), which will require modifications to standard GRAPPA approaches. Nonetheless, this aspect of the function has been preserved to match the public multicoil data.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction (< 1.0) of low-frequency columns to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

class direct.common.subsample.FastMRIMagicMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: MagicMaskFunc

Vertical line mask function as implemented in [1].

FastMRIMagicMaskFunc exploits the conjugate symmetry via offset-sampling. It is essentially an equispaced mask with an offset for the opposite site of the k-space. Since MRI images often exhibit approximate conjugate k-space symmetry, this mask is generally more efficient than FastMRIEquispacedMaskFunc.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling_mask. An acceleration of 4 retains 25% of the k-space, the method is given by mask_type. Has to be the same length as center_fractions if uniform_range is not True.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction (< 1.0) of low-frequency columns to be retained.
uniform_rangebool: If True then an acceleration will be uniformly sampled between the two values. Default: False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

References

[1]

Defazio, Aaron. “Offset Sampling Improves Deep Learning Based Accelerated MRI Reconstructions by Exploiting Symmetry.” ArXiv:1912.01101 [Cs, Eess], Feb. 2020. arXiv.org, http://arxiv.org/abs/1912.01101.

class direct.common.subsample.FastMRIRandomMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: RandomMaskFunc

Random vertical line mask function.

The mask selects a subset of columns from the input k-space data. If the k-space data has \(N\) columns, the mask picks out:

\(N_{\text{low freqs}} = (N \times \text{center_fraction})\) columns in the center corresponding to low-frequencies.

The other columns are selected uniformly at random with a probability equal to: \(\text{prob} = (N / \text{acceleration} - N_{\text{low freqs}}) / (N - N_{\text{low freqs}})\). This ensures that the expected number of columns selected is equal to (N / acceleration).

It is possible to use multiple center_fractions and accelerations, in which case one possible (center_fraction, acceleration) is chosen uniformly at random each time the MaskFunc object is called.

For example, if accelerations = [4, 8] and center_fractions = [0.08, 0.04], then there is a 50% probability that 4-fold acceleration with 8% center fraction is selected and a 50% probability that 8-fold acceleration with 4% center fraction is selected.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction of low-frequency columns (float < 1.0) to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

class direct.common.subsample.Gaussian1DMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: CartesianVerticalMaskFunc

Gaussian 1D vertical line mask function.

This method uses Cython under the hood to generate a 1D Gaussian mask, employing rejection sampling.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction of low-frequency columns (float < 1.0) to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

mask_func(shape, return_acs=False, seed=None)[source][source]#

Creates a vertical gaussian mask.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

masktorch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.Gaussian2DMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: BaseMaskFunc

Gaussian 2D mask function.

This method uses Cython under the hood to generate a 2D Gaussian mask, employing rejection sampling.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction of low-frequency samples (float < 1.0) to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

mask_func(shape, return_acs=False, seed=None)[source][source]#

Creates a 2D gaussian mask.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

masktorch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.KtBaseMaskFunc(accelerations, center_fractions, uniform_range=False)[source][source]#

Bases: BaseMaskFunc

Base class for kt mask functions.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction of low-frequency columns (float < 1.0) or number of low-frequence columns (integer) to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.

static crop_center(array, target_height, target_width)[source][source]#

Crops the center of an array to the target height and width.

Parameters:

arrayndarray: The input array.
target_heightint: The target height.
target_widthint: The target width.

Returns:

ndarray: The cropped array.

static find_nearest_empty_location(target_index, empty_indices, row_length)[source][source]#

Finds the nearest empty index to the target index in 2D space.

Parameters:

target_indexint: The index of the target point.
empty_indicesndarray: The indices of empty locations.
row_lengthint: The length of the rows in the 2D array.

Returns:

int: The nearest empty index.

Return type:

int

static linear_indices_to_2d_coordinates(indices, row_length)[source][source]#

Converts linear indices to 2D coordinates.

Parameters:

indicesndarray: The linear indices to convert.
row_lengthint: The length of the rows in the 2D array.

Returns:

tuple of ndarray: The x and y coordinates.

Return type:

tuple[ndarray, ndarray]

static resolve_duplicates_on_kt_grid(phase, time, ny, nt)[source][source]#

Corrects overlapping trajectories in k-space by shifting points to the nearest vacant locations.

Parameters:

phasendarray: The phase coordinates of the trajectories.
timendarray: The time coordinates of the trajectories.
nyint: The number of phase encoding steps.
ntint: The number of time encoding steps.

Returns:

tuple of ndarray: Corrected phase and time coordinates.

Return type:

tuple[ndarray, ndarray]

static zero_pad_to_center(array, target_shape)[source][source]#

Zero pads an array to the target shape around its center.

Parameters:

arrayndarray: The input array.
target_shapetuple of int: The target shape for each dimension.

Returns:

ndarray: The zero-padded array.

Return type:

ndarray

class direct.common.subsample.KtGaussian1DMaskFunc(accelerations, center_fractions, uniform_range=False, alpha=0.28, std_scale=5.0)[source][source]#

Bases: KtBaseMaskFunc

Kt Gaussian 1D mask function.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction of low-frequency columns (float < 1.0) or number of low-frequence columns (integer) to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
alphafloat, optional: 0 < alpha < 1 controls sampling density; 0: uniform density, 1: maximally non-uniform density. Default: 0.28.
std_scalefloat, optional: The standard deviation scaling of the Gaussian envelope for sampling density. Default: 5.0.

mask_func(shape, return_acs=False, seed=None)[source][source]#

Creates a kt Gaussian 1D mask.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

torch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.KtRadialMaskFunc(accelerations, center_fractions, uniform_range=False, crop_corner=False)[source][source]#

Bases: KtBaseMaskFunc

Kt radial mask function.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction of low-frequency columns (float < 1.0) or number of low-frequence columns (integer) to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
crop_cornerbool, optional: If True, the mask is cropped to the corners. Default: False.

mask_func(shape, return_acs=False, seed=None)[source][source]#

Creates a kt radial mask.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

torch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.KtUniformMaskFunc(accelerations, center_fractions, uniform_range=False)[source][source]#

Bases: KtBaseMaskFunc

Kt uniform mask function.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]]: Fraction of low-frequency columns (float < 1.0) or number of low-frequence columns (integer) to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.

mask_func(shape, return_acs=False, seed=None)[source][source]#

Creates a kt uniform mask.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

torch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.MagicMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: CartesianVerticalMaskFunc

Vertical line mask function as implemented in [1].

MagicMaskFunc exploits the conjugate symmetry via offset-sampling. It is essentially an equispaced mask with an offset for the opposite site of the k-space. Since MRI images often exhibit approximate conjugate k-space symmetry, this mask is generally more efficient than EquispacedMaskFunc.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling_mask. An acceleration of 4 retains 25% of the k-space, the method is given by mask_type. Has to be the same length as center_fractions if uniform_range is not True.
center_fractionsUnion[list[Number], tuple[Number, …]]: If < 1.0 this corresponds to the fraction of low-frequency columns to be retained. If >= 1 (integer) this corresponds to the exact number of low-frequency columns to be retained.
uniform_rangebool: If True then an acceleration will be uniformly sampled between the two values. Default: False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

References

[1]

Defazio, Aaron. “Offset Sampling Improves Deep Learning Based Accelerated MRI Reconstructions by Exploiting Symmetry.” ArXiv:1912.01101 [Cs, Eess], Feb. 2020. arXiv.org, http://arxiv.org/abs/1912.01101.

mask_func(shape, return_acs=False, seed=None)[source][source]#

Creates a vertical equispaced mask that exploits conjugate symmetry.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

masktorch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.MaskFuncMode(value)[source][source]#

Bases: DirectEnum

An enumeration.

DYNAMIC = 'dynamic'#

MULTISLICE = 'multislice'#

STATIC = 'static'#

class direct.common.subsample.RadialMaskFunc(accelerations, center_fractions=None, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: CIRCUSMaskFunc

Computes CIRCUS radial masks for Cartesian data.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]], optional: Fraction (< 1.0) of low-frequency samples to be retained. If None, it will calculate the acs mask based on the maximum masked disk in the generated mask (with a tolerance).Default: None.
uniform_rangebool: If True then an acceleration will be uniformly sampled between the two values. Default: False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

class direct.common.subsample.RandomMaskFunc(accelerations, center_fractions, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: CartesianVerticalMaskFunc

Random vertical line mask function.

The mask selects a subset of columns from the input k-space data. If the k-space data has \(N\) columns, the mask picks out:

\(N_{\text{low freqs}} = (N \times \text{center_fraction})\) columns in the center corresponding to low-frequencies if center_fraction < 1.0, or \(N_{\text{low freqs}} = \text{center_fraction}\) if center_fraction >= 1 and is integer.

The other columns are selected uniformly at random with a probability equal to: \(\text{prob} = (N / \text{acceleration} - N_{\text{low freqs}}) / (N - N_{\text{low freqs}})\). This ensures that the expected number of columns selected is equal to (N / acceleration).

It is possible to use multiple center_fractions and accelerations, in which case one possible (center_fraction, acceleration) is chosen uniformly at random each time the MaskFunc object is called.

For example, if accelerations = [4, 8] and center_fractions = [0.08, 0.04], then there is a 50% probability that 4-fold acceleration with 8% center fraction is selected and a 50% probability that 8-fold acceleration with 4% center fraction is selected.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[Number], tuple[Number, …]]: If < 1.0 this corresponds to the fraction of low-frequency columns to be retained. If >= 1 (integer) this corresponds to the exact number of low-frequency columns to be retained.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

mask_func(shape, return_acs=False, seed=None)[source][source]#

Creates vertical line mask.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

masktorch.Tensor: The sampling mask.

Return type:

Tensor

class direct.common.subsample.SpiralMaskFunc(accelerations, center_fractions=None, uniform_range=False, mode=MaskFuncMode.STATIC)[source][source]#

Bases: CIRCUSMaskFunc

Computes CIRCUS spiral masks for Cartesian data.

Parameters:

accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[float], tuple[float, …]], optional: Fraction (< 1.0) of low-frequency samples to be retained. If None, it will calculate the acs mask based on the maximum masked disk in the generated mask (with a tolerance).Default: None.
uniform_rangebool: If True then an acceleration will be uniformly sampled between the two values. Default: False.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.

class direct.common.subsample.VariableDensityPoissonMaskFunc(accelerations, center_fractions, mode=MaskFuncMode.STATIC, crop_corner=False, max_attempts=10, tol=0.2, slopes=None)[source][source]#

Bases: BaseMaskFunc

Variable Density Poisson sampling mask function. Based on [1].

Parameters:

accelerationslist or tuple of positive numbers: Amount of under-sampling.
center_fractionslist or tuple of floats: Must have the same length as accelerations. Amount of center fully-sampling. For center_scale=’r’, then a centered disk area with radius equal to \(R = \sqrt{{n_r}^2 + {n_c}^2} \\times r\) will be fully sampled, where \(n_r\) and \(n_c\) denote the input shape.
modeMaskFuncMode: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.
crop_cornerbool, optional: If True mask will be disk. Default: False.
max_attemptsint, optional: Maximum rejection samples. Default: 10.
tolfloat, optional: Maximum deviation between the generated mask acceleration and the desired acceleration. Default: 0.2.
slopesOptional[Union[list[float], tuple[float, …]]]: An increasing sequence of non-negative floats (of length 2) to be used for the generation of the sampling radius. Default: None.

Notes

Code inspired and modified from [2] with BSD-3 licence, Copyright (c) 2016, Frank Ong, Copyright (c) 2016,
The Regents of the University of California [3].

References

[1]

Bridson, Robert. “Fast Poisson Disk Sampling in Arbitrary Dimensions.” ACM SIGGRAPH 2007 Sketches on - SIGGRAPH ’07, ACM Press, 2007, pp. 22-es. DOI.org (Crossref), https://doi.org/10.1145/1278780.1278807.

[2]

mikgroup/sigpy

[3]

mikgroup/sigpy

mask_func(shape, return_acs=False, seed=None)[source][source]#

Produces variable Density Poisson sampling masks.

Parameters:

shapelist or tuple of ints

The shape of the mask to be created. The shape should at least 3 dimensions. Samples are drawn along the second last dimension.

return_acsbool

Return the autocalibration signal region as a mask.

seedint or iterable of ints or None (optional)

Seed for the random number generator. Setting the seed ensures the same mask is generated: each time for the same shape. Default: None.

Returns:

masktorch.Tensor: The sampling mask of shape (1, shape[0], shape[1], 1).

Return type:

Tensor

poisson(num_rows, num_cols, center_fraction, acceleration, seed=0)[source][source]#

Calculates mask by calling the cython _poisson method.

Parameters:

num_rowsint: Number of rows - x-axis size.
num_colsint: Number of columns - y-axis size.
center_fractionfloat: Amount of center fully-sampling.
accelerationfloat: Acceleration factor.
seedint: Seed to be used by cython function. Default: 0.

Returns:

masktorch.Tensor: Sampling mask of shape (num_rows, num_cols).

Return type:

Tensor

direct.common.subsample.build_masking_function(name, accelerations, center_fractions=None, uniform_range=False, mode=MaskFuncMode.STATIC, **kwargs)[source][source]#

Builds a mask function.

Parameters:

namestr: Name of the mask function.
accelerationsUnion[list[Number], tuple[Number, …]]: Amount of under-sampling.
center_fractionsUnion[list[Number], tuple[Number, …]], optional: Fraction of low-frequency columns (float < 1.0) or number of low-frequence columns (integer) to be retained. If multiple values are provided, then one of these numbers is chosen uniformly each time. If uniform_range is True, then two values should be given, by default None.
uniform_rangebool, optional: If True then an acceleration will be uniformly sampled between the two values, by default False.
modeMaskFuncMode, optional: Mode of the mask function. Can be MaskFuncMode.STATIC, MaskFuncMode.DYNAMIC, or MaskFuncMode.MULTISLICE. If MaskFuncMode.STATIC, then a single mask is created independent of the requested shape, and will be broadcasted to the shape by expanding other dimensions with 1, if applicable. If MaskFuncMode.DYNAMIC, this expects the shape to have more then 3 dimensions, and the mask will be created for each time frame along the fourth last dimension. Similarly for MaskFuncMode.MULTISLICE, the mask will be created for each slice along the fourth last dimension. Default: MaskFuncMode.STATIC.
**kwargsdict[str, Any], optional: Additional keyword arguments to be passed to the mask function. These will be passed as keyword arguments to the mask function constructor. If the mask function constructor does not accept these arguments, they will be ignored.

Returns:

BaseMaskFunc: The mask function.

Return type:

BaseMaskFunc

direct.common.subsample.centered_disk_mask(shape, center_scale)[source][source]#

Creates a mask with a centered disk of radius \(R=\sqrt{c_x \cdot c_y \cdot r / \pi}\).

Parameters:

shapelist or tuple of ints: The shape of the (2D) mask to be created.
center_scalefloat: Center scale.

Returns:

masknp.ndarray

Return type:

ndarray

direct.common.subsample.integerize_seed(seed)[source][source]#

Returns an integer seed.

If input is integer, will return the input. If input is None, will return a random integer seed. If input is a tuple or list, will return a random integer seed based on the input.

Can be useful for functions that take as input only integer seeds (e.g. cython functions).

Parameters:

seedint, tuple or list of ints, None: Input seed to integerize.

Returns:

out_seed: int: Integer seed.

Return type:

int

direct.common.subsample_config module#

class direct.common.subsample_config.MaskingConfig(name: 'str' = '???', accelerations: 'tuple[float, ...]' = (5.0, ), center_fractions: 'Optional[tuple[float, ...]]' = (0.1, ), uniform_range: 'bool' = False, mode: 'MaskFuncMode' = <MaskFuncMode.STATIC: 'static'>, val_accelerations: 'tuple[float, ...]' = (5.0, 10.0), val_center_fractions: 'Optional[tuple[float, ...]]' = (0.1, 0.05))[source][source]#

Bases: BaseConfig

accelerations: tuple[float, ...] = (5.0,)#

center_fractions: Optional[tuple[float, ...]] = (0.1,)#

mode: MaskFuncMode = 'static'#

name: str = '???'#

uniform_range: bool = False#

val_accelerations: tuple[float, ...] = (5.0, 10.0)#

val_center_fractions: Optional[tuple[float, ...]] = (0.1, 0.05)#

direct.common package

Contents

direct.common package#

Submodules#

direct.common.subsample module#

direct.common.subsample_config module#

Module contents#