The density of a Gaussian whose covariance has been factorized: a read-only view. More...

#include <EmrysFilter/Distributions/Gaussian.h>

Public Types
using	ParamsType = GaussianParams<Space_, Scalar_>
	the parameters it reads
using	SpaceType = Space_
	the space the values live in
using	MomentsType = typename ParamsType::MomentsType
	the mean and covariance together
using	Scalar = typename ParamsType::Scalar
	the scalar type
using	Index = typename ParamsType::Index
	Eigen's index type.
using	VectorType = typename ParamsType::VectorType
	a value, such as the mean
using	DifferenceVectorType = typename ParamsType::DifferenceVectorType
	a difference, such as a residual
using	MatrixType = typename ParamsType::MatrixType
	a matrix over differences
using	LltType = Eigen::LLT<MatrixType>
	the Cholesky factorization

Public Member Functions
Index	valueDimension () const
Index	differenceDimension () const
Space_ const &	space () const
MomentsType const &	moments () const
VectorType const &	mean () const
MatrixType const &	covarianceLower () const
template<typename Path>
auto	mean () const
template<typename Path>
auto	mean (Index element) const
	mean<Path>() of one repetition; see GaussianParams::mean<Path>(element).
template<typename Path>
auto	covariance () const
template<typename Path>
auto	covariance (Index element) const
	covariance<Path>() of one repetition; see GaussianParams::covariance<Path>(element).
template<typename RowPath, typename ColPath>
auto	covariance () const
LltType const &	llt () const
Scalar	logDeterminant () const
Scalar	logPeak () const
template<typename Derived>
Scalar	squaredMahalanobisDistance (Eigen::MatrixBase< Derived > const &x) const
template<typename Derived>
Scalar	confidence (Eigen::MatrixBase< Derived > const &x) const
template<typename Derived>
bool	contains (Eigen::MatrixBase< Derived > const &x, Scalar probability) const
template<typename Derived>
Scalar	logDensity (Eigen::MatrixBase< Derived > const &x) const
template<typename Derived>
Scalar	density (Eigen::MatrixBase< Derived > const &x) const
template<typename Path>
auto	marginal () const
	marginal() of the subspace named by the path Path; see GaussianParams::marginal().
template<typename Path>
auto	marginal (Index element) const
	marginal() of one repetition of a repeated block; see GaussianParams::marginal(element).
template<typename GivenPath, typename Derived>
auto	conditional (Eigen::MatrixBase< Derived > const &values) const
template<typename GivenPath, typename Derived>
auto	conditionalWithEvidence (Eigen::MatrixBase< Derived > const &values) const

Static Public Attributes
static constexpr int	ValueDimensionAtCompileTime = ParamsType::ValueDimensionAtCompileTime
	the length of a value, or Eigen::Dynamic
static constexpr int	MaxValueDimensionAtCompileTime = ParamsType::MaxValueDimensionAtCompileTime
	a bound on the length of a value, or Eigen::Dynamic
static constexpr int	DifferenceDimensionAtCompileTime = ParamsType::DifferenceDimensionAtCompileTime
	the length of a difference and the rows of the covariance, or Eigen::Dynamic
static constexpr int	MaxDifferenceDimensionAtCompileTime = ParamsType::MaxDifferenceDimensionAtCompileTime
	a bound on the length of a difference, or Eigen::Dynamic
static constexpr bool	IsParams = false
	a view: it checks its parameters

Detailed Description

template<Space Space_, RealScalar Scalar_ = double>
class Emrys::Gaussian< Space_, Scalar_ >

The density of a Gaussian whose covariance has been factorized: a read-only view.

Represents the density

\[ p(x) = (2\pi)^{-n/2} |\Sigma|^{-1/2} \exp\left(-\tfrac{1}{2}(x-\mu)^T \Sigma^{-1} (x-\mu)\right). \]

Obtained from GaussianParams::toDensity(). It checks its parameters for changes, as its copies do: reading it after they have changed is a programmer error (decisions.md [view-stamp]). A Gaussian must not outlive its source.

See also: class GaussianParams

Member Function Documentation

◆ conditional()

