Namespaces
Automatically generated documentation for ProxNest APIs. All functionality is accessible through a pip installation of the ProxNest package.
- ProxNest.sampling.proximal_nested.ProxNestedSampling(X0, LikeliL, proxH, proxB, params, options)
Executes the proximal nested sampling algorithm
- Parameters
X0 (np.ndarray) – initialisation of the sample chain.
LikeliL (lambda) – function to compute the likelihood value of a sample.
proxH (lambda) – proximity operator of the prior.
proxB (lambda) – proximity operator of the constraint \(\ell_2\)-ball.
params (dict) – parameters for prior resampling subject to likelihood isocontour.
options (dict) – parameters about number of samples, thinning factor, burnning numbers.
- Returns
(Evidence, sample trace).
- Return type
tuple
Notes
MATLAB version: Xiaohao Cai (21/02/2019)
Python version: Matthew Price (9/05/2022)
- ProxNest.sampling.resampling.reorder_samples(samples, likelihood_values)
This program is to find the sample with the smallest likelihood and move it to the end of the list
- Parameters
samples (np.ndarray) – given sample list
likeliVal (np.ndarray) – corresponding likelihood
- Returns
Reordered version of (samples, likelihood_values)
- Return type
tuple
Notes
MATLAB version: Xiaohao Cai (30/01/2019)
Python version: Matthew Price (10/05/2022)
- ProxNest.optimisations.l2_ball_proj.sopt_fast_proj_B2(x, tau, params)
Fast projection algorithm onto the \(\ell_2\)-ball.
Compute the projection onto the \(\ell_2\) ball, i.e. solve
\[z^* = \min_{z} ||x - z||_2^2 s.t. ||y - \Phi z||_2 < \tau\]where \(x\) is the input vector and the solution \(z^*\) is returned as sol.
- Parameters
x (np.ndarray) – A sample position \(x\) in the posterior space.
tau (float) – Radius of likelihood \(\ell_2\)-ball.
params (dict) – Dictionary of parameters defining the optimisation.
- Returns
Optimal solution \(z^*\) of proximal projection.
- Return type
np.ndarray
Notes
[1] M.J. Fadili and J-L. Starck, “Monotone operator splitting for optimization problems in sparse recovery” , IEEE ICIP, Cairo, Egypt, 2009.
[2] Amir Beck and Marc Teboulle, “A Fast Iterative Shrinkage-Thresholding Algorithm for Linear Inverse Problems”, SIAM Journal on Imaging Sciences 2 (2009), no. 1, 183–202.
- ProxNest.optimisations.l1_norm_prox.l1_norm_prox(x, lamb, params)
Proximal operator associated with L1 norm.
Compute the L1 proximal operator, i.e. solve
\[z^* = \min_{z} \frac{1}{2}||x - z||_2^2 + \lambda * ||\Psi^{\dagger} z||_1,\]where \(x\) is the input vector and the solution \(z^*\) is returned as sol.
- Parameters
x (np.ndarray) – A sample position \(x\) in the posterior space.
lamb (float) – Regularisation parameter.
params (dict) – Dictionary of parameters defining the optimisation.
- Returns
Optimal solution \(z^*\) of proximal operator.
- Return type
np.ndarray
Notes
[1] M.J. Fadili and J-L. Starck, “Monotone operator splitting for optimization problems in sparse recovery” , IEEE ICIP, Cairo, Egypt, 2009.
[2] Amir Beck and Marc Teboulle, “A Fast Iterative Shrinkage-Thresholding Algorithm for Linear Inverse Problems”, SIAM Journal on Imaging Sciences 2 (2009), no. 1, 183–202.
- ProxNest.optimisations.tv_norm_prox.augmented_TV_norm_prox(x, lamb, params)
Compute the augmented total variation proximal operator
Compute the TV proximal operator when an additional linear operator A is incorporated in the TV norm, i.e. solve
\[x^* = \min_{x} ||y - x||_2^2 + \lambda * ||A x||_{TV}\]where \(y\) is the input vector and the solution \(x^*\) is returned as sol.
- Parameters
x (np.ndarray) – A sample position \(x\) in the posterior space.
lamb (float) – Regularisation parameter.
params (dict) – Dictionary of parameters defining the optimisation.
- Returns
Optimal solution \(x^*\) of proximal operator.
- Return type
np.ndarray
Notes
[1] A. Beck and M. Teboulle, “Fast gradient-based algorithms for constrained Total Variation Image Denoising and Deblurring Problems”, IEEE Transactions on Image Processing, VOL. 18, NO. 11, 2419-2434, November 2009.
- ProxNest.operators.proximal_operators.hard_thresh(x, T)
Compute the element-wise hard-thresholding of \(x\).
- Parameters
x (np.ndarray) – Array to threshold.
T (float) – Hard-thresholding level (regularisation parameter)
delta (float) – Weighting parameter.
- Returns
Thresholded coefficients of \(x\).
- Return type
np.ndarray
- ProxNest.operators.proximal_operators.l1_projection(x, T, delta, Psi=<ProxNest.operators.sensing_operators.Identity object>)
Compute the l1 proximal operator wrt dictionary \(\Psi\).
- Parameters
x (np.ndarray) – Array to threshold.
T (float) – Soft-thresholding level (regularisation parameter)
delta (float) – Weighting parameter.
Psi (LinearOperator) – Prior dictionary (default = Identity)
- Returns
Thresholded coefficients of \(x\).
- Return type
np.ndarray
- ProxNest.operators.proximal_operators.l2_projection(x, T, delta, Psi=<ProxNest.operators.sensing_operators.Identity object>)
Compute the l2 gradient step wrt dictionary \(\Psi\).
- Parameters
x (np.ndarray) – Array to threshold.
T (float) – Soft-thresholding level (regularisation parameter)
delta (float) – Weighting parameter.
Psi (LinearOperator) – Prior dictionary (default = Identity)
- Returns
Thresholded coefficients of \(x\).
- Return type
np.ndarray
- ProxNest.operators.proximal_operators.soft_thresh(x, T, delta=2)
Compute the element-wise soft-thresholding of \(x\).
- Parameters
x (np.ndarray) – Array to threshold.
T (float) – Soft-thresholding level (regularisation parameter)
delta (float) – Weighting parameter (default = 2).
- Returns
Thresholded coefficients of \(x\).
- Return type
np.ndarray
- class ProxNest.operators.wavelet_operators.db_wavelets(wav, levels, shape, axes=None)
Constructs a linear operator for abstract Daubechies Wavelets.
Notes
Stripped back version of optimus-primal linear operator.
- __init__(wav, levels, shape, axes=None)
Initialises Daubechies Wavelet linear operator class.
- Parameters
wav (string) – Wavelet type (see https://tinyurl.com/5n7wzpmb).
levels (list[int]) – Wavelet levels (scales) to consider.
shape (list[int]) – Dimensionality of input to wavelet transform.
axes (int) – Which axes to perform wavelet transform (default = all axes).
- Raises
ValueError – Raised when levels are not positive definite.
- adj_op(x)
Evaluates the forward adjoint abstract wavelet transform of \(x\).
- Parameters
x (np.ndarray) – Array to adjoint wavelet transform.
- Returns
Array of pixel-space coefficients.
- Return type
np.ndarray
- dir_op(x)
Evaluates the forward abstract wavelet transform of \(x\).
- Parameters
x (np.ndarray) – Array to wavelet transform.
- Raises
ValueError – Raised when the shape of x is not even in every dimension.
- Returns
Flattened array of wavelet coefficients.
- Return type
np.ndarray
- class ProxNest.operators.sensing_operators.Identity
Identity sensing operator
Notes
Implemented originally in optimus-primal.
- adj_op(x)
Computes the forward adjoint operator of the identity class.
- Parameters
x (np.ndarray) – Vector to apply identity to.
- Returns
array of coefficients
- Return type
np.ndarray
- dir_op(x)
Computes the forward operator of the identity class.
- Parameters
x (np.ndarray) – Vector to apply identity to.
- Returns
array of coefficients
- Return type
np.ndarray
- class ProxNest.operators.sensing_operators.MaskedFourier(dim, ratio)
Masked fourier sensing operator i.e. MRI/Radio imaging.
- __init__(dim, ratio)
Initialises the masked fourier sensing operator.
- Parameters
dim (int) – Dimension of square pixel-space image.
ratio (float) – Fraction of measurements observed.
- adj_op(x)
Computes the forward adjoint operator of the class.
- Parameters
x (np.ndarray) – Vector to apply identity to.
- Returns
array of coefficients
- Return type
np.ndarray
- dir_op(x)
Computes the forward operator of the class.
- Parameters
x (np.ndarray) – Vector to apply identity to.
- Returns
array of coefficients
- Return type
np.ndarray
- ProxNest.utils.create_options_dict(samplesL=1000.0, samplesD=10000.0, thinning=100.0, delta=1e-08, burn=100.0, sigma=1)
Compiles a dictionary of option parameters for sampling
- Parameters
samplesL (int) – Number of live samples (default = 1e3).
samplesD (int) – Number of discarded samples (default = 1e4).
thinning (int) – Thinning factors (i.e. iterations per sample, default =1 1e2).
delta (float) – Discretisation stepsize (< Lipschitz constant of \(\nabla F\), default = 1e-8).
burn (int) – Number of burn in samples to be discarded (default = 1e2).
sigma (float) – Noise std of degraded image (default = 1).
- Returns
Dictionary of sampling options.
- Return type
dict
- ProxNest.utils.create_parameters_dict(y=0, Phi=None, Psi=None, epsilon=0.001, tight=True, nu=1, tol=0.001, max_iter=200, verbose=1, u=0, pos=False, reality=False, l1weights=1, rel_obj=0)
Compiles a dictionary of parameters for code simplicity
- Parameters
y (np.ndarray) – Measurements (default = 0).
Phi (linear operator) – Sensing operator (default = None).
Psi (linear operator) – Redundant dictionary (default = None).
epsilon (float) – Radius of the \(\ell_2\) ball (default = 1e-3).
tight (bool) – True if A is a tight frame or False otherwise (default = 1).
nu (float) – Bound on the squared-norm of the operator A, i.e. \(||A x||^2 <= \nu ||x||^2\) (default = 1).
tol (float) – Tolerance, i.e. the algorithms stops if \(\epsilon/(1-tol) <= ||y - A z||_2 <= \epsilon/(1+tol)\) (default = 1e-3).
max_iter (int) – Maximum number of iterations (default: 200).
verbose (int) – Verbosity level (0 = no log, 1 = summary at convergence, 2 = print main steps; default = 1).
u (np.ndarray) – Initial vector for the dual problem, same dimension as y (default = 0).
pos (bool) – Positivity flag (True = positive solution, False (default) general case).
reality (bool) – Reality flag (True = real solution, 0 (default) = general complex case).
l1weights (np.ndarray) – Reweighting of thresholding of \(\ell_1\)-norm (default = 1).
rel_obj (float) – Stopping criterion for \(\ell_1\) proximal sub-iterations (default = 0).
- Returns
Dictionary of parameters.
- Return type
dict
- ProxNest.logs.critical_log(message)
Log a critical message (e.g. core code failures etc).
- Parameters
message – Message to log.
- ProxNest.logs.debug_log(message)
Log a debug message (e.g. for background logs to assist debugging).
- Parameters
message – Message to log.
- ProxNest.logs.info_log(message)
Log an information message (e.g. evidence value printing, run completion etc).
- Parameters
message – Message to log.
- ProxNest.logs.setup_logging(custom_yaml_path=None, default_level=10)
initialise and configure logging.
Should be called at the beginning of code to initialise and configure the desired logging level. Logging levels can be ints in [0,50] where 10 is debug logging and 50 is critical logging.
- Parameters
custom_yaml_path (string) – Complete pathname of desired yaml logging configuration. If empty will provide default logging config.
default_level (int) – Logging level at which to configure.
- Raises
ValueError – Raised if logging.yaml is not in ./logs/ directory.
- ProxNest.logs.warning_log(message)
Log a warning (e.g. for internal code warnings such as large dynamic ranges).
- Parameters
message – Warning to log.