0
# Time Series Forecasting
1

2
Probabilistic forecasting for univariate and multivariate time series data. TimeSeriesPredictor automatically handles both statistical models (ARIMA, ETS) and deep learning models (DeepAR, Transformers) with automatic model selection, hyperparameter tuning, and quantile prediction capabilities.
3

4
## Capabilities
5

6
### TimeSeriesPredictor Class
7

8
Main predictor class for time series forecasting that provides probabilistic multi-step-ahead forecasts with automatic model selection and tuning.
9

10
```python { .api }
11
class TimeSeriesPredictor:
12
    def __init__(
13
        self,
14
        target: str = "target",
15
        known_covariates_names: list = None,
16
        prediction_length: int = 1,
17
        freq: str = None,
18
        eval_metric: str = None,
19
        eval_metric_seasonal_period: int = None,
20
        horizon_weight: list = None,
21
        path: str = None,
22
        verbosity: int = 2,
23
        log_to_file: bool = True,
24
        log_file_path: str = "auto",
25
        quantile_levels: list = None,
26
        cache_predictions: bool = True,
27
        label: str = None,
28
        **kwargs
29
    ):
30
        """
31
        Initialize TimeSeriesPredictor for automated time series forecasting.
32
        
33
        Parameters:
34
        - target: Name of target column containing time series values
35
        - known_covariates_names: Names of covariates known at prediction time
36
        - prediction_length: Forecast horizon (number of time steps)
37
        - freq: Frequency of time series ('D', 'H', 'M', etc.)
38
        - eval_metric: Evaluation metric ('WQL', 'SQL', 'MAE', 'MAPE', 'MASE', 'MSE', 'RMSE', etc.)
39
        - eval_metric_seasonal_period: Seasonal period for scaled metrics
40
        - horizon_weight: Weights for each time step in forecast horizon
41
        - path: Directory to save models and artifacts
42
        - verbosity: Logging verbosity level (0-4)
43
        - log_to_file: Save logs to file
44
        - log_file_path: Path for log file
45
        - quantile_levels: List of quantile levels for probabilistic forecasts
46
        - cache_predictions: Cache predictions for efficiency
47
        - label: Alias for target parameter
48
        """
49
```
50

51
### TimeSeriesDataFrame Class
52

53
Specialized data structure for time series data that extends pandas DataFrame with time series specific functionality.
54

55
```python { .api }
56
class TimeSeriesDataFrame:
57
    def __init__(self, data, id_column: str = None, timestamp_column: str = None):
58
        """
59
        Initialize time series data structure.
60
        
61
        Parameters:
62
        - data: Input DataFrame with time series data
63
        - id_column: Name of column identifying different time series
64
        - timestamp_column: Name of column containing timestamps
65
        """
66
    
67
    @classmethod
68
    def from_data_frame(
69
        cls,
70
        df,
71
        id_column: str = "item_id",
72
        timestamp_column: str = "timestamp"
73
    ):
74
        """
75
        Create TimeSeriesDataFrame from pandas DataFrame.
76
        
77
        Parameters:
78
        - df: Input pandas DataFrame
79
        - id_column: Column identifying different time series
80
        - timestamp_column: Column containing timestamps
81
        
82
        Returns:
83
        TimeSeriesDataFrame: Time series data structure
84
        """
85
```
86

87
### Model Training
88

89
Train forecasting models on time series data with automatic preprocessing and model selection.
90

91
```python { .api }
92
def fit(
93
    self,
94
    train_data,
95
    presets: str = None,
96
    time_limit: int = None,
97
    num_cpus: int = None,
98
    num_gpus: int = None,
99
    num_val_windows: int = None,
100
    hyperparameters: dict = None,
101
    excluded_model_types: list = None,
102
    included_model_types: list = None,
103
    enable_ensemble: bool = None,
104
    random_seed: int = 0,
105
    verbosity: int = None,
106
    **kwargs
107
):
108
    """
109
    Fit TimeSeriesPredictor on time series training data.
110
    
111
    Parameters:
112
    - train_data: Training data (TimeSeriesDataFrame or compatible DataFrame)
113
    - presets: Quality/speed presets ('best_quality', 'high_quality', 'medium_quality', 'fast_training')
114
    - time_limit: Maximum training time in seconds
115
    - num_cpus: Number of CPU cores to use
116
    - num_gpus: Number of GPUs to use  
117
    - num_val_windows: Number of validation windows for model selection
118
    - hyperparameters: Custom hyperparameter configurations
119
    - excluded_model_types: List of model types to exclude
120
    - included_model_types: List of model types to include only
121
    - enable_ensemble: Enable model ensembling
122
    - random_seed: Random seed for reproducibility
123
    - verbosity: Logging verbosity level
124
    
125
    Returns:
126
    TimeSeriesPredictor: Fitted predictor instance
127
    """
128
```
129

