StatsForecast 的核心方法包括：

来源

​
StatsForecast

 StatsForecast (models:List[Any], freq:Union[str,int], n_jobs:int=1,
                fallback_model:Optional[Any]=None, verbose:bool=False)

*StatsForecast 类允许您高效地为大量时间序列拟合多个 StatsForecast 模型。它对至少包含 ids、times 和 targets 三列的 DataFrame df 进行操作。

该类具有内存高效的 StatsForecast.forecast 方法，可避免存储部分模型输出。而具有 Scikit-learn 接口的 StatsForecast.fit 和 StatsForecast.predict 方法则存储拟合好的模型。

StatsForecast 类提供了使用 Dask、Spark 和 Ray 后端的并行化工具。请参阅此处的分布式计算示例。*

# StatsForecast's class usage example

#from statsforecast.core import StatsForecast
from statsforecast.models import ( 
    ADIDA,
    AutoARIMA,
    CrostonClassic,
    CrostonOptimized,
    CrostonSBA,
    HistoricAverage,
    IMAPA,
    Naive,
    RandomWalkWithDrift,
    SeasonalExponentialSmoothing,
    SeasonalNaive,
    SeasonalWindowAverage,
    SimpleExponentialSmoothing,
    TSB,
    WindowAverage,
    DynamicOptimizedTheta,
    AutoETS,
    AutoCES
)

# Generate synthetic panel DataFrame for example
panel_df = generate_series(n_series=9, equal_ends=False, engine='pandas')
panel_df.groupby('unique_id').tail(4)

# Declare list of instantiated StatsForecast estimators to be fitted
# You can try other estimator's hyperparameters
# You can try other methods from the `models.StatsForecast` collection
# Check them here: https://nixtla.github.io/statsforecast/models.html
models=[AutoARIMA(), Naive(), 
        AutoETS(), AutoARIMA(allowmean=True, alias='MeanAutoARIMA')] 

# Instantiate StatsForecast class
fcst = StatsForecast(models=models,
                     freq='D',
                     n_jobs=1,
                     verbose=True)

# Efficiently predict
fcsts_df = fcst.forecast(df=panel_df, h=4, fitted=True)
fcsts_df.groupby('unique_id').tail(4)
来源

​
StatsForecast.fit

 StatsForecast.fit
                    (df:Union[pandas.core.frame.DataFrame,polars.dataframe
                    .frame.DataFrame], prediction_intervals:Optional[stats
                    forecast.utils.ConformalIntervals]=None,
                    id_col:str='unique_id', time_col:str='ds',
                    target_col:str='y')

*拟合统计模型。

将 models 拟合到 DataFrame df 中的大量时间序列，并存储拟合好的模型以便后续检查。*

类型默认值详情
dfUnion包含 ids、times、targets 和 exogenous 的 DataFrame。
prediction_intervalsOptionalNone用于校准预测区间的配置 (保形预测)。
id_colstrunique_id标识每个序列的列。
time_colstrds标识每个时间步长的列，其值可以是时间戳或整数。
target_colstry包含目标的列。
返回StatsForecast返回带有存储的 StatsForecast 拟合 models。
来源

​
StatsForecast.predict

 SatstForecast.predict (h:int, X_df:Union[pandas.core.frame.DataFrame,pola
                        rs.dataframe.frame.DataFrame,NoneType]=None,
                        level:Optional[List[int]]=None)

*预测统计模型。

使用存储的拟合 models 从 DataFrame df 预测大量时间序列。*

类型默认值详情
hint预测范围。
X_dfUnionNone包含 ids、times 和未来外部因子的 DataFrame。
levelOptionalNone用于预测区间的置信水平，介于 0 到 100 之间。
返回pandas 或 polars DataFrameDataFrame，包含用于点预测和概率预测的 models 列
所有拟合 models 的预测。
来源

​
StatsForecast.fit_predict

 StatsForecast.fit_predict (h:int,
                            df:Union[pandas.core.frame.DataFrame,polars.da
                            taframe.frame.DataFrame], X_df:Union[pandas.co
                            re.frame.DataFrame,polars.dataframe.frame.Data
                            Frame,NoneType]=None,
                            level:Optional[List[int]]=None, prediction_int
                            ervals:Optional[statsforecast.utils.ConformalI
                            ntervals]=None, id_col:str='unique_id',
                            time_col:str='ds', target_col:str='y')

*使用统计模型进行拟合和预测。

此方法避免了对象存储带来的内存负担。它类似于 Scikit-Learn 的 fit_predict 方法，但不存储信息。它需要提前知道预测范围 h。

与 StatsForecast.forecast 不同，此方法存储部分模型输出。*

