Skip to content

ForecasterFoundation¶

skforecast.foundation._forecaster_foundation.ForecasterFoundation ¶

ForecasterFoundation(estimator, forecaster_id=None)

Forecaster that wraps a FoundationModel [1]_ for full skforecast ecosystem compatibility: backtesting, model selection, etc.

Unlike ML-based forecasters, there is no training step: the underlying foundation models are zero-shot. fit only stores the context (recent observations) and records index metadata. Predictions are generated directly by the model's predict_quantiles pipeline.

Supports both single-series and multi-series modes. Pass a pandas.Series to fit for single-series forecasting or a wide pandas.DataFrame, a long-format pandas.DataFrame (MultiIndex), or a dict[str, pd.Series] for multi-series (global-model) forecasting.

Parameters:

Name Type Description Default
estimator FoundationModel

A configured FoundationModel instance, e.g. FoundationModel("autogluon/chronos-2-small", context_length=512). See FoundationModel for the list of supported model_id values and adapter-specific parameters.

 required
forecaster_id (str, int)

Name used as an identifier of the forecaster.

 None

Attributes:

Name Type Description
estimator FoundationModel

A clone of the FoundationModel instance provided by the user.
model_id str

HuggingFace model ID. Delegates to estimator.model_id.
context_ dict

Per-series dict of pandas Series containing the last context_length observations from the training data. Delegates to estimator.context_. None before fitting.
context_exog_ dict

Per-series dict of pandas DataFrame containing the last context_length exogenous variables from the training data. Delegates to estimator.context_exog_. None before fitting or if no exogenous variables were provided.
last_window_ dict

Alias for context_.
last_window_exog_ dict

Alias for context_exog_.
context_length int

Maximum number of historical observations used as context. Delegates to estimator.context_length.
window_size int

Desired number of historical observations used as context by the model. Always equals context_length.
allow_exog bool

Whether the underlying adapter uses exogenous variables at all. If False, exog is ignored with an IgnoredArgumentWarning. Delegates to estimator.allow_exog.
supports_past_only_covariates bool

Whether the underlying adapter uses historical exog columns that have no future values as past-only covariates. Delegates to estimator.supports_past_only_covariates.
supports_heterogeneous_covariates bool

Whether the underlying adapter can forecast series with different exog columns in the same backend call. If False, series are grouped by their exog columns at predict time and the adapter is called once per group. Delegates to estimator.supports_heterogeneous_covariates.
supports_nan_in_series bool

Whether the underlying adapter accepts NaN values in the series used as context. Delegates to estimator.supports_nan_in_series.
index_type_ type

Type of index of the input used in training. Delegates to estimator.index_type_.
index_freq_ pandas DateOffset, int

Frequency of the index of the input used in training. A pandas.DateOffset for DatetimeIndex; the step integer for RangeIndex. Delegates to estimator.index_freq_.
context_range_ dict

First and last values of index of the data used during training. A dict keyed by series name with pandas.Index values. Delegates to estimator.context_range_.
series_names_in_ list

Names of the series (levels) provided by the user during training. Delegates to estimator.series_names_in_.
is_multiple_series_ bool

Whether the forecaster was fitted with multiple series. Delegates to estimator.is_multiple_series_.
exog_in_ bool

If the forecaster has been trained using exogenous variable/s. Delegates to estimator.exog_in_.
exog_names_in_ list

Names of the exogenous variables used during training. Delegates to estimator.exog_names_in_.
exog_names_in_per_series_ dict

Names of the exogenous variables used during training for each series. Delegates to estimator.exog_names_in_per_series_.
exog_type_in_ type

Type of exogenous variable/s used in training. Delegates to estimator.exog_type_in_.
creation_date str

Date of creation.
is_fitted bool

Tag to identify if the forecaster has been fitted (trained).
fit_date str

Date of last fit. Delegates to estimator.fit_date.
skforecast_version str

Version of skforecast library used to create the forecaster.
python_version str

Version of python used to create the forecaster.
forecaster_id (str, int)

Name used as an identifier of the forecaster.
__skforecast_tags__ dict

Tags associated with the forecaster.
References

