stats

skforecast.stats._sarimax.Sarimax

Sarimax(
    order=(1, 0, 0),
    seasonal_order=(0, 0, 0, 0),
    trend=None,
    measurement_error=False,
    time_varying_regression=False,
    mle_regression=True,
    simple_differencing=False,
    enforce_stationarity=True,
    enforce_invertibility=True,
    hamilton_representation=False,
    concentrate_scale=False,
    trend_offset=1,
    use_exact_diffuse=False,
    dates=None,
    freq=None,
    missing="none",
    validate_specification=True,
    method="lbfgs",
    maxiter=50,
    start_params=None,
    disp=False,
    sm_init_kwargs={},
    sm_fit_kwargs={},
    sm_predict_kwargs={},
)

Bases: BaseEstimator, RegressorMixin

A universal scikit-learn style wrapper for statsmodels SARIMAX.

This class wraps the statsmodels.tsa.statespace.sarimax.SARIMAX model [1]_ [2]_ to follow the scikit-learn style. The following docstring is based on the statsmodels documentation and it is highly recommended to visit their site for the best level of detail.

Parameters:

Name	Type	Description	Default
order	tuple	The (p,d,q) order of the model for the number of AR parameters, differences, and MA parameters. d must be an integer indicating the integration order of the process. p and q may either be an integers indicating the AR and MA orders (so that all lags up to those orders are included) or else iterables giving specific AR and / or MA lags to include.	(1, 0, 0)
seasonal_order	tuple	The (P,D,Q,s) order of the seasonal component of the model for the AR parameters, differences, MA parameters, and periodicity. D must be an integer indicating the integration order of the process. P and Q may either be an integers indicating the AR and MA orders (so that all lags up to those orders are included) or else iterables giving specific AR and / or MA lags to include. s is an integer giving the periodicity (number of periods in season), often it is 4 for quarterly data or 12 for monthly data.	(0, 0, 0, 0)
trend	str	Parameter controlling the deterministic trend polynomial A(t). 'c' indicates a constant (i.e. a degree zero component of the trend polynomial). 't' indicates a linear trend with time. 'ct' indicates both, 'c' and 't'. Can also be specified as an iterable defining the non-zero polynomial exponents to include, in increasing order. For example, [1,1,0,1] denotes a + b*t + ct^3.	None
measurement_error	bool	Whether or not to assume the endogenous observations y were measured with error.	False
time_varying_regression	bool	Used when an explanatory variables, exog, are provided to select whether or not coefficients on the exogenous estimators are allowed to vary over time.	False
mle_regression	bool	Whether or not to use estimate the regression coefficients for the exogenous variables as part of maximum likelihood estimation or through the Kalman filter (i.e. recursive least squares). If time_varying_regression is True, this must be set to False.	True
simple_differencing	bool	Whether or not to use partially conditional maximum likelihood estimation. If True, differencing is performed prior to estimation, which discards the first s*D + d initial rows but results in a smaller state-space formulation. If False, the full SARIMAX model is put in state-space form so that all data points can be used in estimation.	False
enforce_stationarity	bool	Whether or not to transform the AR parameters to enforce stationarity in the autoregressive component of the model.	True
enforce_invertibility	bool	Whether or not to transform the MA parameters to enforce invertibility in the moving average component of the model.	True
hamilton_representation	bool	Whether or not to use the Hamilton representation of an ARMA process (if True) or the Harvey representation (if False).	False
concentrate_scale	bool	Whether or not to concentrate the scale (variance of the error term) out of the likelihood. This reduces the number of parameters estimated by maximum likelihood by one, but standard errors will then not be available for the scale parameter.	False
trend_offset	int	The offset at which to start time trend values. Default is 1, so that if trend='t' the trend is equal to 1, 2, ..., nobs. Typically is only set when the model created by extending a previous dataset.	1
use_exact_diffuse	bool	Whether or not to use exact diffuse initialization for non-stationary states. Default is False (in which case approximate diffuse initialization is used).	False
method	str	The method determines which solver from scipy.optimize is used, and it can be chosen from among the following strings: 'newton' for Newton-Raphson 'nm' for Nelder-Mead 'bfgs' for Broyden-Fletcher-Goldfarb-Shanno (BFGS) 'lbfgs' for limited-memory BFGS with optional box constraints 'powell' for modified Powell`s method 'cg' for conjugate gradient 'ncg' for Newton-conjugate gradient 'basinhopping' for global basin-hopping solver	'lbfgs'
maxiter	int	The maximum number of iterations to perform.	50
start_params	numpy ndarray	Initial guess of the solution for the loglikelihood maximization. If None, the default is given by estimator.start_params.	None
disp	bool	Set to True to print convergence messages.	False
sm_init_kwargs	dict	Additional keyword arguments to pass to the statsmodels SARIMAX model when it is initialized.	{}
sm_fit_kwargs	dict	Additional keyword arguments to pass to the fit method of the statsmodels SARIMAX model. The statsmodels SARIMAX.fit parameters method, max_iter, start_params and disp have been moved to the initialization of this model and will have priority over those provided by the user using via sm_fit_kwargs.	{}
sm_predict_kwargs	dict	Additional keyword arguments to pass to the get_forecast method of the statsmodels SARIMAXResults object.	{}

Attributes:

Name	Type	Description
order	tuple	The (p,d,q) order of the model for the number of AR parameters, differences, and MA parameters.
seasonal_order	tuple	The (P,D,Q,s) order of the seasonal component of the model for the AR parameters, differences, MA parameters, and periodicity.
trend	str	Deterministic trend polynomial A(t).
measurement_error	bool	Whether or not to assume the endogenous observations y were measured with error.
time_varying_regression	bool	Used when an explanatory variables, exog, are provided to select whether or not coefficients on the exogenous estimators are allowed to vary over time.
mle_regression	bool	Whether or not to use estimate the regression coefficients for the exogenous variables as part of maximum likelihood estimation or through the Kalman filter (i.e. recursive least squares). If time_varying_regression is True, this must be set to False.
simple_differencing	bool	Whether or not to use partially conditional maximum likelihood estimation.
enforce_stationarity	bool	Whether or not to transform the AR parameters to enforce stationarity in the autoregressive component of the model.
enforce_invertibility	bool	Whether or not to transform the MA parameters to enforce invertibility in the moving average component of the model.
hamilton_representation	bool	Whether or not to use the Hamilton representation of an ARMA process (if True) or the Harvey representation (if False).
concentrate_scale	bool	Whether or not to concentrate the scale (variance of the error term) out of the likelihood. This reduces the number of parameters estimated by maximum likelihood by one, but standard errors will then not be available for the scale parameter.
trend_offset	int	The offset at which to start time trend values.
use_exact_diffuse	bool	Whether or not to use exact diffuse initialization for non-stationary states.
method	str	The method determines which solver from scipy.optimize is used.
maxiter	int	The maximum number of iterations to perform.
start_params	numpy ndarray	Initial guess of the solution for the loglikelihood maximization.
disp	bool	Set to True to print convergence messages.
sm_init_kwargs	dict	Additional keyword arguments to pass to the statsmodels SARIMAX model when it is initialized.
sm_fit_kwargs	dict	Additional keyword arguments to pass to the fit method of the statsmodels SARIMAX model.
sm_predict_kwargs	dict	Additional keyword arguments to pass to the get_forecast method of the statsmodels SARIMAXResults object.
_sarimax_params	dict	Parameters of this model that can be set with the set_params method.
output_type	str	Format of the object returned by the predict method. This is set automatically according to the type of y used in the fit method to train the model, 'numpy' or 'pandas'.
sarimax	object	The statsmodels.tsa.statespace.sarimax.SARIMAX object created.
fitted	bool	Tag to identify if the estimator has been fitted (trained).
sarimax_res	object	The resulting statsmodels.tsa.statespace.sarimax.SARIMAXResults object created by statsmodels after fitting the SARIMAX model.
training_index	pandas Index	Index of the training series as long as it is a pandas Series or Dataframe.

References

.. [1] Statsmodels SARIMAX API Reference. https://www.statsmodels.org/stable/generated/statsmodels.tsa.statespace.sarimax.SARIMAX.html

.. [2] Statsmodels SARIMAXResults API Reference. https://www.statsmodels.org/stable/generated/statsmodels.tsa.statespace.sarimax.SARIMAXResults.html

Methods:

Name	Description
fit	Fit the model to the data.
predict	Forecast future values and, if desired, their confidence intervals.
append	Recreate the results object with new data appended to the original data.
apply	Apply the fitted parameters to new data unrelated to the original data.
extend	Recreate the results object for new data that extends the original data.
set_params	Set new values to the parameters of the estimator.
params	Get the parameters of the model. The order of variables is the trend
summary	Get a summary of the SARIMAXResults object.
get_info_criteria	Get the selected information criteria.

Source code in skforecast\stats\_sarimax.py

def __init__(
    self,
    order: tuple = (1, 0, 0),
    seasonal_order: tuple = (0, 0, 0, 0),
    trend: str = None,
    measurement_error: bool = False,
    time_varying_regression: bool = False,
    mle_regression: bool = True,
    simple_differencing: bool = False,
    enforce_stationarity: bool = True,
    enforce_invertibility: bool = True,
    hamilton_representation: bool = False,
    concentrate_scale: bool = False,
    trend_offset: int = 1,
    use_exact_diffuse: bool = False,
    dates = None,
    freq = None,
    missing = 'none',
    validate_specification: bool = True,
    method: str = 'lbfgs',
    maxiter: int = 50,
    start_params: np.ndarray = None,
    disp: bool = False,
    sm_init_kwargs: dict[str, object] = {},
    sm_fit_kwargs: dict[str, object] = {},
    sm_predict_kwargs: dict[str, object] = {}
) -> None:

    self.order                   = order
    self.seasonal_order          = seasonal_order
    self.trend                   = trend
    self.measurement_error       = measurement_error
    self.time_varying_regression = time_varying_regression
    self.mle_regression          = mle_regression
    self.simple_differencing     = simple_differencing
    self.enforce_stationarity    = enforce_stationarity
    self.enforce_invertibility   = enforce_invertibility
    self.hamilton_representation = hamilton_representation
    self.concentrate_scale       = concentrate_scale
    self.trend_offset            = trend_offset
    self.use_exact_diffuse       = use_exact_diffuse
    self.dates                   = dates
    self.freq                    = freq
    self.missing                 = missing
    self.validate_specification  = validate_specification
    self.method                  = method
    self.maxiter                 = maxiter
    self.start_params            = start_params
    self.disp                    = disp

    # Create the dictionaries with the additional statsmodels parameters to be  
    # used during the init, fit and predict methods. Note that the statsmodels 
    # SARIMAX.fit parameters `method`, `max_iter`, `start_params` and `disp` 
    # have been moved to the initialization of this model and will have 
    # priority over those provided by the user using via `sm_fit_kwargs`.
    self.sm_init_kwargs    = sm_init_kwargs
    self.sm_fit_kwargs     = sm_fit_kwargs
    self.sm_predict_kwargs = sm_predict_kwargs

    # Params that can be set with the `set_params` method
    _, _, _, _sarimax_params = inspect.getargvalues(inspect.currentframe())
    self._sarimax_params = {
        k: v for k, v in _sarimax_params.items() 
        if k not in ['self', '_', '_sarimax_params']
    }

    self._consolidate_kwargs()

    # Create Results Attributes 
    self.output_type    = None
    self.sarimax        = None
    self.fitted         = False
    self.sarimax_res    = None
    self.training_index = None

order instance-attribute

order = order

seasonal_order instance-attribute

seasonal_order = seasonal_order

trend instance-attribute

trend = trend

measurement_error instance-attribute

measurement_error = measurement_error

time_varying_regression instance-attribute

time_varying_regression = time_varying_regression

mle_regression instance-attribute

mle_regression = mle_regression

simple_differencing instance-attribute

simple_differencing = simple_differencing

enforce_stationarity instance-attribute

enforce_stationarity = enforce_stationarity

enforce_invertibility instance-attribute

enforce_invertibility = enforce_invertibility

hamilton_representation instance-attribute

hamilton_representation = hamilton_representation

concentrate_scale instance-attribute

concentrate_scale = concentrate_scale

trend_offset instance-attribute

trend_offset = trend_offset

use_exact_diffuse instance-attribute

use_exact_diffuse = use_exact_diffuse

dates instance-attribute

dates = dates

freq instance-attribute

freq = freq

missing instance-attribute

missing = missing

validate_specification instance-attribute

validate_specification = validate_specification

method instance-attribute

method = method

maxiter instance-attribute

maxiter = maxiter

start_params instance-attribute

start_params = start_params

disp instance-attribute

disp = disp

sm_init_kwargs instance-attribute

sm_init_kwargs = sm_init_kwargs

sm_fit_kwargs instance-attribute

sm_fit_kwargs = sm_fit_kwargs

sm_predict_kwargs instance-attribute

sm_predict_kwargs = sm_predict_kwargs

_sarimax_params instance-attribute

_sarimax_params = {
    k: v
    for k, v in (items())
    if k not in ["self", "_", "_sarimax_params"]
}

output_type instance-attribute

output_type = None

sarimax instance-attribute

sarimax = None

fitted instance-attribute

fitted = False

sarimax_res instance-attribute

sarimax_res = None

training_index instance-attribute

training_index = None

_consolidate_kwargs

_consolidate_kwargs()

Create the dictionaries to be used during the init, fit, and predict methods. Note that the parameters in this model's initialization take precedence over those provided by the user using via the statsmodels kwargs dicts.

Parameters:

Name	Type	Description	Default
self			required

Returns:

Type	Description
None

Source code in skforecast\stats\_sarimax.py

def _consolidate_kwargs(
    self
) -> None:
    """
    Create the dictionaries to be used during the init, fit, and predict methods.
    Note that the parameters in this model's initialization take precedence 
    over those provided by the user using via the statsmodels kwargs dicts.

    Parameters
    ----------
    self

    Returns
    -------
    None

    """

    # statsmodels.tsa.statespace.SARIMAX parameters
    _init_kwargs = self.sm_init_kwargs.copy()
    _init_kwargs.update({
       'order': self.order,
       'seasonal_order': self.seasonal_order,
       'trend': self.trend,
       'measurement_error': self.measurement_error,
       'time_varying_regression': self.time_varying_regression,
       'mle_regression': self.mle_regression,
       'simple_differencing': self.simple_differencing,
       'enforce_stationarity': self.enforce_stationarity,
       'enforce_invertibility': self.enforce_invertibility,
       'hamilton_representation': self.hamilton_representation,
       'concentrate_scale': self.concentrate_scale,
       'trend_offset': self.trend_offset,
       'use_exact_diffuse': self.use_exact_diffuse,
       'dates': self.dates,
       'freq': self.freq,
       'missing': self.missing,
       'validate_specification': self.validate_specification
    })
    self._init_kwargs = _init_kwargs

    # statsmodels.tsa.statespace.SARIMAX.fit parameters
    _fit_kwargs = self.sm_fit_kwargs.copy()
    _fit_kwargs.update({
       'method': self.method,
       'maxiter': self.maxiter,
       'start_params': self.start_params,
       'disp': self.disp,
    })        
    self._fit_kwargs = _fit_kwargs

    # statsmodels.tsa.statespace.SARIMAXResults.get_forecast parameters
    self._predict_kwargs = self.sm_predict_kwargs.copy()

_create_sarimax

_create_sarimax(endog, exog=None)

A helper method to create a new statsmodel SARIMAX model.

Additional keyword arguments to pass to the statsmodels SARIMAX model when it is initialized can be added with the init_kwargs argument when initializing the model.

Parameters:

Name	Type	Description	Default
endog	numpy ndarray, pandas Series, pandas DataFrame	The endogenous variable.	required
exog	numpy ndarray, pandas Series, pandas DataFrame	The exogenous variables.	None

Returns:

Type	Description
None

Source code in skforecast\stats\_sarimax.py

def _create_sarimax(
    self,
    endog: np.ndarray | pd.Series | pd.DataFrame,
    exog: np.ndarray | pd.Series | pd.DataFrame | None = None
) -> None:
    """
    A helper method to create a new statsmodel SARIMAX model.

    Additional keyword arguments to pass to the statsmodels SARIMAX model 
    when it is initialized can be added with the `init_kwargs` argument 
    when initializing the model.

    Parameters
    ----------
    endog : numpy ndarray, pandas Series, pandas DataFrame
        The endogenous variable.
    exog : numpy ndarray, pandas Series, pandas DataFrame, default None
        The exogenous variables.

    Returns
    -------
    None

    """

    self.sarimax = SARIMAX(endog=endog, exog=exog, **self._init_kwargs)

fit

fit(y, exog=None)

Fit the model to the data.

Additional keyword arguments to pass to the fit method of the statsmodels SARIMAX model can be added with the fit_kwargs argument when initializing the model.

Parameters:

Name	Type	Description	Default
y	numpy ndarray, pandas Series, pandas DataFrame	Training time series.	required
exog	numpy ndarray, pandas Series, pandas DataFrame	Exogenous variable/s included as predictor/s. Must have the same number of observations as y and their indexes must be aligned so that y[i] is regressed on exog[i].	None

Returns:

Type	Description
None

Source code in skforecast\stats\_sarimax.py

def fit(
    self,
    y: np.ndarray | pd.Series | pd.DataFrame,
    exog: np.ndarray | pd.Series | pd.DataFrame | None = None
) -> None:
    """
    Fit the model to the data.

    Additional keyword arguments to pass to the `fit` method of the
    statsmodels SARIMAX model can be added with the `fit_kwargs` argument 
    when initializing the model.

    Parameters
    ----------
    y : numpy ndarray, pandas Series, pandas DataFrame
        Training time series.
    exog : numpy ndarray, pandas Series, pandas DataFrame, default None
        Exogenous variable/s included as predictor/s. Must have the same
        number of observations as `y` and their indexes must be aligned so
        that y[i] is regressed on exog[i].

    Returns
    -------
    None

    """

    # Reset values in case the model has already been fitted.
    self.output_type    = None
    self.sarimax_res    = None
    self.fitted         = False
    self.training_index = None

    self.output_type = 'numpy' if isinstance(y, np.ndarray) else 'pandas'

    self._create_sarimax(endog=y, exog=exog)
    self.sarimax_res = self.sarimax.fit(**self._fit_kwargs)
    self.fitted = True

    if self.output_type == 'pandas':
        self.training_index = y.index

predict

predict(
    steps, exog=None, return_conf_int=False, alpha=0.05
)

Forecast future values and, if desired, their confidence intervals.

Generate predictions (forecasts) n steps in the future with confidence intervals. Note that if exogenous variables were used in the model fit, they will be expected for the predict procedure and will fail otherwise.

Additional keyword arguments to pass to the get_forecast method of the statsmodels SARIMAX model can be added with the predict_kwargs argument when initializing the model.

Parameters:

Name	Type	Description	Default
steps	int	Number of steps to predict.	required
exog	numpy ndarray, pandas Series, pandas DataFrame	Value of the exogenous variable/s for the next steps. The number of observations needed is the number of steps to predict.	None
return_conf_int	bool	Whether to get the confidence intervals of the forecasts.	False
alpha	float	The confidence intervals for the forecasts are (1 - alpha) %.	0.05

Returns:

Name	Type	Description
predictions	numpy ndarray, pandas DataFrame	Values predicted by the forecaster and their estimated interval. The output type is the same as the type of y used in the fit method. pred: predictions. lower_bound: lower bound of the interval. (if return_conf_int) upper_bound: upper bound of the interval. (if return_conf_int)

Source code in skforecast\stats\_sarimax.py

@_check_fitted
def predict(
    self,
    steps: int,
    exog: np.ndarray | pd.Series | pd.DataFrame | None = None, 
    return_conf_int: bool = False,
    alpha: float = 0.05
) -> np.ndarray | pd.DataFrame:
    """
    Forecast future values and, if desired, their confidence intervals.

    Generate predictions (forecasts) n steps in the future with confidence
    intervals. Note that if exogenous variables were used in the model fit, 
    they will be expected for the predict procedure and will fail otherwise.

    Additional keyword arguments to pass to the `get_forecast` method of the
    statsmodels SARIMAX model can be added with the `predict_kwargs` argument 
    when initializing the model.

    Parameters
    ----------
    steps : int
        Number of steps to predict. 
    exog : numpy ndarray, pandas Series, pandas DataFrame, default None
        Value of the exogenous variable/s for the next steps. The number of 
        observations needed is the number of steps to predict. 
    return_conf_int : bool, default False
        Whether to get the confidence intervals of the forecasts.
    alpha : float, default 0.05
        The confidence intervals for the forecasts are (1 - alpha) %.

    Returns
    -------
    predictions : numpy ndarray, pandas DataFrame
        Values predicted by the forecaster and their estimated interval. The 
        output type is the same as the type of `y` used in the fit method.

        - pred: predictions.
        - lower_bound: lower bound of the interval. (if `return_conf_int`)
        - upper_bound: upper bound of the interval. (if `return_conf_int`)

    """

    # This is done because statsmodels doesn't allow `exog` length greater than
    # the number of steps
    if exog is not None and len(exog) > steps:
        warnings.warn(
            f"When predicting using exogenous variables, the `exog` parameter "
            f"must have the same length as the number of predicted steps. Since "
            f"len(exog) > steps, only the first {steps} observations are used."
        )
        exog = exog[:steps]

    predictions = self.sarimax_res.get_forecast(
                      steps = steps,
                      exog  = exog,
                      **self._predict_kwargs
                  )

    if not return_conf_int:
        predictions = predictions.predicted_mean
        if self.output_type == 'pandas':
            predictions = predictions.rename("pred").to_frame()
    else:
        if self.output_type == 'numpy':
            predictions = np.column_stack(
                              [predictions.predicted_mean,
                               predictions.conf_int(alpha=alpha)]
                          )
        else:
            predictions = pd.concat((
                              predictions.predicted_mean,
                              predictions.conf_int(alpha=alpha)),
                              axis = 1
                          )
            predictions.columns = ['pred', 'lower_bound', 'upper_bound']

    return predictions

append

append(
    y,
    exog=None,
    refit=False,
    copy_initialization=False,
    **kwargs
)

Recreate the results object with new data appended to the original data.

Creates a new result object applied to a dataset that is created by appending new data to the end of the model's original data [1]_. The new results can then be used for analysis or forecasting.

Parameters:

Name	Type	Description	Default
y	numpy ndarray, pandas Series, pandas DataFrame	New observations from the modeled time-series process.	required
exog	numpy ndarray, pandas Series, pandas DataFrame	New observations of exogenous estimators, if applicable. Must have the same number of observations as y and their indexes must be aligned so that y[i] is regressed on exog[i].	None
refit	bool	Whether to re-fit the parameters, based on the combined dataset.	False
copy_initialization	bool	Whether or not to copy the initialization from the current results set to the new model.	False
**kwargs		Keyword arguments may be used to modify model specification arguments when created the new model object.	{}

Returns:

Type	Description
None

Notes

The y and exog arguments to this method must be formatted in the same way (e.g. Pandas Series versus Numpy array) as were the y and exog arrays passed to the original model.

The y argument to this method should consist of new observations that occurred directly after the last element of y. For any other kind of dataset, see the apply method.

This method will apply filtering to all of the original data as well as to the new data. To apply filtering only to the new data (which can be much faster if the original dataset is large), see the extend method.

References

.. [1] Statsmodels MLEResults append API Reference. https://www.statsmodels.org/stable/generated/statsmodels.tsa.statespace.mlemodel.MLEResults.append.html#statsmodels.tsa.statespace.mlemodel.MLEResults.append

Source code in skforecast\stats\_sarimax.py

@_check_fitted
def append(
    self,
    y: np.ndarray | pd.Series | pd.DataFrame,
    exog: np.ndarray | pd.Series | pd.DataFrame | None = None,
    refit: bool = False,
    copy_initialization: bool = False,
    **kwargs
) -> None:
    """
    Recreate the results object with new data appended to the original data.

    Creates a new result object applied to a dataset that is created by 
    appending new data to the end of the model's original data [1]_. The new 
    results can then be used for analysis or forecasting.

    Parameters
    ----------
    y : numpy ndarray, pandas Series, pandas DataFrame
        New observations from the modeled time-series process.
    exog : numpy ndarray, pandas Series, pandas DataFrame, default None
        New observations of exogenous estimators, if applicable. Must have 
        the same number of observations as `y` and their indexes must be 
        aligned so that y[i] is regressed on exog[i].
    refit : bool, default False
        Whether to re-fit the parameters, based on the combined dataset.
    copy_initialization : bool, default False
        Whether or not to copy the initialization from the current results 
        set to the new model. 
    **kwargs
        Keyword arguments may be used to modify model specification arguments 
        when created the new model object.

    Returns
    -------
    None

    Notes
    -----
    The `y` and `exog` arguments to this method must be formatted in the same 
    way (e.g. Pandas Series versus Numpy array) as were the `y` and `exog` 
    arrays passed to the original model.

    The `y` argument to this method should consist of new observations that 
    occurred directly after the last element of `y`. For any other kind of 
    dataset, see the apply method.

    This method will apply filtering to all of the original data as well as 
    to the new data. To apply filtering only to the new data (which can be 
    much faster if the original dataset is large), see the extend method.

    References
    ----------
    .. [1] Statsmodels MLEResults append API Reference.
           https://www.statsmodels.org/stable/generated/statsmodels.tsa.statespace.mlemodel.MLEResults.append.html#statsmodels.tsa.statespace.mlemodel.MLEResults.append

    """

    fit_kwargs = self._fit_kwargs if refit else None

    self.sarimax_res = self.sarimax_res.append(
                           endog               = y,
                           exog                = exog,
                           refit               = refit,
                           copy_initialization = copy_initialization,
                           fit_kwargs          = fit_kwargs,
                           **kwargs
                       )

apply

apply(
    y,
    exog=None,
    refit=False,
    copy_initialization=False,
    **kwargs
)

Apply the fitted parameters to new data unrelated to the original data.

Creates a new result object using the current fitted parameters, applied to a completely new dataset that is assumed to be unrelated to the model's original data [1]_. The new results can then be used for analysis or forecasting.

Parameters:

Name	Type	Description	Default
y	numpy ndarray, pandas Series, pandas DataFrame	New observations from the modeled time-series process.	required
exog	numpy ndarray, pandas Series, pandas DataFrame	New observations of exogenous estimators, if applicable. Must have the same number of observations as y and their indexes must be aligned so that y[i] is regressed on exog[i].	None
refit	bool	Whether to re-fit the parameters, using the new dataset.	False
copy_initialization	bool	Whether or not to copy the initialization from the current results set to the new model.	False
**kwargs		Keyword arguments may be used to modify model specification arguments when created the new model object.	{}

Returns:

Type	Description
None

Notes

The y argument to this method should consist of new observations that are not necessarily related to the original model's y dataset. For observations that continue that original dataset by follow directly after its last element, see the append and extend methods.

References

.. [1] Statsmodels MLEResults apply API Reference. https://www.statsmodels.org/stable/generated/statsmodels.tsa.statespace.mlemodel.MLEResults.apply.html#statsmodels.tsa.statespace.mlemodel.MLEResults.apply

Source code in skforecast\stats\_sarimax.py

@_check_fitted
def apply(
    self,
    y: np.ndarray | pd.Series | pd.DataFrame,
    exog: np.ndarray | pd.Series | pd.DataFrame | None = None,
    refit: bool = False,
    copy_initialization: bool = False,
    **kwargs
) -> None:
    """
    Apply the fitted parameters to new data unrelated to the original data.

    Creates a new result object using the current fitted parameters, applied 
    to a completely new dataset that is assumed to be unrelated to the model's
    original data [1]_. The new results can then be used for analysis or forecasting.

    Parameters
    ----------
    y : numpy ndarray, pandas Series, pandas DataFrame
        New observations from the modeled time-series process.
    exog : numpy ndarray, pandas Series, pandas DataFrame, default None
        New observations of exogenous estimators, if applicable. Must have 
        the same number of observations as `y` and their indexes must be 
        aligned so that y[i] is regressed on exog[i].
    refit : bool, default False
        Whether to re-fit the parameters, using the new dataset.
    copy_initialization : bool, default False
        Whether or not to copy the initialization from the current results 
        set to the new model. 
    **kwargs
        Keyword arguments may be used to modify model specification arguments 
        when created the new model object.

    Returns
    -------
    None

    Notes
    -----
    The `y` argument to this method should consist of new observations that 
    are not necessarily related to the original model's `y` dataset. For 
    observations that continue that original dataset by follow directly after 
    its last element, see the append and extend methods.

    References
    ----------
    .. [1] Statsmodels MLEResults apply API Reference.
           https://www.statsmodels.org/stable/generated/statsmodels.tsa.statespace.mlemodel.MLEResults.apply.html#statsmodels.tsa.statespace.mlemodel.MLEResults.apply

    """

    fit_kwargs = self._fit_kwargs if refit else None

    self.sarimax_res = self.sarimax_res.apply(
                           endog               = y,
                           exog                = exog,
                           refit               = refit,
                           copy_initialization = copy_initialization,
                           fit_kwargs          = fit_kwargs,
                           **kwargs
                       )

extend

extend(y, exog=None, **kwargs)

Recreate the results object for new data that extends the original data.

Creates a new result object applied to a new dataset that is assumed to follow directly from the end of the model's original data [1]_. The new results can then be used for analysis or forecasting.

Parameters:

Name	Type	Description	Default
y	numpy ndarray, pandas Series, pandas DataFrame	New observations from the modeled time-series process.	required
exog	numpy ndarray, pandas Series, pandas DataFrame	New observations of exogenous estimators, if applicable. Must have the same number of observations as y and their indexes must be aligned so that y[i] is regressed on exog[i].	None
**kwargs		Keyword arguments may be used to modify model specification arguments when created the new model object.	{}

Returns:

Type	Description
None

Notes

The y argument to this method should consist of new observations that occurred directly after the last element of the model's original y array. For any other kind of dataset, see the apply method.

This method will apply filtering only to the new data provided by the y argument, which can be much faster than re-filtering the entire dataset. However, the returned results object will only have results for the new data. To retrieve results for both the new data and the original data, see the append method.

References

.. [1] Statsmodels MLEResults extend API Reference. https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.mlemodel.MLEResults.extend.html#statsmodels.tsa.statespace.mlemodel.MLEResults.extend

Source code in skforecast\stats\_sarimax.py

@_check_fitted
def extend(
    self,
    y: np.ndarray | pd.Series | pd.DataFrame,
    exog: np.ndarray | pd.Series | pd.DataFrame | None = None,
    **kwargs
) -> None:
    """
    Recreate the results object for new data that extends the original data.

    Creates a new result object applied to a new dataset that is assumed to 
    follow directly from the end of the model's original data [1]_. The new 
    results can then be used for analysis or forecasting.

    Parameters
    ----------
    y : numpy ndarray, pandas Series, pandas DataFrame
        New observations from the modeled time-series process.
    exog : numpy ndarray, pandas Series, pandas DataFrame, default None
        New observations of exogenous estimators, if applicable. Must have 
        the same number of observations as `y` and their indexes must be 
        aligned so that y[i] is regressed on exog[i].
    **kwargs
        Keyword arguments may be used to modify model specification arguments 
        when created the new model object.

    Returns
    -------
    None

    Notes
    -----
    The `y` argument to this method should consist of new observations that 
    occurred directly after the last element of the model's original `y` 
    array. For any other kind of dataset, see the apply method.

    This method will apply filtering only to the new data provided by the `y` 
    argument, which can be much faster than re-filtering the entire dataset. 
    However, the returned results object will only have results for the new 
    data. To retrieve results for both the new data and the original data, 
    see the append method.

    References
    ----------
    .. [1] Statsmodels MLEResults extend API Reference.
           https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.mlemodel.MLEResults.extend.html#statsmodels.tsa.statespace.mlemodel.MLEResults.extend

    """

    self.sarimax_res = self.sarimax_res.extend(
                           endog = y,
                           exog  = exog,
                           **kwargs
                       )

set_params

set_params(**params)

Set new values to the parameters of the estimator.

Parameters:

Name	Type	Description	Default
params	dict	Parameters values.	{}

Returns:

Type	Description
None

Source code in skforecast\stats\_sarimax.py

def set_params(
    self, 
    **params: dict[str, object]
) -> None:
    """
    Set new values to the parameters of the estimator.

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

    Returns
    -------
    None

    """

    params = {k: v for k, v in params.items() if k in self._sarimax_params}
    for key, value in params.items():
        setattr(self, key, value)

    self._consolidate_kwargs()

    # Reset values in case the model has already been fitted.
    self.output_type    = None
    self.sarimax_res    = None
    self.fitted         = False
    self.training_index = None

params

params()

Get the parameters of the model. The order of variables is the trend coefficients, the k_exog exogenous coefficients, the k_ar AR coefficients, and finally the k_ma MA coefficients.

Returns:

Name	Type	Description
params	numpy ndarray, pandas Series	The parameters of the model.

Source code in skforecast\stats\_sarimax.py

@_check_fitted
def params(
    self
) -> np.ndarray | pd.Series:
    """
    Get the parameters of the model. The order of variables is the trend
    coefficients, the `k_exog` exogenous coefficients, the `k_ar` AR 
    coefficients, and finally the `k_ma` MA coefficients.

    Returns
    -------
    params : numpy ndarray, pandas Series
        The parameters of the model.

    """

    return self.sarimax_res.params

summary

summary(alpha=0.05, start=None)

Get a summary of the SARIMAXResults object.

Parameters:

Name	Type	Description	Default
alpha	float	The confidence intervals for the forecasts are (1 - alpha) %.	0.05
start	int	Integer of the start observation.	None

Returns:

Name	Type	Description
summary	Summary instance	This holds the summary table and text, which can be printed or converted to various output formats.

Source code in skforecast\stats\_sarimax.py

@_check_fitted
def summary(
    self,
    alpha: float = 0.05,
    start: int = None
) -> object:
    """
    Get a summary of the SARIMAXResults object.

    Parameters
    ----------
    alpha : float, default 0.05
        The confidence intervals for the forecasts are (1 - alpha) %.
    start : int, default None
        Integer of the start observation.

    Returns
    -------
    summary : Summary instance
        This holds the summary table and text, which can be printed or 
        converted to various output formats.

    """

    return self.sarimax_res.summary(alpha=alpha, start=start)

get_info_criteria

get_info_criteria(criteria='aic', method='standard')

Get the selected information criteria.

Check https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.sarimax.SARIMAXResults.info_criteria.html to know more about statsmodels info_criteria method.

Parameters:

Name	Type	Description	Default
criteria	str	The information criteria to compute. Valid options are {'aic', 'bic', 'hqic'}.	'aic'
method	str	The method for information criteria computation. Default is 'standard' method; 'lutkepohl' computes the information criteria as in Lütkepohl (2007).	'standard'

Returns:

Name	Type	Description
metric	float	The value of the selected information criteria.

Source code in skforecast\stats\_sarimax.py

@_check_fitted
def get_info_criteria(
    self,
    criteria: str = 'aic',
    method: str = 'standard'
) -> float:
    """
    Get the selected information criteria.

    Check https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.sarimax.SARIMAXResults.info_criteria.html
    to know more about statsmodels info_criteria method.

    Parameters
    ----------
    criteria : str, default 'aic'
        The information criteria to compute. Valid options are {'aic', 'bic',
        'hqic'}.
    method : str, default 'standard'
        The method for information criteria computation. Default is 'standard'
        method; 'lutkepohl' computes the information criteria as in Lütkepohl
        (2007).

    Returns
    -------
    metric : float
        The value of the selected information criteria.

    """

    if criteria not in ['aic', 'bic', 'hqic']:
        raise ValueError(
            "Invalid value for `criteria`. Valid options are 'aic', 'bic', "
            "and 'hqic'."
        )

    if method not in ['standard', 'lutkepohl']:
        raise ValueError(
            "Invalid value for `method`. Valid options are 'standard' and "
            "'lutkepohl'."
        )

    metric = self.sarimax_res.info_criteria(criteria=criteria, method=method)

    return metric

skforecast.stats._arar.Arar

Arar(max_ar_depth=None, max_lag=None, safe=True)

Bases: BaseEstimator, RegressorMixin

Scikit-learn style wrapper for the ARAR time-series model.

This estimator treats a univariate sequence as "the feature". Call fit(y) with a 1D array-like of observations in time order, then produce out-of-sample forecasts via predict(steps) and prediction intervals via predict_interval(steps, level=...). In-sample diagnostics are available through fitted_, residuals_() and summary().

Parameters:

Name	Type	Description	Default
max_ar_depth	int	Maximum AR depth considered for the (1, i, j, k) AR selection stage.	None
max_lag	int	Maximum lag used when estimating autocovariances.	None
safe	bool	If True, falls back to a mean-only model on numerical issues or very short series; otherwise errors are raised.	True

Attributes:

Name	Type	Description
max_ar_depth	(int,)	Maximum AR depth considered for the (1, i, j, k) AR selection stage.
max_lag	int	Maximum lag used when estimating autocovariances.
safe	bool	If True, falls back to a mean-only model on numerical issues or very short series; otherwise errors are raised.
model_	tuple	Raw tuple returned by arar(...): (Y, best_phi, best_lag, sigma2, psi, sbar).
y_	ndarray of shape (n_samples,)	Original training series (float).
coef_	ndarray of shape (4,)	Selected AR coefficients for lags (1, i, j, k).
lags_	tuple	Selected lags (1, i, j, k).
sigma2_	float	Innovation variance.
psi_	ndarray	Memory-shortening filter.
sbar_	float	Mean of shortened series.
n_features_in_	int	For sklearn compatibility (always 1).
fitted_values_	ndarray of shape (n_samples,)	In-sample fitted values (NaN for first k-1 terms).
residuals_in_	ndarray of shape (n_samples,)	In-sample residuals (observed - fitted).

Methods:

Name	Description
fit	Fit the ARAR model to a univariate time series.
predict	Generate mean forecasts steps ahead.
predict_interval	Forecast with symmetric normal-theory prediction intervals.
residuals_	In-sample residuals (observed - fitted).
fitted_	In-sample fitted values.
summary	Print a simple textual summary of the fitted ARAR model.
score	R^2 using in-sample fitted values (ignores initial NaNs).

Source code in skforecast\stats\_arar.py

def __init__(self, max_ar_depth: int | None = None, max_lag: int | None = None, safe: bool = True):
    self.max_ar_depth = max_ar_depth
    self.max_lag = max_lag
    self.safe = safe

max_ar_depth instance-attribute

max_ar_depth = max_ar_depth

max_lag instance-attribute

max_lag = max_lag

safe instance-attribute

safe = safe

fit

fit(y, exog=None)

Fit the ARAR model to a univariate time series.

Parameters:

Name	Type	Description	Default
y	array-like of shape (n_samples,)	Time-ordered numeric sequence.	required
exog	None	Exogenous variables. Ignored, present for API compatibility.	None

Returns:

Name	Type	Description
self	Arar	Fitted estimator.

Source code in skforecast\stats\_arar.py

def fit(self, y: pd.Series | np.ndarray, exog: None = None) -> "Arar":
    """
    Fit the ARAR model to a univariate time series.

    Parameters
    ----------
    y : array-like of shape (n_samples,)
        Time-ordered numeric sequence.
    exog : None
        Exogenous variables. Ignored, present for API compatibility.

    Returns
    -------
    self : Arar
        Fitted estimator.
    """
    y = np.asarray(y, dtype=float).ravel()
    if y.ndim != 1:
        raise ValueError("`y` must be a 1D array-like sequence.")
    if y.size < 2 and not self.safe:
        raise ValueError("Series too short to fit ARAR when safe=False.")

    self.model_ = arar(y, max_ar_depth=self.max_ar_depth, max_lag=self.max_lag, safe=self.safe)

    (Y, best_phi, best_lag, sigma2, psi, sbar, max_ar_depth, max_lag) = self.model_

    self.y_ = np.asarray(Y, dtype=float)
    self.coef_ = np.asarray(best_phi, dtype=float)
    self.lags_ = tuple(best_lag)
    self.sigma2_ = float(sigma2)
    self.psi_ = np.asarray(psi, dtype=float)
    self.sbar_ = float(sbar)
    self.max_ar_depth = max_ar_depth
    self.max_lag = max_lag
    self.n_features_in_ = 1

    self.fitted_values_ = fitted_arar(self.model_)["fitted"]
    self.residuals_in_ = residuals_arar(self.model_)

    return self

predict

predict(steps, exog=None)

Generate mean forecasts steps ahead.

Parameters:

Name	Type	Description	Default
steps	int	Forecast horizon (must be > 0)	required
exog	None	Exogenous variables. Ignored, present for API compatibility.	None

Returns:

Name	Type	Description
mean	ndarray of shape (h,)	Point forecasts for steps 1..h.

Source code in skforecast\stats\_arar.py

def predict(self, steps: int, exog: None = None) -> np.ndarray:
    """
    Generate mean forecasts steps ahead.

    Parameters
    ----------
    steps : int
        Forecast horizon (must be > 0)
    exog : None
        Exogenous variables. Ignored, present for API compatibility.

    Returns
    -------
    mean : ndarray of shape (h,)
        Point forecasts for steps 1..h.
    """
    check_is_fitted(self, "model_")
    if not isinstance(steps, (int, np.integer)) or steps <= 0:
        raise ValueError("`steps` must be a positive integer.")
    return forecast(self.model_, h=steps)["mean"]

predict_interval

predict_interval(
    steps=1, level=(80, 95), as_frame=True, exog=None
)

Forecast with symmetric normal-theory prediction intervals.

Parameters:

Name	Type	Description	Default
steps	int	Forecast horizon.	1
level	iterable of int	Confidence levels in percent.	(80, 95)
as_frame	bool	If True, return a tidy DataFrame with columns: 'mean', 'lower_', 'upper_' for each level L.	True
exog	None	Exogenous variables. Ignored, present for API compatibility.	None

Returns:

Type	Description
DataFrame or dict	If as_frame=True: DataFrame indexed by step (1..h). Else: the raw dict from predict_arar.

Source code in skforecast\stats\_arar.py

def predict_interval(
    self,
    steps: int = 1,
    level=(80, 95),
    as_frame: bool = True,
    exog: None = None
) -> pd.DataFrame | dict:
    """
    Forecast with symmetric normal-theory prediction intervals.

    Parameters
    ----------
    steps : int, default=1
        Forecast horizon.
    level : iterable of int, default=(80, 95)
        Confidence levels in percent.
    as_frame : bool, default=True
        If True, return a tidy DataFrame with columns:
        'mean', 'lower_<L>', 'upper_<L>' for each level L.
    exog : None
        Exogenous variables. Ignored, present for API compatibility.

    Returns
    -------
    DataFrame or dict
        If as_frame=True: DataFrame indexed by step (1..h).
        Else: the raw dict from `predict_arar`.
    """
    check_is_fitted(self, "model_")
    out = forecast(self.model_, h=steps, level=level)
    if not as_frame:
        return out

    idx = pd.RangeIndex(1, steps + 1, name="step")
    df = pd.DataFrame({"mean": out["mean"]}, index=idx)
    for i, L in enumerate(out["level"]):
        df[f"lower_{L}"] = out["lower"][:, i]
        df[f"upper_{L}"] = out["upper"][:, i]
    return df

residuals_

residuals_()

In-sample residuals (observed - fitted).

Returns:

Name	Type	Description
residuals	ndarray of shape (n_samples,)

Source code in skforecast\stats\_arar.py

def residuals_(self) -> np.ndarray:
    """
    In-sample residuals (observed - fitted).

    Returns
    -------
    residuals : ndarray of shape (n_samples,)
    """
    check_is_fitted(self, "model_")
    return self.residuals_in_

fitted_

fitted_()

In-sample fitted values.

Returns:

Name	Type	Description
fitted	ndarray of shape (n_samples,)

Source code in skforecast\stats\_arar.py

def fitted_(self) -> np.ndarray:
    """
    In-sample fitted values.

    Returns
    -------
    fitted : ndarray of shape (n_samples,)
    """
    check_is_fitted(self, "model_")
    return self.fitted_values_

summary

summary()

Print a simple textual summary of the fitted ARAR model.

Source code in skforecast\stats\_arar.py

def summary(self) -> None:
    """
    Print a simple textual summary of the fitted ARAR model.
    """
    check_is_fitted(self, "model_")
    return summary_arar(self.model_)

score

score(y=None)

R^2 using in-sample fitted values (ignores initial NaNs).

Parameters:

Name	Type	Description	Default
y	ignored	Present for API compatibility.	None

Returns:

Name	Type	Description
score	float	Coefficient of determination.

Source code in skforecast\stats\_arar.py

def score(self, y=None) -> float:
    """
    R^2 using in-sample fitted values (ignores initial NaNs).

    Parameters
    ----------
    y : ignored
        Present for API compatibility.

    Returns
    -------
    score : float
        Coefficient of determination.
    """
    check_is_fitted(self, "model_")
    y = self.y_
    fitted = self.fitted_values_
    mask = ~np.isnan(fitted)
    if mask.sum() < 2:
        return float("nan")
    ss_res = np.sum((y[mask] - fitted[mask]) ** 2)
    ss_tot = np.sum((y[mask] - y[mask].mean()) ** 2) + np.finfo(float).eps
    return 1.0 - ss_res / ss_tot