Univariate Prophet

Bases: Prophetverse

Univariate Prophetverse forecaster - prophet model implemented in numpyro.

Differences to facebook's prophet:

• logistic trend. Here, another parametrization is considered, and the capacity is not passed as input, but inferred from the data.

• the users can pass arbitrary sktime transformers as feature_transformer, for instance FourierFeatures or HolidayFeatures.

• no default weekly_seasonality/yearly_seasonality, this is left to the user via the feature_transformer parameter

• Uses changepoint_interval instead of n_changepoints to set changepoints.

• accepts configurations where each exogenous variable has a different function relating it to its additive effect on the time series. One can, for example, set different priors for a group of feature, or use a Hill function to model the effect of a feature.

Parameters:

Name	Type	Description	Default
changepoint_interval	int	Number of potential changepoints to sample in the history.	25
changepoint_range	float or int	Proportion of the history in which trend changepoints will be estimated. if float, must be between 0 and 1. The range will be that proportion of the training history. if int, ca nbe positive or negative. Absolute value must be less than number of training points. The range will be that number of points. A negative int indicates number of points counting from the end of the history, a positive int from the beginning.	0.8
changepoint_prior_scale	float	Regularization parameter controlling the flexibility of the automatic changepoint selection.	0.001
offset_prior_scale	float	Scale parameter for the prior distribution of the offset. The offset is the constant term in the piecewise trend equation.	0.1
feature_transformer	sktime transformer, BaseTransformer	Transformer object to generate Fourier terms, holiday or other features. If None, no additional features are used. For multiple features, pass a FeatureUnion object with the transformers.	None
capacity_prior_scale	float	Scale parameter for the prior distribution of the capacity.	0.2
capacity_prior_loc	float	Location parameter for the prior distribution of the capacity.	1.1
noise_scale	float	Scale parameter for the observation noise.	0.05
trend	str, optional, one of "linear" (default) or "logistic"	Type of trend to use. Can be "linear" or "logistic".	'logistic'
mcmc_samples	int	Number of MCMC samples to draw.	2000
mcmc_warmup	int	Number of MCMC warmup steps. Also known as burn-in.	200
mcmc_chains	int	Number of MCMC chains to run in parallel.	4
inference_method	str, optional, one of "mcmc" or "map"	Inference method to use. Can be "mcmc" or "map".	"map"
optimizer_name	str	Name of the numpyro optimizer to use for variational inference.	"Adam"
optimizer_kwargs	dict	Additional keyword arguments to pass to the numpyro optimizer.	{}
optimizer_steps	int	Number of optimization steps to perform for variational inference.	100_000
exogenous_effects	List[AbstractEffect]	A list of prophetverse AbstractEffect objects defining the exogenous effects to be used in the model.	None
default_effect	AbstractEffectm optional, defalut=None	The default effect to be used when no effect is specified for a variable.	None
default_exogenous_prior	tuple	Default prior distribution for exogenous effects.	None
rng_key	jax.random.PRNGKey or None (default	Random number generator key.	None

Examples:

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.prophetverse import Prophetverse
>>> from prophetverse.effects.fourier import LinearFourierSeasonality
>>> from prophetverse.utils.regex import no_input_columns
>>> y = load_airline()
>>> model = Prophetverse(
...     exogenous_effects=[
...         (
...             "seasonality",
...             LinearFourierSeasonality(
...                 sp_list=[12],
...                 fourier_terms_list=[3],
...                 freq="M",
...                 effect_mode="multiplicative",
...             ),
...             no_input_columns,
...         )
...     ],
... )
>>> model.fit(y)
>>> model.predict(fh=[1, 2, 3])

Source code in src/prophetverse/sktime/univariate.py

class Prophet(Prophetverse):
    """Univariate ``Prophetverse`` forecaster - prophet model implemented in numpyro.

    Differences to facebook's prophet:

    * logistic trend. Here, another parametrization is considered,
      and the capacity is not passed as input, but inferred from the data.

    * the users can pass arbitrary ``sktime`` transformers as ``feature_transformer``,
      for instance ``FourierFeatures`` or ``HolidayFeatures``.

    * no default weekly_seasonality/yearly_seasonality, this is left to the user
      via the ``feature_transformer`` parameter

    * Uses ``changepoint_interval`` instead of ``n_changepoints`` to set changepoints.

    * accepts configurations where each exogenous variable has a different function
      relating it to its additive effect on the time series.
      One can, for example, set different priors for a group of feature,
      or use a Hill function to model the effect of a feature.

    Parameters
    ----------
    changepoint_interval : int, optional, default=25
        Number of potential changepoints to sample in the history.

    changepoint_range : float or int, optional, default=0.8
        Proportion of the history in which trend changepoints will be estimated.

        * if float, must be between 0 and 1.
          The range will be that proportion of the training history.

        * if int, ca nbe positive or negative.
          Absolute value must be less than number of training points.
          The range will be that number of points.
          A negative int indicates number of points
          counting from the end of the history, a positive int from the beginning.

    changepoint_prior_scale : float, optional, default=0.001
        Regularization parameter controlling the flexibility
        of the automatic changepoint selection.

    offset_prior_scale : float, optional, default=0.1
        Scale parameter for the prior distribution of the offset.
        The offset is the constant term in the piecewise trend equation.

    feature_transformer : sktime transformer, BaseTransformer, optional, default=None
        Transformer object to generate Fourier terms, holiday or other features.
        If None, no additional features are used.
        For multiple features, pass a ``FeatureUnion`` object with the transformers.

    capacity_prior_scale : float, optional, default=0.2
        Scale parameter for the prior distribution of the capacity.

    capacity_prior_loc : float, optional, default=1.1
        Location parameter for the prior distribution of the capacity.

    noise_scale : float, optional, default=0.05
        Scale parameter for the observation noise.
    trend : str, optional, one of "linear" (default) or "logistic"
        Type of trend to use. Can be "linear" or "logistic".

    mcmc_samples : int, optional, default=2000
        Number of MCMC samples to draw.

    mcmc_warmup : int, optional, default=200
        Number of MCMC warmup steps. Also known as burn-in.

    mcmc_chains : int, optional, default=4
        Number of MCMC chains to run in parallel.

    inference_method : str, optional, one of "mcmc" or "map", default="map"
        Inference method to use. Can be "mcmc" or "map".

    optimizer_name : str, optional, default="Adam"
        Name of the numpyro optimizer to use for variational inference.

    optimizer_kwargs : dict, optional, default={}
        Additional keyword arguments to pass to the numpyro optimizer.

    optimizer_steps : int, optional, default=100_000
        Number of optimization steps to perform for variational inference.

    exogenous_effects : List[AbstractEffect], optional, default=None
        A list of ``prophetverse`` ``AbstractEffect`` objects
        defining the exogenous effects to be used in the model.

    default_effect : AbstractEffectm optional, defalut=None
        The default effect to be used when no effect is specified for a variable.

    default_exogenous_prior : tuple, default=None
        Default prior distribution for exogenous effects.

    rng_key : jax.random.PRNGKey or None (default
        Random number generator key.

    Examples
    --------
    >>> from sktime.datasets import load_airline
    >>> from sktime.forecasting.prophetverse import Prophetverse
    >>> from prophetverse.effects.fourier import LinearFourierSeasonality
    >>> from prophetverse.utils.regex import no_input_columns
    >>> y = load_airline()
    >>> model = Prophetverse(
    ...     exogenous_effects=[
    ...         (
    ...             "seasonality",
    ...             LinearFourierSeasonality(
    ...                 sp_list=[12],
    ...                 fourier_terms_list=[3],
    ...                 freq="M",
    ...                 effect_mode="multiplicative",
    ...             ),
    ...             no_input_columns,
    ...         )
    ...     ],
    ... )
    >>> model.fit(y)
    >>> model.predict(fh=[1, 2, 3])
    """

    def __init__(
        self,
        changepoint_interval=25,
        changepoint_range=0.8,
        changepoint_prior_scale=0.001,
        offset_prior_scale=0.1,
        feature_transformer=None,
        capacity_prior_scale=0.2,
        capacity_prior_loc=1.1,
        noise_scale=0.05,
        trend="logistic",
        mcmc_samples=2000,
        mcmc_warmup=200,
        mcmc_chains=4,
        inference_method="map",
        optimizer_name="Adam",
        optimizer_kwargs=None,
        optimizer_steps=100_000,
        exogenous_effects=None,
        default_effect=None,
        scale=None,
        rng_key=None,
    ):

        super().__init__(
            changepoint_interval=changepoint_interval,
            changepoint_range=changepoint_range,
            changepoint_prior_scale=changepoint_prior_scale,
            offset_prior_scale=offset_prior_scale,
            feature_transformer=feature_transformer,
            capacity_prior_scale=capacity_prior_scale,
            capacity_prior_loc=capacity_prior_loc,
            noise_scale=noise_scale,
            trend=trend,
            mcmc_samples=mcmc_samples,
            mcmc_warmup=mcmc_warmup,
            mcmc_chains=mcmc_chains,
            inference_method=inference_method,
            optimizer_name=optimizer_name,
            optimizer_kwargs=optimizer_kwargs,
            optimizer_steps=optimizer_steps,
            exogenous_effects=exogenous_effects,
            likelihood="normal",
            default_effect=default_effect,
            scale=scale,
            rng_key=rng_key,
        )