Factorial Hidden Markov Model (F-HMM)

Contents

Factorial Hidden Markov Model (F-HMM)
- Factorial HMM Models
- Factorial HMM Components

Factorial HMM Models 

class ssm.factorial_hmm.base.FactorialHMM(num_states, initial_condition, transitions, emissions)

Factorial HMM base class.

The model consists of $G$ discrete latent states $z_t = (z_{t1}, \ldots, z_{tG})$ . The $g$ -th state takes values $(0, ..., K_g-1)$ .

Parameters

num_states (tuple or list) – number of discrete latent states per group
initial_condition (FactorialInitialCondition) – factorial initial state object
transitions (FactorialTransitions) – factorial transitions object
emissions (FactorialEmissions) – factorial emissions object

initialize(data, covariates=None, metadata=None, key=None, method='kmeans')

Initialize the model parameters by performing an M-step with state assignments determined by the specified method (random or kmeans).

Parameters

key (jr.PRNGKey) – random seed
data (np.ndarray) – array of observed data of shape $(\text{batch} , \text{num\_timesteps} , \text{emissions\_dim})$
covariates (PyTree, optional) – optional covariates with leaf shape (B, T, …). Defaults to None.
metadata (PyTree, optional) – optional metadata with leaf shape (B, …). Defaults to None.
method (str, optional) – state assignment method. One of “random” or “kmeans”. Defaults to “kmeans”.

Raises

ValueError – when initialize method is not recognized

Return type

None

class ssm.factorial_hmm.models.NormalFactorialHMM(num_states, initial_probs=None, transition_matrices=None, emission_means=None, emission_variance=0.0001, seed=None)

Factorial HMM with scalar Gaussian emissions.

The model consists of $G$ discrete latent states $z_t = (z_{t1}, \ldots, z_{tG})$ . The $g$ -th state takes values $(0, ..., K_g-1)$ .

The emission mean is a sum of means associated with each group,

$\mathbb{E} \left[x_t \mid z_t \right] = \sum_g \mu_{g,z_{tg}}$

For example, the emissions may be measurements from a home’s power meter and the groups may correspond to appliances, which may be either on or off ( $z_{tg} \in \{0,1\}$ ). If off, the appliance contributes nothing to the measurement ( $\mu_{g,0}=0$ ), but if on, the appliance contributes $\mu_{g,1}$ .

Parameters

num_states (tuple or list) – number of discrete latent states per group
initial_state_probs (np.ndarray, optional) – initial state probabilities with shape $(\text{num\_states},)$ . Defaults to None.
transitions (Transitions, optional) – object specifying transitions Defaults to None. If specified, then transition_matrix is ignored.
transition_matrix (np.ndarray, optional) – transition matrix with shape $(\text{num\_states}, \text{num\_states})$ . Defaults to None. Only used if transitions is None.
emission_means (np.ndarray, optional) – specifies emission means with shape $(\text{num\_states}, \text{emission\_dims})$ . Defaults to None.
emission_covariances (np.ndarray, optional) – specifies emissions covariances with shape $(\text{num\_states}, \text{emission\_dims}, \text{emission\_dims})$ . Defaults to None.
seed (jr.PRNGKey, optional) – random seed. Defaults to None.
initial_probs (tuple) –
transition_matrices (tuple) –
emission_variance (float) –

Factorial HMM Components 

Factorial HMM Initials 

class ssm.factorial_hmm.initial.FactorialInitialCondition(initial_probs=None, initial_condition_objects=None)

Initial distribution for several indpendent discrete states.

Parameters

initial_probs (tuple or list) –
initial_condition_objects (tuple or list) –

log_initial_probs(data, covariates=None, metadata=None): Return [log Pr(z_1 = k) for k in range(num_states)]

distribution(covariates=None, metadata=None)

Return the distribution of z_1.

Parameters

covariates (PyTree, optional) – optional covariates with leaf shape (B, T, …). Defaults to None.
metadata (PyTree, optional) – optional metadata with leaf shape (B, …). Defaults to None.

Returns

