API Reference¶

This is the class and function reference of PyHHMM.

Please refer to the full user guide for further details, as the class and function raw specifications may not be enough to give full guidelines on their uses.

BaseHMM¶

class pyhhmm.base.BaseHMM(n_states, tr_params='st', init_params='st', init_type='uniform', pi_prior=1.0, A_prior=1.0, learning_rate=0.0, verbose=True)¶

Bases: object

Base class for the Hidden Markov Models. It allows for training evaluation and sampling from the HMM.

Parameters

n_states (int, optional) – number of hidden states in the model
tr_params (str, optional) – controls which parameters are updated in the training process. Can contain any combination of ‘s’ for starting probabilities (pi), ‘t’ for transition matrix, and other characters for subclass-specific emission parameters. Defaults to all parameters.
init_params (str, optional) – controls which parameters are initialised prior to training. Can contain any combination of ‘s’ for starting probabilities (pi), ‘t’ for transition matrix, and other characters for subclass-specific emission parameters. Defaults to all parameters.
init_type (str, optional) – controls whether pi and A are initialised from a Dirichlet or a uniform distribution. Defaults to ‘uniform’.
pi_prior (array_like, optional) – array of shape (n_states, ) setting the parameters of the Dirichlet prior distribution for the starting probabilities. Defaults to 1.
A_prior (array_like, optional) – array of shape (n_states, ), giving the parameters of the Dirichlet prior distribution for each row of the transition probabilities ‘A’. Defaults to 1.
pi (array_like) – array of shape (n_states, ) giving the initial state occupation distribution ‘pi’
A (array_like) – array of shape (n_states, n_states) giving the matrix of transition probabilities between states
learning_rate (float, optional) – a value from [0,1), controlling how much the past values of the model parameters count when computing the new model parameters during training; defaults to 0.
verbose (bool, optional) – flag to be set to True if per-iteration convergence reports should be printed. Defaults to True.

decode(obs_sequences, algorithm='viterbi')¶

Find the best state sequence (path), given the model and an observation.: i.e: max(P(Q|O,model)).

Parameters

obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
algorithm (string, optional) – name of the decoder algorithm to use; must be one of ‘viterbi’ or ‘map’. Defaults to ‘viterbi’.

Returns

log-probability of the produced state sequence

Return type

float

Returns

list of arrays of shape (n_samples, n_states) containing labels for each observation from obs_sequences obtained via the given decoder algorithm

Return type

list

forward(obs_seq, B_map=None)¶

Forward-Backward procedure is used to efficiently calculate the probability of the observations, given the model - P(O|model).

Parameters

obs_seq (array_like) – an observation sequence
B_map (array_like, optional) – mapping of the observations’ mass/density Bj(Ot) to Bj(t)

Returns

the log of the probability, i.e. the log likehood model, give the observation - logL(model|O).

Return type

float

get_stationary_distribution()¶

Compute the stationary distribution of states. The stationary distribution is proportional to the left-eigenvector associated with the largest eigenvalue (i.e., 1) of the transition matrix.

Returns: the stationary distribution of states
Return type: array_like

predict(X, algorithm='viterbi')¶

Find the most probable state sequence corresponding to X.

Parameters

X (array-like) – feature matrix of individual samples, shape (n_samples, n_features)
algorithm (string, optional) – name of the decoder algorithm to use; must be one of ‘viterbi’ or ‘map’. Defaults to ‘viterbi’.

Returns

labels for each sample from X

Return type

array-like

predict_proba(obs_sequences)¶

Compute the posterior probability for each state in the model.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: list of arrays of shape (n_samples, n_states) containing the state-membership probabilities for each sample in the observation sequences
Return type: list

sample(n_sequences=1, n_samples=1, return_states=False)¶

Generate random samples from the model.

Parameters

n_sequences (int, optional) – number of sequences to generate, defeaults to 1.
n_samples (int, optional) – number of samples to generate per sequence; defeaults to 1. If multiple sequences have to be generated, it is a list of the individual sequence lengths
return_states (bool, optional) – if True, the method returns the state sequence from which the samples were generated, defeaults to False.

