autoencoder.spherical.transform#

Module Contents#

Classes#

SignalToS2

Computes the spherical harmonic coefficients.

S2ToSignal

Computes the DWI from the spherical harmonic coefficients.

SO3ToSignal

Computes the DWI from the Wigner-D matrix coefficients.

Functions#

group_b_values(gradients, parameters, b_s, ti_idx = 0, te_idx = 0, data_grouped = None, data = None)

Group DWI gradients by b-values and returns the grouped gradient directions.

group_te_ti_b_values(parameters, data = None)

Group DWI gradient direction by b-values and TI and TE parameters if applicable.
autoencoder.spherical.transform.group_b_values(gradients, parameters, b_s, ti_idx=0, te_idx=0, data_grouped=None, data=None)#

Group DWI gradients by b-values and returns the grouped gradient directions. This function is necessary for the S^2 fourier transforms.

Parameters

  • gradients (numpy.ndarray) – empty numpy array to store gradients of shape: {TI, TE, b-value, gradient directions, xyz}. The gradient direction dimension can be an arbitrary value as it will be resized in this function.

  • parameters (numpy.ndarray) – ungrouped gradient directions.

  • b_s (numpy.ndarray) – all unique b-values.

  • ti_idx (Optional[int]) – TI index of the gradients attribute. Defaults to 0.

  • te_idx (Optional[int]) – TE index of the gradients attribute. Defaults to 0.

  • data_grouped (Optional[torch.Tensor]) – empty numpy array to store grouped data in. Defaults to None

  • data (Optional[torch.Tensor]) – Optional data to group. Defaults to None.

Returns

grouped gradient directions of shape {TI, TE, b-value, gradient directions, xyz} and grouped data of shape {batch size, TI, TE, gradient directions, b-values}

Return type

Tuple[numpy.ndarray, numpy.ndarray]

autoencoder.spherical.transform.group_te_ti_b_values(parameters, data=None)#

Group DWI gradient direction by b-values and TI and TE parameters if applicable. This function is necessary for the S^2 fourier transforms.

Parameters

  • parameters (numpy.ndarray) – ungrouped gradients directions.

  • data (Optional[torch.Tensor]) – Optional data to group. Defaults to None.

Returns

grouped gradient directions of shape {TI, TE, b-value, gradient directions, xyz} and optionally grouped data of shape {batch size, TI, TE, gradient directions, b-values}

Return type

Tuple[numpy.ndarray, Optional[numpy.ndarray]]

class autoencoder.spherical.transform.SignalToS2(gradients, sh_degree_max, inversion_function, **kwargs)#

Bases: torch.nn.Module

Computes the spherical harmonic coefficients. According to:

\[\hat{s}^m_l = \int_{S^2} s(r) \overline{Y^m_l(r)} dr\]

where \(\hat{s}^m_l\) are the spherical coefficients, \(r \in \mathbb{R}^3\), \(s : S^2 \mapsto \mathbb{C}\) and \(\overline{Y^m_l(r)}\) denotes the spherical harmonics, the overbar denotes the complex conjugation.

See “Spherical CNNs” by T. Cohen et al. for more information [2].

Example usage:

1# Create random dwi data with 90 gradient directions and 4 b-values
2gradients = torch.rand((1,1,4, 90, 3)) # {TI, TE, b-values, gradients, xyz}
3data = torch.rand((1,1,512, 90, 4)) # {TI, TE, batch size, gradients, b-values}
4
5signal_to_s2 = SignalToS2(gradients, 4, "gram_schmidt")
6signal_to_s2(data)
Parameters

  • gradients (Union[torch.Tensor, numpy.ndarray]) – Vectors to fit the Spherical Harmonics to. Has to be of shape (TI, TE, a, b, 3), where a are the number of b-values (shells) and b is the number of gradient directions. The vector is in cartesian coordinates (xyz).

  • sh_degree_max (int) – Maximum degree (l) of Spherical Harmonics to fit. Denoted by \(L_{max}\) in the equation.

  • inversion_function (Literal[lms, lms_tikhonov, lms_laplace_beltrami, gram_schmidt]) –

    name of the inversion function to apply. Available functions are:

Raises

ValueError – raised when an unknown inversion function is given.

property n_sh(self)#
forward(self, x)#
Parameters

x (torch.Tensor) –

lms_sh_inv(self, sh, l_max, **kwargs)#

Inversion of spherical harmonic basis with least-mean square

Parameters

  • sh (numpy.ndarray) – real spherical harmonics bases of even degree (each column is a basis)

  • l_max (int) – spherical harmonics degree