distribution (tfd.Distribution) – distribution of z_1

m_step(data, posterior, covariates=None, metadata=None)

Update the initial distribution in an M step given posteriors over the latent states.

Parameters

dataset (np.ndarray) – the observed dataset with shape (B, T, D)
posteriors (HMMPosterior) – posteriors over the latent states with leaf shape (B, …)
covariates (PyTree, optional) – optional covariates with leaf shape (B, T, …). Defaults to None.
metadata (PyTree, optional) – optional metadata with leaf shape (B, …). Defaults to None.

Returns

initial_condition (InitialCondition) – updated initial condition object

Return type

FactorialInitialCondition

Factorial HMM Transitions 

class ssm.factorial_hmm.transitions.FactorialTransitions(transitions)

Transitions over several hidden states evolving in parallel.

distribution(state, covariates=None, metadata=None)

Return the conditional distribution of z_t given state z_{t-1}

Parameters

state (int) – state z_{t-1}
covariates (PyTree, optional) – optional covariates with leaf shape (B, T, …). Defaults to None.
metadata (PyTree, optional) – optional metadata with leaf shape (B, …). Defaults to None.

Returns

distribution (tfd.Distribution) – conditional distribution of z_t given state z_{t-1}.

log_transition_matrices(data, covariates=None, metadata=None)

Returns the log probability of data where

$\texttt{log\_P}[i, j] = \log \Pr(z_{t+1} = j | z_t = i)$

if the transition probabilities are stationary or

$\texttt{log\_P}[t, i, j] = \log \Pr(z_{t+1} = j | z_t = i)$

if they are nonstationary.

Parameters: data (np.ndarray) – observed data
Returns: log probs (np.ndarray) – log probability as defined above

m_step(data, posterior, covariates=None, metadata=None)

Update the transition parameters in an M step given posteriors over the latent states.

Parameters

dataset (np.ndarray) – the observed dataset with shape (B, T, D)
posteriors (HMMPosterior) – posteriors over the latent states with leaf shape (B, …)
covariates (PyTree, optional) – optional covariates with leaf shape (B, T, …). Defaults to None.
metadata (PyTree, optional) – optional metadata with leaf shape (B, …). Defaults to None.

Returns

transitions (Transitions) – updated transitions object

Return type

FactorialTransitions

Factorial HMM Emissions 

class ssm.factorial_hmm.emissions.FactorialEmissions(num_states)

Parameters: num_states (tuple) –

class ssm.factorial_hmm.emissions.NormalFactorialEmissions(num_states, means=None, log_scale=0.0, emissions_distribution=None, emissions_distribution_prior=None)

Normal Emissions for a Factorial HMM.

The emission mean is a sum of means associated with each group.

$x_t | \{z_{tj} \}_{j=1}^J ~ N(\sum_j m_{z_{tj}}, \sigma^2)$

Can be initialized by specifying parameters or by passing in a pre-initialized emissions_distribution object.

Parameters

num_states (tuple) – number of discrete latent states per group
means (tuple or list, optional) – state-dependent and group-dependent emission means. Defaults to None.
variance (np.ndarray, optional) – emission variance shared by all states
emissions_distribution (ssmd.MultivariateNormalTriL, optional) – initialized emissions distribution. Defaults to None.
emissions_distribution_prior (ssmd.NormalInverseWishart, optional) – initialized emissions distribution prior. Defaults to None.
log_scale (float) –

distribution(state, covariates=None, metadata=None): Return the conditional distribution of emission x_t given state z_t and (optionally) covariates u_t.

log_likelihoods(data, covariates=None, metadata=None): Compute log p(x_t | z_t=(k_1, …, k_J)) for all t and (k_1,…,k_J).

Factorial Hidden Markov Model (F-HMM)

Factorial HMM Models

Factorial HMM Components

Factorial HMM Initials

Factorial HMM Transitions

Factorial HMM Emissions

Factorial HMM Models 

Factorial HMM Components 

Factorial HMM Initials 

Factorial HMM Transitions 

Factorial HMM Emissions 