Time Series Forecaster

Overview

Specialized forecasting pipelines for time-dependent data. Handles trend analysis, seasonality detection, and future predictions using statistical methods, machine learning, and deep learning approaches—all integrated with SpecWeave's increment workflow.

Why Time Series is Different

Standard ML assumptions violated:

• ❌ Data is NOT independent (temporal correlation)
• ❌ Data is NOT identically distributed (trends, seasonality)
• ❌ Random train/test split is WRONG (breaks temporal order)

Time series requirements:

• ✅ Temporal order preserved
• ✅ No data leakage from future
• ✅ Stationarity checks
• ✅ Autocorrelation analysis
• ✅ Seasonality decomposition

Forecasting Methods

1. Statistical Methods (Baseline)

ARIMA (AutoRegressive Integrated Moving Average):

from specweave import TimeSeriesForecaster

forecaster = TimeSeriesForecaster(
    method="arima",
    increment="0042"
)

# Automatic order selection (p, d, q)
forecaster.fit(train_data)

# Forecast next 30 periods
forecast = forecaster.predict(horizon=30)

# Generates:
# - Trend analysis
# - Seasonality decomposition
# - Autocorrelation plots (ACF, PACF)
# - Residual diagnostics
# - Forecast with confidence intervals

Seasonal Decomposition:

# Decompose into trend + seasonal + residual
decomposition = forecaster.decompose(
    data=sales_data,
    model='multiplicative',  # Or 'additive'
    period=12  # Monthly seasonality
)

# Creates:
# - Trend component plot
# - Seasonal component plot
# - Residual component plot
# - Strength of trend/seasonality metrics

2. Prophet (Facebook)

Best for: Business time series (sales, website traffic, user growth)

from specweave import ProphetForecaster

forecaster = ProphetForecaster(increment="0042")

# Prophet handles:
# - Multiple seasonality (daily, weekly, yearly)
# - Holidays and events
# - Missing data
# - Outliers

forecaster.fit(
    data=sales_data,
    holidays=us_holidays,  # Built-in holiday effects
    seasonality_mode='multiplicative'
)

forecast = forecaster.predict(horizon=90)

# Generates:
# - Trend + seasonality + holiday components
# - Change point detection
# - Uncertainty intervals
# - Cross-validation results

Prophet with Custom Regressors:

# Add external variables (marketing spend, weather, etc.)
forecaster.add_regressor("marketing_spend")
forecaster.add_regressor("temperature")

# Prophet incorporates external factors into forecast

3. Deep Learning (LSTM/GRU)

Best for: Complex patterns, multivariate forecasting, non-linear relationships

from specweave import LSTMForecaster

forecaster = LSTMForecaster(
    lookback_window=30,  # Use 30 past observations
    horizon=7,  # Predict 7 steps ahead
    increment="0042"
)

# Automatically handles:
# - Sequence creation
# - Train/val/test split (temporal)
# - Scaling
# - Early stopping

forecaster.fit(
    data=sensor_data,
    epochs=100,
    batch_size=32
)

forecast = forecaster.predict(horizon=7)

# Generates:
# - Training history plots
# - Validation metrics
# - Attention weights (if using attention)
# - Forecast uncertainty estimation

4. Multivariate Forecasting

VAR (Vector AutoRegression) - Multiple related time series:

from specweave import VARForecaster

# Forecast multiple related series simultaneously
forecaster = VARForecaster(increment="0042")

# Example: Forecast sales across multiple stores
# Each store's sales affects others
forecaster.fit(data={
    'store_1_sales': store1_data,
    'store_2_sales': store2_data,
    'store_3_sales': store3_data
})

forecast = forecaster.predict(horizon=30)
# Returns forecasts for all 3 stores

Time Series Best Practices

1. Temporal Train/Test Split

# ❌ WRONG: Random split (data leakage!)
X_train, X_test = train_test_split(data, test_size=0.2)

# ✅ CORRECT: Temporal split
split_date = "2024-01-01"
train = data[data.index < split_date]
test = data[data.index >= split_date]

# Or use last N periods as test
train = data[:-30]  # All but last 30 observations
test = data[-30:]   # Last 30 observations

2. Stationarity Testing

from specweave import TimeSeriesAnalyzer

analyzer = TimeSeriesAnalyzer(increment="0042")

# Check stationarity (required for ARIMA)
stationarity = analyzer.check_stationarity(data)

