The parameters of a probability distribution over a discrete space: one weight per value. More...

#include <EmrysFilter/Distributions/Categorical.h>

Public Types
using	Scalar = Scalar_
	the scalar type of the weights
using	SpaceType = Space_
	the discrete space
using	DensityType = Categorical<Space_, Scalar_>
	the view toDensity() returns
using	ArrayType
	One entry per value, in flat-index order.

Public Member Functions
	CategoricalParams (Space_ space={})
	The uniform distribution over space, with log-weights that are its log-probabilities.
template<typename Derived>
	CategoricalParams (Space_ space, Eigen::DenseBase< Derived > const &logWeights)
	The distribution over space whose probabilities are proportional to \( e^{\ell_v} \), with logWeights \( \ell \), one per value.
Space_ const &	space () const
Eigen::Index	cardinality () const
ArrayType const &	logWeights () const
Scalar	logWeight (Eigen::Index value) const
std::expected< Scalar, WeightError >	logTotalWeight () const
template<typename Derived>
void	setLogWeights (Eigen::DenseBase< Derived > const &logWeights)
	Sets the log-weights to logWeights, one per value.
template<typename Derived>
void	setWeights (Eigen::DenseBase< Derived > const &weights)
	Sets the weights to weights, one per value, which need not sum to one.
void	setLogWeight (Eigen::Index value, Scalar logWeight)
	Sets the log-weight of the value with flat index value to logWeight.
void	setWeight (Eigen::Index value, Scalar weight)
	Sets the weight of the value with flat index value to weight.
template<typename... Values> requires (sizeof...(Values) > 0)
void	setLogWeight (Scalar logWeight)
	Sets the log-weight of the value with the named values Values, one per axis (see valueOf()), to logWeight.
template<typename... Values> requires (sizeof...(Values) > 0)
void	setWeight (Scalar weight)
	Sets the weight of the value with the named values Values, one per axis (see valueOf()), to weight.
template<typename Derived>
void	reweight (Eigen::DenseBase< Derived > const &logLikelihoods)
	Multiplies each value's weight by its likelihood \( e^{\ell_v} \), with logLikelihoods \( \ell \) one per value, and checks nothing: several measurements can be added before one toDensity() or normalize().
template<typename Derived>
std::expected< Scalar, WeightError >	update (Eigen::DenseBase< Derived > const &logLikelihoods)
	Bayes' rule: multiplies each value's probability by its likelihood \( e^{\ell_v} \), with logLikelihoods \( \ell \) one per value, and normalizes.
std::expected< void, WeightError >	normalize ()
	Shifts the log-weights so that the weights sum to one, or returns the WeightError that stops it, leaving them unchanged.
template<typename P>
auto	marginal () const
template<typename P>
auto	conditional (Eigen::Index value) const
template<typename Value>
auto	conditional () const
std::expected< DensityType, WeightError >	toDensity () const &
void	toDensity () const &&=delete
	A density of a temporary would outlive it.

Static Public Member Functions
template<typename Derived>
static CategoricalParams	fromWeights (Space_ space, Eigen::DenseBase< Derived > const &weights)
template<typename Derived> requires FixedSizeSpace<Space_>
static CategoricalParams	fromWeights (Eigen::DenseBase< Derived > const &weights)
template<typename... Weights> requires FixedSizeSpace<Space_> && (CardinalityAtCompileTime != Eigen::Dynamic) && (sizeof...(Weights) > 0) && (std::convertible_to<Weights, Scalar_> && ...)
static CategoricalParams	fromWeights (Weights... weights)

Static Public Attributes
static constexpr int	CardinalityAtCompileTime = Space_::Cardinality
	the number of values, or Eigen::Dynamic
static constexpr int	MaxCardinalityAtCompileTime = Space_::MaxCardinality
	a bound on it, or Eigen::Dynamic
static constexpr bool	IsParams = true
	parameters, which views check

Detailed Description

template<DiscreteSpace Space_, RealScalar Scalar_ = double>
class Emrys::CategoricalParams< Space_, Scalar_ >

The parameters of a probability distribution over a discrete space: one weight per value.

The categorical distribution, kept as one log-weight per value, so that a value can be improbable without underflowing. The weights need not sum to one, and they are not checked when they are written: a histogram can be filled, a weight set by name, or several sensors' log-likelihoods added with reweight(), one write at a time, since only the whole set has to sum to something. toDensity() checks them once and returns the Categorical that evaluates the probabilities (decisions.md [params-and-density]). A value is its flat index (see Discrete spaces), and a value named by tags is valueOf<Mode, Turn, Outlier>().

auto p = CategoricalParams<Mode>::fromWeights(6.0, 1.0, 2.5, 0.5);
p.setWeight<Turn, Outlier>(0.0);          // rule a value out
auto const evidence = p.update(logLikelihoods);   // Bayes' rule, or a WeightError
auto const density = p.toDensity();      // the probabilities, or a WeightError
density->probability<Turn>();            // an event
p = predict(p, chain);                   // one step of a MarkovChain

The array holds one weight per value: inline up to the space's MaxCardinality, as a mean stores its coordinates, and on the heap only for an unbounded space.

Template Parameters

Space_	the discrete space (see Discrete spaces)
Scalar_	scalar type of the weights, `double` by default

See also: Categorical, MarkovChain, predict()

Member Typedef Documentation

◆ ArrayType

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

using Emrys::CategoricalParams< Space_, Scalar_ >::ArrayType

Initial value:

Eigen::Array<Scalar_, CardinalityAtCompileTime, 1, Eigen::ColMajor, MaxCardinalityAtCompileTime, 1>

One entry per value, in flat-index order.

Member Function Documentation

◆ cardinality()

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

Eigen::Index Emrys::CategoricalParams< Space_, Scalar_ >::cardinality ( ) const

inlinenodiscard

Returns: the number of values

◆ conditional() [1/2]

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

template<typename Value>

auto Emrys::CategoricalParams< Space_, Scalar_ >::conditional ( ) const

inlinenodiscard

Returns: the parameters of the other axes given the named value Value (a value's tag or a TagPath ending in one): conditional<Turn>() is conditional<Maneuver>(Maneuver::index<Turn>())

◆ conditional() [2/2]

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

template<typename P>

auto Emrys::CategoricalParams< Space_, Scalar_ >::conditional ( Eigen::Index value ) const

inlinenodiscard

Returns: the parameters of the other axes given that the axis named by the path P (a tag or a TagPath) has the value with index value in it: the weights of the values that have it. If they are all zero, toDensity() on the result says so.

◆ fromWeights() [1/3]

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

template<typename Derived>
requires FixedSizeSpace<Space_>

CategoricalParams Emrys::CategoricalParams< Space_, Scalar_ >::fromWeights ( Eigen::DenseBase< Derived > const & weights )

inlinestaticnodiscard

Returns: the distribution over the fixed-size space proportional to weights: fromWeights(space, weights) in Space_{}.

◆ fromWeights() [2/3]

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

template<typename Derived>

CategoricalParams Emrys::CategoricalParams< Space_, Scalar_ >::fromWeights	(	Space_	space,
		Eigen::DenseBase< Derived > const &	weights )

inlinestaticnodiscard

Returns: the distribution over space proportional to weights, one per value, which need not sum to one. A negative weight has no logarithm, so toDensity() reports it as WeightError::NonFinite.

◆ fromWeights() [3/3]

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

template<typename... Weights>
requires FixedSizeSpace<Space_> && (CardinalityAtCompileTime != Eigen::Dynamic) && (sizeof...(Weights) > 0) &&
(std::convertible_to<Weights, Scalar_> && ...)

CategoricalParams Emrys::CategoricalParams< Space_, Scalar_ >::fromWeights ( Weights... weights )

inlinestaticnodiscard

Returns: the distribution over the fixed-size space proportional to weights, one argument per value in flat-index order, written without an Eigen vector: CategoricalParams<Maneuver>::fromWeights(0.9, 0.1). The space must have a fixed number of values, and the count is checked at compile time.

◆ logTotalWeight()

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

std::expected< Scalar, WeightError > Emrys::CategoricalParams< Space_, Scalar_ >::logTotalWeight ( ) const

inlinenodiscard

Returns: the log of the sum of the weights, or the WeightError that makes them fail to define a distribution: they are all zero, or one is NaN or \( +\infty \)

◆ logWeight()

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

Scalar Emrys::CategoricalParams< Space_, Scalar_ >::logWeight ( Eigen::Index value ) const

inlinenodiscard

Returns: the log-weight of the value with flat index value

◆ logWeights()

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

ArrayType const & Emrys::CategoricalParams< Space_, Scalar_ >::logWeights ( ) const

inlinenodiscard

Returns: the log-weight of each value

◆ marginal()

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

template<typename P>

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

inlinenodiscard

Returns: the parameters of the axis named by the path P (a tag or a TagPath), summed over the others, with the same total weight

◆ space()

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

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

inlinenodiscard

Returns: the discrete space

◆ toDensity()

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

std::expected< DensityType, WeightError > Emrys::CategoricalParams< Space_, Scalar_ >::toDensity ( ) const &

inlinenodiscard

Returns: a Categorical that checks this object, or the WeightError that makes the weights fail to define a distribution (see logTotalWeight())

◆ update()

template<DiscreteSpace Space_, RealScalar Scalar_ = double>

template<typename Derived>

std::expected< Scalar, WeightError > Emrys::CategoricalParams< Space_, Scalar_ >::update ( Eigen::DenseBase< Derived > const & logLikelihoods )

inlinenodiscard

Bayes' rule: multiplies each value's probability by its likelihood \( e^{\ell_v} \), with logLikelihoods \( \ell \) one per value, and normalizes.

Returns: the log of the evidence \( \sum_v p_v e^{\ell_v} \), or a WeightError if the weights before or after fail to define a distribution, in which case they are unchanged

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

EmrysFilter/Distributions/Categorical.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ ArrayType

Member Function Documentation

◆ cardinality()

◆ conditional() [1/2]

◆ conditional() [2/2]

◆ fromWeights() [1/3]

◆ fromWeights() [2/3]

◆ fromWeights() [3/3]

◆ logTotalWeight()

◆ logWeight()

◆ logWeights()

◆ marginal()

◆ space()

◆ toDensity()

◆ update()