Returns

a list containing one or n_sequences sample sequences

Return type

list

Returns

a list containing the state sequences that generated each sample sequence

Return type

list

score(obs_sequences)¶

Compute the per-sample average log-likelihood of the given data.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: the average of log-likelihoods over all the observation sequences
Return type: float

score_samples(obs_sequences)¶

Compute the log-likelihood of each sample.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: list of log-likelihoods over all the observation sequences
Return type: list

train(obs_sequences, n_init=1, n_iter=100, conv_thresh=0.1, conv_iter=5, ignore_conv_crit=False, plot_log_likelihood=False, no_init=False, n_processes=None, print_every=1)¶

Updates the HMMs parameters given a new set of observed sequences. The observations can either be a single (1D) array of observed symbols, or a 2D array (matrix), where each row denotes a multivariate time sample (multiple features). The model parameters are reinitialised ‘n_init’ times. For each initialisation the updated model parameters and the log-likelihood is stored and the best model is selected at the end.

Parameters

obs_sequences (list) – a list of arrays containing the observation sequences of different lengths
n_init (int, optional) – number of initialisations to perform; defaults to 1
n_iter (int, optional) – max number of iterations to run for each initialisation; defaults to 100
conv_thresh (float, optional) – the threshold for the likelihood increase (convergence); defaults to 0.1
conv_iter (int, optional) – number of iterations for which the convergence criteria has to hold before early-stopping; defaults to 5
ignore_conv_crit (bool, optional) – flag to indicate whether to iterate until n_iter is reached or perform early-stopping; defaults to False
plot_log_likelihood (bool, optional) – parameter to activate plotting the evolution of the log-likelihood after each initialisation; defaults to False
no_init (bool, optional) – flag to indicate wheather to initialise the Parameters before training (it can only be True if the parameters are manually set before or they were already trained); defaults to False
n_processes (int, optional) – number of processes to use if the training should be performed using parallelisation; defaults to None
print_every (int, optional) – if verbose is True, print progress info every ‘print_every’ iterations; defaults to 1

Returns

the updated model

Return type

object

Returns

the log_likelihood of the best model

Return type

float

GaussianHMM¶

class pyhhmm.gaussian.GaussianHMM(n_states=1, n_emissions=1, tr_params='stmc', init_params='stmc', covariance_type='diagonal', pi_prior=1.0, A_prior=1.0, means_prior=0, means_weight=0, covars_prior=0.01, covars_weight=1, min_covar=0.001, learning_rate=0.0, verbose=False)¶

Bases: pyhhmm.base.BaseHMM

Hidden Markov Model with Gaussian emissions.

Parameters

n_states (int, optional) – number of hidden states in the model
n_emissions (int, optional) – number of Gaussian features
tr_params – controls which parameters are updated in the training process. Can contain any combination of ‘s’ for starting probabilities (pi), ‘t’ for transition matrix, ‘m’ for state means and ‘c’ for covariances. Defaults to all parameters.
init_params (str, optional) – controls which parameters are initialised prior to training. Can contain any combination of ‘s’ for starting probabilities (pi), ‘t’ for transition matrix, ‘m’ for state means and ‘c’ for covariances. Defaults to all parameters.
covariance_type (str, optional) – string describing the type of covariance parameters to use, defaults to ‘full’.
pi_prior (np.array, optional) – array of shape (n_states, ) setting the parameters of the Dirichlet prior distribution for the starting probabilities. Defaults to 1.
pi (np.array) – array of shape (n_states, ) giving the initial state occupation distribution ‘pi’
A_prior (np.array, optional) – array of shape (n_states, ), giving the parameters of the Dirichlet prior distribution for each row of the transition probabilities ‘A’. Defaults to 1.
A (np.array) – array of shape (n_states, n_states) giving the matrix of transition probabilities between states
means_prior (np.array, optional) – array of shape (n_states, 1), the mean of the Normal prior distribution for the means. Defaults to 0.
means_weight (np.array, optional) – array of shape (n_states, 1), the precision of the Normal prior distribution for the means. Defaults to 0.
means (np.array) – array of shape (n_states, n_emissions) containing the mean parameters for each state
covars_prior (np.array, optional) – array of shape (n_states, 1), the mean of the Normal prior distribution for the covariance matrix. Defaults to 0.
covars_weight (np.array, optional) – array of shape (n_states, 1), the precision of the Normal prior distribution for the covariance. Defaults to 0.
min_covar (float, optional) – floor on the diagonal of the covariance matrix to prevent overfitting. Defaults to 1e-3.
covars (np.array) – covariance parameters for each state arranged in an array of shape depends covariance_type: (n_states, ) if ‘spherical’, (n_states, n_emissions) if ‘diagonal’, (n_states, n_emissions, n_emissions) if ‘full’, (n_emissions, n_emissions) if ‘tied’
learning_rate (float, optional) – a value from [0,1), controlling how much the past values of the model parameters count when computing the new model parameters during training; defaults to 0.
verbose (bool, optional) – flag to be set to True if per-iteration convergence reports should be printed. Defaults to True.

