forecaster-ai 0.3.0

Enterprise-grade time series forecasting package with ARIMA, Prophet, LSTM models, and advanced decomposition

Forecaster-AI 🚀

Enterprise-grade time series forecasting package with ARIMA, Prophet, LSTM models, and advanced decomposition

---

📦 Installation

pip install forecaster-ai

Requirements: Python 3.9+

---

✨ What's New in v0.3.0

🎉 All Models Now Fully Functional!

• ✅ LSTM Forecaster - Complete implementation with recursive prediction
• ✅ ARIMA & Auto-ARIMA - Statistical time series models
• ✅ Prophet - Facebook's forecasting tool
• ✅ Ensemble Methods - Combine multiple models
• ✅ Time Series Decomposition - STL and Classical methods
• ✅ Special Cases - Intermittent demand & new product forecasting

---

🎯 Quick Start

Basic Forecasting with ARIMA

import pandas as pd
from forecasting.models import ARIMAForecaster
from forecasting.core.config import ForecastConfig

# Your time series data
data = pd.Series([100, 105, 110, 108, 115, 120, 118, 125, 130, 128])

# Configure forecast
config = ForecastConfig(
    horizon=5,              # Forecast 5 periods ahead
    confidence_level=0.95   # 95% confidence intervals
)

# Create and fit model
forecaster = ARIMAForecaster(config, order=(2, 1, 2))
forecaster.fit(data)

# Generate forecast
forecast, conf_int = forecaster.predict()

print("Forecast:", forecast)
print("Confidence Intervals:", conf_int)

---

📚 Complete Model Guide

1. ARIMA Forecaster

Best for: Stationary time series, short-term forecasts

from forecasting.models import ARIMAForecaster
from forecasting.core.config import ForecastConfig

config = ForecastConfig(horizon=30)

# Manual parameter specification
forecaster = ARIMAForecaster(
    config=config,
    order=(2, 1, 2),              # (p, d, q)
    seasonal_order=(1, 1, 1, 7),  # (P, D, Q, s) - weekly seasonality
    trend='c'                      # constant trend
)

forecaster.fit(data)
forecast, conf_int = forecaster.predict(horizon=30)

# Get model metrics
metrics = forecaster.get_validation_metrics()
print(f"AIC: {metrics['aic']}, BIC: {metrics['bic']}")

2. Auto-ARIMA Forecaster

Best for: Automatic parameter selection, exploratory analysis

from forecasting.models import AutoARIMAForecaster

config = ForecastConfig(horizon=30)

# Automatic parameter selection
forecaster = AutoARIMAForecaster(
    config=config,
    seasonal=True,
    m=7,                    # Seasonal period (7 for weekly)
    max_p=5,                # Max AR order
    max_q=5,                # Max MA order
    max_d=2,                # Max differencing
    information_criterion='aic',
    stepwise=True           # Faster search
)

forecaster.fit(data)
forecast, conf_int = forecaster.predict()

# See selected parameters
metrics = forecaster.get_validation_metrics()
print(f"Selected order: {metrics['order']}")
print(f"Seasonal order: {metrics['seasonal_order']}")

3. Prophet Forecaster

Best for: Daily/weekly data with strong seasonality, holidays

from forecasting.models import ProphetForecaster

config = ForecastConfig(horizon=90)

forecaster = ProphetForecaster(
    config=config,
    growth='linear',                    # or 'logistic'
    changepoint_prior_scale=0.05,       # Trend flexibility
    seasonality_prior_scale=10.0,       # Seasonality strength
    seasonality_mode='additive',        # or 'multiplicative'
    yearly_seasonality='auto',
    weekly_seasonality='auto',
    daily_seasonality=False
)

forecaster.fit(data)
forecast, conf_int = forecaster.predict(horizon=90)

# Add custom seasonality
forecaster.add_seasonality(
    name='monthly',
    period=30.5,
    fourier_order=5
)

# Add holidays
forecaster.add_country_holidays('US')

4. LSTM Forecaster

Best for: Complex patterns, long sequences, multivariate data

from forecasting.models import LSTMForecaster

config = ForecastConfig(horizon=30, random_seed=42)

