coptic 0.1.0

Advanced time series forecasting library with multiple algorithms

Coptic - Advanced Time Series Forecasting Library

A comprehensive Python library for time series forecasting with multiple algorithms including Random Forest, XGBoost, Prophet, and ARIMA. Coptic provides a unified interface for different forecasting models with automatic feature engineering, data preprocessing, and comprehensive evaluation metrics.

🚀 Features

• Multiple Algorithms: Random Forest, XGBoost, Prophet, and ARIMA models
• Unified API: Single interface for all forecasting models
• Automatic Feature Engineering: Time-based features, lags, rolling statistics
• Data Preprocessing: Built-in data cleaning and outlier detection
• Comprehensive Metrics: MAE, RMSE, MAPE, SMAPE, MASE, and more
• Visualization Tools: Forecast plots, residual analysis, feature importance
• Easy Model Comparison: Compare multiple models effortlessly
• Model Persistence: Save and load trained models

📦 Installation

From PyPI (Recommended)

pip install coptic

From Source

git clone https://github.com/yourusername/coptic.git
cd coptic
pip install -e .

Dependencies

Coptic requires Python 3.7+ and the following packages:

• numpy >= 1.20.0
• pandas >= 1.2.0
• scikit-learn >= 0.24.0
• matplotlib >= 3.3.0
• xgboost >= 1.3.0
• prophet >= 1.0.0
• pmdarima >= 1.8.0
• statsmodels >= 0.12.0

🎯 Quick Start

Basic Usage

import pandas as pd
from coptic import CopticForecaster

# Load your time series data
df = pd.read_csv('your_data.csv')
# Ensure your data has date and target columns

# Create forecaster
forecaster = CopticForecaster(model_type="randomforest")

# Fit the model
forecaster.fit(df, date_col="date", target_col="sales")

# Generate forecasts
forecast = forecaster.predict(periods=30)

# Plot results
forecaster.plot()

# Evaluate performance (if you have test data)
test_metrics = forecaster.evaluate(test_df)
print(test_metrics)

Advanced Usage

from coptic import CopticForecaster
from coptic.preprocessing import DataCleaner

# Clean your data first
cleaner = DataCleaner(remove_outliers=True, outlier_method='iqr')
clean_df = cleaner.clean(df, date_col="date", target_col="sales")

# Create forecaster with custom parameters
forecaster = CopticForecaster(
    model_type="xgboost",
    n_estimators=200,
    learning_rate=0.1,
    max_depth=6
)

# Fit with validation data for early stopping
forecaster.fit(
    clean_df, 
    date_col="date", 
    target_col="sales",
    validation_data=val_df
)

# Generate forecasts with confidence intervals
forecast = forecaster.predict(periods=60, freq="D")

# Plot feature importance (for tree-based models)
forecaster.plot_feature_importance()

# Save the model
forecaster.save("my_forecaster.pkl")

# Load the model later
loaded_forecaster = CopticForecaster.load("my_forecaster.pkl")

🔧 Supported Models

1. Random Forest

forecaster = CopticForecaster(
    model_type="randomforest",
    n_estimators=100,
    max_depth=None,
    random_state=42
)

2. XGBoost

forecaster = CopticForecaster(
    model_type="xgboost",
    n_estimators=100,
    learning_rate=0.1,
    max_depth=6,
    early_stopping_rounds=10
)

3. Prophet

forecaster = CopticForecaster(
    model_type="prophet",
    seasonality_mode='additive',
    yearly_seasonality=True,
    weekly_seasonality=True
)

4. ARIMA

forecaster = CopticForecaster(
    model_type="arima",
    seasonal=True,
    m=12,  # seasonal period
    max_p=3,
    max_q=3
)

📊 Data Preprocessing

Data Cleaning

from coptic.preprocessing import DataCleaner

cleaner = DataCleaner(
    remove_outliers=True,
    outlier_method='iqr',  # 'iqr', 'zscore', 'isolation_forest'
    fill_method='interpolate'  # 'interpolate', 'forward_fill', 'mean'
)

clean_df = cleaner.clean(df, date_col="date", target_col="sales")

# Get data quality report
quality_report = cleaner.get_data_quality_report(df, "date", "sales")

Feature Engineering

from coptic.preprocessing import FeatureGenerator

feature_gen = FeatureGenerator(
    add_lags=True,
    add_seasonality=True,
    add_statistics=True,
    lag_periods=[1, 7, 30],
    rolling_windows=[7, 30, 90]
)

X, y = feature_gen.generate_features(df, "date", "sales")

📈 Evaluation and Visualization

Comprehensive Metrics

# Get detailed metrics
metrics = forecaster.evaluate(test_df)
print(f"MAE: {metrics['mae']:.2f}")
print(f"RMSE: {metrics['rmse']:.2f}")
print(f"MAPE: {metrics['mape']:.2f}%")
print(f"R²: {metrics['r2']:.3f}")

# Get forecast accuracy summary
from coptic.utils.metrics import forecast_accuracy_summary
summary = forecast_accuracy_summary(metrics)
print(summary)

Visualization

# Basic forecast plot
forecaster.plot()

# Plot with custom settings
forecaster.plot(plot_components=True, figsize=(15, 8))

# Residual analysis
from coptic.utils.plot import plot_residuals
plot_residuals(y_true, y_pred, dates=test_dates)

# Compare multiple models
from coptic.utils.plot import plot_multiple_forecasts
forecasts_dict = {
    'Random Forest': rf_forecast,
    'XGBoost': xgb_forecast,
    'Prophet': prophet_forecast
}
plot_multiple_forecasts(train_df, forecasts_dict)

🔍 Model Comparison

models = {
    'RandomForest': CopticForecaster(model_type="randomforest"),
    'XGBoost': CopticForecaster(model_type="xgboost"),
    'Prophet': CopticForecaster(model_type="prophet"),
    'ARIMA': CopticForecaster(model_type="arima")
}

results = {}
for name, model in models.items():
    model.fit(train_df, date_col="date", target_col="sales")
    forecast = model.predict(periods=30)
    metrics = model.evaluate(test_df)
    results[name] = metrics

# Compare results
comparison_df = pd.DataFrame(results).T
print(comparison_df[['mae', 'rmse', 'mape', 'r2']])

📚 Examples

Check out our example notebooks for detailed tutorials:

• Getting Started with Coptic
• Sales Forecasting Example
• Model Comparison Tutorial
• Advanced Feature Engineering
• Custom Seasonality with Prophet

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/yourusername/coptic.git
cd coptic
pip install -e ".[dev]"

Running Tests

pytest tests/

Code Formatting

black coptic/
flake8 coptic/

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: coptic.readthedocs.io
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🎉 Acknowledgments

• Built on top of excellent libraries: scikit-learn, XGBoost, Prophet, pmdarima
• Inspired by the forecasting community and real-world use cases
• Thanks to all contributors and users

🚀 What's Next?

• Deep learning models (LSTM, Transformer)
• Automated hyperparameter optimization
• Ensemble methods
• More preprocessing options
• Streaming forecasts
• Cloud deployment tools

---

Made with ❤️ by the Coptic Team