pytomography.priors.nearest_neighbour

The code here is implementation of priors that depend on summation over nearest neighbours \(s\) to voxel \(r\) given by \(V(f) = \beta \sum_{r,s}w_{r,s}\phi_0(f_r, f_s)\). These priors have first order gradients given by \(\nabla_r V(f) = \sum_s w_{r,s} \phi_1(f_r, f_s)\) where \(\phi_1(f_r, f_s) = \nabla_r (\phi_0(f_r, f_s) + \phi_0(f_s, f_r))\). In addition, they have higher order gradients given by \(\nabla_{r'r} V(f) = \theta(r-r')\left(\sum_s w_{r,s} \phi_2^{(1)}(f_r, f_s)\right) + w_{r,r'}\phi_2^{(2)}(f_r, f_{r'})\) where \(\phi_2^{(1)}(f_r, f_s) = \nabla_r \phi_1(f_r, f_s)\) and \(\phi_2^{(2)}(f_r, f_s) = \nabla_s \phi_1(f_r, f_s)\). The particular \(\phi\) functions must be implemented by subclasses depending on the functionality required. The second order derivative is only required to be implemented if one wishes to use the prior function in error estimation

Module Contents

Classes

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