Emrys::StudentT< Space_, Scalar_ > Class Template Reference

The multivariate Student-t distribution: a Gaussian with heavier tails. More...

#include <EmrysFilter/Distributions/StudentT.h>

Public Types
using	ScaleGaussianType = GaussianParams<Space_, Scalar_>
	\( \mathcal{N}(\mu, \Sigma) \), which holds the parameters
using	MomentsType = typename ScaleGaussianType::MomentsType
	a mean and covariance together
using	Scalar = Scalar_
	the scalar type
using	Index = Eigen::Index
	Eigen's index type.
using	SpaceType = Space_
	the space the values live in
using	VectorType = typename MomentsType::VectorType
	a value
using	MatrixType = typename MomentsType::MatrixType
	a matrix over differences

Public Member Functions
Index	valueDimension () const
Index	differenceDimension () const
Space_ const &	space () const
VectorType const &	location () const
MatrixType const &	scale () const
Scalar	dof () const
ScaleGaussianType::DensityType	scaleDensity () const
template<typename Derived>
Scalar	logDensity (Eigen::MatrixBase< Derived > const &x) const
template<typename Derived>
Scalar	density (Eigen::MatrixBase< Derived > const &x) const
std::expected< MomentsType, MomentsError >	moments () const
Scalar	logDensityAtSquaredDistance (Scalar squaredDistance) const
template<typename Path>
auto	marginal () const
	marginal() of the subspace named by the tag path Path (see idx()), in that subspace.
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

Static Public Member Functions
template<MatrixExpression Location, typename ScaleDerived>
static std::expected< StudentT, StudentTError >	create (Space_ space, Location &&location, Eigen::MatrixBase< ScaleDerived > const &scale, Scalar dof)
template<MatrixExpression Location, typename ScaleDerived>
static std::expected< StudentT, StudentTError >	create (Location &&location, Eigen::MatrixBase< ScaleDerived > const &scale, Scalar dof)
	create() in the default space.
static std::expected< StudentT, StudentTError >	create (ScaleGaussianType const &gaussian, Scalar dof)
	create() from the location and scale of gaussian, which keeps its space.

Static Public Attributes
static constexpr int	ValueDimensionAtCompileTime = MomentsType::ValueDimensionAtCompileTime
	the length of a value, or Eigen::Dynamic
static constexpr int	MaxValueDimensionAtCompileTime = MomentsType::MaxValueDimensionAtCompileTime
	a bound on the length of a value, or Eigen::Dynamic
static constexpr int	DifferenceDimensionAtCompileTime = MomentsType::DifferenceDimensionAtCompileTime
	the length of a difference and the rows of the scale matrix, or Eigen::Dynamic
static constexpr int	MaxDifferenceDimensionAtCompileTime = MomentsType::MaxDifferenceDimensionAtCompileTime
	a bound on the length of a difference, or Eigen::Dynamic

Detailed Description

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

The multivariate Student-t distribution: a Gaussian with heavier tails.

The multivariate t-distribution. With location \( \mu \), scale matrix \( \Sigma \), and \( \nu \) degrees of freedom in \( d \) dimensions,

\[ p(x) = \frac{\Gamma\left(\frac{\nu + d}{2}\right)}{\Gamma\left(\frac{\nu}{2}\right) (\nu\pi)^{d/2} |\Sigma|^{1/2}} \left(1 + \frac{\delta^2}{\nu}\right)^{-\frac{\nu + d}{2}}, \]

where \( \delta^2 = (x \boxminus \mu)^T \Sigma^{-1} (x \boxminus \mu) \). It is a scale mixture of Gaussians: \( x = \mu + L z / \sqrt{u / \nu} \) with \( z \sim \mathcal{N}(0, I) \), \( u \sim \chi^2_\nu \), and \( \Sigma = L L^T \). As \( \nu \to \infty \) it approaches \( \mathcal{N}(\mu, \Sigma) \); \( \nu = 1 \) is the Cauchy distribution.

The scale matrix is not the covariance: the covariance is \( \frac{\nu}{\nu - 2} \Sigma \), and only exists for \( \nu > 2 \) (see moments()). Densities use the nearest image, as a Gaussian's do.

Created by create(), which checks the degrees of freedom and factorizes the scale matrix, and returns a StudentTError if either fails; it has no public constructor [checked-factories]. A StudentT is an immutable value that owns its parameters.

Template Parameters

