A hidden Markov model filter: a CategoricalParams state, the chain that moves it, and the log-evidence of the measurements so far. More...

#include <EmrysFilter/Filters/HiddenMarkovFilter.h>

Inheritance diagram for Emrys::HiddenMarkovFilter< Space_, Chain_, Scalar_, Upkeep_ >:

Public Types
using	Scalar = Scalar_
	the scalar type of the probabilities
using	SpaceType = Space_
	the discrete space
using	ChainType = Chain_
	the chain
using	StateType = CategoricalParams<Space_, Scalar_>
	the state the filter owns

Public Member Functions
	HiddenMarkovFilter (Chain_ chain, StateType state, std::type_identity_t< Upkeep_ > upkeep={})
	The filter moved by chain, starting from state, with upkeep upkeep, which maintain() runs.
	HiddenMarkovFilter (Chain_ chain)
	The filter moved by chain, starting from the uniform distribution over its space.
StateType const &	state () const
StateType &	state ()
void	setState (StateType state)
	Replaces the state estimate with one on the chain's space, as the constructor's must be, leaving the log-evidence as it is.
Chain_ const &	chain () const
Chain_ &	chain ()
Scalar	logEvidence () const
void	resetLogEvidence ()
	Sets the log-evidence back to zero, to start a new record from the current state.
void	predict ()
	Moves the state one step of a MarkovChain: \( p' = p\, \Pi \).
void	predict (TimeStep< Scalar > auto const &dt)
	Moves the state over an interval of dt, any TimeStep (see Time steps), of a ContinuousTimeMarkovChain: \( p' = p\, e^{Q \Delta t} \).
std::expected< Scalar, WeightError >	predict (TimeStep< Scalar > auto const &dt, ArrivalInterval< Space_, Scalar_ > const &interval)
	Moves the state over an interval of dt of a ContinuousTimeMarkovChain while observing interval of a Markov-modulated Poisson process, and adds its log-likelihood to the log-evidence (see ArrivalInterval).
CategoricalPredictedJoint< Space_, Scalar_ >	predictJoint ()
	Moves the state one step of a MarkovChain, as predict(), and returns the step's joint for a CategoricalHistory.
CategoricalPredictedJoint< Space_, Scalar_ >	predictJoint (TimeStep< Scalar > auto const &dt)
	Moves the state over an interval of dt of a ContinuousTimeMarkovChain, as predict(dt), and returns the step's joint for a CategoricalHistory.
std::expected< CategoricalPredictedJoint< Space_, Scalar_ >, WeightError >	predictJoint (TimeStep< Scalar > auto const &dt, ArrivalInterval< Space_, Scalar_ > const &interval)
	Moves the state over an interval of dt while observing interval, as predict(dt, interval), and returns the step's joint for a CategoricalHistory.
template<EmissionModel< Space_ > E>
std::expected< HiddenMarkovFilterUpdate< Scalar_ >, WeightError >	update (E const &emission)
	Updates the state by emission, by Bayes' rule, in place, and adds the measurement's log-evidence to the total.

Detailed Description

template<DiscreteSpace Space_, typename Chain_ = MarkovChain<Space_>, RealScalar Scalar_ = double, typename Upkeep_ = upkeep::None>
class Emrys::HiddenMarkovFilter< Space_, Chain_, Scalar_, Upkeep_ >

A hidden Markov model filter: a CategoricalParams state, the chain that moves it, and the log-evidence of the measurements so far.

The forward recursion of a hidden Markov model (Rabiner (1989), §III-A), kept normalized at every update as that paper's §V-A scales it, with the log of each step's normalizer summed into logEvidence(), which is \( \log p(z_{1:k}) \), the quantity for comparing models. The weights themselves are logs, so a long run of unlikely measurements underflows neither [discrete-spaces]. A state given by the user need not be normalized; an update checks it, and fails with a WeightError if its weights fail to define a distribution. An update conditions the state where it is, and a measurement no value explains is rejected and leaves it as it was [update-outcomes].

With a MarkovChain, predict() takes one step of the chain. With a ContinuousTimeMarkovChain, predict(dt) moves the state over an interval exactly, and predict(dt, interval) does so while observing an ArrivalInterval, which makes the filter the Markov-modulated Poisson process filter. update() takes any EmissionModel.

auto filter = HiddenMarkovFilter{MarkovChain<Weather>::persistent(0.7), CategoricalParams<Weather>{}};
filter.predict();
auto const updated = filter.update(table.observe(Activity::index<Walk>()));   // or a WeightError
filter.state().toDensity()->probability<Rainy>();
filter.logEvidence();

Template Parameters

Space_	the discrete space (see Discrete spaces)
Chain_	MarkovChain or ContinuousTimeMarkovChain on the space
Scalar_	scalar type of the probabilities, `double` by default
Upkeep_	the upkeep maintain() runs on the state (see Upkeep), upkeep::None unless given one; the library has no action for a categorical state, so it is the caller's own

See also: CategoricalParams, EmissionModel, Filters