.. [1] FoundationModel and adapters: https://skforecast.org/latest/api/foundationmodel.html

Methods:

Name Description
fit

Training Forecaster.
predict

Predict n steps ahead.
predict_interval

Predict n steps ahead with prediction intervals.
predict_quantiles

Predict n steps ahead at specified quantile levels.
set_params

Set new values to the parameters of the underlying estimator.
summary

Show forecaster information.
Source code in skforecast/foundation/_forecaster_foundation.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
def __init__(
    self,
    estimator: FoundationModel,
    forecaster_id: str | int | None = None,
) -> None:

    if not isinstance(estimator, FoundationModel):
        raise TypeError(
            f"`estimator` must be a `FoundationModel` instance. "
            f"Got {type(estimator)}."
        )

    self.estimator          = clone(estimator)
    self.creation_date      = pd.Timestamp.today().strftime('%Y-%m-%d %H:%M:%S')
    self.is_fitted          = False
    self.skforecast_version = __version__
    self.python_version     = sys.version.split(" ")[0]
    self.forecaster_id      = forecaster_id

    self.__skforecast_tags__ = {
        "library": "skforecast",
        "forecaster_name": "ForecasterFoundation",
        "forecaster_task": "regression",
        "forecasting_scope": "single-series | global",
        "forecasting_strategy": "foundation",
        "multiple_estimators": False, 
        "index_types_supported": ["pandas.RangeIndex", "pandas.DatetimeIndex"],
        "requires_index_frequency": True,

        "allowed_input_types_series": [
            "pandas.Series",
            "pandas.DataFrame",
            "long-format pandas.DataFrame",
            "dict[str, pandas.Series]",
        ],
        "supports_exog": True,
        "allowed_input_types_exog": [
            "pandas.Series",
            "pandas.DataFrame",
            "long-format pandas.DataFrame",
            "dict[str, pandas.Series | pandas.DataFrame | None]",
        ],
        "handles_missing_values_series": True,
        "handles_missing_values_exog": True,

        "supports_lags": False,
        "supports_window_features": False,
        "supports_calendar_features": False,
        "supports_transformer_series": False,
        "supports_transformer_exog": False,
        "supports_categorical_features": True,
        "supports_weight_func": False,
        "supports_differentiation": False,

        "prediction_types": ["point", "interval", "quantiles"],
        "supports_probabilistic": True,
        "probabilistic_methods": ["quantile_native"],
        "handles_binned_residuals": False,
    }

Attributes¶

estimator instance-attribute ¶

estimator = clone(estimator)

creation_date instance-attribute ¶

creation_date = pd.Timestamp.today().strftime(
    "%Y-%m-%d %H:%M:%S"
)

is_fitted instance-attribute ¶

is_fitted = False

skforecast_version instance-attribute ¶

skforecast_version = __version__

python_version instance-attribute ¶

python_version = sys.version.split(' ')[0]

forecaster_id instance-attribute ¶

forecaster_id = forecaster_id

context_length property ¶

context_length

Maximum number of historical observations used as context.

Returns:

Name Type Description
context_length int

Maximum context length. Delegates to estimator.context_length.

model_id property ¶

model_id

HuggingFace model ID.

Returns:

Name Type Description
model_id str

HuggingFace model ID. Delegates to estimator.model_id.

window_size property ¶

window_size

Desired number of historical observations used as context by the model. Always equals context_length.

Returns:

Name Type Description
window_size int

Context window size. Delegates to estimator.context_length.

allow_exog property ¶

allow_exog

Whether the underlying adapter uses exogenous variables at all.

Returns:

Name Type Description
allow_exog bool

Delegates to estimator.allow_exog. If False, exog is ignored with an IgnoredArgumentWarning.

supports_past_only_covariates property ¶

supports_past_only_covariates

Whether the underlying adapter uses historical exog columns that have no future values as past-only covariates.

Returns:

Name Type Description
supports_past_only_covariates bool

Delegates to estimator.supports_past_only_covariates.

supports_heterogeneous_covariates property ¶

supports_heterogeneous_covariates

Whether the underlying adapter can forecast series with different exog columns in the same backend call.

Returns:

Name Type Description
supports_heterogeneous_covariates bool

