[docs] Revamp of feature guides (#1301)

* fixed conditional seasonality * fixed conditional seasonality * checked all notebooks and resolved all bugs * improved global local * restructure * fixed warnings * fixed live plotting * improved cross-validation
ourownstory · Apr 26, 2023 · 4279834 · 4279834
1 parent 45111be
commit 4279834
Show file tree

Hide file tree

Showing 83 changed files with 148,274 additions and 2,479 deletions.
diff --git a/docs/feature-guides-archive/autoregression_yosemite_temps.ipynb b/docs/feature-guides-archive/autoregression_yosemite_temps.ipynb
diff --git a/docs/feature-guides-archive/events_holidays_peyton_manning.ipynb b/docs/feature-guides-archive/events_holidays_peyton_manning.ipynb
diff --git a/docs/feature-guides-archive/global_modeling.ipynb b/docs/feature-guides-archive/global_modeling.ipynb
diff --git a/docs/feature-guides-archive/lagged_covariates_energy_ercot.ipynb b/docs/feature-guides-archive/lagged_covariates_energy_ercot.ipynb
diff --git a/docs/feature-guides-archive/migration_from_prophet.ipynb b/docs/feature-guides-archive/migration_from_prophet.ipynb
@@ -0,0 +1,308 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import logging\n",
+    "import warnings\n",
+    "import pandas as pd\n",
+    "from prophet import Prophet\n",
+    "from neuralprophet import NeuralProphet, set_log_level\n",
+    "\n",
+    "set_log_level(\"ERROR\")\n",
+    "logging.getLogger(\"prophet\").setLevel(logging.ERROR)\n",
+    "warnings.filterwarnings(\"ignore\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Migrating from Prophet to NeuralProphet\n",
+    "Both the Prophet and the NeuralProphet model share the concept of decomposing a time series into it's components which allows a human to inspect and interprete the individual components of the forecast. Since NeuralProphet adds new functionality, its interface may differ in part. We provide a guide on migrating a Prophet application to NeuralProphet. In the following we will provide code snippets for the most common functionalities when migrating from Prophet."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> If you are looking to quickly evaluate NeuralProphet for your existing application, consider checking out [this](https://github.com/ourownstory/neural_prophet/blob/main/tutorials/feature-use/prophet_to_torch_prophet.ipynb) notebook to explore TorchProphet."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = pd.read_csv(\"https://raw.githubusercontent.com/facebook/prophet/main/examples/example_wp_log_peyton_manning.csv\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Trend\n",
+    "\n",
+    "In both frameworks, the trend can be configured during the init of the forecaster object. Pay attention to that the naming of the attributes might be slightly different between the two (eg. `changepoint_range` vs. `changepoints_range`)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Prophet\n",
+    "p = Prophet(growth=\"linear\", n_changepoints=10, changepoint_range=0.5)\n",
+    "p.fit(df)\n",
+    "\n",
+    "# NeuralProphet\n",
+    "np = NeuralProphet(growth=\"linear\", n_changepoints=10, changepoints_range=0.5)\n",
+    "np.fit(df)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Seasonality\n",
+    "\n",
+    "In both frameworks, custom seasonality can be added using the `add_seasonality(...)` function."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Prophet\n",
+    "p = Prophet(weekly_seasonality=False)\n",
+    "p = p.add_seasonality(name=\"monthly\", period=30.5, fourier_order=5)\n",
+    "p.fit(df)\n",
+    "\n",
+    "# NeuralProphet\n",
+    "np = NeuralProphet(weekly_seasonality=False)\n",
+    "np = np.add_seasonality(name=\"monthly\", period=30.5, fourier_order=5)\n",
+    "np.fit(df)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Country holidays\n",
+    "\n",
+    "The `add_country_holidays(...)` function works identical in both framework."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Prophet\n",
+    "p = Prophet()\n",
+    "p = p.add_country_holidays(country_name=\"US\")\n",
+    "p.fit(df)\n",
+    "\n",
+    "# NeuralProphet\n",
+    "np = NeuralProphet()\n",
+    "np = np.add_country_holidays(country_name=\"US\")\n",
+    "np.fit(df)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Future regressors"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def nfl_sunday(ds):\n",
+    "    date = pd.to_datetime(ds)\n",
+    "    if date.weekday() == 6 and (date.month > 8 or date.month < 2):\n",
+    "        return 1\n",
+    "    else:\n",
+    "        return 0\n",
+    "\n",
+    "\n",
+    "df_nfl = df.copy()\n",
+    "df_nfl[\"nfl_sunday\"] = df_nfl[\"ds\"].apply(nfl_sunday)\n",
+    "\n",
+    "# Prophet\n",
+    "p = Prophet()\n",
+    "p = p.add_regressor(\"nfl_sunday\")\n",
+    "p.fit(df_nfl)\n",
+    "future_p = p.make_future_dataframe(periods=30)\n",
+    "future_p[\"nfl_sunday\"] = future_p[\"ds\"].apply(nfl_sunday)\n",
+    "_ = p.predict(future_p)\n",
+    "\n",
+    "# NeuralProphet\n",
+    "np = NeuralProphet()\n",
+    "future_np = np.make_future_dataframe(df_nfl, periods=30)\n",
+    "np = np.add_future_regressor(\"nfl_sunday\")\n",
+    "np.fit(df_nfl)\n",
+    "future_np[\"nfl_sunday\"] = future_np[\"ds\"].apply(nfl_sunday)\n",
+    "_ = np.predict(future_np)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Holidays & Events\n",
+    "\n",
+    "What is referred to as \"holidays\" in Prophet is named \"events\" more generically in NeuralProphet. In Prophet, holidays are passed during the init of the Prophet forecaster. In NeuralProphet, they are added using the `add_events(...)` function."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Prophet\n",
+    "superbowl_p = pd.DataFrame(\n",
+    "    {\n",
+    "        \"holiday\": \"superbowl\",\n",
+    "        \"ds\": pd.to_datetime([\"2010-02-07\", \"2014-02-02\", \"2016-02-07\"]),\n",
+    "        \"lower_window\": 0,\n",
+    "        \"upper_window\": 1,\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "p = Prophet(holidays=superbowl_p)\n",
+    "p = p.fit(df)\n",
+    "future_p = p.make_future_dataframe(periods=30)\n",
+    "forecast_p = p.predict(future_p)\n",
+    "\n",
+    "# NeuralProphet\n",
+    "superbowl_np = pd.DataFrame(\n",
+    "    {\n",
+    "        \"event\": \"superbowl\",\n",
+    "        \"ds\": pd.to_datetime([\"2010-02-07\", \"2014-02-02\", \"2016-02-07\"]),\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "np = NeuralProphet()\n",
+    "np = np.add_events(\"superbowl\", lower_window=0, upper_window=1)\n",
+    "history_df = np.create_df_with_events(df, superbowl_np)\n",
+    "_ = np.fit(history_df)\n",
+    "future_np = np.make_future_dataframe(history_df, events_df=superbowl_np, periods=30)\n",
+    "forecast_np = np.predict(future_np)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Regularization\n",
+    "\n",
+    "In Prophet, the argument `prior_scale` can be used to configure regularization. In NeuralProphet, regularization is controlled via the `reg` argument. `prior_scale` and `reg` have an inverse relationship and therefore cannot directly be translated."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Prophet\n",
+    "from prophet import Prophet\n",
+    "\n",
+    "p = Prophet(seasonality_prior_scale=0.5)\n",
+    "\n",
+    "# NeuralProphet\n",
+    "from neuralprophet import NeuralProphet\n",
+    "\n",
+    "np = NeuralProphet(seasonality_reg=0.1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Uncertainty\n",
+    "\n",
+    "In Prophet, all forecasts are configured to use uncertainty intervals automatically. In NeuralProphet, the uncertaintly intervals need to be configured by the user. TorchProphet uses the default uncertainty intervals as defined in Prophet to mirror the behviour.\n",
+    "\n",
+    "However, the uncertainty interval calculation differs between Prophet and NeuralProphet. Since Prophet uses a MAP estimate for uncertainty by default [Thread](https://github.com/facebook/prophet/issues/1124), NeuralProphet relies on quantile regression. Thus, the values are not directly comparable."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Prophet\n",
+    "p = Prophet(interval_width=0.80)\n",
+    "\n",
+    "# NeuralProphet\n",
+    "np = NeuralProphet(quantiles=[0.90, 0.10])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Unsupported features in TorchProphet\n",
+    "- **Saturating forecasts**  \n",
+    "  Saturating forecasts limit the predicted value to a certain limit called capacity. In Prophet, this is archieved by passing the `growth='logistic'` argument during initialization and providing a capacity limit. This functionality is currently not supported by NeuralProphet.\n",
+    "- **Conditional seasonality**  \n",
+    "  Conditional seasonality allows to model certain events as seasonal effects (eg. whether it's currently NFL season). This can be archieved in Prophet by passing the argument `condition_name` to `add_seasonality(...)`. This feature is currently also not supported in NeuralProphet.\n",
+    "\n",
+    "### Additional features of TorchProphet\n",
+    "- **Autoregression**  \n",
+    "  TorchProphet allows to model autoregression of arbitrary lag lengths by building on a Neural Network implementation of the autoregression algorithm (called AR-Net). More information can be found here [Autoregression](https://neuralprophet.com/html/autoregression_yosemite_temps.html).\n",
+    "- **Lagged regressors**  \n",
+    "  TorchProphet does not only support \"future\" regressors like in Prophet, but also lagged regressors that are simultaneous to the time series to predict. More information can be found here [Lagged covariates](https://neuralprophet.com/html/lagged_covariates_energy_ercot.html).\n",
+    "- **Global model**  \n",
+    "  TorchProphet supports hierachical forecasts by training a global model on many simultaneous time series that is used to improve the performance of predicting an individual time series. More infos can be found here [Global Model](https://neuralprophet.com/html/global_modeling.html).\n",
+    "- **Neural Network architecture**  \n",
+    "  TorchProphet models the forecast components using a Neural Network. By default, the network has no hidden layers. However, for more complex time series, the depth of the network can be increased to learn more complex relations.\n",
+    "- **PyTorch**  \n",
+    "  TorchProphet is build on Pytorch (soon PyTorch Lightning) and thus provides interfaces for developers to extend the vanilla model for specific use cases."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3.8.9 ('venv': venv)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.9"
+  },
+  "orig_nbformat": 4,
+  "vscode": {
+   "interpreter": {
+    "hash": "e488e6bd15b38f84fe669bfc536f96b6c5fb6be3ab1c1213873b81c0afcbd577"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}