LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
lsst::meas::modelfit::TruncatedGaussian Class Reference

Represents a multidimensional Gaussian function truncated at zero. More...

#include <TruncatedGaussian.h>

Public Types

enum  SampleStrategy { DIRECT_WITH_REJECTION , ALIGN_AND_WEIGHT }
 Enum that describes different ways of sampling from a multidimensional TruncatedGaussian. More...
 
typedef TruncatedGaussianSampler Sampler
 
typedef TruncatedGaussianLogEvaluator LogEvaluator
 
typedef TruncatedGaussianEvaluator Evaluator
 

Public Member Functions

Sampler sample (SampleStrategy strategy) const
 Create a Sampler object that uses the given strategy. More...
 
Sampler sample (Scalar minRejectionEfficiency=0.1) const
 Create a Sampler object that determines the strategy to use automatically. More...
 
LogEvaluator evaluateLog () const
 Create a LogEvaluator object that can be used to efficiently evaluate the -log of the function. More...
 
Evaluator evaluate () const
 Create an Evaluator object that can be used to efficiently evaluate the function. More...
 
int getDim () const
 Return the dimensionality of the function. More...
 
Vector maximize () const
 Return the location of the maximum of the truncated Gaussian. More...
 
Scalar getUntruncatedFraction () const
 Return the fraction of the Gaussian integral that was truncated by the bounds. More...
 
Scalar getLogPeakAmplitude () const
 Return the -log of the peak amplitude of the untruncated function. More...
 
Scalar getLogIntegral () const
 Return the -log of the integral of the truncated function. More...
 
 ~TruncatedGaussian ()
 

Static Public Member Functions

static TruncatedGaussian fromSeriesParameters (Scalar q0, Vector const &gradient, Matrix const &hessian)
 Create from the first and second logarithmic derivatives of the Gaussian. More...
 
static TruncatedGaussian fromStandardParameters (Vector const &mean, Matrix const &covariance)
 Create from the "standard" mean and covariance parameters of the normal distribution. More...
 

Friends

class TruncatedGaussianSampler
 
class TruncatedGaussianLogEvaluator
 

Detailed Description

Represents a multidimensional Gaussian function truncated at zero.

This is typically used to represent the posterior probability of amplitude parameters, given a flat prior; we require that the amplitudes each be positive but otherwise do not modify the Gaussian likelihood.

Currently only 1 and 2 dimensions are supported, and all dimensions must be truncated. Computing integrals is the only operation for which > 2-d is not implemented, but the integrals must be computed upon construction, so we can't support any other operations for > 2-d either.

Many operations on TruncatedGaussians are defined in -log space, as underflow/overflow problems will often occur in the non-log forms.

See Truncated Gaussian Math for implementation notes

Definition at line 59 of file TruncatedGaussian.h.

Member Typedef Documentation

◆ Evaluator

Definition at line 89 of file TruncatedGaussian.h.

◆ LogEvaluator

Definition at line 88 of file TruncatedGaussian.h.

◆ Sampler

Definition at line 87 of file TruncatedGaussian.h.

Member Enumeration Documentation

◆ SampleStrategy

Enum that describes different ways of sampling from a multidimensional TruncatedGaussian.

Enumerator
DIRECT_WITH_REJECTION 

Draw from the untruncated Gaussian, and discard negative draws.

This approach is fast for minimally-truncated Gaussians, and produces ideally distributed samples with unit weights (because we discard with replacement). This approach can be extremely inefficient when the untruncated fraction is small, and cannot be used when the Hessian matrix is singular (as this sets the untruncated fraction to zero).

ALIGN_AND_WEIGHT 

Create a similar Gaussian with no x-y covariance, and importance sample by drawing from the independent 1-d truncated Gaussians.

This approach is faster for Gaussians that are heavily truncated, but it requires the use of per-sample weights and may produce "noisier" samples (in that regions with low weight may have many samples, while regions with high weight have few). It may also be slower for minimally truncated Gaussians because each 1-d variate requires an inverse erfc evaluation. In 1-d, this produces unit weights and ideally distributed samples, but still uses an inverse erfc approach rather than rejection to create samples.