类型默认值详情
hint预测范围。
dfUnion包含 ids、times、targets 和 exogenous 的 DataFrame。
X_dfUnionNone包含 ids、times 和未来外部因子的 DataFrame。
levelOptionalNone用于预测区间的置信水平，介于 0 到 100 之间。
prediction_intervalsOptionalNone用于校准预测区间的配置 (保形预测)。
id_colstrunique_id标识每个序列的列。
time_colstrds标识每个时间步长的列，其值可以是时间戳或整数。
target_colstry包含目标的列。
返回UnionDataFrame，包含用于点预测和概率预测的 models 列
所有拟合 models 的预测。
来源

​
StatsForecast.forecast

 StatsForecast.forecast (h:int,
                         df:Union[pandas.core.frame.DataFrame,polars.dataf
                         rame.frame.DataFrame], X_df:Union[pandas.core.fra
                         me.DataFrame,polars.dataframe.frame.DataFrame,Non
                         eType]=None, level:Optional[List[int]]=None,
                         fitted:bool=False, prediction_intervals:Optional[
                         statsforecast.utils.ConformalIntervals]=None,
                         id_col:str='unique_id', time_col:str='ds',
                         target_col:str='y')

*内存高效的预测。

此方法避免了对象存储带来的内存负担。它类似于 Scikit-Learn 的 fit_predict 方法，但不存储信息。它需要提前知道预测范围 h。*

类型默认值详情
hint预测范围。
dfUnion包含 ids、times、targets 和 exogenous 的 DataFrame。
X_dfUnionNone包含 ids、times 和未来外部因子的 DataFrame。
levelOptionalNone用于预测区间的置信水平，介于 0 到 100 之间。
fittedboolFalse存储样本内预测。
prediction_intervalsOptionalNone用于校准预测区间的配置 (保形预测)。
id_colstrunique_id标识每个序列的列。
time_colstrds标识每个时间步长的列，其值可以是时间戳或整数。
target_colstry包含目标的列。
返回UnionDataFrame，包含用于点预测和概率预测的 models 列
所有拟合 models 的预测。
# StatsForecast.forecast method usage example

#from statsforecast.core import StatsForecast
from statsforecast.utils import AirPassengersDF as panel_df
from statsforecast.models import AutoARIMA, Naive

# Instantiate StatsForecast class
fcst = StatsForecast(models=[AutoARIMA(), Naive()],
                     freq='D', n_jobs=1)

# Efficiently predict without storing memory
fcsts_df = fcst.forecast(df=panel_df, h=4, fitted=True)
fcsts_df.groupby('unique_id').tail(4)
来源

​
StatsForecast.forecast_fitted_values

 StatsForecast.forecast_fitted_values ()

*访问样本内预测。

执行 StatsForecast.forecast 后，您可以访问每个模型的样本内预测值。要获取它们，您需要将 fitted=True 传递给 StatsForecast.forecast 方法，然后使用 StatsForecast.forecast_fitted_values 方法。*

# StatsForecast.forecast_fitted_values method usage example

#from statsforecast.core import StatsForecast
from statsforecast.utils import AirPassengersDF as panel_df
from statsforecast.models import Naive

# Instantiate StatsForecast class
fcst = StatsForecast(models=[AutoARIMA()], freq='D', n_jobs=1)

# Access insample predictions
fcsts_df = fcst.forecast(df=panel_df, h=12, fitted=True, level=(90, 10))
insample_fcsts_df = fcst.forecast_fitted_values()
insample_fcsts_df.tail(4)
来源

​
StatsForecast.cross_validation

 StatsForecast.cross_validation (h:int,
                                 df:Union[pandas.core.frame.DataFrame,pola
                                 rs.dataframe.frame.DataFrame],
                                 n_windows:int=1, step_size:int=1,
                                 test_size:Optional[int]=None,
                                 input_size:Optional[int]=None,
                                 level:Optional[List[int]]=None,
                                 fitted:bool=False,
                                 refit:Union[bool,int]=True, prediction_in
                                 tervals:Optional[statsforecast.utils.Conf
                                 ormalIntervals]=None,
                                 id_col:str='unique_id',
                                 time_col:str='ds', target_col:str='y')

*时间序列交叉验证。

通过多个训练窗口（链式或滚动方式）高效地拟合一系列 StatsForecast 模型。

StatsForecast.models 的速度有助于克服这种评估技术的高计算成本。时间序列交叉验证通过增加测试集的长度和多样性，提供了更好的模型泛化能力衡量标准。*

类型默认值详情
hint预测范围。
dfUnion包含 ids、times、targets 和 exogenous 的 DataFrame。
n_windowsint1用于交叉验证的窗口数量。
step_sizeint1每个窗口之间的步长。
test_sizeOptionalNone测试集长度。如果传递，将 n_windows 设置为 None。
input_sizeOptionalNone每个窗口的输入大小，如果不是 None，则为滚动窗口。
levelOptionalNone用于预测区间的置信水平，介于 0 到 100 之间。
fittedboolFalse存储样本内预测。
refitUnionTrue是否为每个窗口重新拟合模型。
如果为整数，则每 refit 个窗口训练模型。
prediction_intervalsOptionalNone用于校准预测区间的配置 (保形预测)。
id_colstrunique_id标识每个序列的列。
time_colstrds标识每个时间步长的列，其值可以是时间戳或整数。
target_colstry包含目标的列。
返回UnionDataFrame，包含用于点预测和概率预测的样本内 models 列
所有拟合 models 的预测。
# StatsForecast.crossvalidation method usage example

#from statsforecast.core import StatsForecast
from statsforecast.utils import AirPassengersDF as panel_df
from statsforecast.models import Naive

# Instantiate StatsForecast class
fcst = StatsForecast(models=[Naive()],
                     freq='D', n_jobs=1, verbose=True)

# Access insample predictions
rolled_fcsts_df = fcst.cross_validation(df=panel_df, h=14, n_windows=2)
rolled_fcsts_df.head(4)
来源

​
StatsForecast.cross_validation_fitted_values

 StatsForecast.cross_validation_fitted_values ()

*访问样本内交叉验证预测。

执行 StatsForecast.cross_validation 后，您可以访问每个模型和窗口的样本内预测值。要获取它们，您需要将 fitted=True 传递给 StatsForecast.cross_validation 方法，然后使用 StatsForecast.cross_validation_fitted_values 方法。*

# StatsForecast.cross_validation_fitted_values method usage example

#from statsforecast.core import StatsForecast
from statsforecast.utils import AirPassengersDF as panel_df
from statsforecast.models import Naive

# Instantiate StatsForecast class
fcst = StatsForecast(models=[Naive()],
                     freq='D', n_jobs=1)

# Access insample predictions
rolled_fcsts_df = fcst.cross_validation(df=panel_df, h=12, n_windows=2, fitted=True)
insample_rolled_fcsts_df = fcst.cross_validation_fitted_values()
insample_rolled_fcsts_df.tail(4)
来源

​
StatsForecast.plot

 StatsForecast.plot
                     (df:Union[pandas.core.frame.DataFrame,polars.datafram
                     e.frame.DataFrame], forecasts_df:Union[pandas.core.fr
                     ame.DataFrame,polars.dataframe.frame.DataFrame,NoneTy
                     pe]=None, unique_ids:Union[List[str],NoneType,numpy.n
                     darray]=None, plot_random:bool=True,
                     models:Optional[List[str]]=None,
                     level:Optional[List[float]]=None,
                     max_insample_length:Optional[int]=None,
                     plot_anomalies:bool=False, engine:str='matplotlib',
                     id_col:str='unique_id', time_col:str='ds',
                     target_col:str='y',
                     resampler_kwargs:Optional[Dict]=None)

绘制预测和样本内值。

类型默认值详情
dfUnion包含 ids、times、targets 和 exogenous 的 DataFrame。
forecasts_dfUnionNone包含 ids、times 和 models 的 DataFrame。
unique_idsUnionNone要绘制的 ids。如果为 None，则随机选择。
plot_randomboolTrue随机选择要绘制的时间序列。
modelsOptionalNone要绘制的模型列表。
levelOptionalNone如果传递，则绘制的预测区间列表。
max_insample_lengthOptionalNone要绘制的最大训练/样本内观测数量。
plot_anomaliesboolFalse为每个预测区间绘制异常点。
enginestrmatplotlib用于绘图的库。'plotly'、'plotly-resampler' 或 'matplotlib'。
id_colstrunique_id标识每个序列的列。
time_colstrds标识每个时间步长的列，其值可以是时间戳或整数。
target_colstry包含目标的列。
resampler_kwargsOptionalNone要传递给 plotly-resampler 构造函数的 Kwargs。
如需进一步自定义 (“show_dash”)，请调用方法，
存储绘图对象并向其添加额外参数
show_dash 方法。
来源

​
StatsForecast.save

 StatsForecast.save (path:Union[pathlib.Path,str,NoneType]=None,
                     max_size:Optional[str]=None, trim:bool=False)

该函数将保存带有特定设置的 StatsForecast 类，以使其可重现。

类型默认值详情
pathUnionNone要保存的文件路径。如果为 None，将在当前
目录中使用当前的 UTC 时间戳创建文件。
max_sizeOptionalNoneStatsForecast 对象不应超过此大小。
可用字节命名：[‘B’, ‘KB’, ‘MB’, ‘GB’]
trimboolFalse删除任何推理不需要的属性。
来源

​
StatsForecast.load

 StatsForecast.load (path:Union[pathlib.Path,str])

自动将模型加载到就绪的 StatsForecast 中。

