pytomography.priors — PyTomography 0.8.0 documentation

Skip to main content
`Ctrl`+`K`

# `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` | 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.
`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)

  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)

  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)

  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)

  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, weight=None)

  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.

    - weight (NeighbourWeight, optional) –

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