cornucopia.qmri

This module contains transforms that implement physics-based forward models of MR image formation.

RandomSusceptibilityMixtureTransform

RandomSusceptibilityMixtureTransform(mu_tissue=Uniform(9, 10), sigma_tissue=0.01, mu_bone=Uniform(12, 13), sigma_bone=0.1, fwhm=2, label_air=0, label_bone=None, dtype=None, *, shared='channels', **kwargs)

Bases: NonFinalTransform

A RandomGaussianMixtureTransform tailored to susceptibility maps.

This transform returns a delta susceptibility map (with respect to air), in ppm.

Parameters:

Name	Type	Description	Default
`mu_tissue`	`Sampler \| float`	Distribution of negative susceptibility offsets (in ppm) of soft tissues with respect to air. Will be negated (air susceptibility is larger than all tissues). If float: upper bound.	`Uniform(9, 10)`
`sigma_tissue`	`Sampler \| float`	Standard deviation of susceptibility offsets, within class. If float: uper bound.	`0.01`
`mu_bone`	`Sampler \| float`	Distribution of negative susceptibility offsets (in ppm) of hard tissues with respect to air. Will be negated (air susceptibility is larger than all tissues). If float: upper bound.	`Uniform(12, 13)`
`sigma_bone`	`SamplerOrBound[float]`	Standard deviation of susceptibility offsets, within class. If float: upper bound.	`0.1`
`fwhm`	`Sampler \| [list of] float`	Sampling function for smoothing width. If float: upper bound.	`2`
`label_air`	`[list of] int`	Labels corresponding to air.	`0`
`label_bone`	`[list of] int`	Labels corresponding to bone and teeth.	`None`

Next `class-attribute` `instance-attribute`

Next = GaussianMixtureTransform

The transform type returned by make_final(..., max_depth=1).

Final `class-attribute` `instance-attribute`

Final = GaussianMixtureFinalTransform

The transform type returned by make_final(..., max_depth=inf).

SusceptibilityToFieldmapTransform

SusceptibilityToFieldmapTransform(axis=-1, field_strength=3, larmor=42576000.0, s0=0.4, s1=-9.5, voxel_size=1, mask_air=False, **kwargs)

Bases: FinalTransform

Convert a susceptibiity map (in ppm) into a field map (in Hz)

Parameters:

Name	Type	Description	Default
`axis`	`int \| sequence[float]`	Direction of the main magnetic field. - If a vector or floats, it is unit vector that encodes the direction of the main magnetic field in the "scaled voxel" coordinate systems. - If an int, the main magnetic field is assumed to be aligned with one of the dimensions of the voxel grid, and `zaxis` is the index of this dimension. I.e., `0` is equivalent to `[1, 0, 0]`.	`-1`
`field_strength`	`float`	Strength of the main magnetic field, in Tesla. If None, return a fieldmap in ppm.	`3`
`larmor`	`float`	Larmor frequency (default: Larmor frequency of water)	`42576000.0`
`s0`	`float`	Susceptibility of air (ppm)	`0.4`
`s1`	`float`	Susceptibility of tissue minus susceptiblity of air (ppm) (only used if `ds` is a boolean mask)	`-9.5`
`voxel_size`	`[list of] float`	Voxel size	`1`
`mask_air`	`bool`	Mask air (where delta susceptibility == 0) from resulting fieldmap.	`False`

ShimTransform

ShimTransform(linear=None, quadratic=None, isocenter=None, **kwargs)

Bases: FinalTransform

Parameters:

Name	Type	Description	Default
`linear`	`(3\|1,) tensor \| [list of] float`	Linear components (3D: [XY, XZ, YX], 2D: [XY])	`None`
`quadratic`	`(2\|1,) tensor \| [list of] float`	Quadratic components (3D: [XXYY, XXZZ], 2D: [XXYY])	`None`
`isocenter`	`(3\|2,) tensor \| [list of] float`	Coordinates of the isocenter, in voxels	`None`

Other Parameters:

Name	Type	Description
`returns`	`[(list \| dict) of] {'input', 'output', 'shim'}`

OptimalShimTransform

OptimalShimTransform(max_order=2, lam_abs=1, lam_grad=10, mask=True, **kwargs)

Bases: NonFinalTransform

Compute a linear combination of spherical harmonics that flattens the input field map

Parameters:

Name	Type	Description	Default
`max_order`	`int`	Maximum order of spherical basis functions	`2`
`lam_abs`	`float`	Regularization factor for absolute values	`1`
`lam_grad`	`float`	Regularization factor for first order gradients	`10`
`mask`	`bool`	Mask zeros/NaNs from objective functions	`True`

Other Parameters:

Name	Type	Description
`returns`	`[list or dict of] {'input', 'output', 'shim'}`

Next `class-attribute` `instance-attribute`

