pymc_forecast.forecaster#

Forecaster classes: fit a forecasting model, then draw probabilistic forecasts.

Three inference backends behind one interface: Forecaster (variational, ADVI by default), HMCForecaster (MCMC via pm.sample), and PathfinderForecaster (pymc-extras Pathfinder). Construction fits the model on (data, covariates); forecast() then rebuilds the model over extended covariates and samples the horizon. Construct without data to defer the fit (fit()).

class pymc_forecast.forecaster.Forecaster(model_fn, data=None, covariates=None, *, method='advi', optimizer=None, backend=None, num_steps=10000, random_seed=None, progressbar=None, fit_kwargs=None)[source]#

Bases: BaseForecaster

Fit a forecasting model with variational inference (ADVI by default).

Mean-field ADVI can underconverge silently — the posterior looks fine but is biased and overconfident. A post-fit heuristic warns when the ELBO is still descending (see _check_vi_convergence()); absence of the warning is not proof of convergence, so check losses has plateaued before trusting results, and prefer HMCForecaster when accuracy matters more than speed.

Parameters:

  • model_fn – See BaseForecaster.

  • data – See BaseForecaster.

  • covariates – See BaseForecaster.

  • random_seed – See BaseForecaster.

  • method – VI method: "advi" (mean-field, default) or "fullrank_advi", or any pm.fit-compatible inference object.

  • optimizer – None (Adam with lr 0.01), a positive learning rate, or a PyMC optimizer such as pm.adam(learning_rate=...). The JAX backend accepts None or a positive learning rate.

  • backend – None or "pytensor" uses pm.fit. "jax" runs mean-field ADVI and Adam as one JAX lax.scan on the selected accelerator (GPU when a CUDA JAX is installed), while retaining PyMC’s ordinary approximation object for posterior sampling. The optional jax extra is required.

  • num_steps – Number of optimization steps.

  • progressbar – Show the fit progress bar.

  • fit_kwargs – Extra keyword arguments for pm.fit. progressbar is accepted here for compatibility, but the direct argument is preferred (passing both raises).

approx#

The fitted pm.Approximation.

losses#

The ELBO loss history (one value per step).

class pymc_forecast.forecaster.HMCForecaster(model_fn, data=None, covariates=None, *, draws=1000, tune=1000, chains=2, nuts_sampler='pymc', random_seed=None, progressbar=None, sample_kwargs=None)[source]#

Bases: BaseForecaster

Fit a forecasting model with MCMC (NUTS by default).

Parameters:

  • model_fn – See BaseForecaster.

  • data – See BaseForecaster.

  • covariates – See BaseForecaster.

  • random_seed – See BaseForecaster.

  • draws – MCMC schedule (defaults 1000 / 1000 / 2).

  • tune – MCMC schedule (defaults 1000 / 1000 / 2).

  • chains – MCMC schedule (defaults 1000 / 1000 / 2).

  • nuts_sampler – NUTS backend: "pymc" (default), "nutpie", "numpyro", or "blackjax".

  • progressbar – Show the sampling progress bar.

  • sample_kwargs – Extra keyword arguments for pm.sample. progressbar is accepted here for compatibility, but the direct argument is preferred (passing both raises).

idata#

The full MCMC result (posterior, sample stats, …).

class pymc_forecast.forecaster.PathfinderForecaster(model_fn, data=None, covariates=None, *, random_seed=None, progressbar=None, pathfinder_kwargs=None)[source]#

Bases: BaseForecaster

Fit a forecasting model with Pathfinder variational inference.

A thin wrapper over pymc_extras.fit_pathfinder. pymc-extras is imported lazily, so constructing this class is the opt-in that requires it.

Parameters:

  • model_fn – See BaseForecaster.

  • data – See BaseForecaster.

  • covariates – See BaseForecaster.

  • random_seed – See BaseForecaster.

  • progressbar – Show the fit progress bar.

  • pathfinder_kwargs – Extra keyword arguments for pymc_extras.fit_pathfinder (e.g. num_paths, num_draws). progressbar is accepted here for compatibility, but the direct argument is preferred (passing both raises).

idata#

The Pathfinder result with its posterior group.