decode(obs_sequences, algorithm='viterbi')¶

Find the best state sequence (path), given the model and an observation.: i.e: max(P(Q|O,model)).

Parameters

obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
algorithm (string, optional) – name of the decoder algorithm to use; must be one of ‘viterbi’ or ‘map’. Defaults to ‘viterbi’.

Returns

log-probability of the produced state sequence

Return type

float

Returns

list of arrays of shape (n_samples, n_states) containing labels for each observation from obs_sequences obtained via the given decoder algorithm

Return type

list

forward(obs_seq, B_map=None)¶

Forward-Backward procedure is used to efficiently calculate the probability of the observations, given the model - P(O|model).

Parameters

obs_seq (array_like) – an observation sequence
B_map (array_like, optional) – mapping of the observations’ mass/density Bj(Ot) to Bj(t)

Returns

the log of the probability, i.e. the log likehood model, give the observation - logL(model|O).

Return type

float

get_n_fit_scalars_per_param()¶: Return the number of trainable model parameters.

get_stationary_distribution()¶

Compute the stationary distribution of states. The stationary distribution is proportional to the left-eigenvector associated with the largest eigenvalue (i.e., 1) of the transition matrix.

Returns: the stationary distribution of states
Return type: array_like

predict(X, algorithm='viterbi')¶

Find the most probable state sequence corresponding to X.

Parameters

X (array-like) – feature matrix of individual samples, shape (n_samples, n_features)
algorithm (string, optional) – name of the decoder algorithm to use; must be one of ‘viterbi’ or ‘map’. Defaults to ‘viterbi’.

Returns

labels for each sample from X

Return type

array-like

predict_proba(obs_sequences)¶

Compute the posterior probability for each state in the model.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: list of arrays of shape (n_samples, n_states) containing the state-membership probabilities for each sample in the observation sequences
Return type: list

sample(n_sequences=1, n_samples=1, return_states=False)¶

Generate random samples from the model.

Parameters

n_sequences (int, optional) – number of sequences to generate, defeaults to 1.
n_samples (int, optional) – number of samples to generate per sequence; defeaults to 1. If multiple sequences have to be generated, it is a list of the individual sequence lengths
return_states (bool, optional) – if True, the method returns the state sequence from which the samples were generated, defeaults to False.

Returns

a list containing one or n_sequences sample sequences

Return type

list

Returns

a list containing the state sequences that generated each sample sequence

Return type

list

score(obs_sequences)¶

Compute the per-sample average log-likelihood of the given data.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: the average of log-likelihoods over all the observation sequences
Return type: float

score_samples(obs_sequences)¶

Compute the log-likelihood of each sample.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: list of log-likelihoods over all the observation sequences
Return type: list

train(obs_sequences, n_init=1, n_iter=100, conv_thresh=0.1, conv_iter=5, ignore_conv_crit=False, plot_log_likelihood=False, no_init=False, n_processes=None, print_every=1)¶

