Multi-sequence Hidden Markov Models

HMMRBM extends HiddenMarkovModels.jl with multi-sequence containers that reuse the same emission parameters across several observation streams. Each sequence keeps its own initial distribution and transition matrix, while a shared parameter tensor drives the Restricted Boltzmann Machine emissions.

Types

HMMRBM.MultiSeqHMM — Type

struct MultiSeqHMM{T,F,AV,AM,Aθ} <: AbstractVector{SingleSeqHMM{MultiSeqHMM{T,F,AV,AM,Aθ},Int}}

A multi-sequence Hidden Markov Model (HMM) whose emission distributions share parameters across sequences.

It acts as a collection of single-sequence HMMs (SingleSeqHMM), one per observed sequence.

Type F is the emission distribution family type and must implement distribution(::F, parameter).

The returned distribution type must implement:

Random.rand(::AbstractRNG, dist)
DensityInterface.logdensityof(dist, obs)

HMMRBM.SingleSeqHMM — Type

struct SingleSeqHMM{T,I<:Integer} <: AbstractHMM

A single-sequence Hidden Markov Model (HMM) view into a MultiSeqHMM.

HMMRBM.Distribution — Type

Distribution

The following functions must be defined:

family(::T)::DistributionFamily{T} where T<:Distribution
parameter(::T) where T<:Distribution
Random.rand(::AbstractRNG, dist::T) where T<:Distribution
DensityInterface.logdensityof(dist::T, obs) where T<:Distribution

HMMRBM.DistributionFamily — Type

DistributionFamily{T<:Distribution}

The following functions must be defined:

distribution(::DistributionFamily{T}, parameter)::T where T<:Distribution
baum_value_gradient(dist::Distribution, obs_seq, γ)::Tuple{Function,Function}

where the returned tuple contains the objective and gradient functions required by Baum-Welch

Functions

HMMRBM.inits — Function

inits(hmm::MultiSeqHMM)

Get the vector of initial state distributions for each sequence.

HMMRBM.loginits — Function

loginits(hmm::MultiSeqHMM)

Get the vector of log initial state distributions for each sequence.

HMMRBM.transitions — Function

transitions(hmm::MultiSeqHMM)

Get the vector of transition matrices for each sequence.

HMMRBM.logtransitions — Function

logtransitions(hmm::MultiSeqHMM)

Get the vector of log transition matrices for each sequence.

HMMRBM.emissions — Function

emissions(hmm::MultiSeqHMM)

Get the vector of emission distribution families for each sequence.

HMMRBM.emission — Function

emission(hmm::SingleSeqHMM)

Get the emission distribution family for the single-sequence HMM.

HMMRBM.emission_parameters — Function

emission_parameters(hmm)

Get the shared emission parameters for the HMM.

HMMRBM.hyperparameters — Function

hyperparameters(hmm)

Get the hyperparameters NamedTuple for the HMM.

HMMRBM.parent — Function

parent(hmm::SingleSeqHMM)

Get the parent MultiSeqHMM of the single-sequence HMM.

HMMRBM.sequence_index — Function

sequence_index(hmm::SingleSeqHMM)

Get the sequence index of the single-sequence HMM within its parent MultiSeqHMM.

HMMRBM.hmm_rbm — Function

hmm_rbm(rbms, n_states; l2=0.0)

Create a MultiSeqHMM that ties each observed sequence to one RBM while sharing a common number of hidden Markov states. Initial probabilities and transition matrices are seeded with simple defaults, and the returned model stores the provided ℓ2 regularisation value in its hyperparameters.

HMMRBM.distribution — Function

distribution(family, parameter)

Get the distribution instance associated with the given family and parameter.

HMMRBM.family — Function

family(dist)

Get the distribution family associated with the given dist.

HMMRBM.parameter — Function

parameter(dist)

Get the parameter object associated with the given dist.

HMMRBM.state_count — Function

state_count(hmm)

Get the number of hidden states in the HMM.

state_count(A::GroupedTransitions)

Get the total number of states represented by the grouped transition matrix.

state_count(A::SparseTransitions)

Get the number of states represented by the sparse transition matrix.

state_count(A::AnnealedTransitions)

Get the number of states represented by the annealed transition matrix.

HMMRBM.baum_value_gradient — Function

baum_value_gradient(dist, obs_seq, γ)

Prepare the objective and gradient evaluations required by the Baum-Welch update for a single HMM state.

Returns a tuple of two functions (f, grad!) where f(x) returns the objective value at x, and grad!(∇ₓf, x) fills ∇ₓf with the gradient at x.

HMMRBM.baum_welch_transition_update! — Function

baum_welch_transition_update!(trans, logtrans, expected)

Update the transition matrix trans and logtrans in place using the expected transition counts expected.

Saving

Persistence helpers are provided when the optional dependency HDF5.jl is available. Loading the package with using HDF5 triggers the extension that defines the persistence methods.

HMMRBM.MultiSeqHMM_to_group! — Function

MultiSeqHMM_to_group!(group, hmm; kwargs...)

Persist a MultiSeqHMM into an HDF5 group and optionally store metadata in a dedicated info subgroup.

HMMRBM.MultiSeqHMM_from_group — Function

MultiSeqHMM_from_group(group; emissions)

Rebuild a MultiSeqHMM from datasets stored in an HDF5 group. The caller supplies the emission families that match the stored parameters.

HMMRBM.save_hmm — Function

save_hmm(hmm, filename; kwargs...)

Write a MultiSeqHMM to an HDF5 file, forwarding keyword arguments to MultiSeqHMM_to_group!.

HMMRBM.load_hmm — Function

load_hmm(filename; emissions)

Load a MultiSeqHMM from an HDF5 file by reading the saved arrays and pairing them with the provided emission families.