This module contains the update and forecast functions to work with a latent factor DGLM. There are two sets of functions: The first works with the latent_factor class in PyBATS, which represents latent factors by a mean and a variance. The second set of functions relies on simulated values of a latent factor, which is a more precise but computationally slower method.

The default functions work with the latent_factor class, and are called automatically by analysis, dglm.update, dglm.forecast_marginal, and dglm.forecast_path when there are latent factors in the model.

To use simulated latent factor values, set the argument analytic=False in the dglm methods, and pass in the set of simulated values as phi_samps. It is not currently supported to use the simulated latent factor values within analysis.

Moment-based latent factor analysis

update_lf_analytic[source]

update_lf_analytic(mod, y=None, X=None, phi_mu=None, phi_sigma=None)

update_lf_analytic_dlm[source]

update_lf_analytic_dlm(mod, y=None, X=None, phi_mu=None, phi_sigma=None)

forecast_marginal_lf_analytic[source]

forecast_marginal_lf_analytic(mod, k, X=None, phi_mu=None, phi_sigma=None, nsamps=1, mean_only=False, state_mean_var=False)

forecast_path_lf_copula[source]

forecast_path_lf_copula(mod, k, X=None, phi_mu=None, phi_sigma=None, phi_psi=None, nsamps=1, t_dist=False, y=None, nu=9, return_mu_cov=False)

These functions are called automatically in PyBATS when working with a DGLM that has a latent factor component. The new arguments are:

  • phi_mu: Mean vector of the latent factor. For forecast_path_lf_copula, it should be a list of k mean vectors.
  • phi_sigma: Variance matrix of the latent factor. For forecast_path_lf_copula, it should be a list of k variance matrices.

The following extra arguments are only applicable to path forecasting with forecast_path_lf_copula:

  • phi_psi: This is a list of k-1 covariance matrices $cov(\phi_{t+k}, \phi_{t+j})$. Each element is a numpy array.
  • t_dist: Boolean. By default, a Gaussian copula is used. If True, then a t-copula is used instead.
  • y: Future path of observations y. If provided, output will be the forecast density of y.
  • nu: Degrees of freedom for t-copula.

Simulation-based latent factor analysis

update_lf_sample[source]

update_lf_sample(mod, y=None, X=None, phi_samps=None, parallel=False)

DGLM update function with samples of a latent factor.

$\phi_{samps}$ = Array of simulated values of a latent factor.

update_lf_sample_forwardfilt[source]

update_lf_sample_forwardfilt(mod, y, F, a, R, phi)

forecast_marginal_lf_sample[source]

forecast_marginal_lf_sample(mod, k, X=None, phi_samps=None, mean_only=False)

forecast_path_lf_sample[source]

forecast_path_lf_sample(mod, k, X=None, phi_samps=None)

These functions can be called through dglm.update, dglm.forecast_marginal, and dglm.forecast_path by setting the argument analytic=False. They represent an alternative method of analysis by working with simulated values of the latent factor. The simulated values are passed into the function as an array phi_samps, where each row contains a simulated value of the latent factor.

This is a more accurate analysis method because it does not reduce the distribution of the latent factor down to its mean and variance. However, it is also more computationally demanding to work with the simulated values, so there is a trade-off between speed and accuracy.

Multivariate forecasting with multiple DGLMs

forecast_joint_marginal_lf_copula[source]

forecast_joint_marginal_lf_copula(mod_list, k, X_list=None, phi_mu=None, phi_sigma=None, nsamps=1, y=None, t_dist=False, nu=9, return_cov=False)

forecast_joint_marginal_lf_copula is used to recouple a set of DGLMs which share the same latent factor. In other words, if the same latent factor is used in multiple models, then their forecasts will be correlated. This function allows for joint forecasting across these separated DGLMs.

A classic example comes from retail sales. The latent factor may represent an effect at the total store level - say, customer traffic based on the day-of-week. A separate DGLM models the sales of each individual item. To jointly forecast the sales of many items, the models can all be passed into forecast_joint_marginal_lf_copula, along with the latent factor mean and variance, to draw joint samples from the forecast distribution.

Multivariate forecasting with multiple DCMMs

forecast_joint_marginal_lf_copula_dcmm[source]

forecast_joint_marginal_lf_copula_dcmm(dcmm_list, k, X_list=None, phi_mu=None, phi_sigma=None, nsamps=1, t_dist=False, nu=9, return_cov=False)

forecast_joint_marginal_lf_copula_dcmm behaves similarly to forecast_joint_marginal_lf_copula, but for a set of related DCMMs instead of related DGLMs.

DCMM forecast functions

forecast_marginal_lf_dcmm[source]

forecast_marginal_lf_dcmm(mod, k, X=None, phi_mu=None, phi_sigma=None, nsamps=1, t_dist=False, nu=9, return_cov=False)

forecast_path_lf_dcmm[source]

forecast_path_lf_dcmm(mod, k, X=None, phi_mu=None, phi_sigma=None, phi_psi=None, nsamps=1, t_dist=False, nu=9, return_cov=False)

These functions are for marginal and path forecasting with a latent factor DCMM. They may be accessed as methods from dcmm.