beetroots.modelling.priors package

Submodules

beetroots.modelling.priors.abstract_prior module

class beetroots.modelling.priors.abstract_prior.PriorProbaDistribution(D: int, N: int)

Bases: ABC

Abstract Base Class for a probability distribution on non-countable set

D

number of distinct physical parameters

Type:

int

N

number of pixels in each physical dimension

Type:

int

abstract gradient_neglog_pdf(Theta: ndarray) → ndarray

abstract hess_diag_neglog_pdf(Theta: ndarray) → ndarray

abstract neglog_pdf(Theta: ndarray) → float | ndarray

beetroots.modelling.priors.abstract_spatial_prior module

class beetroots.modelling.priors.abstract_spatial_prior.SpatialPrior(spatial_prior_params: SpatialPriorParams, cloud_name: str, D: int, N: int, df: DataFrame, list_idx_sampling: List[int])

Bases: PriorProbaDistribution

Abstract Base Class for a spatial regularizing prior

D

number of distinct physical parameters

Type:

int

N

number of pixels in each physical dimension

Type:

int

build_sites(df: DataFrame) → dict[int, ndarray]

builds the site from the DataFrame of positions

Parameters:

df (pd.DataFrame) – positions of the pixels

Returns:

set of sites and corresponding pixels. Forms a partition of the full set of pixels.

Return type:

dict[int, np.ndarray]

dict_neighbors

dict_sites

sites of the graph induced the spatial regularization. A site is a set of nodes that are conditionally independent.

Type:

dict[int, np.ndarray]

abstract gradient_neglog_pdf(Theta: ndarray) → ndarray

Computes the gradient of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

gradient of the spatial regularization

Return type:

np.array of shape (N, D)

abstract hess_diag_neglog_pdf(Theta: ndarray) → ndarray

Computes the diagonal of the hessian of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

diagonal of the hessian of the spatial regularization

Return type:

np.array of shape (N, D)

initial_weights

initial weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

list_edges

set of edges in the graph induced by the spatial regularization

Type:

np.ndarray

abstract neglog_pdf(Theta: ndarray, with_weights: bool = True, **kwargs) → ndarray

computes the negative log pdf (defined up to some multiplicative constant)

Parameters:

Theta (np.array of shape (N, D)) – set of D maps on which we want to evaluate the neg log prior

Returns:

neglog_p – set of the D neg log priors evaluation

Return type:

np.array of shape (D,)

use_next_nearest_neighbors

wether to use the next nearest neighbors (i.e., neighbors in diagonal)

Type:

bool

weights

current value of weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

beetroots.modelling.priors.abstract_spatial_prior.build_list_edges(df: DataFrame, use_next_nearest_neighbors: bool = True) → ndarray

builds the list of edges necessary in the rest of the functions of this file

Parameters:

• df (pandas.DataFrame) – observation map data. The index needs to contain 2 columns (one for the x-coordinate of the pixel and one for its y-coordinate)

• use_next_nearest_neighbors (bool, optional) – wether or not to use the next nearest neighbors, i.e., in diagonal, by default True

Returns:

list_edges – list of 2 by 2 neighboring relations without duplicates (each pair is ordered by lowest id to highest id)

Return type:

numpy.array of shape (-1, 2)

beetroots.modelling.priors.l22_laplacian_prior module

(deprecated) Implementation of L22 Laplacian prior. False implementation.

class beetroots.modelling.priors.l22_laplacian_prior.L22LaplacianSpatialPrior(spatial_prior_params: SpatialPriorParams, cloud_name: str, D: int, N: int, df: DataFrame, list_idx_sampling: List[int])

Bases: SpatialPrior

L22 smooth spatial prior, valid for both 1D and 2D tensors. Its pdf is defined as

\[\forall d \in [1, D], \quad \pi(\Theta_{\cdot d}) \propto \exp \left[- \tau_d \Vert \Delta \Theta_{\cdot d} \Vert_F^2 \right]\]