if not stationarity['is_stationary']:
    # Make stationary via differencing
    data_diff = analyzer.difference(data, order=1)
    
    # Or detrend
    data_detrended = analyzer.detrend(data)

Stationarity Report:

# Stationarity Analysis

## ADF Test (Augmented Dickey-Fuller)
- Test Statistic: -2.15
- P-value: 0.23
- Critical Value (5%): -2.89
- Result: ❌ NON-STATIONARY (p > 0.05)

## Recommendation
Apply differencing (order=1) to remove trend.

After differencing:
- ADF Test Statistic: -5.42
- P-value: 0.0001
- Result: ✅ STATIONARY

3. Seasonality Detection

# Automatic seasonality detection
seasonality = analyzer.detect_seasonality(data)

# Results:
# - Daily: False
# - Weekly: True (period=7)
# - Monthly: True (period=30)
# - Yearly: False

4. Cross-Validation for Time Series

# Time series cross-validation (expanding window)
cv_results = forecaster.cross_validate(
    data=data,
    horizon=30,  # Forecast 30 steps ahead
    n_splits=5,  # 5 expanding windows
    metric='mape'
)

# Visualizes:
# - MAPE across different time periods
# - Forecast vs actual for each fold
# - Model stability over time

5. Handling Missing Data

# Time series-specific imputation
forecaster.handle_missing(
    method='interpolate',  # Or 'forward_fill', 'backward_fill'
    limit=3  # Max consecutive missing values to fill
)

# For seasonal data
forecaster.handle_missing(
    method='seasonal_interpolate',
    period=12  # Use seasonal pattern to impute
)

Common Time Series Patterns

Pattern 1: Sales Forecasting

from specweave import SalesForecastPipeline

pipeline = SalesForecastPipeline(increment="0042")

# Handles:
# - Weekly/monthly seasonality
# - Holiday effects
# - Marketing campaign impact
# - Trend changes

pipeline.fit(
    sales_data=daily_sales,
    holidays=us_holidays,
    regressors={
        'marketing_spend': marketing_data,
        'competitor_price': competitor_data
    }
)

forecast = pipeline.predict(horizon=90)  # 90 days ahead

# Generates:
# - Point forecast
# - Prediction intervals (80%, 95%)
# - Component analysis (trend, seasonality, regressors)
# - Anomaly flags for past data

Pattern 2: Demand Forecasting

from specweave import DemandForecastPipeline

# Inventory optimization, supply chain planning
pipeline = DemandForecastPipeline(
    aggregation='daily',  # Or 'weekly', 'monthly'
    increment="0042"
)

# Multi-product forecasting
forecasts = pipeline.fit_predict(
    products=['product_A', 'product_B', 'product_C'],
    horizon=30
)

# Generates:
# - Demand forecast per product
# - Confidence intervals
# - Stockout risk analysis
# - Reorder point recommendations

Pattern 3: Stock Price Prediction

from specweave import FinancialForecastPipeline

# Stock prices, crypto, forex
pipeline = FinancialForecastPipeline(increment="0042")

# Handles:
# - Volatility clustering
# - Non-linear patterns
# - Technical indicators

pipeline.fit(
    price_data=stock_prices,
    features=['volume', 'volatility', 'RSI', 'MACD']
)

forecast = pipeline.predict(horizon=7)

# Generates:
# - Price forecast with confidence bands
# - Volatility forecast (GARCH)
# - Trading signals (optional)
# - Risk metrics

Pattern 4: Sensor Data / IoT

from specweave import SensorForecastPipeline

# Temperature, humidity, machine metrics
pipeline = SensorForecastPipeline(
    method='lstm',  # Deep learning for complex patterns
    increment="0042"
)

# Multivariate: Multiple sensor readings
pipeline.fit(
    sensors={
        'temperature': temp_data,
        'humidity': humidity_data,
        'pressure': pressure_data
    }
)

forecast = pipeline.predict(horizon=24)  # 24 hours ahead

# Generates:
# - Multi-sensor forecasts
# - Anomaly detection (unexpected values)
# - Maintenance alerts

Evaluation Metrics

Time series-specific metrics:

from specweave import TimeSeriesEvaluator

evaluator = TimeSeriesEvaluator(increment="0042")

metrics = evaluator.evaluate(
    y_true=test_data,
    y_pred=forecast
)

# Metrics:
# - MAPE (Mean Absolute Percentage Error) - business-friendly
# - RMSE (Root Mean Squared Error) - penalizes large errors
# - MAE (Mean Absolute Error) - robust to outliers
# - MASE (Mean Absolute Scaled Error) - scale-independent
# - Directional Accuracy - did we predict up/down correctly?

Evaluation Report:

# Time Series Forecast Evaluation

## Point Metrics
- MAPE: 8.2% (target: <10%) ✅
- RMSE: 124.5
- MAE: 98.3
- MASE: 0.85 (< 1 = better than naive forecast) ✅

## Directional Accuracy
- Correct direction: 73% (up/down predictions)

## Forecast Bias
- Mean Error: -5.2 (slight under-forecasting)
- Bias: -2.1%

## Confidence Intervals
- 80% interval coverage: 79.2% ✅
- 95% interval coverage: 94.1% ✅

## Recommendation
✅ DEPLOY: Model meets accuracy targets and is well-calibrated.

Integration with SpecWeave

Increment Structure

.specweave/increments/0042-sales-forecast/
├── spec.md (forecasting requirements, accuracy targets)
├── plan.md (forecasting strategy, method selection)
├── tasks.md
├── data/
│   ├── train_data.csv
│   ├── test_data.csv
│   └── schema.yaml
├── experiments/
│   ├── arima-baseline/
│   ├── prophet-holidays/
│   └── lstm-multivariate/
├── models/
│   ├── prophet_model.pkl
│   └── lstm_model.h5
├── forecasts/
│   ├── forecast_2024-01.csv
│   ├── forecast_2024-02.csv
│   └── forecast_with_intervals.csv
└── analysis/
    ├── stationarity_test.md
    ├── seasonality_decomposition.png
    └── forecast_evaluation.md

Living Docs Integration

/specweave:sync-docs update

Updates:

<!-- .specweave/docs/internal/architecture/time-series-forecasting.md -->

## Sales Forecasting Model (Increment 0042)

### Method Selected: Prophet
- Reason: Handles multiple seasonality + holidays well
- Alternatives tried: ARIMA (MAPE 12%), LSTM (MAPE 10%)
- Prophet: MAPE 8.2% ✅ BEST

### Seasonality Detected
- Weekly: Strong (7-day cycle)
- Monthly: Moderate (30-day cycle)
- Yearly: Weak

### Holiday Effects
- Black Friday: +180% sales (strongest)
- Christmas: +120% sales
- Thanksgiving: +80% sales

### Forecast Horizon
- 90 days ahead
- Confidence intervals: 80%, 95%
- Update frequency: Weekly retraining

### Model Performance
- MAPE: 8.2% (target: <10%)
- Directional accuracy: 73%
- Deployed: 2024-01-15

Commands

# Create time series forecast
/ml:forecast --horizon 30 --method prophet

# Evaluate forecast
/ml:evaluate-forecast 0042

# Decompose time series
/ml:decompose-timeseries 0042

Advanced Features

1. Ensemble Forecasting

# Combine multiple methods for robustness
ensemble = EnsembleForecast(increment="0042")

ensemble.add_forecaster("arima", weight=0.3)
ensemble.add_forecaster("prophet", weight=0.5)
ensemble.add_forecaster("lstm", weight=0.2)

# Weighted average of all forecasts
forecast = ensemble.predict(horizon=30)

# Ensemble typically 10-20% more accurate than single model

2. Forecast Reconciliation

# For hierarchical time series (e.g., total sales = store1 + store2 + store3)
reconciler = ForecastReconciler(increment="0042")

# Ensures forecasts sum correctly
reconciled = reconciler.reconcile(
    forecasts={
        'total': total_forecast,
        'store1': store1_forecast,
        'store2': store2_forecast,
        'store3': store3_forecast
    },
    method='bottom_up'  # Or 'top_down', 'middle_out'
)

3. Forecast Monitoring

# Track forecast accuracy over time
monitor = ForecastMonitor(increment="0042")

# Compare forecasts vs actuals
monitor.track_performance(
    forecasts=past_forecasts,
    actuals=actual_values
)

# Alerts when accuracy degrades
if monitor.accuracy_degraded():
    print("⚠️ Forecast accuracy dropped 15% - retrain model!")

Summary

Time series forecasting requires specialized techniques:

• ✅ Temporal validation (no random split)
• ✅ Stationarity testing
• ✅ Seasonality detection
• ✅ Trend decomposition
• ✅ Cross-validation (expanding window)
• ✅ Confidence intervals
• ✅ Forecast monitoring

This skill handles all time series complexity within SpecWeave's increment workflow, ensuring forecasts are reproducible, documented, and production-ready.