Updates the HMMs parameters given a new set of observed sequences. The observations can either be a single (1D) array of observed symbols, or a 2D array (matrix), where each row denotes a multivariate time sample (multiple features). The model parameters are reinitialised ‘n_init’ times. For each initialisation the updated model parameters and the log-likelihood is stored and the best model is selected at the end.

Parameters

obs_sequences (list) – a list of arrays containing the observation sequences of different lengths
n_init (int, optional) – number of initialisations to perform; defaults to 1
n_iter (int, optional) – max number of iterations to run for each initialisation; defaults to 100
conv_thresh (float, optional) – the threshold for the likelihood increase (convergence); defaults to 0.1
conv_iter (int, optional) – number of iterations for which the convergence criteria has to hold before early-stopping; defaults to 5
ignore_conv_crit (bool, optional) – flag to indicate whether to iterate until n_iter is reached or perform early-stopping; defaults to False
plot_log_likelihood (bool, optional) – parameter to activate plotting the evolution of the log-likelihood after each initialisation; defaults to False
no_init (bool, optional) – flag to indicate wheather to initialise the Parameters before training (it can only be True if the parameters are manually set before or they were already trained); defaults to False
n_processes (int, optional) – number of processes to use if the training should be performed using parallelisation; defaults to None
print_every (int, optional) – if verbose is True, print progress info every ‘print_every’ iterations; defaults to 1

Returns

the updated model

Return type

object

Returns

the log_likelihood of the best model

Return type

float

MultinomialHMM¶

class pyhhmm.multinomial.MultinomialHMM(n_states, n_emissions, n_features, tr_params='ste', init_params='ste', init_type='uniform', pi_prior=1.0, A_prior=1.0, missing=nan, nr_no_train_de=0, state_no_train_de=None, learning_rate=0.1, verbose=True)¶

Bases: pyhhmm.base.BaseHMM

Hidden Markov Model with multiple multinomial (discrete) emissions.

Parameters

n_states (int) – number of hidden states in the model
n_emissions (int) – number of distinct observation symbols per state
n_features (list) – list of the number of possible observable symbols for each emission
tr_params (str, optional) – controls which parameters are updated in the training process; can contain any combination of ‘s’ for starting probabilities (pi), ‘t’ for transition matrix, and other characters for subclass-specific emission parameters, defaults to ‘ste’
init_params (str, optional) – controls which parameters are initialised prior to training. Can contain any combination of ‘s’ for starting probabilities (pi), ‘t’ for transition matrix, and other characters for subclass-specific emission parameters, defaults to ‘ste’
init_type (str, optional) – name of the initialisation method to use for initialising the start, transition and emission matrices, defaults to ‘random’
pi_prior (float or array_like, optional) – float or array of shape (n_states, ) setting the parameters of the Dirichlet prior distribution for ‘pi’, defaults to 1.0
pi (array_like) – array of shape (n_states, ) giving the initial state occupation distribution ‘pi’
A_prior (float or array_like, optional) – float or array of shape (n_states, n_states), giving the parameters of the Dirichlet prior distribution for each row of the transition probabilities ‘A’, defaults to 1.0
A (array_like) – array of shape (n_states, n_states) giving the matrix of transition probabilities between states
B (list) – the probabilities of emitting a given symbol when in each state
missing (int or np.nan, optional) – a value indicating what character indicates a missed observation in the observation sequences, defaults to np.nan
nr_no_train_de (int, optional) – this number indicates the number of discrete emissions whose Matrix Emission Probabilities are fixed and are not trained; it is important to to order the observed variables such that the ones whose emissions aren’t trained are the last ones, defaults to 0
state_no_train_de (int, optional) – a state index for nr_no_train_de which shouldn’t be updated; defaults to None, which means that the entire emission probability matrix for that discrete emission will be kept unchanged during training, otherwise the last state_no_train_de states won’t be updated, defaults to None
learning_rate (float, optional) – a value from [0,1), controlling how much the past values of the model parameters count when computing the new model parameters during training; defaults to 0.
verbose (bool, optional) – flag to be set to True if per-iteration convergence reports should be printed, defaults to True

