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#

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

Implementation of priors where gradients depend on summation over nearest neighbours \(s\) to voxel \(r\) given by : \(\frac{\partial V}{\partial f_r}=\beta\sum_{r,s}w_{r,s}\phi(f_r, f_s)\) where \(V\) is from the log-posterior probability \(\ln L (\tilde{f}, f) - \beta V(f)\).

QuadraticPrior

Subclass of NearestNeighbourPrior where \(\phi(f_r, f_s)= (f_r-f_s)/\delta\) corresponds to a quadratic prior \(V(f)=\frac{1}{4}\sum_{r,s} w_{r,s} \left(\frac{f_r-f_s}{\delta}\right)^2\)

LogCoshPrior

Subclass of NearestNeighbourPrior where \(\phi(f_r,f_s)=\tanh((f_r-f_s)/\delta)\) corresponds to the logcosh prior \(V(f)=\sum_{r,s} w_{r,s} \log\cosh\left(\frac{f_r-f_s}{\delta}\right)\)

RelativeDifferencePrior

Subclass of NearestNeighbourPrior where \(\phi(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}\) corresponds to the relative difference prior \(V(f)=\sum_{r,s} w_{r,s} \frac{(f_r-f_s)^2}{f_r+f_s+\gamma|f_r-f_s|}\)

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.

class pytomography.priors.Prior(beta)[source]#

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

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_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 compute_gradient()#

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

class pytomography.priors.NearestNeighbourPrior(beta, phi, weight=None, **kwargs)[source]#

Bases: pytomography.priors.prior.Prior

Implementation of priors where gradients depend on summation over nearest neighbours \(s\) to voxel \(r\) given by : \(\frac{\partial V}{\partial f_r}=\beta\sum_{r,s}w_{r,s}\phi(f_r, f_s)\) where \(V\) is from the log-posterior probability \(\ln L (\tilde{f}, f) - \beta V(f)\).

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

  • phi (function) – Function \(\phi\) used in formula above. Input arguments should be \(f_r\), \(f_s\), and any kwargs passed to this initialization function.

  • weight (NeighbourWeight, optional) –

set_object_meta(object_meta)#

Sets object metadata parameters.

Parameters:

object_meta (ObjectMeta) – Object metadata describing the system.

Return type:

None

compute_gradient()#

Computes the gradient of the prior on self.object

Returns:

Tensor of shape [batch_size, Lx, Ly, Lz] representing \(\frac{\partial V}{\partial f_r}\)

Return type:

torch.tensor

class pytomography.priors.QuadraticPrior(beta, delta=1, weight=None)[source]#

Bases: NearestNeighbourPrior

Subclass of NearestNeighbourPrior where \(\phi(f_r, f_s)= (f_r-f_s)/\delta\) corresponds to a quadratic prior \(V(f)=\frac{1}{4}\sum_{r,s} w_{r,s} \left(\frac{f_r-f_s}{\delta}\right)^2\)

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) –

class pytomography.priors.LogCoshPrior(beta, delta=1, weight=None)[source]#

Bases: NearestNeighbourPrior

Subclass of NearestNeighbourPrior where \(\phi(f_r,f_s)=\tanh((f_r-f_s)/\delta)\) corresponds to the logcosh prior \(V(f)=\sum_{r,s} w_{r,s} \log\cosh\left(\frac{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) –

class pytomography.priors.RelativeDifferencePrior(beta=1, gamma=1, epsilon=1e-08, weight=None)[source]#

Bases: NearestNeighbourPrior

Subclass of NearestNeighbourPrior where \(\phi(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}\) corresponds to the relative difference prior \(V(f)=\sum_{r,s} w_{r,s} \frac{(f_r-f_s)^2}{f_r+f_s+\gamma|f_r-f_s|}\)

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

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

  • epsilon (float, optional) – Prevent division by 0, Defaults to 1e-8.

  • weight (NeighbourWeight, optional) –

class pytomography.priors.NeighbourWeight[source]#

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[source]#

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)[source]#

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\).