canari.data_struct

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[source]#

Bases: object

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]))
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)[source]#

Initialize mu and var with a specified lookback length.

Parameters:

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

mu: ndarray#
update(mu_lstm, var_lstm)[source]#

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.

var: ndarray#
class canari.data_struct.StatesHistory[source]#

Bases: object

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]

cov_states: List[ndarray]#
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[source]#

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[source]#

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])[source]#

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.

mu_posterior: List[ndarray]#
mu_prior: List[ndarray]#
mu_smooth: List[ndarray]#
states_name: List[str]#
var_posterior: List[ndarray]#
var_prior: List[ndarray]#
var_smooth: List[ndarray]#
Contents