update docs

docs/_docs/additional_topics.md

@@ -53,7 +53,7 @@ The json file will be portable across systems, and deserialization is backwards
 
 
 
-For time series that exhibit strong seasonality patterns rather than trend changes, it may be useful to force the trend growth rate to be flat. This can be achieved simply by passing `growth=flat` when creating the model:
+For time series that exhibit strong seasonality patterns rather than trend changes, or when we want to rely on the pattern of exogenous regressors (e.g. for causal inference with time series), it may be useful to force the trend growth rate to be flat. This can be achieved simply by passing `growth=flat` when creating the model:
 
 
 ```R
@@ -110,7 +110,7 @@ def warm_start_params(m):
             res[pname] = np.mean(m.params[pname], axis=0)
     return res
 
-df = pd.read_csv('https://raw.githubusercontent.com/facebook/prophet/main/examples/example_wp_log_peyton_manning.csv')
+df = pd.read_csv('../examples/example_wp_log_peyton_manning.csv')
 df1 = df.loc[df['ds'] < '2016-01-19', :]  # All data except the last day
 m1 = Prophet().fit(df1) # A model fit to all data except the last day
 
@@ -133,8 +133,21 @@ There are few caveats that should be kept in mind when considering warm-starting
 
 ### External references
 
+
+
+As we discuss in our [2023 blog post on the state of Prophet](https://medium.com/@cuongduong_35162/facebook-prophet-in-2023-and-beyond-c5086151c138), we have no plans to further develop the underlying Prophet model. If you're looking for state-of-the-art forecasting accuracy, we recommend the following libraries:
+
+
+
+* [`statsforecast`](https://github.com/Nixtla/statsforecast), and other packages from the Nixtla group such as [`hierarchicalforecast`](https://github.com/Nixtla/hierarchicalforecast) and [`neuralforecast`](https://github.com/Nixtla/neuralforecast).
+
+* [`NeuralProphet`](https://neuralprophet.com/), a Prophet-style model implemented in PyTorch, to be more adaptable and extensible.
+
+
+
 These github repositories provide examples of building on top of Prophet in ways that may be of broad interest:
 
+
+
 * [forecastr](https://github.com/garethcull/forecastr): A web app that provides a UI for Prophet.
 
-* [NeuralProphet](https://github.com/ourownstory/neural_prophet): A Prophet-style model implemented in pytorch, to be more adaptable and extensible.

docs/_docs/diagnostics.md

@@ -20,8 +20,8 @@ subsections:
 Prophet includes functionality for time series cross validation to measure forecast error using historical data. This is done by selecting cutoff points in the history, and for each of them fitting the model using data only up to that cutoff point. We can then compare the forecasted values to the actual values. This figure illustrates a simulated historical forecast on the Peyton Manning dataset, where the model was fit to an initial history of 5 years, and a forecast was made on a one year horizon.
 
 
- 
-![png](/prophet/static/diagnostics_files/diagnostics_4_0.png) 
+
+![png](/prophet/static/diagnostics_files/diagnostics_4_0.png)
 
 
 [The Prophet paper](https://peerj.com/preprints/3190.pdf) gives further description of simulated historical forecasts.
@@ -270,8 +270,8 @@ plot_cross_validation_metric(df.cv, metric = 'mape')
 from prophet.plot import plot_cross_validation_metric
 fig = plot_cross_validation_metric(df_cv, metric='mape')
 ```
- 
-![png](/prophet/static/diagnostics_files/diagnostics_17_0.png) 
+
+![png](/prophet/static/diagnostics_files/diagnostics_17_0.png)
 
 
 The size of the rolling window in the figure can be changed with the optional argument `rolling_window`, which specifies the proportion of forecasts to use in each rolling window. The default is 0.1, corresponding to 10% of rows from `df_cv` included in each window; increasing this will lead to a smoother average curve in the figure. The `initial` period should be long enough to capture all of the components of the model, in particular seasonalities and extra regressors: at least a year for yearly seasonality, at least a week for weekly seasonality, etc.
@@ -455,7 +455,3 @@ The Prophet model has a number of input parameters that one might consider tunin
 
 - `uncertainty_samples`: The uncertainty intervals are computed as quantiles from the posterior predictive interval, and the posterior predictive interval is estimated with Monte Carlo sampling. This parameter is the number of samples to use (defaults to 1000). The running time for predict will be linear in this number. Making it smaller will increase the variance (Monte Carlo error) of the uncertainty interval, and making it larger will reduce that variance. So, if the uncertainty estimates seem jagged this could be increased to further smooth them out, but it likely will not need to be changed. As with `interval_width`, this parameter only affects the uncertainty intervals and changing it will not affect in any way the forecast `yhat`; it does not need to be tuned.
 
