pytomography.priors

This module contains classes/functionality for encorporating priors in statistical reconstruction algorithms. Under the modification \(L(\tilde{f}, f) \to L(\tilde{f}, f)e^{-\beta V(f)}\), the log-liklihood becomes \(\ln L(\tilde{f},f) - \beta V(f)\). Typically, the prior has a form \(V(f) = \sum_{r,s} w_{r,s} \phi(f_r,f_s)\). In this expression, \(r\) represents a voxel in the object, \(s\) represents a voxel nearby to voxel \(r\), and \(w_{r,s}\) represents a weighting between the voxels.

Submodules

• pytomography.priors.nearest_neighbour
• pytomography.priors.prior

Package Contents

Classes

Prior	Abstract class for implementation of prior \(V(f)\) where \(V\) is from the log-posterior probability \(\ln L(\tilde{f}, f) - \beta V(f)\). Any function inheriting from this class should implement a foward method that computes the tensor \(\frac{\partial V}{\partial f_r}\) where \(f\) is an object tensor.
NearestNeighbourPrior	Generic class for the nearest neighbour prior.
QuadraticPrior	Subclass of NearestNeighbourPrior corresponding to a quadratic prior: namely \(\phi_0(f_r, f_s) = 1/4 \left[(fr-fs)/\delta\right]^2\) and where the gradient is determined by \(\phi_1(f_r, f_s) = (f_r-f_s)/\delta\)
LogCoshPrior	Subclass of NearestNeighbourPrior corresponding to a logcosh prior: namely \(\phi_0(f_r, f_s) = \tanh((f_r-f_s)/\delta)\) and where the gradient is determined by \(\phi_1(f_r, f_s) = \log \cosh \left[(f_r-f_s)/\delta\right]\)
RelativeDifferencePrior	Subclass of NearestNeighbourPrior corresponding to the relative difference prior: namely \(\phi_0(f_r, f_s) = \frac{(f_r-f_s)^2}{f_r+f_s+\gamma|f_r-f_s|}\) and where the gradient is determined by \(\phi_1(f_r, f_s) = \frac{2(f_r-f_s)(\gamma|f_r-f_s|+3f_s + f_r)}{(\gamma|f_r-f_s|+f_r+f_s)^2}\)
NeighbourWeight	Abstract class for assigning weight \(w_{r,s}\) in nearest neighbour priors.
EuclideanNeighbourWeight	Implementation of NeighbourWeight where inverse Euclidean distance is the weighting between nearest neighbours.
AnatomyNeighbourWeight	Implementation of NeighbourWeight where inverse Euclidean distance and anatomical similarity is used to compute neighbour weight.
TopNAnatomyNeighbourWeight	Implementation of NeighbourWeight where inverse Euclidean distance and anatomical similarity is used. In this case, only the top N most similar neighbours are used as weight

class pytomography.priors.Prior(beta, obj2obj_transforms=[])

Abstract class for implementation of prior \(V(f)\) where \(V\) is from the log-posterior probability \(\ln L(\tilde{f}, f) - \beta V(f)\). Any function inheriting from this class should implement a foward method that computes the tensor \(\frac{\partial V}{\partial f_r}\) where \(f\) is an object tensor.

Parameters:

• beta (float) – Used to scale the weight of the prior

• obj2obj_transforms (Sequence) – Sequence of transforms applied after computation of prior or gradients.

set_object_meta(object_meta)

Sets object metadata parameters.

Parameters:

object_meta (ObjectMeta) – Object metadata describing the system.

Return type:

None

set_beta_scale(factor)

Sets a scale factor for \(\beta\) required for OSEM when finite subsets are used per iteration.

Parameters:

factor (float) – Value by which to scale \(\beta\)

Return type:

None

set_FOV_scale(FOV_scale)

Sets a positionally dependent scaling factor within the FOV for the prior.

Parameters:

• torch.Tensor (float) – Scaling factor

• FOV_scale (torch.Tensor) –

Return type:

None

set_object(object)

Sets the object \(f_r\) used to compute \(\frac{\partial V}{\partial f_r}\)

Parameters:

object (torch.tensor) – Tensor of size [batch_size, Lx, Ly, Lz] representing \(f_r\).

Return type:

None

abstract __call__()

Abstract method to compute the gradient of the prior based on the self.object attribute.

class pytomography.priors.NearestNeighbourPrior(beta, weight=None, **kwargs)

Bases: pytomography.priors.prior.Prior

Generic class for the nearest neighbour prior.

Parameters:

• beta (float) – Used to scale the weight of the prior

• weight (NeighbourWeight, optional) – this specifies \(w_{r,s}\) above. If None, then uses EuclideanNeighbourWeight, which weights neighbouring voxels based on their euclidean distance. Defaults to None.

set_object_meta(object_meta)

Sets object metadata parameters.

Parameters:

object_meta (ObjectMeta) – Object metadata describing the system.

Return type:

None

_pair_contribution(phi, beta_scale=False, second_order_derivative_object=None)

Helper function used to compute prior and associated gradients

Returns:

Tensor of shape [batch_size, Lx, Ly, Lz].

Return type:

torch.tensor

Parameters:

• phi (collections.abc.Callable) –

• second_order_derivative_object (torch.Tensor | None) –

abstract phi0(fr, fs)

abstract phi1(fr, fs)

abstract phi2_1(fr, fs)

abstract phi2_2(fr, fs)

__call__(derivative_order=0)

Used to compute the prior with gradient of specified order. If order 0, then returns a float (the value of the prior). If order 1, then returns a torch.Tensor representative of the prior gradient at each voxel. If order 2, then returns a callable function (representative of a higher order tensor but without storing each component).

Parameters:

