Forecasting Timeseries

Forecasting Time Series

Quick Start

1. Query time series data with the lakehouse (daily granularity, 30-90 days covers both tools well)
2. Use Analyze Time Series Insight to detect anomalies and get a statistical forecast
3. If you need higher accuracy or uncertainty bands, follow up with Forecast with Chronos (needs 14+ days, best with 30+)

When to Use This Skill

• User asks about trends, spikes, or drops in a metric over time
• User wants to predict or forecast future values using local analysis tools
• User asks "is this normal?" about a metric value
• Investigating anomalies or unexpected changes in an ad-hoc session
• User asks for projections, predictions, or what to expect next week/month
• Keywords: "forecast", "predict", "anomaly", "spike", "drop", "trend", "projection", "unusual", "normal range"

This skill vs. forecast tasks: This skill runs on-demand, local analysis using Python tools (Chronos, statsmodels). For recurring, automated forecasting on a schedule, use the configuring-tasks skill to create a forecast task instead.

Two Tools, Two Purposes

There are two complementary time series tools. Use one or both depending on the question.

| | Analyze Time Series Insight | Forecast with Chronos | |---|---|---| | Best for | "What happened?" | "What will happen?" | | Anomaly detection | Yes (Z-score + IQR) | No | | Forecasting method | Exponential smoothing | Chronos-2 ML model | | Uncertainty bands | No | Yes (10th/90th percentile) | | Minimum data | 3 days | 14 days | | Recommended data | 14-90 days | 30-365 days | | Default horizon | 7 days | 14 days | | Max input size | 2000 chars | 3000 chars |

When to Use Each

User question about a metric over time
  │
  ├─ "Is this value normal?" / "Why did X spike?"
  │   → Analyze Time Series Insight (anomaly detection)
  │
  ├─ "What will happen next week?" / "Forecast revenue"
  │   → Forecast with Chronos (ML forecast with uncertainty)
  │
  └─ "Analyze this trend and predict what's next"
      → Both: Analyze first, then Chronos for deeper forecast

Workflow

Step 1: Query the Data

Use query_lakehouse to get daily time series data. Format the result as:

[{"date": "2024-01-01", "value": 100}, {"date": "2024-01-02", "value": 105}]

Keep the data compact. Aggregate to weekly if the date range exceeds 90 days. The tools have strict character limits on input.

Step 2: Run Analysis

Start with Analyze Time Series Insight for a statistical overview:

• Detects anomalous values using Z-score and IQR methods
• Identifies whether the latest value is anomalous
• Provides trend direction and day-over-day change
• Generates a short-term exponential smoothing forecast

Step 3: Enhance with Chronos (Optional)

If the user needs a more accurate forecast or wants confidence intervals, run Forecast with Chronos:

• Provides point forecast plus 10th/90th percentile uncertainty bands
• Better at capturing complex seasonal patterns
• Indicates forecast confidence (high/medium/low based on band width)

Interpreting Results

Anomaly Detection

The analysis tool flags anomalies using two combined methods:

• Z-score: Values more than 2 standard deviations from the mean
• IQR: Values below Q1 - 1.5 IQR or above Q3 + 1.5 IQR

A value flagged by either method is reported. If the latest value is anomalous, it requires attention.

Trend Direction

| Forecast Change | Interpretation | |-----------------|----------------| | > +5% | Increasing trend | | -5% to +5% | Stable | | 50% | Low — wide band, treat with caution |

Common Pitfalls

1. Sending too much data — Tools have 2000/3000 char limits. Aggregate to weekly for long ranges
2. Too few data points — Chronos needs 14+ days. Analysis needs 3+ but works best with 14+
3. Using Chronos for anomaly detection — Chronos only forecasts; use Analyze Time Series for anomalies
4. Skipping aggregation — Hourly data quickly exceeds size limits. Always use daily or weekly granularity
5. Ignoring uncertainty bands — A Chronos forecast with wide bands means low confidence; communicate this clearly
6. Not checking seasonality — Weekly patterns (weekday vs weekend) need at least 14 days to detect
7. Forecasting without context — Always pair forecasts with what the current trend shows

References

• [Chronos forecasting details](references/chronos-forecasting.md) - Read when generating forecasts or configuring prediction horizons and confidence intervals
• [Anomaly detection methods](references/anomaly-detection.md) - Read when detecting anomalies or choosing between statistical methods

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: altertable-ai
• Source: altertable-ai/skills
• License: MIT
• Homepage: https://altertable.ai

Install and usage instructions live in the source repository linked above.