类型详情
pathUnion保存的 StatsForecast 文件路径。
返回sf: StatsForecast之前保存的 StatsForecast
fcst = StatsForecast(
    models=[ADIDA(), SimpleExponentialSmoothing(0.1), 
            HistoricAverage(), CrostonClassic()],
    freq='D',
    n_jobs=1
)
res = fcst.forecast(df=series, h=14)

​
其他

​
整数日期戳

StatsForecast 类也可以接收整数作为日期戳，以下示例展示了如何操作。

# from statsforecast.core import StatsForecast
from statsforecast.utils import AirPassengers as ap
from statsforecast.models import HistoricAverage

int_ds_df = pd.DataFrame({'ds': np.arange(1, len(ap) + 1), 'y': ap})
int_ds_df.insert(0, 'unique_id', 'AirPassengers')
int_ds_df.head()

int_ds_df.tail()

int_ds_df

fcst = StatsForecast(models=[HistoricAverage()], freq=1)
horizon = 7
forecast = fcst.forecast(df=int_ds_df, h=horizon)
forecast.head()

last_date = int_ds_df['ds'].max()
test_eq(forecast['ds'].values, np.arange(last_date + 1, last_date + 1 + horizon))

int_ds_cv = fcst.cross_validation(df=int_ds_df, h=7, test_size=8, n_windows=None)
int_ds_cv

​
外部回归因子

y 之后的每一列都被视为外部回归因子，并将传递给允许使用它们的模型。如果您使用它们，则必须向 StatsForecast.forecast 方法提供未来的值。

class LinearRegression(_TS):
    
    def __init__(self):
        pass
    
    def fit(self, y, X):
        self.coefs_, *_ = np.linalg.lstsq(X, y, rcond=None)
        return self
    
    def predict(self, h, X):
        mean = X @ coefs
        return mean
    
    def __repr__(self):
        return 'LinearRegression()'
    
    def forecast(self, y, h, X=None, X_future=None, fitted=False):
        coefs, *_ = np.linalg.lstsq(X, y, rcond=None)
        return {'mean': X_future @ coefs}
    
    def new(self):
        b = type(self).__new__(type(self))
        b.__dict__.update(self.__dict__)
        return b

series_xreg = series = generate_series(10_000, equal_ends=True)
series_xreg['intercept'] = 1
series_xreg['dayofweek'] = series_xreg['ds'].dt.dayofweek
series_xreg = pd.get_dummies(series_xreg, columns=['dayofweek'], drop_first=True)
series_xreg

dates = sorted(series_xreg['ds'].unique())
valid_start = dates[-14]
train_mask = series_xreg['ds'] < valid_start
series_train = series_xreg[train_mask]
series_valid = series_xreg[~train_mask]
X_valid = series_valid.drop(columns=['y'])
fcst = StatsForecast(
    models=[LinearRegression()],
    freq='D',
)
xreg_res = fcst.forecast(df=series_train, h=14, X_df=X_valid)
xreg_res['y'] = series_valid['y'].values

xreg_res.drop(columns='unique_id').groupby('ds').mean().plot()

xreg_res_cv = fcst.cross_validation(df=series_train, h=3, test_size=5, n_windows=None)

​
预测区间

您可以将参数 level 传递给 StatsForecast.forecast 方法来计算预测区间。目前并非所有模型都能计算它们，因此我们只获取已实现该功能的模型的区间。

ap_df = pd.DataFrame({'ds': np.arange(ap.size), 'y': ap})
ap_df['unique_id'] = 0
sf = StatsForecast(
    models=[
        SeasonalNaive(season_length=12), 
        AutoARIMA(season_length=12)
    ],
    freq=1,
    n_jobs=1
)
ap_ci = sf.forecast(df=ap_df, h=12, level=(80, 95))
fcst.plot(ap_df, ap_ci, level=[80], engine="matplotlib")

​
保形预测区间

您也可以使用以下代码添加保形区间。

from statsforecast.utils import ConformalIntervals

sf = StatsForecast(
    models=[
        AutoARIMA(season_length=12),
        AutoARIMA(
            season_length=12, 
            prediction_intervals=ConformalIntervals(n_windows=2, h=12),
            alias='ConformalAutoARIMA'
        ),
    ],
    freq=1,
    n_jobs=1
)
ap_ci = sf.forecast(df=ap_df, h=12, level=(80, 95))
fcst.plot(ap_df, ap_ci, level=[80], engine="plotly")

您也可以使用以下代码计算所有支持保形区间的模型的保形区间，

sf = StatsForecast(
    models=[
        AutoARIMA(season_length=12),
    ],
    freq=1,
    n_jobs=1
)
ap_ci = sf.forecast(
    df=ap_df, 
    h=12, 
    level=(50, 80, 95), 
    prediction_intervals=ConformalIntervals(h=12),
)
fcst.plot(ap_df, ap_ci, level=[80], engine="matplotlib")