-
-
-- `stan_backend`: If both pystan and cmdstanpy backends set up, the backend can be specified. The predictions will be the same, this will not be tuned.
-

docs/_docs/handling_shocks.md

@@ -4,14 +4,32 @@ docid: "handling_shocks"
 title: "Handling Shocks"
 permalink: /docs/handling_shocks.html
 subsections:
+  - title: Case Study - Pedestrian Activity
+    id: case-study---pedestrian-activity
+  - title: Default model without any adjustments
+    id: default-model-without-any-adjustments
   - title: Treating COVID-19 lockdowns as a one-off holidays
     id: treating-covid-19-lockdowns-as-a-one-off-holidays
   - title: Sense checking the trend
     id: sense-checking-the-trend
   - title: Changes in seasonality between pre- and post-COVID
     id: changes-in-seasonality-between-pre--and-post-covid
+  - title: Further reading
+    id: further-reading
 ---
-
+```python
+# Python
+%matplotlib inline
+from prophet import Prophet
+import pandas as pd
+from matplotlib import pyplot as plt
+import logging
+logging.getLogger('prophet').setLevel(logging.ERROR)
+import warnings
+warnings.filterwarnings("ignore")
+
+plt.rcParams['figure.figsize'] = 9, 6
+```
 As a result of the lockdowns caused by the COVID-19 pandemic, many time series experienced "shocks" during 2020, e.g. spikes in media consumption (Netflix, YouTube), e-commerce transactions (Amazon, eBay), whilst attendance to in-person events declined dramatically.
 
 
@@ -39,7 +57,7 @@ In this page we'll explore some strategies for capturing these effects using Pro
 
 
 
-For this case study we'll use [Pedestrian Sensor data from the City of Melbourne](https://data.melbourne.vic.gov.au/Transport/Pedestrian-Counting-System-Monthly-counts-per-hour/b2ak-trbp). This data measures foot traffic from sensors in various places in the central business district, and we've chosen one sensor (`Sensor_ID = 4`) and aggregated the values to a daily grain.
+For this case study we'll use [Pedestrian Sensor data from the City of Melbourne](https://data.melbourne.vic.gov.au/Transport/Pedestrian-Counting-System-Monthly-counts-per-hour/b2ak-trbp). This data measures foot traffic from sensors in various places in the central business district, and we've chosen one sensor (`Sensor_ID = 4`) and aggregated the values to a daily grain. 
 
 
 
@@ -87,6 +105,9 @@ m = m.fit(df)
 future = m.make_future_dataframe(periods=366)
 forecast = m.predict(future)
 ```
+    02:53:41 - cmdstanpy - INFO - Chain [1] start processing
+    02:53:41 - cmdstanpy - INFO - Chain [1] done processing
+
 
 ```python
 # Python
@@ -106,7 +127,7 @@ m.plot_components(forecast);
 ![png](/prophet/static/handling_shocks_files/handling_shocks_9_0.png)
 
 
-The model seems to fit reasonably to past data, but notice how we're capturing the dips, and the spikes after the dips, as a part of the trend component.
+The model seems to fit reasonably to past data, but notice how we're capturing the dips, and the spikes after the dips, as a part of the trend component. 
 
 
 
@@ -218,6 +239,9 @@ m2 = m2.fit(df)
 future2 = m2.make_future_dataframe(periods=366)
 forecast2 = m2.predict(future2)
 ```
+    02:53:44 - cmdstanpy - INFO - Chain [1] start processing
+    02:53:45 - cmdstanpy - INFO - Chain [1] done processing
+
 
 ```python
 # Python
@@ -276,7 +300,7 @@ a = add_changepoints_to_plot(fig.gca(), m2, forecast2)
 ![png](/prophet/static/handling_shocks_files/handling_shocks_18_0.png)
 
 
-The detected changepoints look reasonable, and the future trend tracks the latest upwards trend in activity, but not to the extent of late 2020. This seems suitable for a best guess of future activity.
+The detected changepoints look reasonable, and the future trend tracks the latest upwards trend in activity, but not to the extent of late 2020. This seems suitable for a best guess of future activity. 
 
 
 
@@ -287,7 +311,7 @@ We can see what the forecast would look like if we wanted to emphasize COVID pat
 # Python
 m3_changepoints = (
     # 10 potential changepoints in 2.5 years
-    pd.date_range('2017-06-02', '2020-01-01', periods=10).date.tolist() +
+    pd.date_range('2017-06-02', '2020-01-01', periods=10).date.tolist() + 
     # 15 potential changepoints in 1 year 2 months
     pd.date_range('2020-02-01', '2021-04-01', periods=15).date.tolist()
 )
@@ -299,6 +323,9 @@ m3 = Prophet(holidays=lockdowns, changepoints=m3_changepoints, changepoint_prior
 m3 = m3.fit(df)
 forecast3 = m3.predict(future2)
 ```
+    02:53:49 - cmdstanpy - INFO - Chain [1] start processing
+    02:53:52 - cmdstanpy - INFO - Chain [1] done processing
+
 
 ```python
 # Python
@@ -365,6 +392,9 @@ m4.add_seasonality(
 # Python
 m4 = m4.fit(df2)
 ```
+    02:53:55 - cmdstanpy - INFO - Chain [1] start processing
+    02:53:56 - cmdstanpy - INFO - Chain [1] done processing
+
 
 We also need to create the `pre_covid` and `post_covid` flags in the future dataframe. This is so that Prophet can apply the correct weekly seasonality parameters to each future date.
 
@@ -417,3 +447,9 @@ A lot of the content in this page was inspired by this [GitHub discussion](https
 
 
 Overall though it's difficult to be confident in our forecasts in these environments when rules are constantly changing and outbreaks occur randomly. In this scenario it's more important to constantly re-train / re-evaluate our models and clearly communicate the increased uncertainty in forecasts.
+
+
+```python
+# Python
+
+```

docs/_docs/multiplicative_seasonality.md

@@ -68,7 +68,7 @@ fig = m.plot_components(forecast)
 ![png](/prophet/static/multiplicative_seasonality_files/multiplicative_seasonality_10_0.png)
 
 
-With `seasonality_mode='multiplicative'`, holiday effects will also be modeled as multiplicative. Any added seasonalities or extra regressors will by default use whatever `seasonality_mode` is set to, but can be overridden by specifying `mode='additive'` or `mode='multiplicative'` as an argument when adding the seasonality or regressor.
+With `seasonality_mode='multiplicative'`, holiday effects will also be modeled as multiplicative. Any added seasonalities or extra regressors will by default use whatever `seasonality_mode` is set to, but can be overriden by specifying `mode='additive'` or `mode='multiplicative'` as an argument when adding the seasonality or regressor.
 
 
 
@@ -88,3 +88,4 @@ m.add_seasonality('quarterly', period=91.25, fourier_order=8, mode='additive')
 m.add_regressor('regressor', mode='additive')
 ```
 Additive and multiplicative extra regressors will show up in separate panels on the components plot. Note, however, that it is pretty unlikely to have a mix of additive and multiplicative seasonalities, so this will generally only be used if there is a reason to expect that to be the case.
+

docs/_docs/non-daily_data.md

@@ -95,7 +95,7 @@ The forecast seems quite poor, with much larger fluctuations in the future than
 
 ```R
 # R
-future2 <- future %>%
+future2 <- future %>% 
   filter(as.numeric(format(ds, "%H")) < 6)
 fcst <- predict(m, future2)
 plot(m, fcst)
@@ -200,3 +200,4 @@ In monthly data, yearly seasonality can also be modeled with binary extra regres
 
 
 Holiday effects are applied to the particular date on which the holiday was specified. With data that has been aggregated to weekly or monthly frequency, holidays that don't fall on the particular date used in the data will be ignored: for example, a Monday holiday in a weekly time series where each data point is on a Sunday. To include holiday effects in the model, the holiday will need to be moved to the date in the history dataframe for which the effect is desired. Note that with weekly or monthly aggregated data, many holiday effects will be well-captured by the yearly seasonality, so added holidays may only be necessary for holidays that occur in different weeks throughout the time series.
+

docs/_docs/outliers.md

@@ -99,3 +99,4 @@ fig = m.plot(m.predict(future))
 ```
 
 ![png](/prophet/static/outliers_files/outliers_13_0.png)
+

docs/_docs/saturating_forecasts.md

@@ -24,11 +24,11 @@ Prophet allows you to make forecasts using a [logistic growth](https://en.wikipe
 
 ```R
 # R
-df <- read.csv('https://raw.githubusercontent.com/facebook/prophet/main/examples/example_wp_log_R.csv')
+df <- read.csv('https://raw.githubusercontent.com/facebook/prophet/main/examples/example_wp_log_peyton_manning.csv')
 ```
 ```python
 # Python
-df = pd.read_csv('https://raw.githubusercontent.com/facebook/prophet/main/examples/example_wp_log_R.csv')
+df = pd.read_csv('https://raw.githubusercontent.com/facebook/prophet/main/examples/example_wp_log_peyton_manning.csv')
 ```
 We must specify the carrying capacity in a column `cap`. Here we will assume a particular value, but this would usually be set using data or expertise about the market size.
 
@@ -119,3 +119,4 @@ fig = m.plot(fcst)
 
 
 To use a logistic growth trend with a saturating minimum, a maximum capacity must also be specified.
+