template<Space Space_, RealScalar Scalar_ = double>

template<typename GivenPath, typename Derived>

auto Emrys::Gaussian< Space_, Scalar_ >::conditional ( Eigen::MatrixBase< Derived > const & values ) const

inlinenodiscard

Returns: a copy of the conditional distribution given the subspace named by the path GivenPath; see GaussianParams::conditional().

◆ conditionalWithEvidence()

template<Space Space_, RealScalar Scalar_ = double>

template<typename GivenPath, typename Derived>

auto Emrys::Gaussian< Space_, Scalar_ >::conditionalWithEvidence ( Eigen::MatrixBase< Derived > const & values ) const

inlinenodiscard

Returns: conditional() and the log-evidence of values; see GaussianParams::conditionalWithEvidence().

◆ confidence()

template<Space Space_, RealScalar Scalar_ = double>

template<typename Derived>

Scalar Emrys::Gaussian< Space_, Scalar_ >::confidence ( Eigen::MatrixBase< Derived > const & x ) const

inlinenodiscard

Returns: the confidence of x: the probability of the smallest confidence region that contains it, \( F_{\chi^2_k}(d_M^2(x)) \), with \( k \) the difference dimension

The density falls as squaredMahalanobisDistance() grows, and the squaredMahalanobisDistance() of a draw is chi-squared with \( k \) degrees of freedom, so this is also the probability that a draw is denser than x. The confidence of a draw is uniform on \( [0, 1] \). The mean has confidence 0, as does every value in dimension zero.

See also: contains(), squaredMahalanobisDistance(), chiSquaredCdf()

◆ contains()

template<Space Space_, RealScalar Scalar_ = double>

template<typename Derived>

bool Emrys::Gaussian< Space_, Scalar_ >::contains	(	Eigen::MatrixBase< Derived > const &	x,
		Scalar	probability ) const

inlinenodiscard

Returns: whether x lies in the probability confidence region, the ellipsoid \( d_M^2(x) \le \chi^{2\,-1}_k(p) \) that holds probability of the mass

Agrees with confidence(x) <= probability, but compares squaredMahalanobisDistance() with the quantile instead of evaluating the chi-squared CDF. The region is the one-standard-deviation ellipsoid of the Gaussian that GaussianParams::scaleToConfidence() makes. In dimension zero every value is inside.

Parameters

x	a value
probability	the confidence, in \( (0, 1) \)

See also: confidence(), GaussianParams::scaleToConfidence(), chiSquaredQuantile()

◆ covariance() [1/2]

template<Space Space_, RealScalar Scalar_ = double>

template<typename RowPath, typename ColPath>

auto Emrys::Gaussian< Space_, Scalar_ >::covariance ( ) const

inlinenodiscard

Returns: the cross-covariance of two blocks; see GaussianParams::covariance<RowPath, ColPath>().

◆ covariance() [2/2]

template<Space Space_, RealScalar Scalar_ = double>

template<typename Path>

auto Emrys::Gaussian< Space_, Scalar_ >::covariance ( ) const

inlinenodiscard

Returns: the covariance of the block named by Path; see GaussianParams::covariance<Path>().

◆ covarianceLower()

template<Space Space_, RealScalar Scalar_ = double>

MatrixType const & Emrys::Gaussian< Space_, Scalar_ >::covarianceLower ( ) const

inlinenodiscard

Returns: the source's covariance

◆ density()

template<Space Space_, RealScalar Scalar_ = double>

template<typename Derived>

Scalar Emrys::Gaussian< Space_, Scalar_ >::density ( Eigen::MatrixBase< Derived > const & x ) const

inlinenodiscard

Returns: the density \( p(x) \) at x

Warning: Underflows easily in high dimensions; prefer logDensity().

See also: logDensity()

◆ differenceDimension()

template<Space Space_, RealScalar Scalar_ = double>

Index Emrys::Gaussian< Space_, Scalar_ >::differenceDimension ( ) const

inlinenodiscard

Returns: the number of rows and columns of the covariance

◆ llt()

template<Space Space_, RealScalar Scalar_ = double>