Returns

inverted spherical harmonic bases of even degree

Return type

numpy.ndarray

lms_tikhonov_sh_inv(self, sh, l_max, **kwargs)#

Inversion of spherical harmonic basis with least-mean square regularized with Tikhonov regularization term [3]

Parameters

  • sh (numpy.ndarray) – real spherical harmonics bases of even degree (each column is a basis)

  • l_max (int) – spherical harmonics degree

  • **lambda_ (float) – regularization weight. Defaults to 0.006

Returns

inverted spherical harmonic bases of even degree

Return type

numpy.ndarray

lms_laplace_beltrami_sh_inv(self, sh, l_max, **kwargs)#

Inversion of spherical harmonic basis with least-mean square regularized with Laplace-Beltrami regularization term [4]

Parameters

  • sh (numpy.ndarray) – real spherical harmonics bases of even degree (each column is a basis)

  • l_max (int) – spherical harmonics degree

  • **lambda_ (float) – regularization weight. Defaults to 0.006

Returns

inverted spherical harmonic bases of even degree

Return type

numpy.ndarray

gram_schmidt_sh_inv(self, sh, l_max, **kwargs)#

Inversion of spherical harmonic basis with Gram-Schmidt orthonormalization process [5]

Parameters

  • sh (numpy.ndarray) – real spherical harmonics bases of even degree (each column is a basis)

  • l_max (int) – spherical harmonics degree

  • **n_iter (int) – number of iterations for degree shuffling. Defaults to 1000

Returns

inverted spherical harmonic bases of even degree

Return type

numpy.ndarray

class autoencoder.spherical.transform.S2ToSignal(gradients, sh_degree_max)#

Bases: torch.nn.Module

Computes the DWI from the spherical harmonic coefficients. According to:

\[s(r) = \sum^{L_{max}}_{l=0} \sum^{m=l}_{m=-l} \hat{s}^m_l Y^m_l(r)\]

where \(s(r)\) is the DWI signal, \(r \in \mathbb{R}^3\), \(Y^m_l(r)\) denotes the spherical harmonics and \(\hat{s}^m_l\) are the spherical coefficients.

See “Spherical CNNs” by T. Cohen et al. for more information [2].

Example usage:

1# Create random sh coefficients with 90 gradient directions and 4 b-values
2gradients = torch.rand((4, 90, 3)) # {b-values, gradients, xyz}
3data = torch.rand((512, 90, 4)) # {batch size, gradients, SH coefficients}
4
5s2_to_signal = S2ToSignal(gradients, 4)
6s2_to_signal(data)
Parameters

  • gradients (Union[torch.Tensor, numpy.ndarray]) – Vectors to fit the Spherical Harmonics to. Has to be of shape (TI, TE, a, b, 3), where a are the number of b-values (shells) and b is the number of gradient directions. The vector is in cartesian coordinates (xyz).

  • sh_degree_max (int) – Maximum degree (l) of Spherical Harmonics to fit. Denoted by \(L_{max}\) in the equation.

property n_sh(self)#
forward(self, x)#
Parameters

x (torch.Tensor) –

class autoencoder.spherical.transform.SO3ToSignal(gradients, sh_degree_max)#

Bases: torch.nn.Module

Computes the DWI from the Wigner-D matrix coefficients. Every coefficient in the Wigner-D matrix where \(m != 0\) are thrown away, leaving us with the spherical harmonic coefficients. More formally:

\[Y_l^n(r) = D_l^{m=0,n}(R)\]

After this, the same steps are used as in S2ToSignal.

Example usage:

1gradients = torch.rand((4, 90, 3)) # {b-values, gradients, xyz}
2data = {
3    0: torch.rand((512, 90, 1, 1)), # {batch size, gradients, Wigner-D coefficients, Wigner-D coefficients}
4    2: torch.rand((512, 90, 5, 5)),
5    4: torch.rand((512, 90, 9, 9))
6} # data is expected to be a dict where each key is a sh degree.
7
8so3_to_signal = SO3ToSignal(gradients, 4)
9so3_to_signal(data)
Parameters

  • gradients (torch.Tensor) – Vectors to fit the Spherical Harmonics to. Has to be of shape (a,b,3), where a are the number of b-values (shells) and b is the number of gradient directions. The vector is in cartesian coordinates (xyz).

  • sh_degree_max (int) – Maximum degree of Spherical Harmonics to fit.

forward(self, x)#
Parameters

x (Dict[int, torch.Tensor]) –