Delegates to estimator.supports_heterogeneous_covariates. If False, predict groups the series by their exog columns and calls the adapter once per group.

supports_nan_in_series property ¶

supports_nan_in_series

Whether the underlying adapter accepts NaN values in the series used as context.

Returns:

Name Type Description
supports_nan_in_series bool

Delegates to estimator.supports_nan_in_series. If False, a context with NaN raises a ValueError at predict time.

context_ property ¶

context_

Per-series context stored during fit.

Returns:

Name Type Description
context_ (dict, None)

Per-series dict of pandas Series containing the last context_length observations from the training data. Delegates to estimator.context_. None before fitting.

last_window_ property ¶

last_window_

Alias for context_.

Returns:

Name Type Description
last_window_ (dict, None)

Per-series dict of pandas Series. Alias for context_.

context_exog_ property ¶

context_exog_

Per-series exogenous context stored during fit.

Returns:

Name Type Description
context_exog_ (dict, None)

Per-series dict of pandas DataFrame containing the last context_length exogenous variables from the training data. Delegates to estimator.context_exog_. None before fitting or if no exogenous variables were provided.

last_window_exog_ property ¶

last_window_exog_

Alias for context_exog_.

Returns:

Name Type Description
last_window_exog_ (dict, None)

Per-series dict of pandas DataFrame. Alias for context_exog_.

index_type_ property ¶

index_type_

Type of index of the input used in training.

Returns:

Name Type Description
index_type_ (type, None)

Index type. Delegates to estimator.index_type_. None before fitting.

index_freq_ property ¶

index_freq_

Frequency of the index of the input used in training.

Returns:

Name Type Description
index_freq_ pandas DateOffset, int, None

Index frequency. Delegates to estimator.index_freq_. None before fitting.

context_range_ property ¶

context_range_

First and last values of index of the data used during training.

Returns:

Name Type Description
context_range_ (dict, None)

Per-series index range. Delegates to estimator.context_range_. None before fitting.

series_names_in_ property ¶

series_names_in_

Names of the series (levels) provided by the user during training.

Returns:

Name Type Description
series_names_in_ (list, None)

Series names. Delegates to estimator.series_names_in_. None before fitting.

is_multiple_series_ property ¶

is_multiple_series_

Whether the forecaster was fitted with multiple series.

Returns:

Name Type Description
is_multiple_series_ bool

Delegates to estimator.is_multiple_series_. False before fitting.

exog_in_ property ¶

exog_in_

If the forecaster has been trained using exogenous variable/s.

Returns:

Name Type Description
exog_in_ bool

Delegates to estimator.exog_in_. False before fitting.

exog_names_in_ property ¶

exog_names_in_

Names of the exogenous variables used during training.

Returns:

Name Type Description
exog_names_in_ (list, None)

Delegates to estimator.exog_names_in_. None before fitting.

exog_names_in_per_series_ property ¶

exog_names_in_per_series_

Names of the exogenous variables used during training for each series.

Returns:

Name Type Description
exog_names_in_per_series_ (dict, None)

Delegates to estimator.exog_names_in_per_series_. None before fitting.

exog_type_in_ property ¶

exog_type_in_

Type of exogenous variable/s used in training.

Returns:

Name Type Description
exog_type_in_ (type, None)

Delegates to estimator.exog_type_in_. None before fitting.

fit_date property ¶

fit_date

Date of last fit.

Returns:

Name Type Description
fit_date (str, None)

Delegates to estimator.fit_date. None before fitting.

Methods:¶

fit ¶

fit(series, exog=None)

Training Forecaster.

Stores index metadata and delegates context storage to the underlying adapter. No model training occurs since foundation model is zero-shot.

Parameters:

Name Type Description Default
series pandas Series, pandas DataFrame, dict

Training time series.

  • If pandas.Series: single-series mode.
  • If wide pandas.DataFrame (one column per series): multi-series mode.
  • If long-format pandas.DataFrame with a MultiIndex (first level = series IDs, second level = DatetimeIndex): multi-series mode. Internally converted to a dict. An InputTypeWarning is issued; consider passing a dict directly for better performance.
  • If dict[str, pd.Series]: multi-series mode.
 required