LltType const & Emrys::Gaussian< Space_, Scalar_ >::llt ( ) const

inlinenodiscard

Returns: the Cholesky factorization \( \Sigma = L L^T \) of the covariance

◆ logDensity()

template<Space Space_, RealScalar Scalar_ = double>

template<typename Derived>

Scalar Emrys::Gaussian< Space_, Scalar_ >::logDensity ( Eigen::MatrixBase< Derived > const & x ) const

inlinenodiscard

Returns: the log of the density at x, \( \log p(x) = \mathrm{logPeak} - \frac{1}{2}d_M^2(x) \)

On a space that is not linear this is the density in the tangent space at the mean, with the residual \( x \boxminus \mu \); the wrapped normal is not computed [tangent-gaussians].

See also: logPeak(), squaredMahalanobisDistance(), density()

◆ logDeterminant()

template<Space Space_, RealScalar Scalar_ = double>

Scalar Emrys::Gaussian< Space_, Scalar_ >::logDeterminant ( ) const

inlinenodiscard

Returns: the log-determinant \( \log|\Sigma| \) of the covariance

◆ logPeak()

template<Space Space_, RealScalar Scalar_ = double>

Scalar Emrys::Gaussian< Space_, Scalar_ >::logPeak ( ) const

inlinenodiscard

Returns: the log of the density at the mean, \( -\frac{1}{2}(d \log 2\pi + \log|\Sigma|) \), with \( d \) the difference dimension

See also: logDensity()

◆ marginal()

template<Space Space_, RealScalar Scalar_ = double>

template<typename Path>

auto Emrys::Gaussian< Space_, Scalar_ >::marginal ( ) const

inlinenodiscard

marginal() of the subspace named by the path Path; see GaussianParams::marginal().

It holds a copy of this view, and so of its check of the parameters.

◆ mean() [1/2]

template<Space Space_, RealScalar Scalar_ = double>

template<typename Path>

auto Emrys::Gaussian< Space_, Scalar_ >::mean ( ) const

inlinenodiscard

Returns: the mean of the block named by Path; see GaussianParams::mean<Path>().

◆ mean() [2/2]

template<Space Space_, RealScalar Scalar_ = double>

VectorType const & Emrys::Gaussian< Space_, Scalar_ >::mean ( ) const

inlinenodiscard

Returns: the source's mean

◆ moments()

template<Space Space_, RealScalar Scalar_ = double>

MomentsType const & Emrys::Gaussian< Space_, Scalar_ >::moments ( ) const

inlinenodiscard

Returns: the source's mean and covariance together

◆ space()

template<Space Space_, RealScalar Scalar_ = double>

Space_ const & Emrys::Gaussian< Space_, Scalar_ >::space ( ) const

inlinenodiscard

Returns: the source's space

◆ squaredMahalanobisDistance()

template<Space Space_, RealScalar Scalar_ = double>

template<typename Derived>

Scalar Emrys::Gaussian< Space_, Scalar_ >::squaredMahalanobisDistance ( Eigen::MatrixBase< Derived > const & x ) const

inlinenodiscard

Returns: the squared Mahalanobis distance of x, \( d_M^2(x) = (x \boxminus \mu)^T \Sigma^{-1} (x \boxminus \mu) \)

The NIS is this for a measurement under its predicted density, and the NEES (nees()) for the true state under an estimate.

See also: logDensity()

◆ valueDimension()

template<Space Space_, RealScalar Scalar_ = double>

Index Emrys::Gaussian< Space_, Scalar_ >::valueDimension ( ) const

inlinenodiscard

Returns: the number of coordinates of the mean

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

EmrysFilter/Distributions/Gaussian.h

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ conditional()

◆ conditionalWithEvidence()

◆ confidence()

◆ contains()

◆ covariance() [1/2]

◆ covariance() [2/2]

◆ covarianceLower()

◆ density()

◆ differenceDimension()

◆ llt()

◆ logDensity()

◆ logDeterminant()

◆ logPeak()

◆ marginal()

◆ mean() [1/2]

◆ mean() [2/2]

◆ moments()

◆ space()

◆ squaredMahalanobisDistance()

◆ valueDimension()