decode(obs_sequences, algorithm='viterbi')¶

Find the best state sequence (path), given the model and an observation.: i.e: max(P(Q|O,model)).

Parameters

obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
algorithm (string, optional) – name of the decoder algorithm to use; must be one of ‘viterbi’ or ‘map’. Defaults to ‘viterbi’.

Returns

log-probability of the produced state sequence

Return type

float

Returns

list of arrays of shape (n_samples, n_states) containing labels for each observation from obs_sequences obtained via the given decoder algorithm

Return type

list

forward(obs_seq, B_map=None)¶

Forward-Backward procedure is used to efficiently calculate the probability of the observations, given the model - P(O|model).

Parameters

obs_seq (array_like) – an observation sequence
B_map (array_like, optional) – mapping of the observations’ mass/density Bj(Ot) to Bj(t)

Returns

the log of the probability, i.e. the log likehood model, give the observation - logL(model|O).

Return type

float

get_n_fit_scalars_per_param()¶: Return a mapping of trainable model parameters names (as in self.tr_params) to the number of corresponding scalar parameters that will actually be fitted.

get_stationary_distribution()¶

Compute the stationary distribution of states. The stationary distribution is proportional to the left-eigenvector associated with the largest eigenvalue (i.e., 1) of the transition matrix.

Returns: the stationary distribution of states
Return type: array_like

property missing¶: Getter for the missing value character in the data.

predict(X, algorithm='viterbi')¶

Find the most probable state sequence corresponding to X.

Parameters

X (array-like) – feature matrix of individual samples, shape (n_samples, n_features)
algorithm (string, optional) – name of the decoder algorithm to use; must be one of ‘viterbi’ or ‘map’. Defaults to ‘viterbi’.

Returns

labels for each sample from X

Return type

array-like

predict_proba(obs_sequences)¶

Compute the posterior probability for each state in the model.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: list of arrays of shape (n_samples, n_states) containing the state-membership probabilities for each sample in the observation sequences
Return type: list

sample(n_sequences=1, n_samples=1, return_states=False)¶

Generate random samples from the model.

Parameters

n_sequences (int, optional) – number of sequences to generate, defeaults to 1.
n_samples (int, optional) – number of samples to generate per sequence; defeaults to 1. If multiple sequences have to be generated, it is a list of the individual sequence lengths
return_states (bool, optional) – if True, the method returns the state sequence from which the samples were generated, defeaults to False.

Returns

a list containing one or n_sequences sample sequences

Return type

list

Returns

a list containing the state sequences that generated each sample sequence

Return type

list

score(obs_sequences)¶

Compute the per-sample average log-likelihood of the given data.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: the average of log-likelihoods over all the observation sequences
Return type: float

score_samples(obs_sequences)¶

Compute the log-likelihood of each sample.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: list of log-likelihoods over all the observation sequences
Return type: list

train(obs_sequences, n_init=1, n_iter=100, conv_thresh=0.1, conv_iter=5, ignore_conv_crit=False, plot_log_likelihood=False, no_init=False, n_processes=None, print_every=1)¶

Updates the HMMs parameters given a new set of observed sequences. The observations can either be a single (1D) array of observed symbols, or a 2D array (matrix), where each row denotes a multivariate time sample (multiple features). The model parameters are reinitialised ‘n_init’ times. For each initialisation the updated model parameters and the log-likelihood is stored and the best model is selected at the end.

Parameters

obs_sequences (list) – a list of arrays containing the observation sequences of different lengths
n_init (int, optional) – number of initialisations to perform; defaults to 1
n_iter (int, optional) – max number of iterations to run for each initialisation; defaults to 100
conv_thresh (float, optional) – the threshold for the likelihood increase (convergence); defaults to 0.1
conv_iter (int, optional) – number of iterations for which the convergence criteria has to hold before early-stopping; defaults to 5
ignore_conv_crit (bool, optional) – flag to indicate whether to iterate until n_iter is reached or perform early-stopping; defaults to False
plot_log_likelihood (bool, optional) – parameter to activate plotting the evolution of the log-likelihood after each initialisation; defaults to False
no_init (bool, optional) – flag to indicate wheather to initialise the Parameters before training (it can only be True if the parameters are manually set before or they were already trained); defaults to False
n_processes (int, optional) – number of processes to use if the training should be performed using parallelisation; defaults to None
print_every (int, optional) – if verbose is True, print progress info every ‘print_every’ iterations; defaults to 1

