API reference

CHMMs

Alias for ControlledHiddenMarkovModels.

ControlledHiddenMarkovModels

A package for Hidden Markov Models with exogenous control variables.

AbstractControlledHMM

Alias for AbstractControlledHiddenMarkovModel.

AbstractControlledHiddenMarkovModel

Interface for Hidden Markov Models with arbitrary emissions and exogenous control variables.

Required methods

• nb_states(hmm, par)
• initial_distribution(hmm, par)
• transition_matrix(hmm, control, par)
• emission_parameters(hmm, control, par)
• emission_distribution(hmm, s, θ)

Compatible with

• rand(rng, hmm, control_sequence, par)
• logdensityof(hmm, obs_sequence, control_sequence, par; safe)
• infer_current_state(hmm, obs_sequence, control_sequence, par; safe)

AbstractHMM

Alias for AbstractHiddenMarkovModel.

AbstractHiddenMarkovModel

Interface for Hidden Markov Models with arbitrary emissions.

Required methods

• nb_states(hmm, par)
• initial_distribution(hmm, par)
• transition_matrix(hmm, par)
• emission_distribution(hmm, s, par)

Compatible with

• rand(rng, hmm, T, par)
• logdensityof(hmm, obs_sequence, par)
• infer_current_state(hmm, obs_sequence, par)

HMM

Alias for HiddenMarkovModel.

HiddenMarkovModel{R1,R2,D}

Concrete subtype of AbstractHMM which stores the state and observation parameters directly.

Fields

• p0::Vector{R1}
• P::Matrix{R2}
• emissions::Vector{D}

Compatible with

• • baum_welch_multiple_sequences(obs_sequences, hmm_init, par; kwargs...)
• • baum_welch(obs_sequence, hmm_init, par; kwargs...)

rand(rng, hmm::AbstractHMM, T, par)

Sample a trajectory of length T from hmm with parameters par.

Returns a couple (state_sequence, obs_sequence).

rand(rng, hmm::AbstractControlledHMM, control_sequence, par)

Sample a trajectory from hmm with controls control_sequence and parameters par.

Returns a couple (state_sequence, obs_sequence).

backward!(β, eβ, c, obs_density, P)

Perform a backward pass by mutating β and eβ. Comes after forward pass.

baum_welch(obs_sequences, hmm_init::HMM[, par; maxiter, tol])

Apply the Baum-Welch algorithm on multiple observation sequences, starting from an initial HMM hmm_init with parameters par (not modifed).

emission_distribution(hmm::AbstractControlledHMM, s, θ)

Compute the emission distribution in state s for hmm with emission parameters θ. Note that θ was computed using emission_parameters(hmm, control, par).

The object returned must be sampleable and implement DensityInterface.jl.

emission_distribution(hmm::AbstractHMM, s, par)

Compute the emission distribution in state s for hmm with parameters par.

The object returned must be sampleable and implement DensityInterface.jl.

emission_parameters(hmm::AbstractControlledHMM, control, par)

Compute the parameters of all emission distributions for hmm with control control and parameters par.

emission_type(::Type{<:HMM})

Return the type of an emission distribution object.

fit_mle_from_multiple_sequences(::Type{D}, xs, ws)

Fit a distribution of type D based on multiple sequences of observations xs associated with multiple sequences of weights ws.

Must accept arbitrary iterables for xs and ws.

fit_mle_from_single_sequence(::Type{D}, x, w)

Fit a distribution of type D based on a single sequence of observations x associated with a single sequence of weights w.

Defaults to Distributions.fit_mle, with a special case for vectors of vectors (because Distributions.fit_mle accepts matrices instead). Users are free to override this default for concrete distributions.

forward!(α, c, obs_density, p0, P)

Perform a forward pass by mutating α and c.

forward_backward!(α, c, β, eβ, γ, ξ, obs_density, p0, P)

Apply the full forward-backward algorithm by mutating α, c, β, eβ, γ and ξ.

