tessl/pypi-autogluon

AutoGluon automates machine learning tasks enabling you to easily achieve strong predictive performance in your applications.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Time Series Forecasting

Name: tessl/pypi-autogluon
Author: tessl

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.

Capabilities

TimeSeriesPredictor Class

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

class TimeSeriesPredictor:
    def __init__(
        self,
        target: str = "target",
        known_covariates_names: list = None,
        prediction_length: int = 1,
        freq: str = None,
        eval_metric: str = None,
        eval_metric_seasonal_period: int = None,
        horizon_weight: list = None,
        path: str = None,
        verbosity: int = 2,
        log_to_file: bool = True,
        log_file_path: str = "auto",
        quantile_levels: list = None,
        cache_predictions: bool = True,
        label: str = None,
        **kwargs
    ):
        """
        Initialize TimeSeriesPredictor for automated time series forecasting.
        
        Parameters:
        - target: Name of target column containing time series values
        - known_covariates_names: Names of covariates known at prediction time
        - prediction_length: Forecast horizon (number of time steps)
        - freq: Frequency of time series ('D', 'H', 'M', etc.)
        - eval_metric: Evaluation metric ('WQL', 'SQL', 'MAE', 'MAPE', 'MASE', 'MSE', 'RMSE', etc.)
        - eval_metric_seasonal_period: Seasonal period for scaled metrics
        - horizon_weight: Weights for each time step in forecast horizon
        - path: Directory to save models and artifacts
        - verbosity: Logging verbosity level (0-4)
        - log_to_file: Save logs to file
        - log_file_path: Path for log file
        - quantile_levels: List of quantile levels for probabilistic forecasts
        - cache_predictions: Cache predictions for efficiency
        - label: Alias for target parameter
        """

TimeSeriesDataFrame Class

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

class TimeSeriesDataFrame:
    def __init__(self, data, id_column: str = None, timestamp_column: str = None):
        """
        Initialize time series data structure.
        
        Parameters:
        - data: Input DataFrame with time series data
        - id_column: Name of column identifying different time series
        - timestamp_column: Name of column containing timestamps
        """
    
    @classmethod
    def from_data_frame(
        cls,
        df,
        id_column: str = "item_id",
        timestamp_column: str = "timestamp"
    ):
        """
        Create TimeSeriesDataFrame from pandas DataFrame.
        
        Parameters:
        - df: Input pandas DataFrame
        - id_column: Column identifying different time series
        - timestamp_column: Column containing timestamps
        
        Returns:
        TimeSeriesDataFrame: Time series data structure
        """

Model Training

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

def fit(
    self,
    train_data,
    presets: str = None,
    time_limit: int = None,
    num_cpus: int = None,
    num_gpus: int = None,
    num_val_windows: int = None,
    hyperparameters: dict = None,
    excluded_model_types: list = None,
    included_model_types: list = None,
    enable_ensemble: bool = None,
    random_seed: int = 0,
    verbosity: int = None,
    **kwargs
):
    """
    Fit TimeSeriesPredictor on time series training data.
    
    Parameters:
    - train_data: Training data (TimeSeriesDataFrame or compatible DataFrame)
    - presets: Quality/speed presets ('best_quality', 'high_quality', 'medium_quality', 'fast_training')
    - time_limit: Maximum training time in seconds
    - num_cpus: Number of CPU cores to use
    - num_gpus: Number of GPUs to use  
    - num_val_windows: Number of validation windows for model selection
    - hyperparameters: Custom hyperparameter configurations
    - excluded_model_types: List of model types to exclude
    - included_model_types: List of model types to include only
    - enable_ensemble: Enable model ensembling
    - random_seed: Random seed for reproducibility
    - verbosity: Logging verbosity level
    
    Returns:
    TimeSeriesPredictor: Fitted predictor instance
    """

Forecasting

Generate probabilistic forecasts with quantile predictions and confidence intervals.

def predict(
    self,
    data,
    known_covariates = None,
    model: str = None,
    use_cache: bool = True,
    **kwargs
):
    """
    Generate probabilistic forecasts for time series data.
    
    Parameters:
    - data: Historical time series data (TimeSeriesDataFrame)
    - known_covariates: Future values of known covariates
    - model: Specific model name for prediction
    - use_cache: Use cached predictions if available
    
    Returns:
    TimeSeriesDataFrame: Forecasts with quantile predictions
    """

Model Evaluation

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