exog pandas Series, pandas DataFrame, dict

Historical exogenous variables aligned to series. At prediction time they are forwarded to the underlying adapter as past (historical) covariates, using the adapter-specific covariate format.

In single-series mode: pd.Series or pd.DataFrame aligned to series.

In multi-series mode: a dict[str, pd.Series | pd.DataFrame | None] with one entry per series, a single pd.Series / pd.DataFrame broadcast to all series, or a long-format pd.DataFrame with a MultiIndex (first level = series IDs, second level = DatetimeIndex). Long-format inputs are converted to a dict internally; an InputTypeWarning is issued.

 None

Returns:

Type Description
None
Source code in skforecast/foundation/_forecaster_foundation.py 
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
def fit(
    self,
    series: pd.Series | pd.DataFrame | dict[str, pd.Series],
    exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.Series | pd.DataFrame | None]
        | None
    ) = None,
) -> None:
    """
    Training Forecaster.

    Stores index metadata and delegates context storage to the underlying
    adapter. No model training occurs since foundation model is zero-shot.

    Parameters
    ----------
    series : pandas Series, pandas DataFrame, dict
        Training time series.

        - If `pandas.Series`: single-series mode.
        - If wide `pandas.DataFrame` (one column per series): multi-series
          mode.
        - If long-format `pandas.DataFrame` with a MultiIndex (first level =
          series IDs, second level = `DatetimeIndex`): multi-series
          mode. Internally converted to a dict. An `InputTypeWarning` is
          issued; consider passing a dict directly for better performance.
        - If `dict[str, pd.Series]`: multi-series mode.
    exog : pandas Series, pandas DataFrame, dict, default None
        Historical exogenous variables aligned to `series`. At prediction
        time they are forwarded to the underlying adapter as past
        (historical) covariates, using the adapter-specific covariate
        format.

        In single-series mode: `pd.Series` or `pd.DataFrame` aligned to
        `series`.

        In multi-series mode: a `dict[str, pd.Series | pd.DataFrame | None]`
        with one entry per series, a single `pd.Series` / `pd.DataFrame`
        broadcast to all series, or a long-format `pd.DataFrame` with a
        MultiIndex (first level = series IDs, second level =
        `DatetimeIndex`). Long-format inputs are converted to a `dict`
        internally; an `InputTypeWarning` is issued.

    Returns
    -------
    None

    """

    self.is_fitted = False

    if exog is not None and not self.estimator.allow_exog:
        warnings.warn(
            f"The model '{self.estimator.model_id}' does not support "
            f"exogenous variables. `exog` will be ignored.",
            IgnoredArgumentWarning,
            stacklevel=2,
        )
        exog = None

    self.estimator.fit(series=series, exog=exog)
    self.is_fitted = True

predict ¶

predict(
    steps,
    levels=None,
    context=None,
    context_exog=None,
    exog=None,
    check_inputs=True,
)

Predict n steps ahead.

Parameters:

Name Type Description Default
steps int

Number of steps ahead to forecast.

 required
levels (str, list)

Subset of series to predict. If None, all series in context are predicted.

 None
context pandas Series, pandas DataFrame, dict

Context override for backtesting. When provided, replaces the context stored at fit time. In single-series mode pass a pd.Series; in multi-series mode pass a wide pd.DataFrame or a dict[str, pd.Series]. If longer than context_length, only the last context_length observations are used. If shorter, all available observations are passed as-is and the model handles the reduced context gracefully.

 None
context_exog pandas Series, pandas DataFrame, dict

Historical exogenous variables aligned to context (past covariates, mapped to the adapter-specific covariate format).

 None
exog pandas Series, pandas DataFrame, dict

Future-known exogenous variables for the forecast horizon (future covariates, mapped to the adapter-specific covariate format). Must cover exactly steps steps for each series.

 None
check_inputs bool

If True, the context and context_exog inputs are validated and normalized. If False, context must already be a dict[str, pandas Series] and context_exog must be a dict[str, pandas DataFrame | None] or None. This argument is created for internal use and is not recommended to be changed.

 True

Returns:

Name Type Description
predictions pandas DataFrame

