time-series-forecaster

# 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)**:
```python
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**:
```python
# 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)

```python
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,