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)
• transition_matrix!(P, hmm, control, par)
• emission_parameters(hmm, control, par)
• emission_parameters!(θ, hmm, control, par)
• emission_distribution(hmm, s, θ)

Optional methods

• log_initial_distribution(hmm, par)
• log_transition_matrix(hmm, control, par)
• log_transition_matrix!(logP, hmm, control, par)

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)

Optional methods

• log_initial_distribution(hmm, par)
• log_transition_matrix(hmm, par)

Compatible with

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

ForwardBackwardStorage{R}

Storage for the forward-backward algorithm applied to multiple sequences.

Fields

• α::Vector{Matrix{R}}
• c::Vector{Vector{R}}
• β::Vector{Matrix{R}}
• bβ::Vector{Matrix{R}}
• γ::Vector{Matrix{R}}
• ξ::Vector{Array{R,3}}

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!(β, bβ, c, obs_density, hmm::AbstractHMM, par)

Perform a backward pass by mutating β, bβ and c.

baum_welch(obs_sequence, hmm_init::HMM[, par; max_iterations, tol])

Apply baum_welch_multiple_sequences on a single observation sequence.

baum_welch_multiple_sequences(obs_sequences, hmm_init::HMM[, par; max_iterations, tol])

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

The parameters are not modified.

compute_obs_density(obs_sequence, hmm, par)

Create a new observation density matrix and apply update_obs_density!.

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)

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

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_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.

forward!(α, c, obs_density, hmm::AbstractHMM, par)

Perform a forward pass by mutating α and c.

forward_backward!(α, c, β, bβ, γ, ξ, obs_density, hmm::AbstractHMM, par)

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

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.

If safe = true, everything is done in log scale.

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.

If safe = true, everything is done in log scale.

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_forward_backward_multiple_sequences(obs_densities)

Create a ForwardBackwardStorage with same number type as the vector of observation density matrices.

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.

light_forward_log(obs_sequence, hmm::AbstractHMM, par)

Perform a lightweight forward pass in log scale with minimal storage requirements.

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

Perform a lightweight forward pass in log scale 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!(logP, hmm::AbstractControlledHMM, control, par)

Update logP with the state transition matrix in log scale for hmm with control control and 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_stream 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.

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!(P, hmm::AbstractControlledHMM, control, par)

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

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::AbstractControlledHMM, obs_sequence, control_sequence, par; safe)

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

If safe = true, everything is done in log scale.

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

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

If safe = true, everything is done in log scale.