Long-format DataFrame with columns ['level', 'pred']. The index repeats each forecast timestamp once per series.
Notes

Foundation models are pre-trained and do not learn from the data passed to fit. The fit method only stores context (the last context_length observations) and metadata. This leads to four distinct behaviors depending on the combination of is_fitted and context:

  • Not fitted, context=None: raises NotFittedError. There is no context available for prediction.
  • Fitted, context=None: uses the context and context_exog_ stored during fit. If the user supplies context_exog, it is ignored with a warning.
  • Not fitted, context provided (zero-shot mode): The model uses context and context_exog (if provided) as context for prediction.
  • Fitted, context provided: Stored context is ignored, the provided context and context_exog (if provided) are used for prediction.
Source code in skforecast/foundation/_forecaster_foundation.py 
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
def predict(
    self,
    steps: int,
    levels: str | list[str] | None = None,
    context: pd.Series | pd.DataFrame | dict[str, pd.Series] | None = None,
    context_exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.DataFrame | pd.Series | None]
        | None
    ) = None,
    exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.Series | pd.DataFrame | None]
        | None
    ) = None,
    check_inputs: bool = True,
) -> pd.DataFrame:
    """
    Predict n steps ahead.

    Parameters
    ----------
    steps : int
        Number of steps ahead to forecast.
    levels : str, list, default None
        Subset of series to predict. If `None`, all series in `context` are 
        predicted. 
    context : pandas Series, pandas DataFrame, dict, default None
        Context override for backtesting. When provided, replaces the
        context stored at fit time. In single-series mode pass a
        `pd.Series`; in multi-series mode pass a wide `pd.DataFrame` or a
        `dict[str, pd.Series]`. If longer than `context_length`, only the
        last `context_length` observations are used. If shorter, all
        available observations are passed as-is and the model handles the
        reduced context gracefully.
    context_exog : pandas Series, pandas DataFrame, dict, default None
        Historical exogenous variables aligned to `context` (past
        covariates, mapped to the adapter-specific covariate format).
    exog : pandas Series, pandas DataFrame, dict, default None
        Future-known exogenous variables for the forecast horizon (future
        covariates, mapped to the adapter-specific covariate format).
        Must cover exactly `steps` steps for each series.
    check_inputs : bool, default True
        If `True`, the `context` and `context_exog` inputs are validated
        and normalized. If `False`, `context` must already be a
        `dict[str, pandas Series]` and `context_exog` must be a
        `dict[str, pandas DataFrame | None]` or `None`. This argument
        is created for internal use and is not recommended to be changed.

    Returns
    -------
    predictions : pandas DataFrame
        Long-format DataFrame with columns `['level', 'pred']`.
        The index repeats each forecast timestamp once per series.

    Notes
    -----
    Foundation models are pre-trained and do not learn from the data passed
    to `fit`. The `fit` method only stores context (the last `context_length`
    observations) and metadata. This leads to four distinct behaviors
    depending on the combination of `is_fitted` and `context`:

    - **Not fitted, `context=None`**: raises `NotFittedError`. There is no
    context available for prediction.
    - **Fitted, `context=None`**: uses the context and `context_exog_` stored
    during `fit`. If the user supplies `context_exog`, it is ignored with a
    warning.
    - **Not fitted, `context` provided (zero-shot mode)**: The model uses
    `context` and `context_exog` (if provided) as context for prediction.
    - **Fitted, `context` provided**: Stored context is ignored, the
    provided `context` and `context_exog` (if provided) are used for
    prediction.

    """

    if not self.is_fitted and context is None:
        raise NotFittedError(
            "This forecaster is not fitted yet. Call `fit` with appropriate "
            "arguments before using `predict()`, or pass `context`."
        )

    predictions = self.estimator.predict(
                      steps        = steps,
                      context      = context,
                      context_exog = context_exog,
                      exog         = exog,
                      quantiles    = None,
                      levels       = levels,
                      check_inputs = check_inputs,
                  )

    return predictions

predict_interval ¶

predict_interval(
    steps,
    levels=None,
    context=None,
    context_exog=None,
    exog=None,
    interval=[0.1, 0.9],
    check_inputs=True,
)

