# Coptic - Advanced Time Series Forecasting Library
[](https://badge.fury.io/py/coptic)
[](https://pypi.org/project/coptic/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/yourusername/coptic/actions)
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)
```bash
pip install coptic
```
### From Source
```bash
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
```python
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
```python
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
```python
forecaster = CopticForecaster(
model_type="randomforest",
n_estimators=100,
max_depth=None,
random_state=42
)
```
### 2. XGBoost
```python
forecaster = CopticForecaster(
model_type="xgboost",
n_estimators=100,
learning_rate=0.1,
max_depth=6,
early_stopping_rounds=10
)
```
### 3. Prophet
```python
forecaster = CopticForecaster(
model_type="prophet",
seasonality_mode='additive',
yearly_seasonality=True,
weekly_seasonality=True
)
```
### 4. ARIMA
```python
forecaster = CopticForecaster(
model_type="arima",
seasonal=True,
m=12, # seasonal period
max_p=3,
max_q=3
)
```
## 📊 Data Preprocessing
### Data Cleaning
```python
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
```python
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
```python
# 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
```python
# 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
```python
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](examples/) for detailed tutorials:
- [Getting Started with Coptic](examples/01_getting_started.ipynb)
- [Sales Forecasting Example](examples/02_sales_forecasting.ipynb)
- [Model Comparison Tutorial](examples/03_model_comparison.ipynb)
- [Advanced Feature Engineering](examples/04_feature_engineering.ipynb)
- [Custom Seasonality with Prophet](examples/05_prophet_seasonality.ipynb)
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
git clone https://github.com/yourusername/coptic.git
cd coptic
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest tests/
```
### Code Formatting
```bash
black coptic/
flake8 coptic/
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🆘 Support
- **Documentation**: [coptic.readthedocs.io](https://coptic.readthedocs.io)
- **Issues**: [GitHub Issues](https://github.com/yourusername/coptic/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/coptic/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**
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/coptic",
"name": "coptic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "time-series, forecasting, machine-learning, prophet, arima, xgboost, random-forest",
"author": "Coptic Team",
"author_email": "Coptic Team <contact@coptic-forecasting.com>",
"download_url": "https://files.pythonhosted.org/packages/3a/95/9f5ac1905a2b81f9b2f24f1020a4f2f8e8daf509b2a33617391664b5fe57/coptic-0.1.0.tar.gz",
"platform": null,
"description": "# Coptic - Advanced Time Series Forecasting Library\r\n\r\n[](https://badge.fury.io/py/coptic)\r\n[](https://pypi.org/project/coptic/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://github.com/yourusername/coptic/actions)\r\n\r\nA 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.\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- **Multiple Algorithms**: Random Forest, XGBoost, Prophet, and ARIMA models\r\n- **Unified API**: Single interface for all forecasting models\r\n- **Automatic Feature Engineering**: Time-based features, lags, rolling statistics\r\n- **Data Preprocessing**: Built-in data cleaning and outlier detection\r\n- **Comprehensive Metrics**: MAE, RMSE, MAPE, SMAPE, MASE, and more\r\n- **Visualization Tools**: Forecast plots, residual analysis, feature importance\r\n- **Easy Model Comparison**: Compare multiple models effortlessly\r\n- **Model Persistence**: Save and load trained models\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install coptic\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/coptic.git\r\ncd coptic\r\npip install -e .\r\n```\r\n\r\n### Dependencies\r\n\r\nCoptic requires Python 3.7+ and the following packages:\r\n- numpy >= 1.20.0\r\n- pandas >= 1.2.0\r\n- scikit-learn >= 0.24.0\r\n- matplotlib >= 3.3.0\r\n- xgboost >= 1.3.0\r\n- prophet >= 1.0.0\r\n- pmdarima >= 1.8.0\r\n- statsmodels >= 0.12.0\r\n\r\n## \ud83c\udfaf Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nimport pandas as pd\r\nfrom coptic import CopticForecaster\r\n\r\n# Load your time series data\r\ndf = pd.read_csv('your_data.csv')\r\n# Ensure your data has date and target columns\r\n\r\n# Create forecaster\r\nforecaster = CopticForecaster(model_type=\"randomforest\")\r\n\r\n# Fit the model\r\nforecaster.fit(df, date_col=\"date\", target_col=\"sales\")\r\n\r\n# Generate forecasts\r\nforecast = forecaster.predict(periods=30)\r\n\r\n# Plot results\r\nforecaster.plot()\r\n\r\n# Evaluate performance (if you have test data)\r\ntest_metrics = forecaster.evaluate(test_df)\r\nprint(test_metrics)\r\n```\r\n\r\n### Advanced Usage\r\n\r\n```python\r\nfrom coptic import CopticForecaster\r\nfrom coptic.preprocessing import DataCleaner\r\n\r\n# Clean your data first\r\ncleaner = DataCleaner(remove_outliers=True, outlier_method='iqr')\r\nclean_df = cleaner.clean(df, date_col=\"date\", target_col=\"sales\")\r\n\r\n# Create forecaster with custom parameters\r\nforecaster = CopticForecaster(\r\n model_type=\"xgboost\",\r\n n_estimators=200,\r\n learning_rate=0.1,\r\n max_depth=6\r\n)\r\n\r\n# Fit with validation data for early stopping\r\nforecaster.fit(\r\n clean_df, \r\n date_col=\"date\", \r\n target_col=\"sales\",\r\n validation_data=val_df\r\n)\r\n\r\n# Generate forecasts with confidence intervals\r\nforecast = forecaster.predict(periods=60, freq=\"D\")\r\n\r\n# Plot feature importance (for tree-based models)\r\nforecaster.plot_feature_importance()\r\n\r\n# Save the model\r\nforecaster.save(\"my_forecaster.pkl\")\r\n\r\n# Load the model later\r\nloaded_forecaster = CopticForecaster.load(\"my_forecaster.pkl\")\r\n```\r\n\r\n## \ud83d\udd27 Supported Models\r\n\r\n### 1. Random Forest\r\n```python\r\nforecaster = CopticForecaster(\r\n model_type=\"randomforest\",\r\n n_estimators=100,\r\n max_depth=None,\r\n random_state=42\r\n)\r\n```\r\n\r\n### 2. XGBoost\r\n```python\r\nforecaster = CopticForecaster(\r\n model_type=\"xgboost\",\r\n n_estimators=100,\r\n learning_rate=0.1,\r\n max_depth=6,\r\n early_stopping_rounds=10\r\n)\r\n```\r\n\r\n### 3. Prophet\r\n```python\r\nforecaster = CopticForecaster(\r\n model_type=\"prophet\",\r\n seasonality_mode='additive',\r\n yearly_seasonality=True,\r\n weekly_seasonality=True\r\n)\r\n```\r\n\r\n### 4. ARIMA\r\n```python\r\nforecaster = CopticForecaster(\r\n model_type=\"arima\",\r\n seasonal=True,\r\n m=12, # seasonal period\r\n max_p=3,\r\n max_q=3\r\n)\r\n```\r\n\r\n## \ud83d\udcca Data Preprocessing\r\n\r\n### Data Cleaning\r\n```python\r\nfrom coptic.preprocessing import DataCleaner\r\n\r\ncleaner = DataCleaner(\r\n remove_outliers=True,\r\n outlier_method='iqr', # 'iqr', 'zscore', 'isolation_forest'\r\n fill_method='interpolate' # 'interpolate', 'forward_fill', 'mean'\r\n)\r\n\r\nclean_df = cleaner.clean(df, date_col=\"date\", target_col=\"sales\")\r\n\r\n# Get data quality report\r\nquality_report = cleaner.get_data_quality_report(df, \"date\", \"sales\")\r\n```\r\n\r\n### Feature Engineering\r\n```python\r\nfrom coptic.preprocessing import FeatureGenerator\r\n\r\nfeature_gen = FeatureGenerator(\r\n add_lags=True,\r\n add_seasonality=True,\r\n add_statistics=True,\r\n lag_periods=[1, 7, 30],\r\n rolling_windows=[7, 30, 90]\r\n)\r\n\r\nX, y = feature_gen.generate_features(df, \"date\", \"sales\")\r\n```\r\n\r\n## \ud83d\udcc8 Evaluation and Visualization\r\n\r\n### Comprehensive Metrics\r\n```python\r\n# Get detailed metrics\r\nmetrics = forecaster.evaluate(test_df)\r\nprint(f\"MAE: {metrics['mae']:.2f}\")\r\nprint(f\"RMSE: {metrics['rmse']:.2f}\")\r\nprint(f\"MAPE: {metrics['mape']:.2f}%\")\r\nprint(f\"R\u00b2: {metrics['r2']:.3f}\")\r\n\r\n# Get forecast accuracy summary\r\nfrom coptic.utils.metrics import forecast_accuracy_summary\r\nsummary = forecast_accuracy_summary(metrics)\r\nprint(summary)\r\n```\r\n\r\n### Visualization\r\n```python\r\n# Basic forecast plot\r\nforecaster.plot()\r\n\r\n# Plot with custom settings\r\nforecaster.plot(plot_components=True, figsize=(15, 8))\r\n\r\n# Residual analysis\r\nfrom coptic.utils.plot import plot_residuals\r\nplot_residuals(y_true, y_pred, dates=test_dates)\r\n\r\n# Compare multiple models\r\nfrom coptic.utils.plot import plot_multiple_forecasts\r\nforecasts_dict = {\r\n 'Random Forest': rf_forecast,\r\n 'XGBoost': xgb_forecast,\r\n 'Prophet': prophet_forecast\r\n}\r\nplot_multiple_forecasts(train_df, forecasts_dict)\r\n```\r\n\r\n## \ud83d\udd0d Model Comparison\r\n\r\n```python\r\nmodels = {\r\n 'RandomForest': CopticForecaster(model_type=\"randomforest\"),\r\n 'XGBoost': CopticForecaster(model_type=\"xgboost\"),\r\n 'Prophet': CopticForecaster(model_type=\"prophet\"),\r\n 'ARIMA': CopticForecaster(model_type=\"arima\")\r\n}\r\n\r\nresults = {}\r\nfor name, model in models.items():\r\n model.fit(train_df, date_col=\"date\", target_col=\"sales\")\r\n forecast = model.predict(periods=30)\r\n metrics = model.evaluate(test_df)\r\n results[name] = metrics\r\n\r\n# Compare results\r\ncomparison_df = pd.DataFrame(results).T\r\nprint(comparison_df[['mae', 'rmse', 'mape', 'r2']])\r\n```\r\n\r\n## \ud83d\udcda Examples\r\n\r\nCheck out our [example notebooks](examples/) for detailed tutorials:\r\n\r\n- [Getting Started with Coptic](examples/01_getting_started.ipynb)\r\n- [Sales Forecasting Example](examples/02_sales_forecasting.ipynb)\r\n- [Model Comparison Tutorial](examples/03_model_comparison.ipynb)\r\n- [Advanced Feature Engineering](examples/04_feature_engineering.ipynb)\r\n- [Custom Seasonality with Prophet](examples/05_prophet_seasonality.ipynb)\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\r\n\r\n### Development Setup\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/coptic.git\r\ncd coptic\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\npytest tests/\r\n```\r\n\r\n### Code Formatting\r\n\r\n```bash\r\nblack coptic/\r\nflake8 coptic/\r\n```\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83c\udd98 Support\r\n\r\n- **Documentation**: [coptic.readthedocs.io](https://coptic.readthedocs.io)\r\n- **Issues**: [GitHub Issues](https://github.com/yourusername/coptic/issues)\r\n- **Discussions**: [GitHub Discussions](https://github.com/yourusername/coptic/discussions)\r\n\r\n## \ud83c\udf89 Acknowledgments\r\n\r\n- Built on top of excellent libraries: scikit-learn, XGBoost, Prophet, pmdarima\r\n- Inspired by the forecasting community and real-world use cases\r\n- Thanks to all contributors and users\r\n\r\n## \ud83d\ude80 What's Next?\r\n\r\n- [ ] Deep learning models (LSTM, Transformer)\r\n- [ ] Automated hyperparameter optimization\r\n- [ ] Ensemble methods\r\n- [ ] More preprocessing options\r\n- [ ] Streaming forecasts\r\n- [ ] Cloud deployment tools\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f by the Coptic Team**\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Advanced time series forecasting library with multiple algorithms",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/yourusername/coptic/issues",
"Documentation": "https://coptic.readthedocs.io",
"Homepage": "https://github.com/yourusername/coptic",
"Repository": "https://github.com/yourusername/coptic.git"
},
"split_keywords": [
"time-series",
" forecasting",
" machine-learning",
" prophet",
" arima",
" xgboost",
" random-forest"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "290c0aace520dde39f6827158871d3e68917b0d7ab140ff5063103a26fd4a383",
"md5": "59d68b1b89937646fbf27bb4423f9ea7",
"sha256": "62e7aa17d7e88314c2dc294fbcf3f899eadaad6c2e7a2210918135bbb30c26aa"
},
"downloads": -1,
"filename": "coptic-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "59d68b1b89937646fbf27bb4423f9ea7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 40456,
"upload_time": "2025-07-28T07:24:29",
"upload_time_iso_8601": "2025-07-28T07:24:29.357674Z",
"url": "https://files.pythonhosted.org/packages/29/0c/0aace520dde39f6827158871d3e68917b0d7ab140ff5063103a26fd4a383/coptic-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3a959f5ac1905a2b81f9b2f24f1020a4f2f8e8daf509b2a33617391664b5fe57",
"md5": "436ededf471cd89c5f7d15f2c433d3fd",
"sha256": "6e2a0e03885a5b9b409a00660b585ecee7a1a1e402e123480a1d00b7ba87c730"
},
"downloads": -1,
"filename": "coptic-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "436ededf471cd89c5f7d15f2c433d3fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 73878,
"upload_time": "2025-07-28T07:24:31",
"upload_time_iso_8601": "2025-07-28T07:24:31.176907Z",
"url": "https://files.pythonhosted.org/packages/3a/95/9f5ac1905a2b81f9b2f24f1020a4f2f8e8daf509b2a33617391664b5fe57/coptic-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 07:24:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "coptic",
"github_not_found": true,
"lcname": "coptic"
}
JSON
