[](https://github.com/alexhallam/tablespoon/actions/workflows/python-app.yml)
<h1 align="center">tablespoon</h1>
<p align="center"><b>T</b>ime-series <b>B</b>enchmark methods that are <b>S</b>imple and <b>P</b>robabilistic</p>
<p align="center"><img align="center" src="assets/tbsp.png" width="100" /></p>
# Documentation and quick links
- [Documentation and quick links](#documentation-and-quick-links)
- [Introduction](#introduction)
- [Why Run Simple Methods](#why-run-simple-methods)
- [Quick Example](#quick-example)
- [Seasonal Example](#seasonal-example)
- [Stock Prediction](#stock-prediction)
- [Goals of this package](#goals-of-this-package)
- [Non-Goals](#non-goals)
- [Installation](#installation)
- [Python](#python)
- [Citation](#citation)
- [References](#references)
- [Recommended probabilistic forecasting packages](#recommended-probabilistic-forecasting-packages)
- [Learn more about forecasting](#learn-more-about-forecasting)
- [Built with poetry and pushed to pypi](#built-with-poetry-and-pushed-to-pypi)
# Introduction
Many methods exist for probabilistic forecasting. If you are looking for an
impressive probabilistic forecasting package see the list of recommendation at
the bottom of this README. This package is <b>exceptionally ordinary</b>. It is
expected that this package may be used as a compliment to what is already out
there.
# Why Run Simple Methods
We have found, by experience, many good uses for the methods in this package.
To often we see that forecast methods go in production without a naive method to
accompany it. This is a missed opportunity.
1. **Naive May Be Good Enough**: How good is good enough? I have almost never started a project where the firm receiving the forecast knew the answer to this question, but it is important to get to it early. I think all of us would agree that a forecast error of 0 is best, but in reality how much time should be spent spinning our wheels to get there. Further, many business applications can’t be improved upon even with significant forecast error reduction. I remember hearing a story of a firm which ordered units on pallets. The firm paid by the pallet, not the unit. The forecast team was able to reduce the forecast error, but in the end this did not change the outcome. This is the ‘pallet problem’. As data scientists it is easy to think of error reduction as a continuous function, but this need not map the same way to business value. In this example the continuous error reduction mapped to a discrete pallet. This is a long way of saying, “A naive forecast may be good enough”. What is a naive forecasting method? I typically think of two methods. The mean forecast and the naive forecast. I will go over these in more detail below. There are also some applications where naive methods have been shown to be hard to beat.
2. **Get A Denominator for Relative Metrics**: Though naive methods can usually
be beat it is good to know the relative improvement over the benchmark. This
can allow a forecasting team to market their alternative forecast when the
'skill score' is impressive.
3. **Easy to productionize and get expectations**: Get a sense for *how good is
good enough*. In many applications a forecast team is asked to forecast, but
stakeholders provide no line-in-the-sand for when the forecasting work needs
to stop. One reasonable approach is to run the benchmarks found in this
package then beat the best performing benchmark by a margin that is
statistically significant.
4. **Resilience in Production - Why not have many models?**: Sometimes, despite
best efforts the production model does something unexpected. In this
case it is nice to have a simple backup that is cheap to generate and good
enough to fall back on. In this way a production forecast pipeline gains
strength from a diversity of models.
5. **Easy Uncertainty Quantification**: Recently we see that applications
are not about forecast accuracy, but instead about forecasting uncertainty.
Capturing the full distribution helps firms set "service levels" aka
percentiles of the distribution for which they are prepared to serve. Even
if you have the worlds most accurate unbiased forecast the median point is
, by definition, an underforecast half the time. For this reason it is best to provide a
distribution of simulated future values and the firm may decide for
themselves what risks they are or are not willing to take.
# Quick Example
We show a quick example below.
For more examples see [Simple Example](https://alexhallam.github.io/tablespoon/section/plotting/), [Extended Example](https://alexhallam.github.io/tablespoon/section/extended/)
There are also some Notebook examples
1. [Intro](https://github.com/alexhallam/tablespoon/blob/main/examples/tablespoon.ipynb)
2. [Time Series Cross Validation & Skill Score](https://github.com/alexhallam/tablespoon/blob/main/examples/time_series_cv.ipynb)
### Seasonal Example
```python
import tablespoon as tbsp
from tablespoon.data import SEAS
sn = tbsp.Snaive()
df_sn = sn.predict(
SEAS, horizon=7 * 4, frequency="D", lag=7, uncertainty_samples=8000
).assign(model="snaive")
print(df_sn.head(10))
```
### Stock Prediction
```python
import tablespoon as tbsp
from tablespoon.data import APPL
n = tbsp.Naive()
df_n = n.predict(
APPL, horizon=7 * 4, frequency="D", lag=1, uncertainty_samples=8000
).assign(model="naive")
print(df_n.head(10))
```
```sh
ds rep y_sim model
0 2022-01-02 0 5.20006 naive
1 2022-01-02 1 5.16789 naive
2 2022-01-02 2 5.17641 naive
3 2022-01-02 3 5.19340 naive
4 2022-01-02 4 5.20075 naive
5 2022-01-02 5 5.17681 naive
6 2022-01-02 6 5.20302 naive
7 2022-01-02 7 5.18896 naive
8 2022-01-02 8 5.19622 naive
9 2022-01-02 9 5.17469 naive
```
<p align="center"><img align="center" src="assets/forecasts_n.jpg" width="800" /></p>
# Goals of this package
1. ♙**Simple**: Not just in the forecasts themselves, but also from the
users perspective.
2. ♝**Documented**: It should be very clear exactly how forecasts are getting
generated. We document the parameterization of the models to make this as
obvious and uninteresting as possible. See [Forecast Method Math Documentation](https://alexhallam.github.io/tablespoon/section/math/)
3. ♜**Stable**: We want this package to feel rock solid. For this to happen
we keep the feature set relatively small. We believe that after the initial
development of this package we should spend out time maintaining the code as
oppose to thinking of new features.
4. ♞**Distributional**: Quantification of uncertainty is the name of
the game.
# Non-Goals
1. 🔥**Circut Melting Focus on Speed**: Not to say this is a slow package. In fact, it is very fast!
We just don't put any extra effort to make it faster than `numpy`.
2. 🤖**New/Complex Forecast Models**: Again, this is out of scope. If you are
looking for recommendations please see the bottom of the page.
# Installation
### Python
```
pip3 install tablespoon
```
# Citation
If you would like to cite `tablespoon`, please cite it as follows:
Alex Hallam. **tablespoon: Time-series Benchmark methods that are Simple and Probabilistic** https://github.com/alexhallam/tablespoon, 2022. Version 0.4.6.
```
@misc{tablespoon,
author={Alex Hallam},
title={{tablespoon}: {Time-series Benchmark methods that are Simple and Probabilistic},
howpublished={https://github.com/alexhallam/tablespoon},
note={Version 0.4.6,
year={2022}
}
```
# References
1. Hyndman, R.J., & Athanasopoulos, G. (2021) Forecasting: principles and practice, 3rd edition, OTexts: Melbourne, Australia. OTexts.com/fpp3. Accessed on 2021-09-26.
# Recommended probabilistic forecasting packages
There are many packages that can compliment `tablespoon`
[forecast](https://github.com/robjhyndman/forecast): The king of forecasting
packages. Rob Hyndman is a professor of forecasting and has served as editor of
the journal "International Journal of Forecasting". If you are new to
forecasting please read his free ebook [fpp3](https://otexts.com/fpp3/).
[prophet](https://facebook.github.io/prophet/): A very capable and reliable
forecasting package. I have never seen a bad forecast come out of prophet.
[gluonts](https://ts.gluon.ai/). If you are itching to use neural nets for
forecasting this is a good one to pick.
# Learn more about forecasting
1. Read [fpp3](https://otexts.com/fpp3/)
2. Join the [International Institute of Forecasting](https://forecasters.org/)
and read their publications.
# Built with poetry and pushed to pypi
```sh
poetry publish -u <username> -p <password> --build
```
Raw data
{
"_id": null,
"home_page": "https://alexhallam.github.io/tablespoon/",
"name": "tablespoon",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "forecasting,forecast,probabilistic,naive,benchmark,seasonal naive,mean forecast",
"author": "Alex Hallam",
"author_email": "alexhallam6.28@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c2/eb/9addc4e0453c5a1be874894d08fa0e72f62884a2436b8047764d34e92954/tablespoon-0.5.1.tar.gz",
"platform": null,
"description": "[](https://github.com/alexhallam/tablespoon/actions/workflows/python-app.yml)\n\n<h1 align=\"center\">tablespoon</h1>\n<p align=\"center\"><b>T</b>ime-series <b>B</b>enchmark methods that are <b>S</b>imple and <b>P</b>robabilistic</p>\n\n<p align=\"center\"><img align=\"center\" src=\"assets/tbsp.png\" width=\"100\" /></p>\n\n\n# Documentation and quick links\n- [Documentation and quick links](#documentation-and-quick-links)\n- [Introduction](#introduction)\n- [Why Run Simple Methods](#why-run-simple-methods)\n- [Quick Example](#quick-example)\n - [Seasonal Example](#seasonal-example)\n - [Stock Prediction](#stock-prediction)\n- [Goals of this package](#goals-of-this-package)\n- [Non-Goals](#non-goals)\n- [Installation](#installation)\n - [Python](#python)\n- [Citation](#citation)\n- [References](#references)\n- [Recommended probabilistic forecasting packages](#recommended-probabilistic-forecasting-packages)\n- [Learn more about forecasting](#learn-more-about-forecasting)\n- [Built with poetry and pushed to pypi](#built-with-poetry-and-pushed-to-pypi)\n\n# Introduction\n\nMany methods exist for probabilistic forecasting. If you are looking for an\nimpressive probabilistic forecasting package see the list of recommendation at\nthe bottom of this README. This package is <b>exceptionally ordinary</b>. It is\nexpected that this package may be used as a compliment to what is already out\nthere.\n\n# Why Run Simple Methods\n\nWe have found, by experience, many good uses for the methods in this package.\nTo often we see that forecast methods go in production without a naive method to\naccompany it. This is a missed opportunity.\n\n1. **Naive May Be Good Enough**: How good is good enough? I have almost never started a project where the firm receiving the forecast knew the answer to this question, but it is important to get to it early. I think all of us would agree that a forecast error of 0 is best, but in reality how much time should be spent spinning our wheels to get there. Further, many business applications can\u2019t be improved upon even with significant forecast error reduction. I remember hearing a story of a firm which ordered units on pallets. The firm paid by the pallet, not the unit. The forecast team was able to reduce the forecast error, but in the end this did not change the outcome. This is the \u2018pallet problem\u2019. As data scientists it is easy to think of error reduction as a continuous function, but this need not map the same way to business value. In this example the continuous error reduction mapped to a discrete pallet. This is a long way of saying, \u201cA naive forecast may be good enough\u201d. What is a naive forecasting method? I typically think of two methods. The mean forecast and the naive forecast. I will go over these in more detail below. There are also some applications where naive methods have been shown to be hard to beat.\n2. **Get A Denominator for Relative Metrics**: Though naive methods can usually\n be beat it is good to know the relative improvement over the benchmark. This\n can allow a forecasting team to market their alternative forecast when the\n 'skill score' is impressive.\n3. **Easy to productionize and get expectations**: Get a sense for *how good is\n good enough*. In many applications a forecast team is asked to forecast, but\n stakeholders provide no line-in-the-sand for when the forecasting work needs\n to stop. One reasonable approach is to run the benchmarks found in this\n package then beat the best performing benchmark by a margin that is\n statistically significant.\n4. **Resilience in Production - Why not have many models?**: Sometimes, despite\n best efforts the production model does something unexpected. In this\n case it is nice to have a simple backup that is cheap to generate and good\n enough to fall back on. In this way a production forecast pipeline gains\n strength from a diversity of models.\n5. **Easy Uncertainty Quantification**: Recently we see that applications\n are not about forecast accuracy, but instead about forecasting uncertainty.\n Capturing the full distribution helps firms set \"service levels\" aka\n percentiles of the distribution for which they are prepared to serve. Even\n if you have the worlds most accurate unbiased forecast the median point is\n , by definition, an underforecast half the time. For this reason it is best to provide a\n distribution of simulated future values and the firm may decide for\n themselves what risks they are or are not willing to take.\n\n# Quick Example\n\nWe show a quick example below. \n\nFor more examples see [Simple Example](https://alexhallam.github.io/tablespoon/section/plotting/), [Extended Example](https://alexhallam.github.io/tablespoon/section/extended/)\n\nThere are also some Notebook examples\n1. [Intro](https://github.com/alexhallam/tablespoon/blob/main/examples/tablespoon.ipynb)\n2. [Time Series Cross Validation & Skill Score](https://github.com/alexhallam/tablespoon/blob/main/examples/time_series_cv.ipynb)\n### Seasonal Example\n\n```python\nimport tablespoon as tbsp\nfrom tablespoon.data import SEAS\n\nsn = tbsp.Snaive()\ndf_sn = sn.predict(\n SEAS, horizon=7 * 4, frequency=\"D\", lag=7, uncertainty_samples=8000\n).assign(model=\"snaive\")\n\nprint(df_sn.head(10))\n```\n\n### Stock Prediction\n\n```python\nimport tablespoon as tbsp\nfrom tablespoon.data import APPL\n\nn = tbsp.Naive()\ndf_n = n.predict(\n APPL, horizon=7 * 4, frequency=\"D\", lag=1, uncertainty_samples=8000\n).assign(model=\"naive\")\n\nprint(df_n.head(10))\n```\n\n```sh\n ds rep y_sim model\n0 2022-01-02 0 5.20006 naive\n1 2022-01-02 1 5.16789 naive\n2 2022-01-02 2 5.17641 naive\n3 2022-01-02 3 5.19340 naive\n4 2022-01-02 4 5.20075 naive\n5 2022-01-02 5 5.17681 naive\n6 2022-01-02 6 5.20302 naive\n7 2022-01-02 7 5.18896 naive\n8 2022-01-02 8 5.19622 naive\n9 2022-01-02 9 5.17469 naive\n```\n<p align=\"center\"><img align=\"center\" src=\"assets/forecasts_n.jpg\" width=\"800\" /></p>\n\n\n\n\n# Goals of this package\n\n1. \u2659**Simple**: Not just in the forecasts themselves, but also from the\n users perspective.\n2. \u265d**Documented**: It should be very clear exactly how forecasts are getting\n generated. We document the parameterization of the models to make this as\n obvious and uninteresting as possible. See [Forecast Method Math Documentation](https://alexhallam.github.io/tablespoon/section/math/)\n3. \u265c**Stable**: We want this package to feel rock solid. For this to happen\n we keep the feature set relatively small. We believe that after the initial \n development of this package we should spend out time maintaining the code as\n oppose to thinking of new features.\n4. \u265e**Distributional**: Quantification of uncertainty is the name of\n the game.\n\n# Non-Goals\n\n1. \ud83d\udd25**Circut Melting Focus on Speed**: Not to say this is a slow package. In fact, it is very fast! \n We just don't put any extra effort to make it faster than `numpy`.\n2. \ud83e\udd16**New/Complex Forecast Models**: Again, this is out of scope. If you are\n looking for recommendations please see the bottom of the page.\n\n# Installation\n\n### Python\n\n```\npip3 install tablespoon\n```\n\n# Citation\n\nIf you would like to cite `tablespoon`, please cite it as follows:\n\nAlex Hallam. **tablespoon: Time-series Benchmark methods that are Simple and Probabilistic** https://github.com/alexhallam/tablespoon, 2022. Version 0.4.6.\n\n```\n@misc{tablespoon,\n author={Alex Hallam},\n title={{tablespoon}: {Time-series Benchmark methods that are Simple and Probabilistic},\n howpublished={https://github.com/alexhallam/tablespoon},\n note={Version 0.4.6,\n year={2022}\n}\n```\n\n# References\n\n1. Hyndman, R.J., & Athanasopoulos, G. (2021) Forecasting: principles and practice, 3rd edition, OTexts: Melbourne, Australia. OTexts.com/fpp3. Accessed on 2021-09-26.\n\n# Recommended probabilistic forecasting packages\n\nThere are many packages that can compliment `tablespoon`\n\n[forecast](https://github.com/robjhyndman/forecast): The king of forecasting\npackages. Rob Hyndman is a professor of forecasting and has served as editor of\nthe journal \"International Journal of Forecasting\". If you are new to\nforecasting please read his free ebook [fpp3](https://otexts.com/fpp3/).\n\n[prophet](https://facebook.github.io/prophet/): A very capable and reliable\nforecasting package. I have never seen a bad forecast come out of prophet.\n\n[gluonts](https://ts.gluon.ai/). If you are itching to use neural nets for\nforecasting this is a good one to pick.\n\n# Learn more about forecasting\n\n1. Read [fpp3](https://otexts.com/fpp3/)\n2. Join the [International Institute of Forecasting](https://forecasters.org/)\n and read their publications.\n \n# Built with poetry and pushed to pypi\n\n```sh\npoetry publish -u <username> -p <password> --build\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple probabilistic time series benchmark models",
"version": "0.5.1",
"project_urls": {
"Homepage": "https://alexhallam.github.io/tablespoon/",
"Repository": "https://github.com/alexhallam/tablespoon"
},
"split_keywords": [
"forecasting",
"forecast",
"probabilistic",
"naive",
"benchmark",
"seasonal naive",
"mean forecast"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "26621c2f85217a7586c194284ecebf0939b418098705eb0c1e7e51be6636efa4",
"md5": "dfb4a5f39ee64d699cf376b401ee8007",
"sha256": "284ed6f4448986bcb12441bb3392c3ae9ed3a996550c45f3777e7f79fe1296b2"
},
"downloads": -1,
"filename": "tablespoon-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dfb4a5f39ee64d699cf376b401ee8007",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 51305,
"upload_time": "2023-10-20T21:35:39",
"upload_time_iso_8601": "2023-10-20T21:35:39.547522Z",
"url": "https://files.pythonhosted.org/packages/26/62/1c2f85217a7586c194284ecebf0939b418098705eb0c1e7e51be6636efa4/tablespoon-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c2eb9addc4e0453c5a1be874894d08fa0e72f62884a2436b8047764d34e92954",
"md5": "3f40bb0aabf7a28f23077be4b4b053ab",
"sha256": "9c26f12de23028ac411f11eeb75601b24c8857900a64b66084120c401bb9d879"
},
"downloads": -1,
"filename": "tablespoon-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "3f40bb0aabf7a28f23077be4b4b053ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 54380,
"upload_time": "2023-10-20T21:35:41",
"upload_time_iso_8601": "2023-10-20T21:35:41.746292Z",
"url": "https://files.pythonhosted.org/packages/c2/eb/9addc4e0453c5a1be874894d08fa0e72f62884a2436b8047764d34e92954/tablespoon-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-20 21:35:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexhallam",
"github_project": "tablespoon",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tablespoon"
}
JSON
