canari.data_struct

This module manages historical values for LSTM’ output, cell and hidden states.

It provides two data classes:

• LstmOutputHistory: Maintain a rolling history of the LSTM mean and variance outputs.

• StatesHistory: Save prior, posterior, and smoothed estimates of hidden states over time.

class canari.data_struct.LstmOutputHistory

Container for saving a rolling history of LSTM output means and variances over a fixed lookback window.

Examples

>>> lstm_history = LstmOutputHistory()
>>> lstm_history.initialize(look_back_len=10)
>>> lstm_history.update(mu_lstm=np.array([0.5]), var_lstm=np.array([0.2]))
>>> lstm_history.set(mu=np.array([0.1, 0.2, 0.3]), var=np.array([0.01, 0.02, 0.03]))

mu

Rolling array storing the LSTM mean outputs.

Type:

np.ndarray

var

Rolling array storing the LSTM variance outputs.

Type:

np.ndarray

initialize(look_back_len: int)

Initialize mu and var with a specified lookback length.

Parameters:

look_back_len (int) – Number of time steps to keep in history.

set(mu: ndarray, var: ndarray)

Set the entire rolling window directly with new values for mu and var.

Parameters:

• mu (np.ndarray) – Array of mean values to set.

• var (np.ndarray) – Array of variance values to set.

Raises:

ValueError – If the shapes of mu and var do not match the initialized window size.

update(mu_lstm, var_lstm)

Update the rolling window with new LSTM outputs.

Removes the oldest values and inserts the newest ones at the end of the arrays.

Parameters:

• mu_lstm (np.ndarray or float) – Latest LSTM mean output.

• var_lstm (np.ndarray or float) – Latest LSTM variance output.

class canari.data_struct.StatesHistory

Save estimates of hidden states over time.

Stores the evolution of prior, posterior, and smoothed values for hidden states over time, along with cross-covariances between hidden states at two consecutive timesteps t and t+1.

mu_prior

Mean of the prior hidden states.

Type:

List[np.ndarray]

var_prior

Covariance matrix for the prior hiddens states.

Type:

List[np.ndarray]

mu_posterior

Mean of the posterior hidden states.

Type:

List[np.ndarray]

var_posterior

Covariance matrix for the posterior hidden states.

Type:

List[np.ndarray]

mu_smooth

Mean of the smoothed estimates for hidden states.

Type:

List[np.ndarray]

var_smooth

Covariance matrix for the smoothed estimates for hidden states.

Type:

List[np.ndarray]

cov_states

Cross-covariance matrix for the hidden states at two consecutive timesteps t and t+1.

Type:

List[np.ndarray]

states_name

Names of the tracked hidden states.

Type:

List[str]

get_mean(states_name: str, states_type: str | None = 'posterior', standardization: bool | None = True, scale_const_mean: float | None = 0, scale_const_std: float | None = 1) → ndarray

Retrieve the mean values over time for a specified hidden states and for either a) the prior predicted value, b) the posterior updated values after the filter step, or c) the posterior updated values after the smoother step (smoothed estimates).

Parameters:

• states_name (str) – Name of hidden state to extract.

• states_type (str, optional) – Type of states to return (‘prior’, ‘posterior’, ‘smooth’). Defaults to “posterior”.

• standardization (bool, optional) – Get the standardized values for hidden states. Defaults to True.

• scale_const_mean (float, optional) – Mean used for unstandardization.

• scale_const_std (float, optional) – Standard deviation used for unstandardization.

Returns:

1D arrays of means over time.

Return type:

np.ndarray

get_std(states_name: str, states_type: str | None = 'posterior', standardization: bool | None = True, scale_const_std: float | None = 1) → ndarray

Retrieve the standard deviation values over time for a specified hidden states and for either a) the prior predicted value, b) the posterior updated values after the filter step, or c) the posterior updated values after the smoother step (smoothed estimates).

Parameters:

• states_name (str) – Name of hidden state to extract.

• states_type (str, optional) – Type of states to return (‘prior’, ‘posterior’, ‘smooth’). Defaults to “posterior”.

• standardization (bool, optional) – Get the standardized values for hidden states. Defaults to True.

• scale_const_std (float, optional) – Standard deviation used for unstandardization.

Returns:

1D arrays of standard deviations over time.

Return type:

np.ndarray

initialize(states_name: List[str])

Initialize mu_prior, var_prior, mu_posterior, var_posterior, mu_smooth, var_smooth, and cov_states as empty lists.

Parameters:

states_name (List[str]) – List of hidden state names.

class canari.data_struct.OutputHistory

Save output history mean and variance

initialize()

Initialize mu and var as empty lists.

save_output_history(mu: float, var: float)

Add mu and var to the saved history