Predict n steps ahead with prediction intervals.

Prediction intervals are derived directly from the underlying foundation model's native quantile output; no bootstrapping or residual estimation is used.

Parameters:

Name Type Description Default
steps int

Number of steps ahead to forecast.

 required
levels (str, list)

Subset of series to predict. If None, all series in context are predicted.

 None
context pandas Series, pandas DataFrame, dict

Context override for backtesting.

 None
context_exog pandas Series, pandas DataFrame, dict

Historical exog aligned to context (past covariates).

 None
exog pandas Series, pandas DataFrame, dict

Future-known exogenous variables for the forecast horizon (future covariates).

 None
interval (float, list, tuple)

Confidence level of the prediction interval. Interpretation depends on the method used:

  • If float, represents the nominal (expected) coverage (between 0 and 1). For instance, interval=0.95 corresponds to [0.025, 0.975] quantiles.
  • If list or tuple, defines the exact quantiles to compute, which must be between 0 and 1 inclusive. For example, interval of 95% should be as interval = [0.025, 0.975].

Changed in version 0.23.0: interval is now expressed as quantiles (0-1) instead of percentiles (0-100). Passing percentiles is not longer supported and will raise a ValueError.

 [0.1, 0.9]
check_inputs bool

If True, the context and context_exog inputs are validated and normalized. If False, context must already be a dict[str, pandas Series] and context_exog must be a dict[str, pandas DataFrame | None] or None. This argument is created for internal use and is not recommended to be changed.

 True

Returns:

Name Type Description
predictions pandas DataFrame

Long-format DataFrame with columns ['level', 'pred', 'lower_bound', 'upper_bound'].
Notes

Foundation models are pre-trained and do not learn from the data passed to fit. The fit method only stores context (the last context_length observations) and metadata. This leads to four distinct behaviors depending on the combination of is_fitted and context:

  • Not fitted, context=None: raises NotFittedError. There is no context available for prediction.
  • Fitted, context=None: uses the context and context_exog_ stored during fit. If the user supplies context_exog, it is ignored with a warning.
  • Not fitted, context provided (zero-shot mode): The model uses context and context_exog (if provided) as context for prediction.
  • Fitted, context provided: Stored context is ignored, the provided context and context_exog (if provided) are used for prediction.