Returns

the updated model

Return type

object

Returns

the log_likelihood of the best model

Return type

float

HeterogeneousHMM¶

class pyhhmm.heterogeneous.HeterogeneousHMM(n_states, n_g_emissions, n_d_emissions, n_d_features, tr_params='stmce', init_params='stmce', nr_no_train_de=0, state_no_train_de=None, covariance_type='diagonal', pi_prior=1.0, A_prior=1.0, means_prior=0, means_weight=0, covars_prior=0.01, covars_weight=1, min_covar=0.001, learning_rate=0, verbose=False)¶

Bases: pyhhmm.base.BaseHMM

Implementation of HMM with labels. It can manage Gaussian and categorical features.

Parameters

n_states (int) – number of hidden states in the model
n_g_emissions (int) – number of Gaussian features
n_d_emissions (int) – number of categorical features
n_d_features (list) – number of distinct observation symbols per state
tr_params (str, optional) – controls which parameters are updated in thetraining process; can contain any combination of ‘s’ for startingprobabilities (pi), ‘t’ for transition matrix, and other charactersfor subclass-specific emission parameters, defaults to ‘stmce’
init_params (str, optional) – controls which parameters are initialised prior to training. Can contain any combination of ‘s’ for starting probabilities (pi), ‘t’ for transition matrix, and other characters for subclass-specific emission parameters, defaults to ‘stmce’
nr_no_train_de (int, optional) – this number indicates the number of discrete emissions whose Matrix Emission Probabilities are fixed and are not trained; it is important to to order the observed variables such that the ones whose emissions aren’t trained are the last ones, defaults to 0
state_no_train_de (int, optional) – a state index for nr_no_train_de which shouldn’t be updated; defaults to None, which means that the entire emission probability matrix for that discrete emission will be kept unchanged during training, otherwise the last state_no_train_de states won’t be updated, defaults to None
covariance_type (str, optional) – string describing the type of covariance parameters to use. Defaults to ‘full’.
pi_prior (array_like, optional) – array of shape (n_states, ) setting the parameters of the Dirichlet prior distribution for the starting probabilities. Defaults to 1.
pi (array_like) – array of shape (n_states, ) giving the initial state occupation distribution ‘pi’
A_prior (array_like, optional) – array of shape (n_states, ), giving the parameters of the Dirichlet prior distribution for each row of the transition probabilities ‘A’. Defaults to 1.
A (array_like) – array of shape (n_states, n_states) giving the matrix of transition probabilities between states
B (list) – the probabilities of emitting a given discrete symbol when in each state
means_prior (array_like, optional) – array of shape (n_states, 1), the mean of the Normal prior distribution for the means. Defaults to 0.
means_weight (array_like, optional) – array of shape (n_states, 1), the precision of the Normal prior distribution for the means. Defaults to 0.
means (array_like) – array of shape (n_states, n_emissions) containing the mean parameters for each state
covars_prior (array_like, optional) – array of shape (n_states, 1), the mean of the Normal prior distribution for the covariance matrix. Defaults to 0.
covars_weight (array_like, optional) – array of shape (n_states, 1), the precision of the Normal prior distribution for the covariance. Defaults to 0.
min_covar (float, optional) – floor on the diagonal of the covariance matrix to prevent overfitting. Defaults to 1e-3.
covars (array_like) – covariance parameters for each state arranged in an array of shape depends covariance_type.
learning_rate (float, optional) – a value from [0,1), controlling how much the past values of the model parameters count when computing the new model parameters during training; defaults to 0.
verbose (bool, optional) – flag to be set to True if per-iteration convergence reports should be printed, defaults to True

