canari.common

Utility functions that are used in mulitple classes.

class canari.common.GMA(mu: ndarray, var: ndarray, index1: int | None = None, index2: int | None = None, replace_index: int | None = None)

Bases: object

Gaussian Multiplicative Approximation (GMA).

Approximate the product of two Gaussian variables by a Gausian distribution with exact moments calculation. The class allows augmenting the size of the state vector in order to include the product term.

mu

Mean vector.

Type:

np.ndarray

var

Covariance matrix.

Type:

np.ndarray

delete(index: int)

Remove a variable from the mean and covariance structures.

Parameters:

index (int) – Index of the variable to delete.

get_results() → Tuple[ndarray, ndarray]

Get the current mean and covariance.

Returns:

Mean vector and covariance matrix.

Return type:

Tuple[np.ndarray, np.ndarray]

multiply_and_augment(index1: int, index2: int)

Augment the state vector with mean and covariance from the product of the two variables referred by the two input indices.

Parameters:

• index1 (int) – Index of the first variable.

• index2 (int) – Index of the second variable.

swap(index1: int, index2: int)

Swap two variables in the mean and covariance structures.

Parameters:

• index1 (int) – Index of the first variable.

• index2 (int) – Index of the second variable.

canari.common.backward(obs: float, mu_obs_predict: ndarray, var_obs_predict: ndarray, var_states_prior: ndarray, observation_matrix: ndarray) → Tuple[ndarray, ndarray]

Perform the backward step in Kalman filter.

Parameters:

• obs (float) – Observation.

• mu_obs_predict (np.ndarray) – Predicted mean.

• var_obs_predict (np.ndarray) – Predicted variance.

• var_states_prior (np.ndarray) – Prior covariance matrix for hidden states.

• observation_matrix (np.ndarray) – Observation matrix.

Returns:

A tuple containing:

• delta_mu_states (np.ndarray):

  The delta or corrections for the hidden states means.

• delta_var_states (np.ndarray):

  The delta or corrections for the hidden states covariance matrix.

Return type:

Tuple[np.ndarray, np.ndarray]

canari.common.calc_observation(mu_states: ndarray, var_states: ndarray, observation_matrix: ndarray) → Tuple[ndarray, ndarray]

Estimate observation mean and variance from hidden states and the observation_matrix.

Parameters:

• mu_states (np.ndarray) – Mean of the state variables.

• var_states (np.ndarray) – Covariance matrix of the state variables.

• observation_matrix (np.ndarray) – Observation model matrix.

Returns:

Predicted mean and variance of observations.

Return type:

Tuple[np.ndarray, np.ndarray]

canari.common.create_block_diag(*arrays: ndarray) → ndarray

Create a block diagonal matrix from the provided arrays.

Parameters:

*arrays (np.ndarray) – Variable number of 2D arrays.

Returns:

Block diagonal matrix with input arrays along the diagonal.

Return type:

np.ndarray

canari.common.forward(mu_states_posterior: ndarray, var_states_posterior: ndarray, transition_matrix: ndarray, process_noise_matrix: ndarray, observation_matrix: ndarray, mu_lstm_pred: ndarray | None = None, var_lstm_pred: ndarray | None = None, lstm_indice: int | None = None) → Tuple[ndarray, ndarray, ndarray, ndarray]

Perform the prediction step in Kalman filter.

Parameters:

• mu_states_posterior (np.ndarray) – Posterior hidden states mean vector.

• var_states_posterior (np.ndarray) – Posterior hidden state covariance matrix.

• transition_matrix (np.ndarray) – Transition matrix.

• process_noise_matrix (np.ndarray) – Process noise matrix.

• observation_matrix (np.ndarray) – Observation matrix.

• mu_lstm_pred (Optional[np.ndarray]) – LSTM predicted mean.

• var_lstm_pred (Optional[np.ndarray]) – LSTM predicted variance.

• lstm_indice (Optional[int]) – Index to insert LSTM predictions.

Returns:

A tuple containing:

• mu_obs_predict (np.ndarray):

  The mean for the forecast.

• std_obs_preds (np.ndarray):

  The standard deviation for the forecast.

• mu_states_prior (np.ndarray):

  The prior means for states.

• var_states_prior (np.ndarray):

  The prior covariance matrix for states.

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

canari.common.gaussian_mixture(mu1: ndarray, var1: ndarray, coef1: float, mu2: ndarray, var2: ndarray, coef2: float) → Tuple[ndarray, ndarray]

Perform a reduction of two Gaussian distributions into a single mixture distribution.

Parameters:

• mu1 (np.ndarray) – Mean vector of the first Gaussian.

• var1 (np.ndarray) – Covariance matrix of the first Gaussian.

• coef1 (float) – Mixture weight for the first Gaussian.

• mu2 (np.ndarray) – Mean vector of the second Gaussian.

• var2 (np.ndarray) – Covariance matrix of the second Gaussian.

• coef2 (float) – Mixture weight for the second Gaussian.

Returns:

Mixture mean vector and covariance matrix.

Return type:

Tuple[np.ndarray, np.ndarray]

canari.common.norm_cdf(x) → ndarray

Cumulative distribution function (CDF) of the standard normal distribution. :param x: Value(s) for which to compute the CDF. :type x: float or np.ndarray

Returns:

CDF value(s) for the input.

Return type:

float or np.ndarray

canari.common.norm_pdf(x) → ndarray

Probability density function (PDF) of the standard normal distribution. :param x: Value(s) for which to compute the PDF. :type x: float or np.ndarray

Returns:

PDF value(s) for the input.

Return type:

float or np.ndarray

canari.common.pad_matrix(matrix: ndarray, pad_index: int, pad_row: ndarray | None = None, pad_col: ndarray | None = None) → ndarray

Add a row and/or column padding to the matrix.

Parameters:

• matrix (np.ndarray) – Matrix to pad.

• pad_index (int) – Index to insert the padding.

• pad_row (Optional[np.ndarray]) – Row vector to insert.

• pad_col (Optional[np.ndarray]) – Column vector to insert.

Returns:

Padded matrix.

Return type:

np.ndarray

canari.common.prepare_lstm_input(lstm_output_history: LstmOutputHistory, input_covariates: ndarray) → Tuple[ndarray, ndarray]

Prepare LSTM input by concatenating past LSTM outputs with current input covariates.

Parameters:

• lstm_output_history (LstmOutputHistory) – Historical LSTM mean/variance.

• input_covariates (np.ndarray) – Input covariates.

Returns:

LSTM input mean and variance vectors.

Return type:

Tuple[np.ndarray, np.ndarray]

canari.common.rts_smoother(mu_states_prior: ndarray, var_states_prior: ndarray, mu_states_smooth: ndarray, var_states_smooth: ndarray, mu_states_posterior: ndarray, var_states_posterior: ndarray, cross_cov_states: ndarray, matrix_inversion_tol: float | None = 1e-12, tol_type: str | None = 'relative') → Tuple[ndarray, ndarray]

Rauch-Tung-Striebel (RTS) smoother.

Parameters:

• mu_states_prior (np.ndarray) – Prior mean vector.

• var_states_prior (np.ndarray) – Prior covariance metrix.

• mu_states_smooth (np.ndarray) – Smoothed mean vector.

• var_states_smooth (np.ndarray) – Smoothed covariance matrix.

• mu_states_posterior (np.ndarray) – Posterior mean vector.

• var_states_posterior (np.ndarray) – Posterior covariance matrix.

• cross_cov_states (np.ndarray) – Cross-covariance matrix between hidden states at two consecutive time steps.

• matrix_inversion_tol (Optional[float]) – Regularization tolerance.

Returns:

Updated smoothed mean and covariance.

A tuple containing:

• mu_states_smooth (np.ndarray):

  Updated smoothed means.

• var_states_smooth (np.ndarray):

  Updated smoothed covariance matrix.

Return type:

Tuple[np.ndarray, np.ndarray]