where \(\Vert \cdot \Vert_F\) denotes the Fröbenius norm and \(\Delta \Theta_{\cdot d}\) is the Laplacian of vector :math:ùTheta_{cdot d}`.

D

number of distinct physical parameters

Type:

int

N

number of pixels in each physical dimension

Type:

int

dict_neighbors

dict_sites

sites of the graph induced the spatial regularization. A site is a set of nodes that are conditionally independent.

Type:

dict[int, np.ndarray]

gradient_neglog_pdf(Theta: ndarray, idx_pix: ndarray) → ndarray

Computes the gradient of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

gradient of the spatial regularization

Return type:

np.array of shape (N, D)

hess_diag_neglog_pdf(Theta: ndarray, idx_pix: ndarray) → ndarray

Computes the diagonal of the hessian of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

diagonal of the hessian of the spatial regularization

Return type:

np.array of shape (N, D)

initial_weights

initial weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

list_edges

set of edges in the graph induced by the spatial regularization

Type:

np.ndarray

neglog_pdf(Theta: ndarray, idx_pix: ndarray, with_weights: bool = True, full: bool = False, pixelwise: bool = False, chromatic_gibbs: bool = False, **kwargs) → ndarray

computes the negative log pdf (defined up to some multiplicative constant)

Parameters:

Theta (np.array of shape (N, D)) – set of D maps on which we want to evaluate the neg log prior

Returns:

neglog_p – set of the D neg log priors evaluation

Return type:

np.array of shape (D,)

use_next_nearest_neighbors

wether to use the next nearest neighbors (i.e., neighbors in diagonal)

Type:

bool

weights

current value of weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

beetroots.modelling.priors.l22_laplacian_prior.compute_gradient_from_laplacian(laplacian_: ndarray, idx_pix: ndarray, list_edges: ndarray) → ndarray

evaluates the gradient from the Laplacian matrix

Parameters:

• laplacian (np.ndarray) – Laplacian matrix

• list_edges (np.ndarray) – array containing all the graph edges, identified with pairs of indices of neighboring pixels

Returns:

gradient of the prior neg-log pdf

Return type:

np.ndarray

beetroots.modelling.priors.l22_laplacian_prior.compute_laplacian(Theta: ndarray, list_edges: ndarray, idx_pix: ndarray) → ndarray

evaluates the image Laplacian for each of the D maps, \(\Delta \Theta_{\cdot d}\)

Parameters:

• Theta (np.ndarray of shape (N, D)) – D vectors of N pixels

• list_edges (np.ndarray) – set of edges in the graph induced by the spatial regularization

Returns:

image Laplacian for each of the D maps

Return type:

np.ndarray of shape (N, D)

beetroots.modelling.priors.l22_laplacian_prior.compute_neglog_chromatic_from_laplacian2(laplacian_2: ndarray, list_edges: ndarray, idx_pix: ndarray) → ndarray

evaluates the negative log pdf for each of the D maps, \(\Delta \Theta_{\cdot d}\)

Parameters:

• Theta (np.ndarray of shape (N, D)) – D vectors of N pixels

• dict_neighbors (np.ndarray) – set of neighbors for each pixel

• weights (np.ndarray) – weights for each pixel

Returns:

negative log pdf for each of the D maps

Return type:

np.ndarray of shape (N, D)

beetroots.modelling.priors.l22_prior module

(deprecated) Implementation of L2 norm on image gradient prior

class beetroots.modelling.priors.l22_prior.L22SpatialPrior(spatial_prior_params: SpatialPriorParams, cloud_name: str, D: int, N: int, df: DataFrame, list_idx_sampling: List[int])

Bases: SpatialPrior

L22 smooth spatial prior, valid for both 1D and 2D tensors. Its pdf is defined as

\[\forall d \in [1, D], \quad p(x_d) \propto \exp \left[- \tau_d \Vert \nabla Theta_d \Vert_F^2 \right]\]

where \(\Vert \cdot \Vert_F\) denotes the Fröbenius norm

D

number of distinct physical parameters

Type:

int

N

number of pixels in each physical dimension

Type:

int

dict_neighbors

dict_sites

sites of the graph induced the spatial regularization. A site is a set of nodes that are conditionally independent.

Type:

dict[int, np.ndarray]

gradient_neglog_pdf(Theta: ndarray) → ndarray

Computes the gradient of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

gradient of the spatial regularization

Return type:

np.array of shape (N, D)

hess_diag_neglog_pdf(Theta: ndarray) → ndarray

Computes the diagonal of the hessian of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

diagonal of the hessian of the spatial regularization

Return type:

np.array of shape (N, D)

initial_weights

initial weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

list_edges

set of edges in the graph induced by the spatial regularization

Type:

np.ndarray

neglog_pdf(Theta: ndarray, with_weights: bool = True, **kwargs) → ndarray

computes the negative log pdf (defined up to some multiplicative constant)

Parameters:

Theta (np.array of shape (N, D)) – set of D maps on which we want to evaluate the neg log prior

Returns:

neglog_p – set of the D neg log priors evaluation

Return type:

np.array of shape (D,)

neglog_pdf_one_pix(Theta: ndarray, n: int, list_pixel_candidates: ndarray) → ndarray

computes the neg log-prior when only one pixel is modified

Parameters:

• Theta (np.ndarray of shape (N, D)) – current iterate

• n (int) – the index of the pixel to consider (0 <= n <= N - 1)

• list_pixel_candidates (np.ndarray of shape (N_candidates, D)) – the list of all candidates for pixel n

Returns:

nl_priors – the leg log-prior of the candidates

Return type:

np.ndarray of shape (N_candidates,)

use_next_nearest_neighbors

wether to use the next nearest neighbors (i.e., neighbors in diagonal)

Type:

bool

weights

current value of weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

beetroots.modelling.priors.smooth_indicator_prior module

class beetroots.modelling.priors.smooth_indicator_prior.SmoothIndicatorPrior(D: int, N: int, indicator_margin_scale: float, lower_bounds: ndarray, upper_bounds: ndarray, list_idx_sampling: List[int])

Bases: PriorProbaDistribution

This prior encodes validity intervals \([\underline{\theta}_{d}, \overline{\theta}_{d}]]\) the physical parameters \(\theta_{nd}\) (for \(d \in [\![1, D]\!]\)). The negative log of this prior is

\[\begin{split}\forall n, d, \quad \iota^{\Delta}_{[\underline{\theta}_{d}, \overline{\theta}_{d}]}(\theta_{n,d}) = \begin{cases} 0 \quad \text{ if } \theta_{n,d} \in [\underline{\theta}_{d}, \overline{\theta}_{d}]\\ \left(\frac{\theta_{n,d} - \underline{\theta}_{d}}{\Delta} \right)^4 \quad \text{ if } \theta_{n,d} < \underline{\theta}_{d}\\ \left(\frac{\theta_{n,d} - \overline{\theta}_{d}}{\Delta} \right)^4 \quad \text{ if } \theta_{n,d} > \overline{\theta}_{d} \end{cases}\end{split}\]

with \(\Delta > 0\) a margin scaling parameter.

D

number of distinct physical parameters

Type:

int

N

number of pixels in each physical dimension

Type:

int

gradient_neglog_pdf(Theta: ndarray) → ndarray

gradient of the negative log pdf of the smooth indicator prior

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

g – gradient

Return type:

np.array of shape (N, D)

hess_diag_neglog_pdf(Theta: ndarray) → ndarray

diagonal of the Hessian of the negative log pdf of the smooth indicator prior

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

hess_diag – [description]

Return type:

np.array of shape (N, D)

indicator_margin_scale

scaling parameter \(\Delta\)

Type:

float

lower_bounds

validity interval lower bounds of the set of sampled physical parameters

Type:

np.ndarray

lower_bounds_full

validity interval lower bounds of the full set of D physical parameters

Type:

np.ndarray

neglog_pdf(Theta: ndarray, pixelwise: bool = False) → ndarray

compute the negative log of the prior that approximates the indicator function

\[\begin{split}\forall n, d, \quad \iota^{\Delta}_{[\underline{\theta}_{d}, \overline{\theta}_{d}]}(\theta_{n,d}) = \begin{cases} 0 \quad \text{ if } \theta_{n,d} \in [\underline{\theta}_{d}, \overline{\theta}_{d}]\\ \left(\frac{\theta_{n,d} - \underline{\theta}_{d}}{\Delta} \right)^4 \quad \text{ if } \theta_{n,d} < \underline{\theta}_{d}\\ \left(\frac{\theta_{n,d} - \overline{\theta}_{d}}{\Delta} \right)^4 \quad \text{ if } \theta_{n,d} > \overline{\theta}_{d} \end{cases}\end{split}\]

Parameters:

• Theta (np.array of shape (N, D)) – current iterate

• pixelwise (bool, optional) – wether to return an aggregated result per pixel (if True) or per map (if False), by default False

Returns:

neglog_p – negative log of the smooth indicator prior pdf

Return type:

np.ndarray of shape (D,) or (N,)

neglog_pdf_one_pix(Theta: ndarray) → ndarray

compute the negative log of the prior that approximates the indicator function

\[\begin{split}\forall n, d, \quad \iota^{\Delta}_{[\underline{\theta}_{d}, \overline{\theta}_{d}]}(\theta_{n,d}) = \begin{cases} 0 \quad \text{ if } \theta_{n,d} \in [\underline{\theta}_{d}, \overline{\theta}_{d}]\\ \left(\frac{\theta_{n,d} - \underline{\theta}_{d}}{\Delta} \right)^4 \quad \text{ if } \theta_{n,d} < \underline{\theta}_{d}\\ \left(\frac{\theta_{n,d} - \overline{\theta}_{d}}{\Delta} \right)^4 \quad \text{ if } \theta_{n,d} > \overline{\theta}_{d} \end{cases}\end{split}\]

Parameters:

Theta (np.array of shape (N_candidates, D)) – current iterate

Returns:

neglog_p – negative log of the smooth indicator prior per map

Return type:

numpy array of shape (N_candidates,)

upper_bounds

validity interval upper bounds of the set of sampled physical parameters

Type:

np.ndarray

upper_bounds_full

validity interval upper bounds of the full set of D physical parameters

Type:

np.ndarray

beetroots.modelling.priors.smooth_indicator_prior.gradient_penalty(Theta: ndarray, lower_bounds: ndarray, upper_bounds: ndarray, indicator_margin_scale: float) → ndarray

beetroots.modelling.priors.smooth_indicator_prior.hess_diag_penalty(Theta: ndarray, lower_bounds: ndarray, upper_bounds: ndarray, indicator_margin_scale: float) → ndarray

beetroots.modelling.priors.smooth_indicator_prior.penalty(Theta: ndarray, lower_bounds: ndarray, upper_bounds: ndarray, indicator_margin_scale: float) → ndarray

beetroots.modelling.priors.smooth_indicator_prior.penalty_one_pix(Theta: ndarray, lower_bounds: ndarray, upper_bounds: ndarray, indicator_margin_scale: float) → ndarray

beetroots.modelling.priors.spatial_prior_params module

class beetroots.modelling.priors.spatial_prior_params.SpatialPriorParams(name: str, use_next_nearest_neighbors: bool, initial_regu_weights: ndarray | List[float])

Bases: object

Dataclass to contain data on the spatial prior

Parameters:

• name (str) – name of the spatial regularization type, must be an element of [“L2-laplacian”, “L2-gradient”]

• use_next_nearest_neighbors (bool) – wether or not to use the next nearest neighbors, i.e., in diagonal

• initial_regu_weights (Union[np.ndarray, List[float]]) – initial regularization weights (the regularization weights can be tuned automatically during the Markov chain)

initial_regu_weights

initial regularization weights (the regularization weights can be tuned automatically during the Markov chain)

Type:

Union[np.ndarray, List[float]

name

name of the spatial regularization type, must be an element of [“L2-laplacian”, “L2-gradient”]

Type:

str

use_next_nearest_neighbors

wether or not to use the next nearest neighbors, i.e., in diagonal

Type:

bool

beetroots.modelling.priors.tv_1D_prior module

Defines the Total variation spatial regularization and its derivatives (for 1D signals only)

class beetroots.modelling.priors.tv_1D_prior.TVeps1DSpatialPrior(D: int, N: int, df: DataFrame, weights: ndarray | None = None, eps: float = 0.001)

Bases: SpatialPrior

D

number of distinct physical parameters

Type:

int

N

number of pixels in each physical dimension

Type:

int

dict_neighbors

dict_sites

sites of the graph induced the spatial regularization. A site is a set of nodes that are conditionally independent.

Type:

dict[int, np.ndarray]

gradient_neglog_pdf(x: ndarray) → ndarray

Computes the gradient of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

gradient of the spatial regularization

Return type:

np.array of shape (N, D)

hess_diag_neglog_pdf(x: ndarray) → ndarray

Computes the diagonal of the hessian of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

diagonal of the hessian of the spatial regularization

Return type:

np.array of shape (N, D)

initial_weights

initial weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

list_edges

set of edges in the graph induced by the spatial regularization

Type:

np.ndarray

neglog_pdf(x: ndarray, with_weights: bool = True) → ndarray

computes the negative log pdf (defined up to some multiplicative constant)

Parameters:

Theta (np.array of shape (N, D)) – set of D maps on which we want to evaluate the neg log prior

Returns:

neglog_p – set of the D neg log priors evaluation

Return type:

np.array of shape (D,)

use_next_nearest_neighbors

wether to use the next nearest neighbors (i.e., neighbors in diagonal)

Type:

bool

weights

current value of weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

beetroots.modelling.priors.tv_2D_prior module

Defines the Total variation spatial regularization and its derivatives

class beetroots.modelling.priors.tv_2D_prior.TVeps2DSpatialPrior(D: int, N: int, df: DataFrame, weights: ndarray | None = None, eps: float = 0.001)

Bases: SpatialPrior

D

number of distinct physical parameters

Type:

int

N

number of pixels in each physical dimension

Type:

int

dict_neighbors

dict_sites

sites of the graph induced the spatial regularization. A site is a set of nodes that are conditionally independent.

Type:

dict[int, np.ndarray]

gradient_neglog_pdf(Theta: ndarray) → ndarray

Computes the gradient of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

gradient of the spatial regularization

Return type:

np.array of shape (N, D)

hess_diag_neglog_pdf(Theta: ndarray) → ndarray

Computes the diagonal of the hessian of the spatial regularization

Parameters:

Theta (np.array of shape (N, D)) – current iterate

Returns:

diagonal of the hessian of the spatial regularization

Return type:

np.array of shape (N, D)

initial_weights

initial weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

list_edges

set of edges in the graph induced by the spatial regularization

Type:

np.ndarray

neglog_pdf(Theta: ndarray, with_weights: bool = True) → ndarray

computes the negative log pdf (defined up to some multiplicative constant)

Parameters:

Theta (np.array of shape (N, D)) – set of D maps on which we want to evaluate the neg log prior

Returns:

neglog_p – set of the D neg log priors evaluation

Return type:

np.array of shape (D,)

use_next_nearest_neighbors

wether to use the next nearest neighbors (i.e., neighbors in diagonal)

Type:

bool

weights

current value of weights of the spatial regularization \(\tau\)

Type:

np.ndarray of shape (D,)

beetroots.modelling.priors.tv_2D_prior.compute_gradient_from_tv_matrix(Theta: ndarray, tv_matrix_: ndarray, list_edges: ndarray) → ndarray

beetroots.modelling.priors.tv_2D_prior.compute_tv_matrix(Theta: ndarray, list_edges: ndarray, eps: float) → ndarray

Module contents