decode(obs_sequences, algorithm='viterbi')¶

Find the best state sequence (path), given the model and an observation.: i.e: max(P(Q|O,model)).

Parameters

obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
algorithm (string, optional) – name of the decoder algorithm to use; must be one of ‘viterbi’ or ‘map’. Defaults to ‘viterbi’.

Returns

log-probability of the produced state sequence

Return type

float

Returns

list of arrays of shape (n_samples, n_states) containing labels for each observation from obs_sequences obtained via the given decoder algorithm

Return type

list

forward(obs_seq, B_map=None)¶

Forward-Backward procedure is used to efficiently calculate the probability of the observations, given the model - P(O|model).

Parameters

obs_seq (array_like) – an observation sequence
B_map (array_like, optional) – mapping of the observations’ mass/density Bj(Ot) to Bj(t)

Returns

the log of the probability, i.e. the log likehood model, give the observation - logL(model|O).

Return type

float

get_n_fit_scalars_per_param()¶: Return a dictionary containing the number of trainable variables for each model parameter.

get_stationary_distribution()¶

Compute the stationary distribution of states. The stationary distribution is proportional to the left-eigenvector associated with the largest eigenvalue (i.e., 1) of the transition matrix.

Returns: the stationary distribution of states
Return type: array_like

predict(X, algorithm='viterbi')¶

Find the most probable state sequence corresponding to X.

Parameters

X (array-like) – feature matrix of individual samples, shape (n_samples, n_features)
algorithm (string, optional) – name of the decoder algorithm to use; must be one of ‘viterbi’ or ‘map’. Defaults to ‘viterbi’.

Returns

labels for each sample from X

Return type

array-like

predict_proba(obs_sequences)¶

Compute the posterior probability for each state in the model.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: list of arrays of shape (n_samples, n_states) containing the state-membership probabilities for each sample in the observation sequences
Return type: list

sample(n_sequences=1, n_samples=1, return_states=False)¶

Generate random samples from the model.

Parameters

n_sequences (int, optional) – number of sequences to generate, defeaults to 1.
n_samples (int, optional) – number of samples to generate per sequence; defeaults to 1. If multiple sequences have to be generated, it is a list of the individual sequence lengths
return_states (bool, optional) – if True, the method returns the state sequence from which the samples were generated, defeaults to False.

Returns

a list containing one or n_sequences sample sequences

Return type

list

Returns

a list containing the state sequences that generated each sample sequence

Return type

list

score(obs_sequences)¶

Compute the per-sample average log-likelihood of the given data.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: the average of log-likelihoods over all the observation sequences
Return type: float

score_samples(obs_sequences)¶

Compute the log-likelihood of each sample.

Parameters: obs_sequences (list) – a list of ndarrays containing the observation sequences of different lengths
Returns: list of log-likelihoods over all the observation sequences
Return type: list

train(obs_sequences, n_init=1, n_iter=100, conv_thresh=0.1, conv_iter=5, ignore_conv_crit=False, plot_log_likelihood=False, no_init=False, n_processes=None, print_every=1)¶

Updates the HMMs parameters given a new set of observed sequences. The observations can either be a single (1D) array of observed symbols, or a 2D array (matrix), where each row denotes a multivariate time sample (multiple features). The model parameters are reinitialised ‘n_init’ times. For each initialisation the updated model parameters and the log-likelihood is stored and the best model is selected at the end.

Parameters

obs_sequences (list) – a list of arrays containing the observation sequences of different lengths
n_init (int, optional) – number of initialisations to perform; defaults to 1
n_iter (int, optional) – max number of iterations to run for each initialisation; defaults to 100
conv_thresh (float, optional) – the threshold for the likelihood increase (convergence); defaults to 0.1
conv_iter (int, optional) – number of iterations for which the convergence criteria has to hold before early-stopping; defaults to 5
ignore_conv_crit (bool, optional) – flag to indicate whether to iterate until n_iter is reached or perform early-stopping; defaults to False
plot_log_likelihood (bool, optional) – parameter to activate plotting the evolution of the log-likelihood after each initialisation; defaults to False
no_init (bool, optional) – flag to indicate wheather to initialise the Parameters before training (it can only be True if the parameters are manually set before or they were already trained); defaults to False
n_processes (int, optional) – number of processes to use if the training should be performed using parallelisation; defaults to None
print_every (int, optional) – if verbose is True, print progress info every ‘print_every’ iterations; defaults to 1