Source code in skforecast/foundation/_forecaster_foundation.py 
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
def predict_interval(
    self,
    steps: int,
    levels: str | list[str] | None = None,
    context: pd.Series | pd.DataFrame | dict[str, pd.Series] | None = None,
    context_exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.DataFrame | pd.Series | None]
        | None
    ) = None,
    exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.Series | pd.DataFrame | None]
        | None
    ) = None,
    interval: float | list[float] | tuple[float] = [0.1, 0.9],
    check_inputs: bool = True,
) -> pd.DataFrame:
    """
    Predict n steps ahead with prediction intervals.

    Prediction intervals are derived directly from the underlying
    foundation model's native quantile output; no bootstrapping or
    residual estimation is used.

    Parameters
    ----------
    steps : int
        Number of steps ahead to forecast.
    levels : str, list, default None
        Subset of series to predict. If `None`, all series in `context` are 
        predicted. 
    context : pandas Series, pandas DataFrame, dict, default None
        Context override for backtesting.
    context_exog : pandas Series, pandas DataFrame, dict, default None
        Historical exog aligned to `context` (past covariates).
    exog : pandas Series, pandas DataFrame, dict, default None
        Future-known exogenous variables for the forecast horizon
        (future covariates).
    interval : float, list, tuple, default [0.1, 0.9]
        Confidence level of the prediction interval. Interpretation depends
        on the method used:

        - If `float`, represents the nominal (expected) coverage (between 0
        and 1). For instance, `interval=0.95` corresponds to `[0.025, 0.975]` 
        quantiles.
        - If `list` or `tuple`, defines the exact quantiles to compute, which 
        must be between 0 and 1 inclusive. For example, interval 
        of 95% should be as `interval = [0.025, 0.975]`.

        **Changed in version 0.23.0:** `interval` is now expressed as
        quantiles (0-1) instead of percentiles (0-100). Passing percentiles
        is not longer supported and will raise a `ValueError`.
    check_inputs : bool, default True
        If `True`, the `context` and `context_exog` inputs are validated
        and normalized. If `False`, `context` must already be a
        `dict[str, pandas Series]` and `context_exog` must be a
        `dict[str, pandas DataFrame | None]` or `None`. This argument
        is created for internal use and is not recommended to be changed.

    Returns
    -------
    predictions : pandas DataFrame
        Long-format DataFrame with columns `['level', 'pred', 'lower_bound',
        'upper_bound']`.

    Notes
    -----
    Foundation models are pre-trained and do not learn from the data passed
    to `fit`. The `fit` method only stores context (the last `context_length`
    observations) and metadata. This leads to four distinct behaviors
    depending on the combination of `is_fitted` and `context`:

    - **Not fitted, `context=None`**: raises `NotFittedError`. There is no
    context available for prediction.
    - **Fitted, `context=None`**: uses the context and `context_exog_` stored
    during `fit`. If the user supplies `context_exog`, it is ignored with a
    warning.
    - **Not fitted, `context` provided (zero-shot mode)**: The model uses
    `context` and `context_exog` (if provided) as context for prediction.
    - **Fitted, `context` provided**: Stored context is ignored, the
    provided `context` and `context_exog` (if provided) are used for
    prediction.

    """

    if not self.is_fitted and context is None:
        raise NotFittedError(
            "This forecaster is not fitted yet. Call `fit` with appropriate "
            "arguments before using `predict_interval()`, or pass `context`."
        )

    if isinstance(interval, (list, tuple)):
        check_interval(interval=interval, ensure_symmetric_intervals=False)
    else:
        check_interval(alpha=interval, alpha_literal='interval')
        interval = [0.5 - interval / 2, 0.5 + interval / 2]

    lower_q, upper_q = float(interval[0]), float(interval[1])

    # Always include the median (0.5) so 'pred' is the central forecast.
    quantiles = sorted({lower_q, 0.5, upper_q})

    predictions = self.predict_quantiles(
                      steps        = steps,
                      levels       = levels,
                      context      = context,
                      context_exog = context_exog,
                      exog         = exog,
                      quantiles    = quantiles,
                      check_inputs = check_inputs,
                  )

    predictions = predictions[['level', f'q_{0.5}', f'q_{lower_q}', f'q_{upper_q}']]
    predictions.columns = ['level', 'pred', 'lower_bound', 'upper_bound']

    return predictions

predict_quantiles ¶

predict_quantiles(
    steps,
    levels=None,
    context=None,
    context_exog=None,
    exog=None,
    quantiles=[0.1, 0.5, 0.9],
    check_inputs=True,
)

Predict n steps ahead at specified quantile levels.

Parameters:

Name Type Description Default
steps int

Number of steps ahead to forecast.

 required
levels (str, list)

Subset of series to predict. If None, all series in context are predicted.

 None
context pandas Series, pandas DataFrame, dict

Context override for backtesting.

 None
context_exog pandas Series, pandas DataFrame, dict

Historical exog aligned to context (past covariates).

 None
exog pandas Series, pandas DataFrame, dict

Future-known exogenous variables for the forecast horizon (future covariates).

 None
quantiles (list, tuple)

Quantile levels to forecast. Values must be in the range (0, 1).

 [0.1, 0.5, 0.9]
check_inputs bool

If True, the context and context_exog inputs are validated and normalized. If False, context must already be a dict[str, pandas Series] and context_exog must be a dict[str, pandas DataFrame | None] or None. This argument is created for internal use and is not recommended to be changed.

 True

Returns:

Name Type Description
predictions pandas DataFrame

Long-format DataFrame with columns ['level', 'q_0.1', 'q_0.5', ...].
Notes

Foundation models are pre-trained and do not learn from the data passed to fit. The fit method only stores context (the last context_length observations) and metadata. This leads to four distinct behaviors depending on the combination of is_fitted and context:

  • Not fitted, context=None: raises NotFittedError. There is no context available for prediction.
  • Fitted, context=None: uses the context and context_exog_ stored during fit. If the user supplies context_exog, it is ignored with a warning.
  • Not fitted, context provided (zero-shot mode): The model uses context and context_exog (if provided) as context for prediction.
  • Fitted, context provided: Stored context is ignored, the provided context and context_exog (if provided) are used for prediction.