130
### Forecasting
131

132
Generate probabilistic forecasts with quantile predictions and confidence intervals.
133

134
```python { .api }
135
def predict(
136
    self,
137
    data,
138
    known_covariates = None,
139
    model: str = None,
140
    use_cache: bool = True,
141
    **kwargs
142
):
143
    """
144
    Generate probabilistic forecasts for time series data.
145
    
146
    Parameters:
147
    - data: Historical time series data (TimeSeriesDataFrame)
148
    - known_covariates: Future values of known covariates
149
    - model: Specific model name for prediction
150
    - use_cache: Use cached predictions if available
151
    
152
    Returns:
153
    TimeSeriesDataFrame: Forecasts with quantile predictions
154
    """
155
```
156

157
### Model Evaluation
158

159
Evaluate forecasting performance with time series specific metrics and validation procedures.
160

161
```python { .api }
162
def evaluate(
163
    self,
164
    data,
165
    metrics: list = None,
166
    model: str = None,
167
    display_model_names: bool = False,
168
    **kwargs
169
):
170
    """
171
    Evaluate predictor performance on time series data.
172
    
173
    Parameters:
174
    - data: Test time series data (TimeSeriesDataFrame)
175
    - metrics: List of evaluation metrics to compute
176
    - model: Specific model to evaluate
177
    - display_model_names: Show individual model names in output
178
    
179
    Returns:
180
    dict: Dictionary of evaluation metrics
181
    """
182

183
def leaderboard(
184
    self,
185
    data = None,
186
    model: str = None,
187
    display_model_names: bool = False,
188
    **kwargs
189
):
190
    """
191
    Display model leaderboard with forecasting performance rankings.
192
    
193
    Parameters:
194
    - data: Test data for evaluation (optional)
195
    - model: Specific model to include
196
    - display_model_names: Show detailed model names
197
    
198
    Returns:
199
    DataFrame: Model leaderboard with performance metrics
200
    """
201
```
202

203
### Model Analysis
204

205
Analyze model behavior and generate training summaries.
206

207
```python { .api }
208
def fit_summary(self, verbosity: int = 1, show_plot: bool = False):
209
    """
210
    Display summary of training process and model performance.
211
    
212
    Parameters:
213
    - verbosity: Detail level (0-4)
214
    - show_plot: Show training and validation plots
215
    
216
    Returns:
217
    dict: Training summary information
218
    """
219

220
def info(self) -> dict:
221
    """
222
    Get detailed information about the fitted predictor.
223
    
224
    Returns:
225
    dict: Predictor information including models, metrics, and configuration
226
    """
227
```
228

229
### Model Persistence
230

231
Save and load trained forecasting models.
232

233
```python { .api }
234
def save(self, path: str = None):
235
    """
236
    Save trained predictor to disk.
237
    
238
    Parameters:
239
    - path: Directory to save predictor (uses self.path if None)
240
    """
241

242
@classmethod
243
def load(cls, path: str, verbosity: int = 2):
244
    """
245
    Load saved predictor from disk.
246
    
247
    Parameters:
248
    - path: Directory containing saved predictor
249
    - verbosity: Logging verbosity level
250
    
251
    Returns:
252
    TimeSeriesPredictor: Loaded predictor instance
253
    """
254
```
255

256
### Properties
257

258
Access predictor configuration and fitted model information.
259

260
```python { .api }
261
@property
262
def target(self) -> str:
263
    """Name of target column containing time series values"""
264

265
@property
266
def prediction_length(self) -> int:
267
    """Forecast horizon (number of time steps)"""
268

269
@property
270
def freq(self) -> str:
271
    """Frequency of time series data"""
272

273
@property
274
def quantile_levels(self) -> list:
275
    """List of quantile levels for probabilistic forecasts"""
276

277
@property
278
def eval_metric(self) -> str:
279
    """Evaluation metric used for model selection"""
280

281
@property
282
def known_covariates_names(self) -> list:
283
    """Names of covariates known at prediction time"""
284
```
285