Definition at line 63 of file TruncatedGaussian.h.

63  {
64 
85  };
@ ALIGN_AND_WEIGHT
Create a similar Gaussian with no x-y covariance, and importance sample by drawing from the independe...
@ DIRECT_WITH_REJECTION
Draw from the untruncated Gaussian, and discard negative draws.

Constructor & Destructor Documentation

◆ ~TruncatedGaussian()

lsst::meas::modelfit::TruncatedGaussian::~TruncatedGaussian ( )

Member Function Documentation

◆ evaluate()

TruncatedGaussian::Evaluator lsst::meas::modelfit::TruncatedGaussian::evaluate ( ) const
inline

Create an Evaluator object that can be used to efficiently evaluate the function.

Definition at line 355 of file TruncatedGaussian.h.

355 { return Evaluator(*this); }
TruncatedGaussianEvaluator Evaluator

◆ evaluateLog()

TruncatedGaussian::LogEvaluator lsst::meas::modelfit::TruncatedGaussian::evaluateLog ( ) const
inline

Create a LogEvaluator object that can be used to efficiently evaluate the -log of the function.

Definition at line 353 of file TruncatedGaussian.h.

353 { return LogEvaluator(*this); }
TruncatedGaussianLogEvaluator LogEvaluator

◆ fromSeriesParameters()

static TruncatedGaussian lsst::meas::modelfit::TruncatedGaussian::fromSeriesParameters ( Scalar  q0,
Vector const &  gradient,
Matrix const &  hessian 
)
static

Create from the first and second logarithmic derivatives of the Gaussian.

This causes the TruncatedGaussian to model the function:

\[ f(\alpha) = 1_{\alpha \ge 0}(\alpha) \; e^{-q(0) -g^T \alpha -\frac{1}{2}\alpha^T H \alpha} = 1_{\alpha \ge 0}(\alpha) \; e^{-q(\alpha)} \]

Where \(1_{\alpha \ge 0}(\alpha)\) is the indicator function

\[ 1_{\alpha \ge 0}(\alpha) \equiv \begin{cases} 1 & \text{if $\alpha \ge 0$}\\ 0 & \text{if $\alpha \lt 0$} \end{cases} \]

Note that this implies

\[ \left.\frac{\partial q}{\partial \alpha} \right|_{\alpha=0} = g \]

\[ \left.\frac{\partial^2 q}{\partial \alpha^2} \right|_{\alpha=0} = H \]

with (for \(\alpha \ge 0\))

\[ q(\alpha) \equiv -\ln f(\alpha) \]

Note that unlike that constructed by fromStandardParameters(), in this case \(f(\alpha)\) is NOT normalized to integrate to one.

Parameters
[in]q0Zeroth-order term in the expansion
[in]gradientVector of first derivatives \(g\)
[in]hessianMatrix of second derivatives \(H\) (symmetric)

◆ fromStandardParameters()

static TruncatedGaussian lsst::meas::modelfit::TruncatedGaussian::fromStandardParameters ( Vector const &  mean,
Matrix const &  covariance 
)
static

Create from the "standard" mean and covariance parameters of the normal distribution.

This causes the TruncatedGaussian to model the function:

\[ f(\alpha) = \frac{1_{\alpha \ge 0}(\alpha)}{k\left|2\pi\Sigma\right|^{1/2}} e^{-\frac{1}{2}(\alpha-\mu)^T \Sigma^{-1} (\alpha-\mu)} = \frac{1_{\alpha \ge 0}(\alpha)}{k}\;\Phi(\alpha-\mu,\Sigma) \]

Where \(1_{\alpha \ge 0}(\alpha)\) is the indicator function

\[ 1_{\alpha \ge 0}(\alpha) \equiv \begin{cases} 1 & \text{if $\alpha \ge 0$}\\ 0 & \text{if $\alpha \lt 0$} \end{cases} \]

and \(k\) is the normalization constant that \(f(\alpha)\) integrates to unity:

\[ k \equiv \int_0^{\infty}\!\!\Phi(\alpha-\mu,\Sigma) d\alpha \]

Note that unlike that constructed by fromSeriesParameters(), in this case \(f(\alpha\) is normalized to integrate to one.

Parameters
[in]meanMean vector \(\mu\)
[in]covarianceCovariance matrix \(\Sigma\) (symmetric)

◆ getDim()

int lsst::meas::modelfit::TruncatedGaussian::getDim ( ) const

Return the dimensionality of the function.

◆ getLogIntegral()

Scalar lsst::meas::modelfit::TruncatedGaussian::getLogIntegral ( ) const

Return the -log of the integral of the truncated function.

More precisely, this is simply

\[ -\ln\int_{-\infty}^{\infty} f(\alpha) d\alpha \]

In series form, this is equivalent to

\[ -\ln\int_0^{\infty} e^{-q(\alpha)} d\alpha \]

In standard parameter form it is 0 by construction.

◆ getLogPeakAmplitude()

Scalar lsst::meas::modelfit::TruncatedGaussian::getLogPeakAmplitude ( ) const

Return the -log of the peak amplitude of the untruncated function.

In series form, this is equal to \(q(\mu)\) where \(\mu=-H^{-1}g\). In standard parameter form, this is \(\frac{1}{2}\ln\left|2\pi\Sigma\right| - \ln k\).

◆ getUntruncatedFraction()

Scalar lsst::meas::modelfit::TruncatedGaussian::getUntruncatedFraction ( ) const

Return the fraction of the Gaussian integral that was truncated by the bounds.

In series form (see fromSeriesParameters), this is

\[ \frac{\int_0^{\infty} e^{-q(\alpha)} d\alpha}{\int_{-infty}^{\infty} e^{-q(\alpha)} d\alpha} \]

while in standard parameter form it is simply the normalization \(k\) described in fromStandardParameters().

◆ maximize()

Vector lsst::meas::modelfit::TruncatedGaussian::maximize ( ) const

Return the location of the maximum of the truncated Gaussian.

This is simply the untruncated location parameter mu if all of its elements are positive; otherwise, one or more elements will be zero (and the rest may not be same as the elements of mu).

◆ sample() [1/2]

TruncatedGaussian::Sampler lsst::meas::modelfit::TruncatedGaussian::sample ( SampleStrategy  strategy) const
inline

Create a Sampler object that uses the given strategy.

Warning
do not call this method with DIRECT_WITH_REJECTION unless you are certain the Gaussian is far from degenerate, as an endless loop may result in this case. It is generally safer to use the overload that selects the strategy automatically.

Definition at line 342 of file TruncatedGaussian.h.

342  {
343  return Sampler(*this, strategy);
344 }

◆ sample() [2/2]

TruncatedGaussian::Sampler lsst::meas::modelfit::TruncatedGaussian::sample ( Scalar  minRejectionEfficiency = 0.1) const
inline

Create a Sampler object that determines the strategy to use automatically.

If the efficiency (number of accepted samples divided by number of total samples) is would (on average) be greater than the given value, DIRECT_WITH_REJECTION is used. If not, ALIGN_AND_WEIGHT is used. Note that the sampling effeciency for DIRECT_WITH_REJECTION is exactly the same as the "untruncated fraction".

Definition at line 346 of file TruncatedGaussian.h.

346  {
347  return Sampler(
348  *this,
349  (getUntruncatedFraction() < minRejectionEfficiency) ? ALIGN_AND_WEIGHT : DIRECT_WITH_REJECTION
350  );
351 }
Scalar getUntruncatedFraction() const
Return the fraction of the Gaussian integral that was truncated by the bounds.

Friends And Related Function Documentation

◆ TruncatedGaussianLogEvaluator

friend class TruncatedGaussianLogEvaluator
friend

Definition at line 233 of file TruncatedGaussian.h.

◆ TruncatedGaussianSampler

friend class TruncatedGaussianSampler
friend

Definition at line 232 of file TruncatedGaussian.h.


The documentation for this class was generated from the following file: