Skip to content

Latest commit

 

History

History
156 lines (96 loc) · 4.97 KB

README.md

File metadata and controls

156 lines (96 loc) · 4.97 KB

HiddenMarkovModel Class Documentation

HiddenMarkovModel implements hidden Markov models with Gaussian mixtures as distributions on top of TensorFlow 2.0.

Installation

pip install --upgrade git+https://gitlab.com/kesmarag/hmm-gmm-tf2

Class Definition:

HiddenMarkovModel(p0, tp, em_w, em_mu, em_var)

Arguments:

  • p0: 1D numpy array

    • Determines the probability of the first hidden variable in the Markov chain for each hidden state. (e.g., np.array([0.5, 0.25, 0.25]) for 3 hidden states)

  • tp: 2D numpy array

    • Determines the transition probabilities for moving from one hidden state to another. (e.g., np.array([[0.80, 0.15, 0.05], [0.20, 0.55, 0.25], [0.15, 0.15, 0.70]]) for 3 hidden states)

  • em_w: 2D numpy array

    • Contains the weights of the Gaussian mixtures. Each line corresponds to a hidden state. (e.g., np.array([[0.8, 0.2], [0.5, 0.5], [0.1, 0.9]]) for 3 hidden states, 2 Gaussian mixtures)

  • em_mu: 3D numpy array

    • Determines the mean value vector for each component of the emission distributions. (e.g., np.array([[[2.2, 1.3], [1.2, 0.2]], [[1.3, 5.0], [4.3, -2.3]], [[0.0, 1.2], [0.4, -2.0]]]) for 3 hidden states, 2 Gaussian mixtures)

  • em_var: 3D numpy array

    • Determines the variance vector for each component of the emission distributions. (e.g., np.array([[[2.2, 1.3], [1.2, 0.2]], [[1.3, 5.0], [4.3, -2.3]], [[0.0, 1.2], [0.4, -2.0]]]) for 3 hidden states, 2 Gaussian mixtures)

log_posterior(self, data)

Log probability density function.

Arguments:

  • data: 3D numpy array
    • The first dimension refers to each component of the batch.
    • The second dimension refers to each specific time interval.
    • The third dimension refers to the values of the observed data.

Returns:

  • 1D numpy array with the values of the log-probability function with respect to the observations.

viterbi_algorithm(self, data)

Performs the Viterbi algorithm for calculating the most probable hidden state path of some batch data.

Arguments:

  • data: 3D numpy array
    • The first dimension refers to each component of the batch.
    • The second dimension refers to each specific time interval.
    • The third dimension refers to the values of the observed data.

Returns:

  • 2D numpy array with the most probable hidden state paths.
    • The first dimension refers to each component of the batch.
    • The second dimension the order of the hidden states: (0, 1, ..., K-1), where K is the total number of hidden states.

fit(self, data, max_iter=100, min_var=0.01, verbose=False)

Re-adapts the model parameters with respect to a batch of observations, using the Expectation-Maximization (E-M) algorithm.

Arguments:

  • data: 3D numpy array

    • The first dimension refers to each component of the batch.
    • The second dimension refers to each specific time step.
    • The third dimension refers to the values of the observed data.

  • max_iter: Positive integer number (default: 100)

    • The maximum number of iterations.

  • min_var: Non-negative real value (default: 0.01)

    • The minimum acceptance variance. Used to prevent overfitting of the model.

  • verbose: Boolean (default: False)

    • If True, prints detailed progress information during training.

Returns:

  • 1D numpy array with the log-posterior probability densities for each training iteration.

generate(self, length, num_series=1, p=0.2)

Generates a batch of time series.

Arguments:

  • length: Positive integer

    • The length of each time series.

  • num_series: Positive integer (default: 1)

    • The number of time series to generate.

  • p: Real value between 0.0 and 1.0 (default: 0.2)

    • The importance sampling parameter.

Returns:

  • 3D numpy array with the drawn time series.
  • 2D numpy array with the corresponding hidden states.

kl_divergence(self, other, data)

Estimates the value of the Kullback-Leibler divergence (KLD) between the model and another model with respect to some data.

Arguments:

  • other: Another instance of the HiddenMarkovModel class for comparison.

  • data: 3D numpy array representing observed data.

Returns:

  • Estimated value of the Kullback-Leibler divergence (KLD) between the models with respect to the data.

Example Usage:

import numpy as np
from kesmarag.hmm import HiddenMarkovModel, new_left_to_right_hmm, store_hmm, restore_hmm, toy_example

dataset = toy_example()
model = new_left_to_right_hmm(states=3, mixtures=2, data=dataset)
model.fit(dataset, verbose=True)

# Store and restore the model
store_hmm(model, 'test_model.npz')
loaded_model = restore_hmm('test_model.npz')

# Generate data using the trained model
gen_data = model.generate(700, 10, 0.05)

This code demonstrates how to create, train, store, restore, and generate data using the HiddenMarkovModel class. The class provides functionality for working with hidden Markov models with Gaussian mixtures.