derivative_order (int, optional) – The order of the derivative to compute. This will specify the ouput; only possible values are 0, 1, or 2. Defaults to 0.

Raises:

NotImplementedError – for cases where the derivative order is not between 0 and 2.

Returns:

The prior with derivative of specified order.

Return type:

float | torch.Tensor | Callable

class pytomography.priors.QuadraticPrior(beta, weight=None, delta=1)

Bases: NearestNeighbourPrior

Subclass of NearestNeighbourPrior corresponding to a quadratic prior: namely \(\phi_0(f_r, f_s) = 1/4 \left[(fr-fs)/\delta\right]^2\) and where the gradient is determined by \(\phi_1(f_r, f_s) = (f_r-f_s)/\delta\)

Parameters:

• beta (float) – Used to scale the weight of the prior

• weight (NeighbourWeight, optional) –

• delta (float, optional) – Parameter \(\delta\) in equation above. Defaults to 1.

phi0(fr, fs)

phi1(fr, fs)

class pytomography.priors.LogCoshPrior(beta, delta=1, weight=None)

Bases: NearestNeighbourPrior

Subclass of NearestNeighbourPrior corresponding to a logcosh prior: namely \(\phi_0(f_r, f_s) = \tanh((f_r-f_s)/\delta)\) and where the gradient is determined by \(\phi_1(f_r, f_s) = \log \cosh \left[(f_r-f_s)/\delta\right]\)

Parameters:

• beta (float) – Used to scale the weight of the prior

• delta (float, optional) – Parameter \(\delta\) in equation above. Defaults to 1.

• weight (NeighbourWeight, optional) –

phi0(fr, fs)

phi1(fr, fs)

class pytomography.priors.RelativeDifferencePrior(beta, weight=None, gamma=1, delta=pytomography.delta)

Bases: NearestNeighbourPrior

Subclass of NearestNeighbourPrior corresponding to the relative difference prior: namely \(\phi_0(f_r, f_s) = \frac{(f_r-f_s)^2}{f_r+f_s+\gamma|f_r-f_s|}\) and where the gradient is determined by \(\phi_1(f_r, f_s) = \frac{2(f_r-f_s)(\gamma|f_r-f_s|+3f_s + f_r)}{(\gamma|f_r-f_s|+f_r+f_s)^2}\)

Parameters:

• beta (float) – Used to scale the weight of the prior

• gamma (float, optional) – Parameter \(\gamma\) in equation above. Defaults to 1.

• weight (NeighbourWeight, optional) –

phi0(fr, fs)

phi1(fr, fs)

phi2_1(fr, fs)

phi2_2(fr, fs)

class pytomography.priors.NeighbourWeight

Abstract class for assigning weight \(w_{r,s}\) in nearest neighbour priors.

set_object_meta(object_meta)

Sets object meta to get appropriate spacing information

Parameters:

object_meta (ObjectMeta) – Object metadata.

Return type:

None

abstract __call__(coords)

Computes the weight \(w_{r,s}\) given the relative position \(s\) of the nearest neighbour

Parameters:

coords (Sequence[int,int,int]) – Tuple of coordinates (i,j,k) that represent the shift of neighbour \(s\) relative to \(r\).

class pytomography.priors.EuclideanNeighbourWeight

Bases: NeighbourWeight

Implementation of NeighbourWeight where inverse Euclidean distance is the weighting between nearest neighbours.

__call__(coords)

Computes the weight \(w_{r,s}\) using inverse Euclidean distance between \(r\) and \(s\).

Parameters:

coords (Sequence[int,int,int]) – Tuple of coordinates (i,j,k) that represent the shift of neighbour \(s\) relative to \(r\).

class pytomography.priors.AnatomyNeighbourWeight(anatomy_image, similarity_function)

Bases: NeighbourWeight

Implementation of NeighbourWeight where inverse Euclidean distance and anatomical similarity is used to compute neighbour weight.

Parameters:

• anatomy_image (torch.Tensor[batch_size,Lx,Ly,Lz]) – Object corresponding to an anatomical image (such as CT/MRI)

• similarity_function (Callable) – User-defined function that computes the similarity between \(r\) and \(s\) in the anatomical image. The function should be bounded between 0 and 1 where 1 represets complete similarity and 0 represents complete dissimilarity.

set_object_meta(object_meta)

Sets object meta to get appropriate spacing information

Parameters:

object_meta (ObjectMeta) – Object metadata.

__call__(coords)

Computes the weight \(w_{r,s}\) using inverse Euclidean distance and anatomical similarity between \(r\) and \(s\).

Parameters:

coords (Sequence[int,int,int]) – Tuple of coordinates (i,j,k) that represent the shift of neighbour \(s\) relative to \(r\).

class pytomography.priors.TopNAnatomyNeighbourWeight(anatomy_image, N_neighbours)

Bases: NeighbourWeight

Implementation of NeighbourWeight where inverse Euclidean distance and anatomical similarity is used. In this case, only the top N most similar neighbours are used as weight

Parameters:

• anatomy_image (torch.Tensor[batch_size,Lx,Ly,Lz]) – Object corresponding to an anatomical image (such as CT/MRI)

• N_neighbours (int) – Number of most similar neighbours to use

set_object_meta(object_meta)

Sets object meta to get appropriate spacing information

Parameters:

object_meta (ObjectMeta) – Object metadata.

compute_inclusion_tensor()

__call__(coords)

Computes the weight \(w_{r,s}\) using inverse Euclidean distance and anatomical similarity between \(r\) and \(s\).

Parameters:

coords (Sequence[int,int,int]) – Tuple of coordinates (i,j,k) that represent the shift of neighbour \(s\) relative to \(r\).