Time Series Analysis with DataStoryBot: Trends, Seasonality, Forecasts

Time series data is everywhere — revenue by month, page views by day, sensor readings by minute, stock prices by second. The analytical questions are always the same: Is it going up or down? Is there a seasonal pattern? Is this week unusual? Where is it headed?

DataStoryBot handles these questions well because Code Interpreter has access to the Python time series toolkit: pandas for manipulation, statsmodels for decomposition, scipy for statistical tests, and matplotlib for visualization. Upload a time-indexed CSV, steer toward temporal analysis, and get back a narrative about what your data is doing over time.

This article covers the time series analysis capabilities, the steering prompts that get the best results, and the limitations you should know about.

What You Need in the CSV

Time series analysis requires a column that DataStoryBot can interpret as a time axis. Common formats:

date,revenue
2025-01-01,45230
2025-01-02,47891
2025-01-03,43567

timestamp,temperature,humidity
2026-03-01 00:00:00,22.3,45
2026-03-01 01:00:00,21.8,47
2026-03-01 02:00:00,21.2,49

month,signups
Jan-2025,1234
Feb-2025,1567
Mar-2025,1890

Code Interpreter parses most date formats automatically using pd.to_datetime(). If your format is unusual (e.g., epoch timestamps, or week numbers), mention it in the steering prompt:

steering = (
    "The 'ts' column contains Unix epoch timestamps in seconds. "
    "Convert to datetime before analysis."
)

Trend Detection

The most basic time series question: is it going up, down, or flat?

import requests

BASE_URL = "https://datastory.bot/api"

with open("monthly_revenue.csv", "rb") as f:
    upload = requests.post(f"{BASE_URL}/upload", files={"file": f})
container_id = upload.json()["containerId"]

stories = requests.post(f"{BASE_URL}/analyze", json={
    "containerId": container_id,
    "steeringPrompt": (
        "Analyze the trend in this time series. Identify: "
        "the overall direction, the rate of change, any inflection "
        "points where the trend changed, and how recent values "
        "compare to the historical baseline."
    )
})

DataStoryBot's Code Interpreter typically:

1. Plots the raw time series — the foundation chart
2. Fits a trend line — linear or polynomial, depending on the data shape
3. Identifies inflection points — using change-point detection or visual inspection
4. Quantifies the trend — "growing at 8.3% month-over-month" or "declining at 120 units per week"
5. Narrates the finding — "Revenue has been growing consistently since September, with an acceleration in January that coincides with the product launch"

Example narrative output:

Revenue grew 47% year-over-year, from $1.23M/month in Q1 2025 to $1.81M/month in Q1 2026. The growth rate accelerated in Q4 2025 — from 3.2% month-over-month (Jan-Sep 2025) to 5.8% month-over-month (Oct 2025 - Mar 2026). The inflection point was October 2025, which aligns with the international expansion.

Seasonality Detection

Does the data have a repeating pattern — daily, weekly, monthly, yearly?

stories = requests.post(f"{BASE_URL}/analyze", json={
    "containerId": container_id,
    "steeringPrompt": (
        "Look for seasonal or cyclical patterns. Check for: "
        "day-of-week effects, monthly seasonality, quarterly patterns, "
        "and any recurring spikes or dips. Decompose the time series "
        "into trend, seasonal, and residual components."
    )
})

Code Interpreter uses statsmodels.tsa.seasonal_decompose() or STL decomposition to separate the signal into components:

• Trend — the long-term direction
• Seasonal — the repeating pattern
• Residual — everything else (noise + anomalies)

The narrative might say:

Strong weekly seasonality detected. Revenue peaks on Tuesdays (avg $14.2K) and troughs on Sundays (avg $6.8K). The weekday/weekend ratio is 2.1x. After removing the weekly pattern, the underlying trend shows steady 4% month-over-month growth.

The decomposition chart is typically a 3-panel plot showing each component separately — one of the most informative visualizations for time series data.

Anomaly Detection in Time Series

Time series anomalies differ from static anomalies because the baseline changes. A value that's normal in December might be anomalous in July (seasonality). A value that was normal last year might be anomalous now if the trend has shifted.

stories = requests.post(f"{BASE_URL}/analyze", json={
    "containerId": container_id,
    "steeringPrompt": (
        "Detect anomalies in this time series. Look for: "
        "sudden spikes or drops that deviate from the trend + seasonal pattern, "
        "level shifts where the baseline changed permanently, "
        "and any outlier periods. Use the residual component after "
        "removing trend and seasonality to identify true anomalies."
    )
})