forecaster = LSTMForecaster(
    config=config,
    lookback=30,                # Use last 30 points
    hidden_size=64,             # LSTM hidden units
    num_layers=2,               # Number of LSTM layers
    dropout=0.2,                # Dropout rate
    use_attention=True,         # Attention mechanism
    learning_rate=0.001,
    batch_size=32,
    epochs=100,
    early_stopping_patience=10
)

# Fit with validation split
forecaster.fit(data, validation_split=0.2)

# Generate forecast
forecast, conf_int = forecaster.predict(horizon=30)

# Check training metrics
metrics = forecaster.get_validation_metrics()
print(f"Final validation loss: {metrics['final_val_loss']}")
print(f"Epochs trained: {metrics['epochs_trained']}")

# Plot training history
fig = forecaster.plot_training_history()

5. Ensemble Forecaster

Best for: Combining multiple models for better accuracy

from forecasting.models import (
    EnsembleForecaster,
    ARIMAForecaster,
    ProphetForecaster
)

config = ForecastConfig(horizon=30)

# Create individual models
arima = ARIMAForecaster(config, order=(2, 1, 2))
prophet = ProphetForecaster(config)

# Create ensemble
ensemble = EnsembleForecaster(
    config=config,
    models=[arima, prophet],
    weights=[0.6, 0.4],      # 60% ARIMA, 40% Prophet
    aggregation='weighted'    # 'mean', 'median', or 'weighted'
)

# Fit all models
ensemble.fit(data)

# Generate ensemble forecast
forecast, conf_int = ensemble.predict()

# Check model weights
weights = ensemble.get_model_weights()
print(weights)

---

🔧 Advanced Features

Time Series Decomposition

from forecasting.data.preprocessors import TimeSeriesDecomposer

# STL Decomposition
decomposer = TimeSeriesDecomposer(method='stl', period=7)
trend, seasonal, residual = decomposer.fit_transform(data)

# Classical Decomposition
decomposer = TimeSeriesDecomposer(method='classical', period=12)
components = decomposer.fit_transform(data)

# Reconstruct original series
reconstructed = decomposer.inverse_transform(trend, seasonal, residual)

Data Preprocessing

from forecasting.data.preprocessors import TimeSeriesPreprocessor

preprocessor = TimeSeriesPreprocessor(
    handle_missing='interpolate',
    handle_outliers=True,
    outlier_method='iqr',
    normalize=True,
    decompose=True,
    decomposition_method='stl'
)

# Preprocess data
processed_data = preprocessor.fit_transform(data)

# Inverse transform predictions
original_scale = preprocessor.inverse_transform(predictions)

Intermittent Demand Forecasting

from forecasting.data.special_cases import IntermittentDemandHandler

# For sparse/intermittent data (many zeros)
handler = IntermittentDemandHandler(method='sba')  # or 'croston', 'tsb'
handler.fit(sparse_data)
forecast = handler.predict(horizon=12)

New Product Forecasting

from forecasting.data.special_cases import NewProductHandler

# For products with little/no history
handler = NewProductHandler(method='bootstrap')
handler.fit(similar_products_data)
forecast = handler.predict(horizon=12)

Data Validation

from forecasting.data.validators import TimeSeriesValidator

validator = TimeSeriesValidator()

# Validate data quality
is_valid, errors = validator.validate(data)
if not is_valid:
    print("Validation errors:", errors)

# Check stationarity
is_stationary, p_value = validator.check_stationarity(data)
print(f"Stationary: {is_stationary}, p-value: {p_value}")

# Detect outliers
outliers = validator.detect_outliers(data, method='iqr')
print(f"Found {len(outliers)} outliers")

# Check seasonality
has_seasonality, period = validator.detect_seasonality(data)
print(f"Seasonality: {has_seasonality}, period: {period}")

---

📊 Model Comparison Example

import numpy as np
from forecasting.models import ARIMAForecaster, ProphetForecaster, LSTMForecaster
from forecasting.core.config import ForecastConfig

# Split data
train_data = data[:-30]
test_data = data[-30:]

config = ForecastConfig(horizon=30)

