| Name | optitime-prophet JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A Prophet-inspired forecasting library distilling OptiWisdom OptiScorer insights into autoregressive, changepoint, and diagnostic enhancements. |
| upload_time | 2025-10-22 11:52:22 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
forecasting
prophet
time-series
autoregressive
python
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# OptiProphet
OptiProphet is a from-scratch, Prophet-inspired forecasting library written entirely in Python. It blends classic trend/seasonality decomposition with autoregressive and moving-average enrichments, dynamic changepoint detection, and extensive diagnostics so you can trust the signals hidden inside your time series. The project is engineered with upcoming PyPI distribution in mind and was crafted by **Şadi Evren Şeker** ([@bilgisayarkavramlari](https://github.com/bilgisayarkavramlari)) with direct guidance from OptiWisdom's OptiScorer experimentation track.
> 📌 **OptiScorer heritage** – Many of the decomposition, scoring, and robustness heuristics originate from OptiWisdom's OptiScorer research programmes. OptiProphet packages those lessons into an accessible, open Python toolkit while crediting the foundational OptiScorer work.
## Why OptiProphet?
| Capability | What it gives you |
| --- | --- |
| **Prophet-style trend & seasonality** | Piecewise-linear trend with automatic changepoints, additive seasonalities via Fourier terms. |
| **AR/MA enrichments** | Captures short-term autocorrelation by reusing recent values and residual shocks. |
| **External regressors** | Inject business covariates and time-varying interactions directly into the model. |
| **Uncertainty modelling** | Quantile-aware prediction intervals derived from in-sample dispersion. |
| **Backtesting & diagnostics** | Rolling-origin backtests, outlier surfacing, component strength analysis, and performance metrics. |
| **Robustness toolkit** | Automatic interpolation for sparse data, changepoint detection, and outlier reporting to survive structural breaks. |
All logic is implemented without relying on Prophet or other probabilistic frameworks—only `numpy` and `pandas` are required.
## Installation
The project uses a standard `pyproject.toml` layout so it is ready for PyPI packaging.
```bash
pip install optitime-prophet # once published
```
For local development:
```bash
git clone https://github.com/bilgisayarkavramlari/optitime.git
cd optitime
pip install -e .
```
## Quick start
```python
import pandas as pd
from optitime import OptiProphet
# Load a time series with columns ds (timestamp) and y (value)
data = pd.read_csv("sales.csv", parse_dates=["ds"])
model = OptiProphet(
n_changepoints=20,
ar_order=3,
ma_order=2,
regressors=["promo", "price_index"],
)
model.fit(data)
# Forecast 30 periods into the future
future = model.make_future_dataframe(periods=30, include_history=False)
future["promo"] = 0 # supply regressors for the horizon
future["price_index"] = 1.0
forecast = model.predict(future)
print(forecast.tail())
# The returned frame includes component contributions plus quantile columns
# (e.g. `yhat_q0.10`, `yhat_q0.90`) alongside `yhat_lower`/`yhat_upper` bounds.
# Disable component columns and intervals when you just need point forecasts
lean_forecast = model.predict(
future,
include_components=False,
include_uncertainty=False,
)
print(lean_forecast.tail())
# Inspect decomposition of the training history
components = model.history_components()
print(components.head())
# Evaluate rolling-origin backtest
cv = model.backtest(horizon=14, step=7, strategy="sliding", window=36)
print(cv.describe())
# Fetch detailed diagnostics & quality report
print(model.report())
```
## Bundled datasets
OptiProphet ships with a handful of classic forecasting benchmarks so you can experiment without hunting for data files. Use
`optitime.available_datasets()` to discover what is included and `optitime.load_dataset()` to load a `pandas.DataFrame` that is
ready for modelling.
```python
from optitime import load_dataset, available_datasets
print(available_datasets())
air = load_dataset("air_passengers")
print(air.head())
```
The current catalogue contains:
| Name | Description | Frequency |
| --- | --- | --- |
| `air_passengers` | Monthly totals of international airline passengers (1949-1960). | Monthly |
| `airlines_traffic` | Monthly airline passenger statistics curated from OptiWisdom OptiScorer analyses inspired by the Kaggle Airlines Traffic Passenger Statistics dataset. | Monthly |
| `shampoo_sales` | Monthly shampoo sales in millions of units (1901-1903). | Monthly |
| `us_acc_deaths` | Monthly accidental deaths in the United States (1973-1978). | Monthly |
## Parameter control summary
- Use the `historical_components` constructor argument and the
`history_components()` method to expose or hide historical trend, seasonality,
regressor, and residual columns on demand.
- Call `predict(include_components=False, include_uncertainty=False)` to obtain
a lightweight point forecast for low-latency services.
- Apply selective overrides such as
`predict(component_overrides={"seasonality": False})` when only certain
contributors should be hidden.
- Compare retraining schemes with `backtest(strategy="sliding", window=48)` or
`backtest(strategy="anchored")`.
- The `optitime.BACKTEST_STRATEGIES` constant enumerates every supported
backtest strategy name.
See [`docs/parameters.md`](docs/parameters.md) for a deeper explanation of each
parameter and how it impacts the model.
## Local smoke test
After installing the project you can immediately verify everything is
working by running the bundled sales walkthrough. It loads
`tests/sales.csv`, trains an `OptiProphet` instance, and prints forecasts,
component decompositions, and a rolling backtest summary:
```bash
python tests/run_sales_example.py
```
The output demonstrates how the OptiScorer-inspired diagnostics surface
trend, seasonality, residuals, and interval bounds on a realistic retail
series without any extra setup.
## Visual scenario walkthrough
Recreate the OptiWisdom OptiScorer-inspired parameter sweep on the Kaggle-based
`airlines_traffic` dataset by installing the optional plotting dependency and
running the helper script:
```bash
pip install optitime-prophet[visuals]
python tests/run_airlines_visuals.py
```
The script writes forecast and RMSE visualisations for each backtest strategy
and component setting to the `tests/` directory (`airlines_forecast_*.png`,
`airlines_backtest_*.png`).
## Feature highlights
- **Bundled benchmarks**: Access classic datasets such as AirPassengers, Shampoo Sales, and US Accidental Deaths via
`optitime.load_dataset()` for tutorials, demos, and regression testing.
- **Bidirectional insight**: `history_components()` exposes historical trend, seasonality, residual, and regressor effects, while `predict()` projects the same structure into the future.
- **Backtest ready**: `backtest()` re-fits the model with configurable strategies (expanding, sliding, anchored) to quantify generalisation metrics (MAE, RMSE, MAPE, R²) on rolling horizons.
- **Error-aware**: Empty frames, missing columns, low sample counts, or under-performing fits surface as descriptive exceptions such as `DataValidationError` or `ForecastQualityError`.
- **Structural resilience**: The changepoint detector uses rolling z-scores on second derivatives to adapt to trend shifts. Large residual spikes are flagged as outliers in the diagnostic report.
- **Quantile intervals**: Forecasts include configurable lower/upper bounds (`interval_width` or explicit `quantiles`) using in-sample dispersion, while dedicated columns such as `yhat_q0.10` and `yhat_q0.90` expose raw quantile estimates for downstream pipelines.
- **Autoregression & shocks**: Short-term dynamics are captured with configurable AR and MA lags, automatically rolling forward during forecasting.
- **External signals**: Provide arbitrary regressors during both fit and predict phases to blend business drivers with the statistical core.
- **Parameterized component control**: Manage trend, seasonality, regressor, and
residual columns for both historical analyses and future forecasts on a
per-call basis, including the ability to toggle confidence intervals.
## Error handling
OptiProphet raises explicit errors for problematic scenarios:
- `DataValidationError`: empty dataframes, missing columns, or NaN-heavy features.
- `ModelNotFitError`: methods invoked before `fit()` completes.
- `ForecastQualityError`: triggered when R² drops below the configured threshold or the MAPE exceeds the acceptable ceiling.
These exceptions include actionable messages so automated pipelines (including GitHub Actions or CI) can fail fast without leaving stale artefacts.
## Preparing for PyPI
1. Update `pyproject.toml` metadata if publishing under a different namespace.
2. Create a source distribution and wheel: `python -m build`.
3. Upload with `twine upload dist/*` once credentials are configured.
## Documentation
- [API overview](docs/api.md)
- [Parameter guide](docs/parameters.md)
## Development roadmap
- Bayesian residual bootstrapping for richer predictive distributions.
- Optional Torch/NumPyro backends for transfer learning under sparse conditions.
- Expanded diagnostics dashboard (streamlit) for interactive exploration.
## Contributing & PR workflow
If you plan to contribute back via pull requests, make sure your local clone
knows where to send them. Configure the Git remote once after cloning:
```bash
git remote add origin https://github.com/bilgisayarkavramlari/optitime.git
git fetch origin
```
The `make_pr` helper used in this project depends on the remote named
`origin`; without it the PR tooling will raise a “failed to create new pr”
error. After the remote is configured you can run the usual contribution
pipeline:
```bash
python -m compileall src
git status
git commit -am "Describe your change"
make_pr
```
This ensures the automation has enough repository context to open a pull
request successfully.
## Maintainer & contact
OptiProphet is maintained by Şadi Evren Şeker. For enquiries or partnership opportunities please reach out via **optitime@optiwisdom.com**.
## License
Released under the MIT License.
## References
- Taylor, S. J., & Letham, B. (2018). *Forecasting at scale*. The American Statistician, 72(1), 37-45.
- Box, G. E. P., Jenkins, G. M., Reinsel, G. C., & Ljung, G. M. (2015). *Time Series Analysis: Forecasting and Control* (5th ed.). Wiley.
- Hyndman, R. J., & Athanasopoulos, G. (2021). *Forecasting: Principles and Practice* (3rd ed.). OTexts.
Raw data
{
"_id": null,
"home_page": null,
"name": "optitime-prophet",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "forecasting, prophet, time-series, autoregressive, python",
"author": null,
"author_email": "\u015eadi Evren \u015eeker <optitime@optiwisdom.com>",
"download_url": "https://files.pythonhosted.org/packages/5b/42/9477c4c5c081cea5ff10bb0b8be14478efec80ebdf46e55c6cb5dba955bf/optitime_prophet-0.1.0.tar.gz",
"platform": null,
"description": "# OptiProphet\n\nOptiProphet is a from-scratch, Prophet-inspired forecasting library written entirely in Python. It blends classic trend/seasonality decomposition with autoregressive and moving-average enrichments, dynamic changepoint detection, and extensive diagnostics so you can trust the signals hidden inside your time series. The project is engineered with upcoming PyPI distribution in mind and was crafted by **\u015eadi Evren \u015eeker** ([@bilgisayarkavramlari](https://github.com/bilgisayarkavramlari)) with direct guidance from OptiWisdom's OptiScorer experimentation track.\n\n> \ud83d\udccc **OptiScorer heritage** \u2013 Many of the decomposition, scoring, and robustness heuristics originate from OptiWisdom's OptiScorer research programmes. OptiProphet packages those lessons into an accessible, open Python toolkit while crediting the foundational OptiScorer work.\n\n## Why OptiProphet?\n\n| Capability | What it gives you |\n| --- | --- |\n| **Prophet-style trend & seasonality** | Piecewise-linear trend with automatic changepoints, additive seasonalities via Fourier terms. |\n| **AR/MA enrichments** | Captures short-term autocorrelation by reusing recent values and residual shocks. |\n| **External regressors** | Inject business covariates and time-varying interactions directly into the model. |\n| **Uncertainty modelling** | Quantile-aware prediction intervals derived from in-sample dispersion. |\n| **Backtesting & diagnostics** | Rolling-origin backtests, outlier surfacing, component strength analysis, and performance metrics. |\n| **Robustness toolkit** | Automatic interpolation for sparse data, changepoint detection, and outlier reporting to survive structural breaks. |\n\nAll logic is implemented without relying on Prophet or other probabilistic frameworks\u2014only `numpy` and `pandas` are required.\n\n## Installation\n\nThe project uses a standard `pyproject.toml` layout so it is ready for PyPI packaging.\n\n```bash\npip install optitime-prophet # once published\n```\n\nFor local development:\n\n```bash\ngit clone https://github.com/bilgisayarkavramlari/optitime.git\ncd optitime\npip install -e .\n```\n\n## Quick start\n\n```python\nimport pandas as pd\nfrom optitime import OptiProphet\n\n# Load a time series with columns ds (timestamp) and y (value)\ndata = pd.read_csv(\"sales.csv\", parse_dates=[\"ds\"])\n\nmodel = OptiProphet(\n n_changepoints=20,\n ar_order=3,\n ma_order=2,\n regressors=[\"promo\", \"price_index\"],\n)\n\nmodel.fit(data)\n\n# Forecast 30 periods into the future\nfuture = model.make_future_dataframe(periods=30, include_history=False)\nfuture[\"promo\"] = 0 # supply regressors for the horizon\nfuture[\"price_index\"] = 1.0\nforecast = model.predict(future)\nprint(forecast.tail())\n\n# The returned frame includes component contributions plus quantile columns\n# (e.g. `yhat_q0.10`, `yhat_q0.90`) alongside `yhat_lower`/`yhat_upper` bounds.\n\n# Disable component columns and intervals when you just need point forecasts\nlean_forecast = model.predict(\n future,\n include_components=False,\n include_uncertainty=False,\n)\nprint(lean_forecast.tail())\n\n# Inspect decomposition of the training history\ncomponents = model.history_components()\nprint(components.head())\n\n# Evaluate rolling-origin backtest\ncv = model.backtest(horizon=14, step=7, strategy=\"sliding\", window=36)\nprint(cv.describe())\n\n# Fetch detailed diagnostics & quality report\nprint(model.report())\n```\n\n## Bundled datasets\n\nOptiProphet ships with a handful of classic forecasting benchmarks so you can experiment without hunting for data files. Use\n`optitime.available_datasets()` to discover what is included and `optitime.load_dataset()` to load a `pandas.DataFrame` that is\nready for modelling.\n\n```python\nfrom optitime import load_dataset, available_datasets\n\nprint(available_datasets())\nair = load_dataset(\"air_passengers\")\nprint(air.head())\n```\n\nThe current catalogue contains:\n\n| Name | Description | Frequency |\n| --- | --- | --- |\n| `air_passengers` | Monthly totals of international airline passengers (1949-1960). | Monthly |\n| `airlines_traffic` | Monthly airline passenger statistics curated from OptiWisdom OptiScorer analyses inspired by the Kaggle Airlines Traffic Passenger Statistics dataset. | Monthly |\n| `shampoo_sales` | Monthly shampoo sales in millions of units (1901-1903). | Monthly |\n| `us_acc_deaths` | Monthly accidental deaths in the United States (1973-1978). | Monthly |\n\n## Parameter control summary\n\n- Use the `historical_components` constructor argument and the\n `history_components()` method to expose or hide historical trend, seasonality,\n regressor, and residual columns on demand.\n- Call `predict(include_components=False, include_uncertainty=False)` to obtain\n a lightweight point forecast for low-latency services.\n- Apply selective overrides such as\n `predict(component_overrides={\"seasonality\": False})` when only certain\n contributors should be hidden.\n- Compare retraining schemes with `backtest(strategy=\"sliding\", window=48)` or\n `backtest(strategy=\"anchored\")`.\n- The `optitime.BACKTEST_STRATEGIES` constant enumerates every supported\n backtest strategy name.\n\nSee [`docs/parameters.md`](docs/parameters.md) for a deeper explanation of each\nparameter and how it impacts the model.\n\n## Local smoke test\n\nAfter installing the project you can immediately verify everything is\nworking by running the bundled sales walkthrough. It loads\n`tests/sales.csv`, trains an `OptiProphet` instance, and prints forecasts,\ncomponent decompositions, and a rolling backtest summary:\n\n```bash\npython tests/run_sales_example.py\n```\n\nThe output demonstrates how the OptiScorer-inspired diagnostics surface\ntrend, seasonality, residuals, and interval bounds on a realistic retail\nseries without any extra setup.\n\n## Visual scenario walkthrough\n\nRecreate the OptiWisdom OptiScorer-inspired parameter sweep on the Kaggle-based\n`airlines_traffic` dataset by installing the optional plotting dependency and\nrunning the helper script:\n\n```bash\npip install optitime-prophet[visuals]\npython tests/run_airlines_visuals.py\n```\n\nThe script writes forecast and RMSE visualisations for each backtest strategy\nand component setting to the `tests/` directory (`airlines_forecast_*.png`,\n`airlines_backtest_*.png`).\n\n## Feature highlights\n\n- **Bundled benchmarks**: Access classic datasets such as AirPassengers, Shampoo Sales, and US Accidental Deaths via\n `optitime.load_dataset()` for tutorials, demos, and regression testing.\n- **Bidirectional insight**: `history_components()` exposes historical trend, seasonality, residual, and regressor effects, while `predict()` projects the same structure into the future.\n- **Backtest ready**: `backtest()` re-fits the model with configurable strategies (expanding, sliding, anchored) to quantify generalisation metrics (MAE, RMSE, MAPE, R\u00b2) on rolling horizons.\n- **Error-aware**: Empty frames, missing columns, low sample counts, or under-performing fits surface as descriptive exceptions such as `DataValidationError` or `ForecastQualityError`.\n- **Structural resilience**: The changepoint detector uses rolling z-scores on second derivatives to adapt to trend shifts. Large residual spikes are flagged as outliers in the diagnostic report.\n- **Quantile intervals**: Forecasts include configurable lower/upper bounds (`interval_width` or explicit `quantiles`) using in-sample dispersion, while dedicated columns such as `yhat_q0.10` and `yhat_q0.90` expose raw quantile estimates for downstream pipelines.\n- **Autoregression & shocks**: Short-term dynamics are captured with configurable AR and MA lags, automatically rolling forward during forecasting.\n- **External signals**: Provide arbitrary regressors during both fit and predict phases to blend business drivers with the statistical core.\n- **Parameterized component control**: Manage trend, seasonality, regressor, and\n residual columns for both historical analyses and future forecasts on a\n per-call basis, including the ability to toggle confidence intervals.\n\n## Error handling\n\nOptiProphet raises explicit errors for problematic scenarios:\n\n- `DataValidationError`: empty dataframes, missing columns, or NaN-heavy features.\n- `ModelNotFitError`: methods invoked before `fit()` completes.\n- `ForecastQualityError`: triggered when R\u00b2 drops below the configured threshold or the MAPE exceeds the acceptable ceiling.\n\nThese exceptions include actionable messages so automated pipelines (including GitHub Actions or CI) can fail fast without leaving stale artefacts.\n\n## Preparing for PyPI\n\n1. Update `pyproject.toml` metadata if publishing under a different namespace.\n2. Create a source distribution and wheel: `python -m build`.\n3. Upload with `twine upload dist/*` once credentials are configured.\n\n## Documentation\n\n- [API overview](docs/api.md)\n- [Parameter guide](docs/parameters.md)\n\n## Development roadmap\n\n- Bayesian residual bootstrapping for richer predictive distributions.\n- Optional Torch/NumPyro backends for transfer learning under sparse conditions.\n- Expanded diagnostics dashboard (streamlit) for interactive exploration.\n\n## Contributing & PR workflow\n\nIf you plan to contribute back via pull requests, make sure your local clone\nknows where to send them. Configure the Git remote once after cloning:\n\n```bash\ngit remote add origin https://github.com/bilgisayarkavramlari/optitime.git\ngit fetch origin\n```\n\nThe `make_pr` helper used in this project depends on the remote named\n`origin`; without it the PR tooling will raise a \u201cfailed to create new pr\u201d\nerror. After the remote is configured you can run the usual contribution\npipeline:\n\n```bash\npython -m compileall src\ngit status\ngit commit -am \"Describe your change\"\nmake_pr\n```\n\nThis ensures the automation has enough repository context to open a pull\nrequest successfully.\n\n## Maintainer & contact\n\nOptiProphet is maintained by \u015eadi Evren \u015eeker. For enquiries or partnership opportunities please reach out via **optitime@optiwisdom.com**.\n\n## License\n\nReleased under the MIT License.\n\n## References\n\n- Taylor, S. J., & Letham, B. (2018). *Forecasting at scale*. The American Statistician, 72(1), 37-45.\n- Box, G. E. P., Jenkins, G. M., Reinsel, G. C., & Ljung, G. M. (2015). *Time Series Analysis: Forecasting and Control* (5th ed.). Wiley.\n- Hyndman, R. J., & Athanasopoulos, G. (2021). *Forecasting: Principles and Practice* (3rd ed.). OTexts.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Prophet-inspired forecasting library distilling OptiWisdom OptiScorer insights into autoregressive, changepoint, and diagnostic enhancements.",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/bilgisayarkavramlari/optitime",
"Homepage": "https://github.com/bilgisayarkavramlari/optitime",
"Issues": "https://github.com/bilgisayarkavramlari/optitime/issues"
},
"split_keywords": [
"forecasting",
" prophet",
" time-series",
" autoregressive",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1854c180cb48016ca6fbc18c8d1d0c87e850bb0dae7c117dd71910184f41ac7e",
"md5": "23baa030da34b7a50152531214b55aaf",
"sha256": "de3f09b0df7ad51ea26f9b92f8f3032f242acaff71f569d83fe0cf5243921fa8"
},
"downloads": -1,
"filename": "optitime_prophet-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "23baa030da34b7a50152531214b55aaf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21875,
"upload_time": "2025-10-22T11:52:20",
"upload_time_iso_8601": "2025-10-22T11:52:20.833733Z",
"url": "https://files.pythonhosted.org/packages/18/54/c180cb48016ca6fbc18c8d1d0c87e850bb0dae7c117dd71910184f41ac7e/optitime_prophet-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5b429477c4c5c081cea5ff10bb0b8be14478efec80ebdf46e55c6cb5dba955bf",
"md5": "f12db1437d622ecfbab7d01e5321b785",
"sha256": "ff1340f1ed248460ec1dd70fe9ee25301a0d3a46031488b171943732fcf8987d"
},
"downloads": -1,
"filename": "optitime_prophet-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f12db1437d622ecfbab7d01e5321b785",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 25892,
"upload_time": "2025-10-22T11:52:22",
"upload_time_iso_8601": "2025-10-22T11:52:22.112207Z",
"url": "https://files.pythonhosted.org/packages/5b/42/9477c4c5c081cea5ff10bb0b8be14478efec80ebdf46e55c6cb5dba955bf/optitime_prophet-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 11:52:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bilgisayarkavramlari",
"github_project": "optitime",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "optitime-prophet"
}