By telling Code Interpreter to use residuals for anomaly detection, you get anomalies that are adjusted for trend and seasonality — a value that's high relative to the trend-adjusted, seasonally-adjusted baseline, not just high relative to the raw average.

For a deeper dive on anomaly detection patterns, see anomaly detection in CSV data.

Basic Forecasting

DataStoryBot can project forward based on historical patterns — but with important caveats.

stories = requests.post(f"{BASE_URL}/analyze", json={
    "containerId": container_id,
    "steeringPrompt": (
        "Forecast the next 6 months based on historical trends "
        "and seasonal patterns. Use an appropriate method "
        "(exponential smoothing, linear trend extrapolation, or "
        "seasonal ARIMA if the data supports it). Report confidence "
        "intervals and clearly state the assumptions."
    )
})

Code Interpreter typically uses:

• Linear extrapolation for data with a clear linear trend
• Exponential smoothing (Holt-Winters) for data with trend + seasonality
• ARIMA/SARIMA for more complex patterns with sufficient data

The forecast narrative always includes caveats:

Projected monthly revenue for the next 6 months: $1.92M → $2.18M (Holt-Winters exponential smoothing with additive seasonality). The 95% confidence interval widens from ±$80K for next month to ±$230K for month 6. This projection assumes the current growth rate of 5.8% MoM holds and no major external shocks occur. Historical model accuracy on the last 6 months of actuals: MAPE = 4.2%.

Multi-Variable Time Series

When your CSV has multiple time-indexed metrics, DataStoryBot can analyze relationships between them:

stories = requests.post(f"{BASE_URL}/analyze", json={
    "containerId": container_id,
    "steeringPrompt": (
        "This dataset has multiple metrics over time: "
        "revenue, marketing_spend, and customer_count. "
        "Analyze how these metrics relate to each other over time. "
        "Look for leading indicators — does marketing_spend predict "
        "future revenue? Does customer_count lead or lag revenue?"
    )
})

Cross-correlation analysis finds time-lagged relationships:

Marketing spend leads revenue by approximately 3 weeks (peak cross-correlation r=0.68 at lag 21 days). A $10K increase in weekly marketing spend is associated with a $34K increase in revenue 3 weeks later. Customer count and revenue are nearly synchronous (peak correlation at lag 0 days, r=0.92).

What DataStoryBot Can't Do with Time Series

Real-time streaming. DataStoryBot processes uploaded files. It's not a streaming analytics system. For real-time time series monitoring, use Prometheus, InfluxDB, or Datadog.

Deep learning forecasting. Code Interpreter can run statsmodels and basic sklearn, but it's not going to train a transformer or LSTM in a 5-minute container session. For machine learning forecasting, use dedicated tools like Prophet, NeuralProphet, or AWS Forecast.

Very long history. Time series with millions of data points will hit the 50 MB file limit and the container's execution timeout. Pre-aggregate to daily or weekly granularity before uploading.

Real-time anomaly alerting. DataStoryBot can detect anomalies in historical data. It can't monitor a live stream and fire alerts. Use it for periodic batch analysis — daily or weekly anomaly sweeps.

Multivariate forecasting with many variables. Code Interpreter handles 2-5 variables well. A 50-variable VAR model is beyond the container's practical scope.

Steering Prompt Recipes

Weekly business review:

steering = (
    "This is weekly business data. Summarize the current week's "
    "performance vs. the 4-week rolling average. Flag any metrics "
    "that moved more than 10% from the rolling average. "
    "Include a trend line for the past 12 weeks."
)

Seasonal business:

steering = (
    "This is a seasonal business (retail). Compare year-over-year "
    "performance for the same period. Decompose into trend and "
    "seasonal components. Is this year tracking above or below "
    "the seasonal baseline?"
)

Capacity planning:

steering = (
    "Analyze server capacity metrics over time. At the current "
    "growth rate, when will we hit 80% utilization? Forecast "
    "the next 3 months with confidence intervals."
)

What to Read Next

For the trend detection fundamentals, start with how to find trends in your data automatically.

For anomaly detection in time series context, see anomaly detection in CSV data.

For the steering prompt techniques that drive these analyses, read prompt engineering for data analysis.

Or upload your own time series data to the DataStoryBot playground and steer it toward temporal analysis.