Space_	space of the coordinates (see Spaces)
Scalar_	scalar type

See also

drawSamples(StudentT const &, Eigen::Index, G &)

Member Function Documentation

conditional()

template<Space Space_, RealScalar Scalar_ = double>

template<typename GivenPath, typename Derived>

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

inlinenodiscard

Returns

the distribution of the other coordinates given that the subspace named by the path GivenPath equals values, in the space of the remaining blocks (see GaussianParams::conditional()): again a Student-t, or a StudentTError if its scale fails to factorize, as it may for a numerically singular source.

With \( d_b \) given difference coordinates at squared Mahalanobis distance \( \delta_b^2 \) from their location, the conditional has \( \nu + d_b \) degrees of freedom, the Gaussian conditional's location \( \mu_a \boxplus K (v \boxminus \mu_b) \), and the Gaussian conditional's scale \( \Sigma_{aa} - K \Sigma_{ba} \) times \( (\nu + \delta_b^2) / (\nu + d_b) \), with \( K = \Sigma_{ab} \Sigma_{bb}^{-1} \). So values far from the location widen it. The result is Ding (2016), Theorem 1.

create()

template<Space Space_, RealScalar Scalar_ = double>

template<MatrixExpression Location, typename ScaleDerived>

std::expected< StudentT, StudentTError > Emrys::StudentT< Space_, Scalar_ >::create ( Space_ space, Location && location, Eigen::MatrixBase< ScaleDerived > const & scale, Scalar dof )

inlinestaticnodiscard

Returns

a Student-t with location location, scale matrix scale, and dof degrees of freedom in space, or a StudentTError if dof is not positive and finite, or scale is not positive definite or not finite. Only the lower triangle of scale is read.

density()

template<Space Space_, RealScalar Scalar_ = double>

template<typename Derived>

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

inlinenodiscard

Returns

the density at x

Warning

Underflows easily in high dimensions; prefer logDensity().

differenceDimension()

template<Space Space_, RealScalar Scalar_ = double>

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

inlinenodiscard

Returns

the number of rows and columns of the scale matrix

dof()

template<Space Space_, RealScalar Scalar_ = double>

Scalar Emrys::StudentT< Space_, Scalar_ >::dof ( ) const

inlinenodiscard

Returns

the degrees of freedom \( \nu \)

location()

template<Space Space_, RealScalar Scalar_ = double>

VectorType const & Emrys::StudentT< Space_, Scalar_ >::location ( ) const

inlinenodiscard

Returns

the location \( \mu \): the mode and median, and the mean when \( \nu > 1 \)

logDensity()

template<Space Space_, RealScalar Scalar_ = double>

template<typename Derived>

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

inlinenodiscard

Returns

the log of the density at x

See also

density()

logDensityAtSquaredDistance()

template<Space Space_, RealScalar Scalar_ = double>

Scalar Emrys::StudentT< Space_, Scalar_ >::logDensityAtSquaredDistance ( Scalar squaredDistance ) const

inlinenodiscard

Returns

the log-density at a point whose squared Mahalanobis distance under the scale matrix is squaredDistance

moments()

template<Space Space_, RealScalar Scalar_ = double>

std::expected< MomentsType, MomentsError > Emrys::StudentT< Space_, Scalar_ >::moments ( ) const

inlinenodiscard

Returns

the mean \( \mu \) and covariance \( \frac{\nu}{\nu - 2} \Sigma \), or MomentsError::Infinite if \( \nu \le 2 \), when the covariance is infinite

scale()

template<Space Space_, RealScalar Scalar_ = double>

MatrixType const & Emrys::StudentT< Space_, Scalar_ >::scale ( ) const

inlinenodiscard

Returns

the scale matrix \( \Sigma \), symmetric

scaleDensity()

template<Space Space_, RealScalar Scalar_ = double>

ScaleGaussianType::DensityType Emrys::StudentT< Space_, Scalar_ >::scaleDensity ( ) const

inlinenodiscard

Returns

a view of \( \mathcal{N}(\mu, \Sigma) \), whose factorization this distribution shares. It must not outlive this distribution.

space()

template<Space Space_, RealScalar Scalar_ = double>

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

inlinenodiscard

Returns

the space the values live in, with its sizes

valueDimension()

template<Space Space_, RealScalar Scalar_ = double>

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

inlinenodiscard

Returns

the number of coordinates of the location

---

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

• EmrysFilter/Distributions/StudentT.h