infer_current_state(hmm::AbstractHMM, obs_sequence, par; safe)

Infer the posterior distribution of the current state given obs_sequence for hmm with parameters par.

infer_current_state(hmm::AbstractControlledHMM, obs_sequence, control_sequence, par; safe)

Infer the posterior distribution of the current state given obs_sequence for hmm with controls control_sequence and parameters par.

initial_distribution(hmm::AbstractControlledHMM, par)

Return the vector of initial state probabilities for hmm with parameters par.

initial_distribution(hmm::AbstractHMM, par)

Compute the vector of initial state probabilities for hmm with parameters par.

initialize_obs_density(obs_sequence, hmm, par)

Create a new observation density matrix and apply update_obs_density!.

is_prob_vec(p; atol)

Check if p is a probability distribution vector.

iszero_safe(x::R)

Check if a number x is zero by comparing its inverse with typemax(R).

This is useful in the following case:

julia> x = 1e-320
1.0e-320

julia> iszero(x)
false

julia> inv(x)
Inf

light_forward(obs_sequence, hmm::AbstractHMM, par)

Perform a lightweight forward pass with minimal storage requirements.

light_forward(obs_sequence, control_sequence, hmm::AbstractControlledHMM, par)

Perform a lightweight forward pass with minimal storage requirements.

log_initial_distribution(hmm::AbstractControlledHMM, par)

Return the vector of initial state probabilities in log scale for hmm with parameters par.

log_initial_distribution(hmm::AbstractHMM, par)

Compute the vector of initial state probabilities in log scale for hmm with parameters par.

log_transition_matrix(hmm::AbstractControlledHMM, control, par)

Compute the state transition matrix in log scale for hmm with control control and parameters par.

log_transition_matrix(hmm::AbstractHMM, par)

Compute the state transition matrix in log scale for hmm with parameters par.

logsumexp(a)

Use logsumexp_offline to compute the logsumexp of an iterable a.

logsumexp_stream(::Type{T}, a)

Compute the logsumexp function in a single pass for an iterable a with elements of type T. Source: https://www.nowozin.net/sebastian/blog/streaming-log-sum-exp-computation.html

make_log_prob_vec!(logp)

Shift logp so that exp.(logp) becomes a probability distribution vector.

make_log_trans_mat!(logP)

Scale logP so that exp.(logP) becomes a transition (stochastic) matrix.

make_prob_vec!(p)

Scale p into a probability distribution vector.

make_trans_mat!(P)

Scale P into a transition (stochastic) matrix.

marginals!(γ, ξ, α, β, eβ, P)

Compute state and transition marginals by mutating γ and ξ. Comes after backward pass.

nb_states(hmm::AbstractControlledHMM, par)

Return the number of states for hmm with parameters par.

nb_states(hmm::AbstractHMM, par)

Compute the number of states for hmm with parameters par.

rand_prob_vec(rng, n)

Return a random probability distribution vector of size n.

rand_trans_mat(rng, n)

Return a transition (stochastic) matrix of size n with random transition probability distributions.

transition_matrix(hmm::AbstractControlledHMM, control, par)

Compute the state transition matrix for hmm with control control and parameters par.

transition_matrix(hmm::AbstractHMM, par)

Compute the state transition matrix for hmm with parameters par.

uniform_prob_vec(n)

Return a uniform probability distribution vector of size n.

uniform_trans_mat(n)

Return a transition (stochastic) matrix of size n with uniform transition probability distributions.

update_obs_density!(obs_density, obs_sequence, hmm::AbstractHMM, par)

Update the values obs_density[s, t] using the emission density of hmm with parameters par applied to obs_sequence[t].

logdensityof(hmm::AbstractHMM, obs_sequence, par; safe)

Compute the log likelihood of obs_sequence for hmm with parameters par.

logdensityof(hmm::AbstractControlledHMM, obs_sequence, control_sequence, par; safe)

Compute the log likelihood of obs_sequence for hmm with controls control_sequence and parameters par.