pymc_forecast.forecaster#

Forecaster, HMCForecaster, and PathfinderForecaster call fit_vi, fit_mcmc, and fit_pathfinder. Constructors and attributes did not change. A model body passed to them is (covariates, data=None).

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 (call fit later).

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 median ELBO loss over the final 10% of steps (at least 10) is still clearly below the median over a same-sized window starting mid-run; 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 (callable or pymc_forecast.model.ForecastingModel) – The model body (see BaseForecaster).

  • data (xarray.DataArray, pandas.Series, pandas.DataFrame or array_like, optional) – Observed training series, normalized with as_dataarray(). None constructs the forecaster unfitted; call fit later.

  • covariates (xarray.DataArray, pandas.Series, pandas.DataFrame or array_like, optional) – Covariates on the same "time" coordinate as data; rows past the training window are dropped during fitting. None for models without covariates.

  • method (str or pymc.variational.Inference, default "advi") – VI method: "advi" (mean-field), "fullrank_advi", "svgd" or "asvgd" (case-insensitive, forwarded to pm.fit), or a pymc.variational.Inference instance — which fits the model it was built on and ignores this forecaster’s model and random_seed. The JAX backend accepts only "advi".

  • optimizer (float or callable, optional) – 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 ({"pytensor", "jax"}, optional) – 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 (int, default 10_000) – Number of optimization steps.

  • random_seed (int, optional) – Seed for the fit; also the default seed for later fit calls.

  • progressbar (bool, optional) – Show the fit progress bar; None means off. Ignored by the JAX backend. May instead be given in fit_kwargs, but not both.

  • fit_kwargs (mapping, optional) – Extra keyword arguments for pm.fit. progressbar is accepted here for compatibility, but the direct argument is preferred (passing both raises). Must be empty with backend="jax".

model_fn#

The model body passed to the constructor.

Type:

callable or pymc_forecast.model.ForecastingModel

model#

The training model; None before the first fit.

Type:

pymc.Model or None

approx#

The fitted approximation (set by fitting).

Type:

pymc.variational.Approximation

losses#

The per-step loss history (approx.hist); empty for "svgd" and "asvgd", which record no loss (set by fitting).

Type:

numpy.ndarray

idata#

Always None for variational fits (set by fitting).

Type:

None

Raises:
Warns:

UserWarning – When the post-fit heuristic finds the ELBO still descending, or the loss history contains non-finite values so convergence cannot be assessed.

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 (callable or pymc_forecast.model.ForecastingModel) – The model body (see BaseForecaster).

  • data (xarray.DataArray, pandas.Series, pandas.DataFrame or array_like, optional) – Observed training series, normalized with as_dataarray(). None constructs the forecaster unfitted; call fit later.

  • covariates (xarray.DataArray, pandas.Series, pandas.DataFrame or array_like, optional) – Covariates on the same "time" coordinate as data; rows past the training window are dropped during fitting. None for models without covariates.

  • draws (int, default 1000) – Number of posterior draws per chain.

  • tune (int, default 1000) – Number of tuning steps per chain.

  • chains (int, default 2) – Number of chains.

  • nuts_sampler ({"pymc", "nutpie", "numpyro", "blackjax"}, default "pymc") – NUTS backend, forwarded to pm.sample; non-PyMC samplers need their optional package installed.

  • random_seed (int or numpy.random.Generator, optional) – Seed for the fit, forwarded to pm.sample; also the default seed for later fit calls.

  • progressbar (bool, optional) – Show the sampling progress bar; None means off. May instead be given in sample_kwargs, but not both.

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

model_fn#

The model body passed to the constructor.

Type:

callable or pymc_forecast.model.ForecastingModel

model#

The training model; None before the first fit.

Type:

pymc.Model or None

idata#

The full MCMC result (posterior, sample stats, …), as returned by pm.sample (set by fitting).

Type:

xarray.DataTree or arviz.InferenceData

approx#

Always None for MCMC fits (set by fitting).

Type:

None

losses#

Always None for MCMC fits (set by fitting).

Type:

None

Raises:
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 only when fitting, so constructing without data does not require it.

Parameters:

  • model_fn (callable or pymc_forecast.model.ForecastingModel) – The model body (see BaseForecaster).

  • data (xarray.DataArray, pandas.Series, pandas.DataFrame or array_like, optional) – Observed training series, normalized with as_dataarray(). None constructs the forecaster unfitted; call fit later.

  • covariates (xarray.DataArray, pandas.Series, pandas.DataFrame or array_like, optional) – Covariates on the same "time" coordinate as data; rows past the training window are dropped during fitting. None for models without covariates.

  • random_seed (int, optional) – Seed for the fit, forwarded to pymc_extras.fit_pathfinder; also the default seed for later fit calls.

  • progressbar (bool, optional) – Show the fit progress bar; None means off. May instead be given in pathfinder_kwargs, but not both.

  • pathfinder_kwargs (mapping, optional) – 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).

model_fn#

The model body passed to the constructor.

Type:

callable or pymc_forecast.model.ForecastingModel

model#

The training model; None before the first fit.

Type:

pymc.Model or None

idata#

The Pathfinder result with its posterior group (set by fitting).

Type:

xarray.DataTree or arviz.InferenceData

approx#

Always None for Pathfinder fits (set by fitting).

Type:

None

losses#

Always None for Pathfinder fits (set by fitting).

Type:

None

Raises: