Merge pull request #838 from uber/doc-update-20240121

Doc update 20240121
uber · Jan 22, 2024 · c853d61 · c853d61
2 parents 447487f + f2fda79
commit c853d61
Show file tree

Hide file tree

Showing 52 changed files with 1,401 additions and 31,588 deletions.
diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ The default page of the repo is on `dev` branch. To install the dev version, ple
 This project
 
 - is stable and being incubated for long-term support. It may contain new experimental code, for which APIs are subject to change.
-- requires PyStan as a system dependency. PyStan is licensed under [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html), which is a free, copyleft license for software.
+- requires [cmdstanpy](https://mc-stan.org/cmdstanpy/) as one of the core dependencies for Bayesian sampling.
 
 # Orbit: A Python Package for Bayesian Forecasting
 

diff --git a/docs/about.rst b/docs/about.rst
@@ -20,8 +20,8 @@ It also supports the following sampling methods for model estimation:
 -  Stochastic Variational Inference (SVI) as a hybrid-sampling method on approximate
    distribution
 
-Under the hood, the package is leveraging probabilistic program such as `pyro <https://pyro.ai/>`__ and `PyStan 2.0
-<https://pystan2.readthedocs.io/en/latest/>`__.
+Under the hood, the package is leveraging probabilistic program such as `pyro <https://pyro.ai/>`__ and `cmdstanpy
+<https://mc-stan.org/cmdstanpy/>`__.
 
 
 Citation

diff --git a/docs/conf.py b/docs/conf.py
@@ -50,7 +50,7 @@
 ]
 
 # autodoc_mock_imports = [
-#     'pandas', 'torch', 'pystan', 'tqdm', 'matplotlib.pyplot'
+#     'pandas', 'torch', 'cmdstanpy', 'tqdm', 'matplotlib.pyplot'
 #     'pyro', 'matplotlib', 'seaborn', 'scipy', 'sklearn']
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/tutorials/build_your_own_model.ipynb b/docs/tutorials/build_your_own_model.ipynb
@@ -42,11 +42,11 @@
     "\n",
     "### Model\n",
     "\n",
-    "**Model** is an object defined by a class inherited from `BaseTemplate` a.k.a **Model Template** in the diagram below.  It mainly turns the logic of `fit()` and `predict()` concrete by supplying the `fitter` as a file (**PyStan**) or a callable class (**Pyro**) and the internal `predict()` method. This object defines the overall inputs, model structure, parameters and likelihoods.\n",
+    "**Model** is an object defined by a class inherited from `BaseTemplate` a.k.a **Model Template** in the diagram below.  It mainly turns the logic of `fit()` and `predict()` concrete by supplying the `fitter` as a file (**CmdStanPy**) or a callable class (**Pyro**) and the internal `predict()` method. This object defines the overall inputs, model structure, parameters and likelihoods.\n",
     "\n",
     "### Estimator\n",
     "\n",
-    "Meanwhile, there are different APIs implement slightly different ways of sampling and optimization (for **MAP**). `orbit` is designed to support various APIs such as **PyStan** and **Pyro** (hopefully PyMC3, Numpyro in the future!). The logic separating the call of different APIs with different interface is done by the **Estimator** class which is further inherited in `PyroEstimator` and `StanEstimator`.\n"
+    "Meanwhile, there are different APIs implement slightly different ways of sampling and optimization (for **MAP**). `orbit` is designed to support various APIs such as **CmdStanPy** and **Pyro** (hopefully PyMC3, Numpyro in the future!). The logic separating the call of different APIs with different interface is done by the **Estimator** class which is further inherited in `PyroEstimator` and `StanEstimator`.\n"
    ]
   },
   {
@@ -496,7 +496,7 @@
     {
      "data": {
       "text/plain": [
-       "<orbit.forecaster.svi.SVIForecaster at 0x2a5da37c0>"
+       "<orbit.forecaster.svi.SVIForecaster at 0x17f0f6070>"
       ]
      },
      "execution_count": 11,
@@ -531,25 +531,25 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:10:27 - orbit - INFO - Using SVI (Pyro) with steps: 501, samples: 100, learning rate: 0.1, learning_rate_total_decay: 1.0 and particles: 100.\n",
-      "2024-01-11 22:10:28 - orbit - INFO - step    0 loss = 27333, scale = 0.077497\n",
+      "2024-01-21 13:47:27 - orbit - INFO - Using SVI (Pyro) with steps: 501, samples: 100, learning rate: 0.1, learning_rate_total_decay: 1.0 and particles: 100.\n",
+      "2024-01-21 13:47:27 - orbit - INFO - step    0 loss = 27333, scale = 0.077497\n",
       "INFO:orbit:step    0 loss = 27333, scale = 0.077497\n",
-      "2024-01-11 22:10:29 - orbit - INFO - step  100 loss = 12594, scale = 0.00924\n",
+      "2024-01-21 13:47:29 - orbit - INFO - step  100 loss = 12594, scale = 0.00924\n",
       "INFO:orbit:step  100 loss = 12594, scale = 0.00924\n",
-      "2024-01-11 22:10:31 - orbit - INFO - step  200 loss = 12596, scale = 0.0094562\n",
+      "2024-01-21 13:47:31 - orbit - INFO - step  200 loss = 12596, scale = 0.0094562\n",
       "INFO:orbit:step  200 loss = 12596, scale = 0.0094562\n",
-      "2024-01-11 22:10:33 - orbit - INFO - step  300 loss = 12591, scale = 0.0092175\n",
+      "2024-01-21 13:47:32 - orbit - INFO - step  300 loss = 12591, scale = 0.0092175\n",
       "INFO:orbit:step  300 loss = 12591, scale = 0.0092175\n",
-      "2024-01-11 22:10:35 - orbit - INFO - step  400 loss = 12594, scale = 0.0095741\n",
+      "2024-01-21 13:47:34 - orbit - INFO - step  400 loss = 12594, scale = 0.0095741\n",
       "INFO:orbit:step  400 loss = 12594, scale = 0.0095741\n",
-      "2024-01-11 22:10:36 - orbit - INFO - step  500 loss = 12591, scale = 0.0095602\n",
+      "2024-01-21 13:47:36 - orbit - INFO - step  500 loss = 12591, scale = 0.0095602\n",
       "INFO:orbit:step  500 loss = 12591, scale = 0.0095602\n"
      ]
     },
     {
      "data": {
       "text/plain": [
-       "<orbit.forecaster.svi.SVIForecaster at 0x2a5da37c0>"
+       "<orbit.forecaster.svi.SVIForecaster at 0x17f0f6070>"
       ]
      },
      "execution_count": 12,

diff --git a/docs/tutorials/decompose_prediction.ipynb b/docs/tutorials/decompose_prediction.ipynb
@@ -111,13 +111,13 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:10:53 - orbit - INFO - Sampling (PyStan) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
+      "2024-01-21 14:39:49 - orbit - INFO - Sampling (CmdStanPy) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
      ]
     },
     {
      "data": {
       "text/plain": [
-       "<orbit.forecaster.full_bayes.FullBayesianForecaster at 0x1058475b0>"
+       "<orbit.forecaster.full_bayes.FullBayesianForecaster at 0x108f9ca60>"
       ]
      },
      "execution_count": 4,

diff --git a/docs/tutorials/dlt.ipynb b/docs/tutorials/dlt.ipynb
@@ -201,7 +201,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:11:09 - orbit - INFO - Optimizing (PyStan) with algorithm: LBFGS.\n"
+      "2024-01-21 13:46:06 - orbit - INFO - Optimizing (CmdStanPy) with algorithm: LBFGS.\n"
      ]
     },
     {
@@ -218,8 +218,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "CPU times: user 795 ms, sys: 1.27 s, total: 2.06 s\n",
-      "Wall time: 481 ms\n"
+      "CPU times: user 613 ms, sys: 1.34 s, total: 1.96 s\n",
+      "Wall time: 729 ms\n"
      ]
     }
    ],
@@ -252,13 +252,13 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:11:10 - orbit - INFO - Sampling (PyStan) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
+      "2024-01-21 13:46:06 - orbit - INFO - Sampling (CmdStanPy) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
      ]
     },
     {
      "data": {
       "text/plain": [
-       "<orbit.forecaster.full_bayes.FullBayesianForecaster at 0x174876ca0>"
+       "<orbit.forecaster.full_bayes.FullBayesianForecaster at 0x175098400>"
       ]
      },
      "execution_count": 5,
@@ -333,7 +333,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:11:12 - orbit - INFO - Optimizing (PyStan) with algorithm: LBFGS.\n"
+      "2024-01-21 13:46:08 - orbit - INFO - Optimizing (CmdStanPy) with algorithm: LBFGS.\n"
      ]
     },
     {
@@ -350,8 +350,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "CPU times: user 1.01 s, sys: 956 ms, total: 1.97 s\n",
-      "Wall time: 501 ms\n"
+      "CPU times: user 593 ms, sys: 1.38 s, total: 1.97 s\n",
+      "Wall time: 468 ms\n"
      ]
     }
    ],
@@ -403,15 +403,15 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:11:12 - orbit - INFO - Optimizing (PyStan) with algorithm: LBFGS.\n"
+      "2024-01-21 13:46:09 - orbit - INFO - Optimizing (CmdStanPy) with algorithm: LBFGS.\n"
      ]
     },
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "CPU times: user 280 ms, sys: 110 ms, total: 391 ms\n",
-      "Wall time: 351 ms\n"
+      "CPU times: user 324 ms, sys: 268 ms, total: 592 ms\n",
+      "Wall time: 344 ms\n"
      ]
     },
     {
@@ -479,7 +479,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:11:13 - orbit - INFO - Optimizing (PyStan) with algorithm: LBFGS.\n"
+      "2024-01-21 13:46:10 - orbit - INFO - Optimizing (CmdStanPy) with algorithm: LBFGS.\n"
      ]
     },
     {
@@ -496,8 +496,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "CPU times: user 1.14 s, sys: 941 ms, total: 2.08 s\n",
-      "Wall time: 468 ms\n"
+      "CPU times: user 735 ms, sys: 1.51 s, total: 2.24 s\n",
+      "Wall time: 478 ms\n"
      ]
     }
    ],
@@ -552,7 +552,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:11:14 - orbit - INFO - Sampling (PyStan) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
+      "2024-01-21 13:46:10 - orbit - INFO - Sampling (CmdStanPy) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
      ]
     },
     {
@@ -684,11 +684,13 @@
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "source": [
     "### High Dimensional and  Fourier Series Regression\n",
     "\n",
-    "In case of high dimensional regression, users can consider fixing the smoothness with a relatively small levels smoothing values e.g. setting `level_sm_input=0.01`. This is particularly useful in modeling higher frequency time-series such as daily and hourly data using regression on Fourier series. Check out the `examples/` folder for more details."
+    "In case of high dimensional regression, users can consider fixing the smoothness with a relatively small levels smoothing values e.g. setting `level_sm_input=0.01`. This is particularly useful in modeling higher frequency time-series such as daily and hourly data using regression on Fourier series. Check out the `examples/` folder for the details."
    ]
   }
  ],
@@ -722,6 +724,11 @@
    "toc_position": {},
    "toc_section_display": true,
    "toc_window_display": true
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "091dbfa208428afaf5ec1bce184d496f586fd9ce3f39e55cfff16a9adc2d3379"
+   }
   }
  },
  "nbformat": 4,

diff --git a/docs/tutorials/ets_lgt_dlt_missing_response.ipynb b/docs/tutorials/ets_lgt_dlt_missing_response.ipynb
@@ -297,13 +297,13 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:12:15 - orbit - INFO - Sampling (PyStan) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
+      "2024-01-21 14:38:49 - orbit - INFO - Sampling (CmdStanPy) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
      ]
     },
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "675e617a68644e69bc19461f72afcb76",
+       "model_id": "7127326a60cb455a92d2f29cc00a7a3d",
        "version_major": 2,
        "version_minor": 0
       },
@@ -317,7 +317,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "e61ef67e9c1349a391fa6d7dd8049409",
+       "model_id": "788443932419449f9e398df74e8180ab",
        "version_major": 2,
        "version_minor": 0
       },
@@ -331,7 +331,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "4b4e1e5d00f0412fb2e3db4fe0f7f877",
+       "model_id": "f75584f0370742288f15096a09a23ee2",
        "version_major": 2,
        "version_minor": 0
       },
@@ -345,7 +345,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "a0676da571094a85b5d2f7028395da0a",
+       "model_id": "ee67293605f9471c876b59bd14d63cc0",
        "version_major": 2,
        "version_minor": 0
       },
@@ -397,13 +397,13 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:12:15 - orbit - INFO - Sampling (PyStan) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
+      "2024-01-21 14:38:50 - orbit - INFO - Sampling (CmdStanPy) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
      ]
     },
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "62892bd875c846049d52ee7c19c7ec4f",
+       "model_id": "91631a6519be4f9eb191e0655fbac846",
        "version_major": 2,
        "version_minor": 0
       },
@@ -417,7 +417,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "f95443129e8f4ad6b519cde63f110bb7",
+       "model_id": "5117ba9e278f4c93915daa1cade2411e",
        "version_major": 2,
        "version_minor": 0
       },
@@ -431,7 +431,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "42da72d1bdf44ade9718c58a0f720fec",
+       "model_id": "e047da76e6a3451dbfb3895656ccc731",
        "version_major": 2,
        "version_minor": 0
       },
@@ -445,7 +445,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "6fa4d95140674159917f351e5cef602e",
+       "model_id": "da8adf7c21ea478ebc9471902d193535",
        "version_major": 2,
        "version_minor": 0
       },
@@ -497,13 +497,13 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "2024-01-11 22:12:19 - orbit - INFO - Sampling (PyStan) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
+      "2024-01-21 14:38:53 - orbit - INFO - Sampling (CmdStanPy) with chains: 4, cores: 8, temperature: 1.000, warmups (per chain): 225 and samples(per chain): 25.\n"
      ]
     },
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "d00171d6ff2545f4a040fd4eaa0cbc85",
+       "model_id": "c51672ad186240cc80ddffdcddff9c3d",
        "version_major": 2,
        "version_minor": 0
       },
@@ -517,7 +517,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "91ba7166933843f58b473ebb545db892",
+       "model_id": "956c2e23d6514668bf16bceac75fbbc8",
        "version_major": 2,
        "version_minor": 0
       },
@@ -531,7 +531,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "0c82ee131b7447d59a20223622fbb1b6",
+       "model_id": "aa820a1c6a57417cbe4ba807f7d1e063",
        "version_major": 2,
        "version_minor": 0
       },
@@ -545,7 +545,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "e2f800290b394e4f8a483e2bf8d36644",
+       "model_id": "e6349c96e2044c65a8b9f99a03fe181d",
        "version_major": 2,
        "version_minor": 0
       },
@@ -811,7 +811,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 14,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2021-12-16T20:11:05.798766Z",