Source code in skforecast/foundation/_forecaster_foundation.py 
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
def predict_quantiles(
    self,
    steps: int,
    levels: str | list[str] | None = None,
    context: pd.Series | pd.DataFrame | dict[str, pd.Series] | None = None,
    context_exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.DataFrame | pd.Series | None]
        | None
    ) = None,
    exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.Series | pd.DataFrame | None]
        | None
    ) = None,
    quantiles: list[float] | tuple[float] = [0.1, 0.5, 0.9],
    check_inputs: bool = True,
) -> pd.DataFrame:
    """
    Predict n steps ahead at specified quantile levels.

    Parameters
    ----------
    steps : int
        Number of steps ahead to forecast.
    levels : str, list, default None
        Subset of series to predict. If `None`, all series in `context` are 
        predicted. 
    context : pandas Series, pandas DataFrame, dict, default None
        Context override for backtesting.
    context_exog : pandas Series, pandas DataFrame, dict, default None
        Historical exog aligned to `context` (past covariates).
    exog : pandas Series, pandas DataFrame, dict, default None
        Future-known exogenous variables for the forecast horizon
        (future covariates).
    quantiles : list, tuple, default [0.1, 0.5, 0.9]
        Quantile levels to forecast. Values must be in the range (0, 1).
    check_inputs : bool, default True
        If `True`, the `context` and `context_exog` inputs are validated
        and normalized. If `False`, `context` must already be a
        `dict[str, pandas Series]` and `context_exog` must be a
        `dict[str, pandas DataFrame | None]` or `None`. This argument
        is created for internal use and is not recommended to be changed.

    Returns
    -------
    predictions : pandas DataFrame
        Long-format DataFrame with columns `['level', 'q_0.1', 'q_0.5', ...]`.

    Notes
    -----
    Foundation models are pre-trained and do not learn from the data passed
    to `fit`. The `fit` method only stores context (the last `context_length`
    observations) and metadata. This leads to four distinct behaviors
    depending on the combination of `is_fitted` and `context`:

    - **Not fitted, `context=None`**: raises `NotFittedError`. There is no
    context available for prediction.
    - **Fitted, `context=None`**: uses the context and `context_exog_` stored
    during `fit`. If the user supplies `context_exog`, it is ignored with a
    warning.
    - **Not fitted, `context` provided (zero-shot mode)**: The model uses
    `context` and `context_exog` (if provided) as context for prediction.
    - **Fitted, `context` provided**: Stored context is ignored, the
    provided `context` and `context_exog` (if provided) are used for
    prediction.

    """

    if not self.is_fitted and context is None:
        raise NotFittedError(
            "This forecaster is not fitted yet. Call `fit` with appropriate "
            "arguments before using `predict_quantiles()`, or pass `context`."
        )

    predictions = self.estimator.predict(
                      steps        = steps,
                      context      = context,
                      context_exog = context_exog,
                      exog         = exog,
                      quantiles    = list(quantiles),
                      levels       = levels,
                      check_inputs = check_inputs,
                  )

    return predictions

set_params ¶

set_params(params)

Set new values to the parameters of the underlying estimator.

After calling this method, the forecaster is reset to an unfitted state.

Parameters:

Name Type Description Default
params dict

Parameters values.

 required

Returns:

Type Description
None
Source code in skforecast/foundation/_forecaster_foundation.py 
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
def set_params(self, params: dict[str, object]) -> None:
    """
    Set new values to the parameters of the underlying estimator.

    After calling this method, the forecaster is reset to an unfitted state.

    Parameters
    ----------
    params : dict
        Parameters values.

    Returns
    -------
    None

    """

    self.estimator.set_params(**params)
    self.is_fitted = False

summary ¶

summary()

Show forecaster information.

Returns:

Type Description
None
Source code in skforecast/foundation/_forecaster_foundation.py 
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
def summary(self) -> None:
    """
    Show forecaster information.

    Returns
    -------
    None

    """

    print(self.__repr__())