Next = AddValueTransform

The transform type returned by make_final.

Final `class-attribute` `instance-attribute`

Final = AddValueTransform

The transform type returned by make_final.

RandomShimTransform

RandomShimTransform(coefficients=5, max_order=2, *, shared=False, **kwargs)

Bases: NonFinalTransform

Sample a random (imperfect) shim.

This function randomly samples the coefficients of a field encoded by spherical harmonics.

Parameters:

Name	Type	Description	Default
`coefficients`	`Sampler \| int`	Sampler for spherical harmonics coefficients (or upper bound)	`5`
`max_order`	`Sampler \| int`	Sampler for spherical harmonics order (or upper bound)	`2`

Other Parameters:

Name	Type	Description
`returns`	`[list or dict of] {'input', 'output', 'shim'}`
`shared`	`(channels, tensors, channels + tensors, '')`

Next `class-attribute` `instance-attribute`

Next = ShimTransform

The transform type returned by make_final(..., max_depth=1).

Final `class-attribute` `instance-attribute`

Final = AddValueTransform

The transform type returned by make_final(..., max_depth=inf).

HertzToPhaseTransform

HertzToPhaseTransform(te=0, **kwargs)

Bases: FinalTransform

Converts a ΔB0 field (in Hz) into a Phase shift field Δφ (in rad)

Parameters:

Name	Type	Description	Default
`te`	`float`	Echo time, in sec.	`0`

HertzToVoxelShiftTransform

HertzToVoxelShiftTransform(bandwidth=140, **kwargs)

Bases: FinalTransform

Converts a ΔB0 field (in Hz) into a voxel shift field Δv

Parameters:

Name	Type	Description	Default
`bandwidth`	`float`	Bandwidth, in Hz/pixel.	`140`

ApplyB0DistortionTransform

ApplyB0DistortionTransform(flow=None, vdm=None, controls=None, order=3, bound='border', nearest_if_label=True, axis=-1, *, dtype=None, device=None, **kwargs)

Bases: FinalTransform

Final (deterministic) elastic transform

Parameters:

Name	Type	Description	Default
`flow`	`(C, D, *spatial) tensor`	Flow field (in voxels) (if not provided, `vdm` of `controls` must be provided)	`None`
`vdm`	`(C, *spatial) tensor`	Voxel displacement field (if not provided, `controls` must be provided)	`None`
`controls`	`(C, *shape) tensor`	Spline control points (if not provided, `vdm` must be provided)	`None`
`order`	`1..7`	Order of the splines that encode the smooth deformation.	`3`
`bound`	`(zeros, border, reflection)`	Padding mode used for the deformed image.	`'zeros'`
`nearest_if_label`	`bool`	By default, if a tensor has an integer data type, it is deformed using label-specific resampling (each unique label is extracted and resampled using linear interpolation, and an argmax output label map is computed on the fly). If `nearest_if_label=True`, the entire label map will be resampled at once using nearest-neighbour interpolation.	`True`
`axis`	`int \| sequence[float]`	If int, the distortion is applied along this dimension. If sequence of floats, it is a unit vector that encodes the direction of the distortion in the voxel coordinate system.	`-1`

make_vdm

make_vdm(shape, controls=None)

Upsample the control points to the final full size

Parameters:

Name	Type	Description	Default
`shape`	`list[int]`	Target shape	required
`controls`	`(C, *shape) tensor`	Spline control points	`self.controls`

Returns:

Name	Type	Description
`vdm`	`(C, *fullshape) tensor`	Upampled voxel displacement field

make_flow

make_flow(vdm)

Make a flow field from the voxel displacement map

xform

xform(x, /, *, args=NoArguments())

Deform the input tensor

Parameters:

Name	Type	Description	Default
`x`	`(C, *spatial) tensor`	Input tensor	required

Returns:

Name	Type	Description
`out`	`[dict or list of] tensor`	The tensors returned by this function depend on the value of `self.returns`. See `ElasticTransform`.

B0DistortionTransform

B0DistortionTransform(dmax=0.1, unit='fov', shape=5, bound='circular', order=3, nearest_if_label=True, axis=-1, *, dtype=None, device=None, shared=True, **kwargs)

Bases: NonFinalTransform

Elastic distortion along a single dimension.

The number of control points is fixed but coefficients are randomly sampled from a uniform distribution.

This is not a realistic B0 distortion model. For a more realistic model, see RealisticB0DistortionTransform.

Parameters:

Name	Type	Description	Default
`dmax`	`[list of] float`	Max displacement per dimension	`0.1`
`unit`	`(fov, vox)`	Unit of `dmax`.	`'fov'`
`shape`	`[list of] int`	Number of spline control points	`5`
`bound`	`(zeros, border, reflection, circular)`	Padding mode used for the deformed image.	`'zeros'`
`order`	`1..7`	Order of the splines that encode the smooth deformation.	`3`
`nearest_if_label`	`bool`	By default, if a tensor has an integer data type, it is deformed using label-specific resampling (each unique label is extracted and resampled using linear interpolation, and an argmax output label map is computed on the fly). If `nearest_if_label=True`, the entire label map will be resampled at once using nearest-neighbour interpolation.	`True`
`axis`	`int \| sequence[float]`	If int, the distortion is applied along this dimension. If sequence of floats, it is a unit vector that encodes the direction of the distortion in the voxel coordinate system.	`-1`

Other Parameters:

Name	Type	Description
`returns`	`[list or dict of] {'input', 'output', 'flow', 'vdm', 'controls'}`	'input': The input image 'output': The deformed image 'flow': The flow field 'vdm': The voxel displacement map (VDM) 'controls': The control points of the VDM
`shared`	`(channels, tensors, channels + tensors, '')`	Apply same transform to all images/channels

Final `class-attribute` `instance-attribute`

Final = ApplyB0DistortionTransform

The transform type returned by make_final.

Next `class-attribute` `instance-attribute`

Next = ApplyB0DistortionTransform

The transform type returned by make_final.

make_final

make_final(x, /, max_depth=inf, *, vdm=True, flow=True)

Generate a deterministic transform with constant parameters

Parameters:

Name	Type	Description	Default
`x`	`(C, *spatial) tensor`	Tensor to deform	required
`max_depth`	`int`	Maximum number of transforms to unroll	`inf`
`vdm`	`bool`	Precompute the upsampled voxel displacement field	`True`
`flow`	`bool`	Precompute the flow field	`True`

Returns:

Name	Type	Description
`xform`	`Final`	Final transform with parameters `vdm : (C, spatial) tensor`, the upsampled VDM `control : (C, *shape) tensor`, the spline control points

RandomB0DistortionTransform

RandomB0DistortionTransform(dmax=0.1, shape=5, unit='fov', bound='circular', order=3, nearest_if_label=True, axis=None, *, dtype=None, device=None, shared=True, shared_vdm=None, **kwargs)

Bases: FinalTransform

Randomized elastic distortion along a single dimension.

Parameters:

Name	Type	Description	Default
`dmax`	`Sampler \| [list of] float`	Max displacement per dimension	`0.1`
`shape`	`Sampler \| [list of] int`	Number of spline control points	`5`
`unit`	`(fov, vox)`	Unit of `dmax`.	`'fov'`
`bound`	`(zeros, border, reflection, circular)`	Padding mode used for the deformed image.	`'zeros'`
`order`	`1..7`	Order of the splines that encode the smooth deformation.	`3`
`nearest_if_label`	`bool`	By default, if a tensor has an integer data type, it is deformed using label-specific resampling (each unique label is extracted and resampled using linear interpolation, and an argmax output label map is computed on the fly). If `nearest_if_label=True`, the entire label map will be resampled at once using nearest-neighbour interpolation.	`True`
`axis`	`Sampler \| int \| sequence[float]`	If int, the distortion is applied along this dimension. If sequence of floats, it is a unit vector that encodes the direction of the distortion in the voxel coordinate system.	`None`

Other Parameters:

Name	Type	Description
`returns`	`[list or dict of] {'input', 'output', 'flow', 'vdm', 'controls'}`	'input': The input image 'output': The deformed image 'flow': The flow field 'vdm': The voxel displacement map (VDM) 'controls': The control points of the VDM
`shared`	`(channels, tensors, channels + tensors, '')`	Apply same transform to all images/channels
`shared_vdm`	`(channels, tensors, channels + tensors, '', None)`	Whether to share random field across tensors and/or channels. By default: same as `shared`

Next `class-attribute` `instance-attribute`

Next = B0DistortionTransform

The transform type returned by make_final(..., max_depth=1).

Final `class-attribute` `instance-attribute`

Final = ApplyB0DistortionTransform

The transform type returned by make_final(..., max_depth=inf).

GradientEchoTransform

GradientEchoTransform(tr=0.025, te=0.007, alpha=20, pd=None, t1=None, t2=None, b1=1, mt=0, **kwargs)

Bases: FinalTransform

Spoiled Gradient Echo forward model

Parameters:

Name	Type	Description	Default
`tr`	`float`	Repetition time, in sec	`0.025`
`te`	`float`	Echo time, in sec	`0.007`
`alpha`	`float`	Nominal flip angle, in degree	`20`
`pd`	`float \| None`	Proton density (PD). If None, the first input channel is PD.	`None`
`t1`	`float \| None`	Longitudinal relaxation time (T1), in sec. If None, the second input channel is T1.	`None`
`t2`	`float \| None`	Apparent transverse relaxation time (T2), in sec. If None, the third input channel is T2.	`None`
`b1`	`float \| None`	Transmit efficiency (B1+). `1` means 100% efficiency. If None, the fourth input channel is B1+.	`1`
`mt`	`float \| None`	Magnetization transfer saturation (MTsat). If None, the fifth input channel is MTsat.	`0`

get_parameters

get_parameters(x)

Assign each input channel to the appropriate parameter.

xform

xform(x)

Parameters:

Name Type Description Default

x

(K, *spatial)

Parameters that were not set during class instantiation (i.e., whose value was None), in the order:

- pd: Proton density
- t1: Longitudinal relaxation time (T1), in sec.
- t2: Apparent transverse relaxation time (T2*), in sec.
- b1: Transmit efficiency (B1+). `1` means 100% efficiency.
- mt: Magnetization transfer saturation (MTsat).

required

ReturnGradientEchoParameters

ReturnGradientEchoParameters(param, **kwargs)

Bases: ReturnValueTransform

Store parameter maps

GMMGradientEchoTransform

GMMGradientEchoTransform(prm, fwd, mask=None, **kwargs)

Bases: FinalTransform

Apply GRE forward model to parameters, then mask

Parameters:

Name	Type	Description	Default
`prm`	`ReturnGradientEchoParameters`	Transform that returns the parameter maps required by `fwd`	required
`fwd`	`GradientEchoTransform`	Forward model that generates the GRE image from the parameters	required
`mask`	`Transform`	Transform that applies a mask to the output of `fwd`.	`None`

RandomGMMGradientEchoTransform

RandomGMMGradientEchoTransform(tr=0.05, te=0.05, alpha=90, pd=1, t1=10, t2=100, mt=0.1, b1=RandomMulFieldTransform(vmax=1.5), sigma=0.2, fwhm=2, **kwargs)

Bases: NonFinalTransform

Generate a Spoiled Gradient Echo image from synthetic PD/T1/T2 maps.

Parameters:

Name	Type	Description	Default
`tr`	`Sampler \| float`	Random sampler for repetition time, or upper bound	`0.05`
`te`	`Sampler \| float`	Random sampler for echo time, or upper bound	`0.05`
`alpha`	`Sampler \| float`	Random sampler for nominal flip angle, or upper bound	`90`
`pd`	`Sampler \| float`	Random sampler for proton density, or upper bound	`1`
`t1`	`Sampler \| float`	Random sampler for longitudinal relaxation, or upper bound	`10`
`t2`	`Sampler \| float`	Random sampler for apparent transverse relaxation, or upper bound	`100`
`mt`	`Sampler \| float`	Random sampler for magnetization transfer saturation, or upper bound	`0.1`
`b1`	`Transform`	A transformation that samples a smooth multiplicative field	`RandomMulFieldTransform(vmax=1.5)`
`sigma`	`Sampler \| float`	Random sampler for intra-class standard deviation (in percent), or upper bound	`0.2`
`fwhm`	`Sampler \| float`	Random sampler for intra-class smoothing (in voxels), or upper bound	`2`

Final `class-attribute` `instance-attribute`

Final = GMMGradientEchoTransform

The transform type returned by make_final.

Next `class-attribute` `instance-attribute`

Next = GMMGradientEchoTransform

The transform type returned by make_final.

get_parameters

get_parameters(x)

Sample each parameter.

cornucopia.qmri

RandomSusceptibilityMixtureTransform

Next class-attribute instance-attribute

Final class-attribute instance-attribute

SusceptibilityToFieldmapTransform

ShimTransform

OptimalShimTransform

Next class-attribute instance-attribute

Final class-attribute instance-attribute

RandomShimTransform

Next class-attribute instance-attribute

Final class-attribute instance-attribute

HertzToPhaseTransform

HertzToVoxelShiftTransform

ApplyB0DistortionTransform

make_vdm

make_flow

xform

B0DistortionTransform

Final class-attribute instance-attribute

Next class-attribute instance-attribute

make_final

RandomB0DistortionTransform

Next class-attribute instance-attribute

Final class-attribute instance-attribute

GradientEchoTransform

get_parameters

xform

ReturnGradientEchoParameters

GMMGradientEchoTransform

RandomGMMGradientEchoTransform

Final class-attribute instance-attribute

Next class-attribute instance-attribute

get_parameters

Next `class-attribute` `instance-attribute`

Final `class-attribute` `instance-attribute`

Next `class-attribute` `instance-attribute`

Final `class-attribute` `instance-attribute`

Next `class-attribute` `instance-attribute`

Final `class-attribute` `instance-attribute`

Final `class-attribute` `instance-attribute`

Next `class-attribute` `instance-attribute`

Next `class-attribute` `instance-attribute`

Final `class-attribute` `instance-attribute`

Final `class-attribute` `instance-attribute`

Next `class-attribute` `instance-attribute`