def evaluate(
    self,
    data,
    metrics: list = None,
    model: str = None,
    display_model_names: bool = False,
    **kwargs
):
    """
    Evaluate predictor performance on time series data.
    
    Parameters:
    - data: Test time series data (TimeSeriesDataFrame)
    - metrics: List of evaluation metrics to compute
    - model: Specific model to evaluate
    - display_model_names: Show individual model names in output
    
    Returns:
    dict: Dictionary of evaluation metrics
    """

def leaderboard(
    self,
    data = None,
    model: str = None,
    display_model_names: bool = False,
    **kwargs
):
    """
    Display model leaderboard with forecasting performance rankings.
    
    Parameters:
    - data: Test data for evaluation (optional)
    - model: Specific model to include
    - display_model_names: Show detailed model names
    
    Returns:
    DataFrame: Model leaderboard with performance metrics
    """

Model Analysis

Analyze model behavior and generate training summaries.

def fit_summary(self, verbosity: int = 1, show_plot: bool = False):
    """
    Display summary of training process and model performance.
    
    Parameters:
    - verbosity: Detail level (0-4)
    - show_plot: Show training and validation plots
    
    Returns:
    dict: Training summary information
    """

def info(self) -> dict:
    """
    Get detailed information about the fitted predictor.
    
    Returns:
    dict: Predictor information including models, metrics, and configuration
    """

Model Persistence

Save and load trained forecasting models.

def save(self, path: str = None):
    """
    Save trained predictor to disk.
    
    Parameters:
    - path: Directory to save predictor (uses self.path if None)
    """

@classmethod
def load(cls, path: str, verbosity: int = 2):
    """
    Load saved predictor from disk.
    
    Parameters:
    - path: Directory containing saved predictor
    - verbosity: Logging verbosity level
    
    Returns:
    TimeSeriesPredictor: Loaded predictor instance
    """

Properties

Access predictor configuration and fitted model information.

@property
def target(self) -> str:
    """Name of target column containing time series values"""

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

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

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

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

@property
def known_covariates_names(self) -> list:
    """Names of covariates known at prediction time"""

Usage Examples

Basic Time Series Forecasting

from autogluon.timeseries import TimeSeriesPredictor, TimeSeriesDataFrame
import pandas as pd

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

# Convert to TimeSeriesDataFrame
ts_data = TimeSeriesDataFrame.from_data_frame(
    df, 
    id_column='item_id', 
    timestamp_column='timestamp'
)

# Train forecasting models
predictor = TimeSeriesPredictor(
    target='target',
    prediction_length=30,  # Forecast 30 days ahead
    freq='D',  # Daily frequency
    eval_metric='MASE'  # Mean Absolute Scaled Error
)

predictor.fit(
    ts_data,
    presets='high_quality',
    time_limit=3600
)

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

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

# View model leaderboard
leaderboard = predictor.leaderboard(ts_data)
print(leaderboard)

Forecasting with Known Covariates

# Time series with external features known in advance
predictor = TimeSeriesPredictor(
    target='sales',
    prediction_length=7,  # Weekly forecast
    freq='D',
    known_covariates_names=['holiday', 'promotion', 'temperature'],
    quantile_levels=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
)

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

# For prediction, provide future values of known covariates
future_covariates = TimeSeriesDataFrame.from_data_frame(
    future_covariate_df,
    id_column='store_id',
    timestamp_column='date'
)

# Generate forecasts with covariates
forecasts = predictor.predict(
    historical_data,
    known_covariates=future_covariates
)

# Access quantile predictions
median_forecast = forecasts['0.5']  # Median prediction
lower_bound = forecasts['0.1']      # 10th percentile
upper_bound = forecasts['0.9']      # 90th percentile

Custom Model Configuration

# Custom hyperparameters and model selection
hyperparameters = {
    'DeepAR': {
        'epochs': 100,
        'context_length': 48,
        'learning_rate': 1e-3
    },
    'Transformer': {
        'epochs': 50,
        'context_length': 96,
        'd_model': 128
    },
    'ETS': {},  # Use default ETS parameters
    'ARIMA': {'max_p': 5, 'max_q': 5, 'max_d': 2}
}

predictor = TimeSeriesPredictor(
    target='demand',
    prediction_length=24,  # 24 hours ahead
    freq='H',
    eval_metric='RMSE',
    eval_metric_seasonal_period=24,  # Daily seasonality
    path='./forecasting_models'
)

predictor.fit(
    train_data,
    hyperparameters=hyperparameters,
    excluded_model_types=['SeasonalNaive'],  # Exclude simple baselines
    enable_ensemble=True,
    time_limit=7200
)

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

Install with Tessl CLI