How to Build a Forecasting Pipeline with TimeCopilot Using Foundation Models and Automated Anomaly Detection

In this tutorial, we build an end-to-end forecasting workflow with TimeCopilot, an open-source framework designed for time series analysis. We prepare a panel dataset containing real airline passenger data along with a synthetic seasonal series seeded with injected anomalies. We then evaluate a diverse collection of statistical, foundation, and optional GPU-based forecasting models to demonstrate the flexibility and power of modern forecasting techniques. Using rolling cross-validation and multiple error metrics, we identify the strongest model, generate probabilistic forecasts with prediction intervals, visualize future trends, and automatically detect unusual observations. Finally, we explore TimeCopilot's optional LLM agent, which selects a forecasting model and translates its predictions into an accessible analytical response.

Installing TimeCopilot and Pinning Compatible Versions

Before building the pipeline, ensure you have the correct environment. TimeCopilot requires Python 3.9+ and depends on specific versions of NumPy and SciPy for stability. We recommend pinning NumPy to 1.23.5 and SciPy to 1.7.3 to avoid compatibility issues with the latest releases. Install TimeCopilot using pip:

pip install timecopilot numpy==1.23.5 scipy==1.7.3

Preparing the Panel Dataset

We construct a panel dataset combining:

• Real airline passenger data: monthly totals from 1949 to 1960 (Box & Jenkins dataset).
• Synthetic seasonal series: a 3-year monthly series with a 12-period seasonality and an injected anomaly (a large spike) at month 18.

Both series are labeled and stacked into a panel format with columns: timestamp, value, series_id. This structure allows TimeCopilot to handle multiple time series simultaneously.

Model Selection and Evaluation

TimeCopilot provides a unified interface to several model families:

• Statistical models: ARIMA, SARIMA, ETS (Exponential Smoothing).
• Foundation models: TimeGPT, Lag-Llama (via Hugging Face transformers).
• GPU-based models: N-BEATS, TFT (Temporal Fusion Transformer), available if a CUDA-compatible GPU is present.

We perform rolling cross-validation with a window of 12 steps and evaluate each model on:

• MAE (Mean Absolute Error)
• RMSE (Root Mean Squared Error)
• MAPE (Mean Absolute Percentage Error)

The code snippet below shows the evaluation loop:

from timecopilot import TimeCopilot
import pandas as pd

# Load panel data
df = pd.read_csv('panel_data.csv')

# Initialize TimeCopilot
tc = TimeCopilot(
    df=df,
    target='value',
    index='timestamp',
    freq='MS',
    panel='series_id'
)

# Evaluate models
results = tc.evaluate_models(  # hypothetical API; adjust per actual docs
    models=['sarima', 'timegpt', 'lagllama'],
    cross_val_steps=12,
    metrics=['mae', 'rmse', 'mape']
)
print(results)

Generating Probabilistic Forecasts and Prediction Intervals

Once the best model is identified (e.g., SARIMA for the seasonal synthetic series), we generate forecasts with prediction intervals:

best_model = 'sarima'
forecasts = tc.forecast(
    model=best_model,
    horizon=12,  # forecast next 12 months
    return_intervals=True,
    alpha=0.05   # 95% confidence intervals
)

Visualizing Future Trends and Anomalies

TimeCopilot includes plotting utilities. We visualize historical data, forecasts, and prediction intervals:

tc.plot_forecast(
    forecasts,
    intervals=True,
    series_id='synthetic'  # plot only one panel
)

For anomaly detection, we flag observations outside the prediction intervals:

anomalies = tc.detect_anomalies(
    model=best_model,
    alpha=0.05
)
print(anomalies)

Using the LLM Agent for Model Selection and Explanation

TimeCopilot's optional LLM agent (powered by OpenAI GPT-4 or similar) can:

1. Analyze the dataset and recommend the best model.
2. Convert numerical forecasts into a human-readable summary.



Example invocation:




from timecopilot.agents import LLMAgent

agent = LLMAgent(api_key='your-openai-key')
recommendation = agent.recommend_model(df)
print(f"LLM recommends: {recommendation}")

# Get explanation for a forecast
explanation = agent.explain_forecast(forecasts)
print(explanation)




Conclusion




This tutorial demonstrated a complete forecasting pipeline using TimeCopilot: from data preparation with panel data and anomaly injection, through model evaluation with rolling cross-validation, to probabilistic forecasting and automated interpretation via an LLM agent. By combining foundation models, statistical benchmarks, and AI-driven explanations, TimeCopilot streamlines building robust forecasting systems for real-world applications.




For the full working code, including data generation scripts and detailed model configurations, please refer to the accompanying notebook on GitHub.

via MarkTechPost