canari.model_assemble

Assemble of multiple :class:~canari.model.Model instances. This class is used when the target model depends on a covariate that is itself modeled by another Model.

class canari.model_assemble.ModelAssemble(target_model: Model, covariate_model: Model | List[Model])

Bases: object

Assemble of Model instances.

Parameters:

• target_model (Model) – the target (dependent) model.

• covariate_model (List[Model]) – the independent model used as input for the target one.

backward(obs: float) → Tuple[ndarray, ndarray, ndarray, ndarray]

Update step in the Kalman filter for one time step.

filter(data: Dict[str, ndarray]) → Tuple[ndarray, ndarray]

Run the Kalman filter over an entire dataset, i.e., repeatly apply the Kalman prediction and update steps over multiple time steps.

Parameters:

data (Dict[str, np.ndarray]) – Includes ‘x’ and ‘y’.

Returns:

A tuple containing:

• mu_obs_preds (np.ndarray):

  The means for forecasts.

• std_obs_preds (np.ndarray):

  The standard deviations for forecasts.

Return type:

Tuple[np.ndarray, np.ndarray]

forecast(data: Dict[str, ndarray], posterior_covariate: bool | None = False, update_param_covar_model: bool | None = False) → Tuple[ndarray, ndarray]

Perform multi-step-ahead forecast over an entire dataset by recursively making one-step-ahead predictions, i.e., reapeatly apply the Kalman prediction step over multiple time steps.

Parameters:

• data (Dict[str, np.ndarray]) – A dictionary containing key ‘x’ as input covariates, if exists ‘y’ (real observations) will not be used.

• posterior_covariate (Optional[bool]) – Estimate the posterior for covariate model or not. If True, the posteriors for covariates are used as input for the target model. Otherwise, priors are used. Defaults to False.

• update_param_covar_model (Optional[bool]) – Update the network parameters for the covariate models or not. Defaults to False.

Returns:

A tuple containing:

• mu_obs_preds (np.ndarray):

  The means for forecasts.

• std_obs_preds (np.ndarray):

  The standard deviations for forecasts.

Return type:

Tuple[np.ndarray, np.ndarray]

forward(input_covariates: ndarray | None = None, posterior_covariate: bool | None = True, update_param_covar_model: bool | None = True) → Tuple[ndarray, ndarray]

Make a one-step-ahead prediction using the prediction step of the Kalman filter. If no input_covariates for LSTM, use an empty np.ndarray. Recall forward() for each model.

This function is used at the one-time-step level.

Parameters:

• input_covariates (Optional[np.ndarray]) – Input covariates for LSTM at time t.

• posterior_covariate (Optional[bool]) – Estimate the posterior for covariate model or not. If True, the posteriors for covariates are used as input for the target model. Otherwise, priors are used. Defaults to True.

• update_param_covar_model (Optional[bool]) – Update the network parameters for the covariate models or not. Defaults to True.

Returns:

A tuple containing:

• mu_pred (np.ndarray):

  The predictive mean of the observation at t+1.

• var_pred (np.ndarray):

  The predictive variance of the observation at t+1.

Return type:

Tuple[np.ndarray, np.ndarray]

lstm_train(train_data: Dict[str, ndarray], validation_data: Dict[str, ndarray], use_val_posterior_covariate: bool | None = False, update_param_covar_model: bool | None = False, white_noise_decay: bool | None = True, white_noise_max_std: float | None = 5, white_noise_decay_factor: float | None = 0.9) → Tuple[ndarray, ndarray]

Train the LstmNetwork component for each model on the provided training set, then evaluate on the validation set. Optionally apply exponential decay on the white noise standard deviation over epochs.

Parameters:

• train_data (Dict[str, np.ndarray]) – Dictionary with keys ‘x’ and ‘y’ for training inputs and targets.

• validation_data (Dict[str, np.ndarray]) – Dictionary with keys ‘x’ and ‘y’ for validation inputs and targets.

• posterior_covariate (Optional[bool]) – Estimate the posterior for covariate model or not. If True, the posteriors for covariates are used as input for the target model. Otherwise, priors are used. Defaults to False.

• update_param_covar_model (Optional[bool]) – Update the network parameters for the covariate models or not. Defaults to False.

• white_noise_decay (bool, optional) – If True, apply an exponential decay on the white noise standard deviation over epochs, if a white noise component exists. Defaults to True.

• white_noise_max_std (float, optional) – Upper bound on the white-noise standard deviation when decaying. Defaults to 5.

• white_noise_decay_factor (float, optional) – Multiplicative decay factor applied to the white‐noise standard deviation each epoch. Defaults to 0.9.

Returns:

A tuple containing:

• mu_validation_preds (np.ndarray):

  The means for multi-step-ahead predictions for the validation set.

• std_validation_preds (np.ndarray):

  The standard deviations for multi-step-ahead predictions for the validation set.

Return type:

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

set_memory(time_step: int)

Set memory for each model to a specific time step. Recall set_memory() for each model.

Parameters:

time_step (int) – Time step to set the memory.

smoother(matrix_inversion_tol: float | None = 1e-12, tol_type: str | None = 'relative')

Run the Kalman smoother over an entire time series data, i.e., repeatly apply the RTS smoothing equation over multiple time steps.

Parameters:

• matrix_inversion_tol (float) – Numerical stability threshold for matrix pseudoinversion (pinv). Defaults to 1E-12.

• tol_type (Optional[str]) – Tolerance type, “relative” or “absolute”. Defaults to “relative”.