286
## Usage Examples
287

288
### Basic Time Series Forecasting
289

290
```python
291
from autogluon.timeseries import TimeSeriesPredictor, TimeSeriesDataFrame
292
import pandas as pd
293

294
# Prepare time series data
295
df = pd.DataFrame({
296
    'item_id': ['A', 'A', 'A', 'B', 'B', 'B'] * 100,
297
    'timestamp': pd.date_range('2020-01-01', periods=600, freq='D'),
298
    'target': np.random.randn(600).cumsum(),
299
    'feature1': np.random.randn(600)
300
})
301

302
# Convert to TimeSeriesDataFrame
303
ts_data = TimeSeriesDataFrame.from_data_frame(
304
    df, 
305
    id_column='item_id', 
306
    timestamp_column='timestamp'
307
)
308

309
# Train forecasting models
310
predictor = TimeSeriesPredictor(
311
    target='target',
312
    prediction_length=30,  # Forecast 30 days ahead
313
    freq='D',  # Daily frequency
314
    eval_metric='MASE'  # Mean Absolute Scaled Error
315
)
316

317
predictor.fit(
318
    ts_data,
319
    presets='high_quality',
320
    time_limit=3600
321
)
322

323
# Generate forecasts
324
forecasts = predictor.predict(ts_data)
325
print(f"Forecast shape: {forecasts.shape}")
326
print(f"Quantile levels: {forecasts.columns}")
327

328
# Evaluate performance
329
scores = predictor.evaluate(ts_data)
330
print(f"MASE: {scores['MASE']:.3f}")
331

332
# View model leaderboard
333
leaderboard = predictor.leaderboard(ts_data)
334
print(leaderboard)
335
```
336

337
### Forecasting with Known Covariates
338

339
```python
340
# Time series with external features known in advance
341
predictor = TimeSeriesPredictor(
342
    target='sales',
343
    prediction_length=7,  # Weekly forecast
344
    freq='D',
345
    known_covariates_names=['holiday', 'promotion', 'temperature'],
346
    quantile_levels=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
347
)
348

349
# Training data includes both target and known covariates
350
predictor.fit(train_data, presets='best_quality')
351

352
# For prediction, provide future values of known covariates
353
future_covariates = TimeSeriesDataFrame.from_data_frame(
354
    future_covariate_df,
355
    id_column='store_id',
356
    timestamp_column='date'
357
)
358

359
# Generate forecasts with covariates
360
forecasts = predictor.predict(
361
    historical_data,
362
    known_covariates=future_covariates
363
)
364

365
# Access quantile predictions
366
median_forecast = forecasts['0.5']  # Median prediction
367
lower_bound = forecasts['0.1']      # 10th percentile
368
upper_bound = forecasts['0.9']      # 90th percentile
369
```
370

371
### Custom Model Configuration
372

373
```python
374
# Custom hyperparameters and model selection
375
hyperparameters = {
376
    'DeepAR': {
377
        'epochs': 100,
378
        'context_length': 48,
379
        'learning_rate': 1e-3
380
    },
381
    'Transformer': {
382
        'epochs': 50,
383
        'context_length': 96,
384
        'd_model': 128
385
    },
386
    'ETS': {},  # Use default ETS parameters
387
    'ARIMA': {'max_p': 5, 'max_q': 5, 'max_d': 2}
388
}
389

390
predictor = TimeSeriesPredictor(
391
    target='demand',
392
    prediction_length=24,  # 24 hours ahead
393
    freq='H',
394
    eval_metric='RMSE',
395
    eval_metric_seasonal_period=24,  # Daily seasonality
396
    path='./forecasting_models'
397
)
398

399
predictor.fit(
400
    train_data,
401
    hyperparameters=hyperparameters,
402
    excluded_model_types=['SeasonalNaive'],  # Exclude simple baselines
403
    enable_ensemble=True,
404
    time_limit=7200
405
)
406

407
# Analyze training results
408
summary = predictor.fit_summary(verbosity=2, show_plot=True)
409
print(f"Best model: {summary['best_model']}")
410
print(f"Training time: {summary['fit_time']:.1f}s")
411
```