Returns

the updated model

Return type

object

Returns

the log_likelihood of the best model

Return type

float

Utils¶

pyhhmm.utils.aic_hmm(log_likelihood, dof)¶

Function to compute the Aikaike’s information criterion for an HMM given the log-likelihood of observations.

Parameters

log_likelihood (float) – logarithmised likelihood of the model dof (int) - single numeric value representing the number of trainable parameters of the model
dof (int) – single numeric value representing the number of trainable parameters of the model

Returns

the Aikaike’s information criterion

Return type

float

pyhhmm.utils.bic_hmm(log_likelihood, dof, n_samples)¶

Function to compute Bayesian information criterion for an HMM given a the log-likelihood of observations.

Parameters

log_likelihood (float) – logarithmised likelihood of the model dof (int) - single numeric value representing the number of trainable parameters of the model
dof (int) – single numeric value representing the number of trainable parameters of the model
n_samples (int) – length of the time-series of observations

Returns

the Bayesian information criterion

Return type

float

pyhhmm.utils.get_n_fit_scalars(hmm)¶

Function to compute the degrees of freedom of a HMM based on the parameters that are trained in it.

Parameters: hmm (object) – a hidden Markov model (GaussianHMM, MultinomialHMM, etc)
Returns: single numeric value representing the number of trainable parameters of the model
Return type: int

pyhhmm.utils.load_model(filename)¶

Function to load an HMM model from a pickle file.

Parameters: filename (str) – full path or just file name where to save the variable
Returns: the trained HMM that was in the file
Return type: object

pyhhmm.utils.plot_decode(obs_seq, data_cols, state_seq, discrete_columns=None, state_names=None, time_stamps=None, figsize=10, 20, filename=None)¶

Function for plotting the decoded sequence with the corresponding states.

Parameters

obs_seq (array_like) – an observation sequence
data_cols (list) – name of (Gaussian) data columns (name of each column)
state_seq (list) – the decoded state sequence
discrete_columns (list, optional) – only in case of HMM with labels, the list of label names, defaults to None
state_names (list, optional) – list of state names, only if applicable, defaults to None
time_stamps ([list, optional) – list of time_stamps when the observations where recorded (if applicable, otherwise discrete values are applied, starting of 0 to len(state_seq)), defaults to None
figsize (tuple, optional) – size of the plot, defaults to (10, 20)
filename (str, optional) – full path with figure name if it should be saved, defaults to None

pyhhmm.utils.plot_model_selection(n_states, criteria, filename=None)¶

Function to plot the different model order selection criteria vs the number of states of a HMM.

Parameters

n_states (list) – list of number of states that were used to compute the criteria
criteria (dict) – the keys correspond to the different criteria that were computed (AIC, BIC, etc) and the values are a list of length len(n_states) containing the criteria values for the different number of states
filename (string, optional) – full path to where to save the figure, defaults to None

pyhhmm.utils.pretty_print_hmm(model, hmm_type='Multinomial', states=None, emissions=None)¶

Function to pretty print the parameters of an hmm model.

Parameters

model (object) – and HMM object
hmm_type (str, optional) – the type of the HMM model; can be ‘Multinomial’, ‘Gaussian’ or ‘Heterogeneous’, defaults to ‘Multinomial’
states (list, optional) – list with the name of states, if any, defaults to None
emissions (list, optional) – list of the names of the emissions, if any, defaults to None

pyhhmm.utils.save_model(model, filename)¶

Function to save an hmm model (or any variable) to a pickle file.

Parameters

model (object) – the trained HMM to be saved
filename (str) – full path or just file name where to save the variable