# Train multiple models
models = {
    'ARIMA': ARIMAForecaster(config, order=(2, 1, 2)),
    'Prophet': ProphetForecaster(config),
    'LSTM': LSTMForecaster(config, lookback=30, epochs=50)
}

results = {}
for name, model in models.items():
    model.fit(train_data)
    forecast, _ = model.predict()
    mae = np.mean(np.abs(forecast.values - test_data.values))
    results[name] = mae
    print(f"{name} MAE: {mae:.2f}")

# Find best model
best_model = min(results, key=results.get)
print(f"\nBest model: {best_model}")

---

💾 Model Persistence

# Save model
forecaster.save_model('my_model.pkl')

# Load model
from forecasting.models import ARIMAForecaster
loaded_forecaster = ARIMAForecaster.load_model('my_model.pkl')

# Use loaded model
forecast, conf_int = loaded_forecaster.predict(horizon=30)

---

🎨 Visualization

import matplotlib.pyplot as plt

# Plot forecast
plt.figure(figsize=(12, 6))
plt.plot(data.index, data.values, label='Historical', color='blue')
plt.plot(forecast.index, forecast.values, label='Forecast', color='red')
plt.fill_between(
    conf_int.index,
    conf_int['lower'],
    conf_int['upper'],
    alpha=0.3,
    color='red',
    label='95% CI'
)
plt.legend()
plt.title('Time Series Forecast')
plt.xlabel('Date')
plt.ylabel('Value')
plt.grid(True)
plt.show()

---

📖 Configuration Options

from forecasting.core.config import ForecastConfig, PreprocessingConfig

# Forecast configuration
config = ForecastConfig(
    horizon=30,                    # Forecast periods
    confidence_level=0.95,         # Confidence interval level
    frequency='D',                 # Data frequency
    random_seed=42,                # Reproducibility
    preprocessing=PreprocessingConfig(
        handle_missing='interpolate',
        handle_outliers=True,
        normalize=True,
        decompose=True,
        decomposition_method='stl',
        seasonal_period=7
    )
)

---

🚀 Performance Tips

1. For Large Datasets

# Use Auto-ARIMA with stepwise search
forecaster = AutoARIMAForecaster(config, stepwise=True, max_p=3, max_q=3)

2. For Fast Training

# Reduce LSTM epochs and use early stopping
forecaster = LSTMForecaster(
    config,
    epochs=50,
    early_stopping_patience=5,
    batch_size=64
)

3. For Better Accuracy

# Use ensemble with multiple models
ensemble = EnsembleForecaster(
    config,
    models=[arima, prophet, lstm],
    aggregation='weighted'
)

---

🔍 Troubleshooting

Issue: "Model not converging"

# Solution: Adjust parameters or preprocess data
from forecasting.data.preprocessors import TimeSeriesPreprocessor

preprocessor = TimeSeriesPreprocessor(
    normalize=True,
    handle_outliers=True
)
clean_data = preprocessor.fit_transform(data)

Issue: "Poor forecast accuracy"

# Solution: Try ensemble or different model
ensemble = EnsembleForecaster(
    config,
    models=[model1, model2, model3],
    aggregation='mean'
)

Issue: "LSTM training too slow"

# Solution: Reduce complexity or use GPU
forecaster = LSTMForecaster(
    config,
    hidden_size=32,      # Reduce from 64
    num_layers=1,        # Reduce from 2
    epochs=30,           # Reduce from 100
    device='cuda'        # Use GPU if available
)

---

📦 Dependencies

Core dependencies (automatically installed):

• numpy>=1.24.0
• pandas>=2.0.0
• scikit-learn>=1.3.0
• statsmodels>=0.14.0
• torch>=2.0.0
• prophet>=1.1.0
• pmdarima>=2.0.0

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📄 License

This project is licensed under the MIT License.

---

📧 Contact

Author: Surya Tripathi
Email: [e-mail]

---

🙏 Acknowledgments

Built with:

• statsmodels for ARIMA
• Prophet by Facebook
• PyTorch for LSTM
• pmdarima for Auto-ARIMA

---

📚 Additional Resources

• Complete Examples
• Quick Start Guide
• Migration Guide
• Implementation Status

---

Made with ❤️ by Bob