Update site with documentation updates

docs/_data/nav_docs.yml

@@ -4,7 +4,8 @@
   - id: quick_start
   - id: saturating_forecasts
   - id: trend_changepoints
-  - id: seasonality_and_holiday_effects
+  - id: seasonality,_holiday_effects,_and_regressors
+  - id: multiplicative_seasonality
   - id: uncertainty_intervals
   - id: outliers
   - id: non-daily_data

docs/_docs/contributing.md

@@ -5,7 +5,7 @@ title: "Getting Help and Contributing"
 permalink: /docs/contributing.html
 ---
 
-Prophet has an non-fixed release cycle but we will be making bugfixes in response to user feedback and adding features.  Its current state is Beta (v0.3), we expect no obvious bugs. Please let us know if you encounter a bug by [filing an issue](https://github.com/facebook/prophet/issues). Github issues is also the right place to ask questions about using Prophet.
+Prophet has a non-fixed release cycle but we will be making bugfixes in response to user feedback and adding features.  Its current state is Beta (v0.3), we expect no obvious bugs. Please let us know if you encounter a bug by [filing an issue](https://github.com/facebook/prophet/issues). Github issues is also the right place to ask questions about using Prophet.
 
 We appreciate all contributions. If you are planning to contribute back bug-fixes, please do so without any further discussion.
 

docs/_docs/multiplicative_seasonality.md

@@ -0,0 +1,81 @@
+---
+layout: docs
+docid: "multiplicative_seasonality"
+title: "Multiplicative Seasonality"
+permalink: /docs/multiplicative_seasonality.html
+---
+By default Prophet fits additive seasonalities, meaning the effect of the seasonality is added to the trend to get the forecast. This time series of the number of air passengers is an example of when additive seasonality does not work:
+
+```R
+# R
+df <- read.csv('../examples/example_air_passengers.csv')
+m <- prophet(df)
+future <- make_future_dataframe(m, 50, freq = 'm')
+forecast <- predict(m, future)
+plot(m, forecast)
+```
+```python
+# Python
+df = pd.read_csv('../examples/example_air_passengers.csv')
+m = Prophet()
+m.fit(df)
+future = m.make_future_dataframe(50, freq='MS')
+forecast = m.predict(future)
+fig = m.plot(forecast)
+```
+ 
+![png](/prophet/static/multiplicative_seasonality_files/multiplicative_seasonality_4_0.png) 
+
+
+This time series has a clear yearly cycle, but the seasonality in the forecast is too large at the start of the time series and too small at the end. In this time series, the seasonality is not a constant additive factor as assumed by Prophet, rather it grows with the trend. This is multiplicative seasonality.
+
+Prophet can model multiplicative seasonality by setting `seasonality_mode='multiplicative'` in the input arguments:
+
+```R
+# R
+m <- prophet(df, seasonality.mode = 'multiplicative')
+forecast <- predict(m, future)
+plot(m, forecast)
+```
+```python
+# Python
+m = Prophet(seasonality_mode='multiplicative')
+m.fit(df)
+forecast = m.predict(future)
+fig = m.plot(forecast)
+```
+ 
+![png](/prophet/static/multiplicative_seasonality_files/multiplicative_seasonality_7_0.png) 
+
+
+The components figure will now show the seasonality as a percent of the trend:
+
+```R
+# R
+prophet_plot_components(m, forecast)
+```
+```python
+# Python
+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 overriden by specifying `mode='additive'` or `mode='multiplicative'` as an argument when adding the seasonality or regressor.
+
+For example, this block sets the built-in seasonalities to multiplicative, but includes an additive quarterly seasonality and an additive regressor:
+
+```R
+# R
+m <- prophet(seasonality.mode = 'multiplicative')
+m <- add_seasonality(m, 'quarterly', period = 91.25, fourier.order = 8, mode = 'additive')
+m <- add_regressor(m, 'regressor', mode = 'additive')
+```
+```python
+# Python
+m = Prophet(seasonality_mode='multiplicative')
+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.

docs/_docs/outliers.md

@@ -8,22 +8,20 @@ There are two main ways that outliers can affect Prophet forecasts. Here we make
 
 ```R
 # R
-df <- read.csv('../examples/example_wp_R_outliers1.csv')
-df$y <- log(df$y)
+df <- read.csv('../examples/example_wp_log_R_outliers1.csv')
 m <- prophet(df)
 future <- make_future_dataframe(m, periods = 1096)
 forecast <- predict(m, future)
-plot(m, forecast);
+plot(m, forecast)
 ```
 ```python
 # Python
-df = pd.read_csv('../examples/example_wp_R_outliers1.csv')
-df['y'] = np.log(df['y'])
+df = pd.read_csv('../examples/example_wp_log_R_outliers1.csv')
 m = Prophet()
 m.fit(df)
 future = m.make_future_dataframe(periods=1096)
 forecast = m.predict(future)
-m.plot(forecast);
+fig = m.plot(forecast)
 ```
  
 ![png](/prophet/static/outliers_files/outliers_4_0.png) 
@@ -40,13 +38,13 @@ outliers <- (as.Date(df$ds) > as.Date('2010-01-01')
 df$y[outliers] = NA
 m <- prophet(df)
 forecast <- predict(m, future)
-plot(m, forecast);
+plot(m, forecast)
 ```
 ```python
 # Python
 df.loc[(df['ds'] > '2010-01-01') & (df['ds'] < '2011-01-01'), 'y'] = None
 model = Prophet().fit(df)
-model.plot(model.predict(future));
+fig = model.plot(model.predict(future))
 ```
  
 ![png](/prophet/static/outliers_files/outliers_7_0.png) 
@@ -56,22 +54,20 @@ In the above example the outliers messed up the uncertainty estimation but did n
 
 ```R
 # R
-df <- read.csv('../examples/example_wp_R_outliers2.csv')
-df$y = log(df$y)
+df <- read.csv('../examples/example_wp_log_R_outliers2.csv')
 m <- prophet(df)
 future <- make_future_dataframe(m, periods = 1096)
 forecast <- predict(m, future)
-plot(m, forecast);
+plot(m, forecast)
 ```
 ```python
 # Python
-df = pd.read_csv('../examples/example_wp_R_outliers2.csv')
-df['y'] = np.log(df['y'])
+df = pd.read_csv('../examples/example_wp_log_R_outliers2.csv')
 m = Prophet()
 m.fit(df)
 future = m.make_future_dataframe(periods=1096)
 forecast = m.predict(future)
-m.plot(forecast);
+fig = m.plot(forecast)
 ```
  
 ![png](/prophet/static/outliers_files/outliers_10_0.png) 
@@ -86,13 +82,13 @@ outliers <- (as.Date(df$ds) > as.Date('2015-06-01')
 df$y[outliers] = NA
 m <- prophet(df)
 forecast <- predict(m, future)
-plot(m, forecast);
+plot(m, forecast)
 ```
 ```python
 # Python
 df.loc[(df['ds'] > '2015-06-01') & (df['ds'] < '2015-06-30'), 'y'] = None
 m = Prophet().fit(df)
-m.plot(m.predict(future));
+fig = m.plot(m.predict(future))
 ```
  
 ![png](/prophet/static/outliers_files/outliers_13_0.png) 

docs/_docs/saturating_forecasts.md

@@ -10,40 +10,37 @@ By default, Prophet uses a linear model for its forecast. When forecasting growt
 
 Prophet allows you to make forecasts using a [logistic growth](https://en.wikipedia.org/wiki/Logistic_function) trend model, with a specified carrying capacity. We illustrate this with the log number of page visits to the [R (programming language)](https://en.wikipedia.org/wiki/R_%28programming_language%29) page on Wikipedia:
 
-```python
-# Python
-df = pd.read_csv('../examples/example_wp_R.csv')
-import numpy as np
-df['y'] = np.log(df['y'])
-```
 ```R
 # R
-df <- read.csv('../examples/example_wp_R.csv')
-df$y <- log(df$y)
+df <- read.csv('../examples/example_wp_log_R.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.
-
 ```python
 # Python
-df['cap'] = 8.5
+df = pd.read_csv('../examples/example_wp_log_R.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.
+
 ```R
 # R
 df$cap <- 8.5
 ```
+```python
+# Python
+df['cap'] = 8.5
+```
 The important things to note are that `cap` must be specified for every row in the dataframe, and that it does not have to be constant. If the market size is growing, then `cap` can be an increasing sequence.
 
 We then fit the model as before, except pass in an additional argument to specify logistic growth:
 
+```R
+# R
+m <- prophet(df, growth = 'logistic')
+```
 ```python
 # Python
 m = Prophet(growth='logistic')
 m.fit(df)
 ```
-```R
-# R
-m <- prophet(df, growth = 'logistic')
-```
 We make a dataframe for future predictions as before, except we must also specify the capacity in the future. Here we keep capacity constant at the same value as in the history, and forecast 3 years into the future:
 
 ```R
@@ -51,14 +48,14 @@ We make a dataframe for future predictions as before, except we must also specif
 future <- make_future_dataframe(m, periods = 1826)
 future$cap <- 8.5
 fcst <- predict(m, future)
-plot(m, fcst);
+plot(m, fcst)
 ```
 ```python
 # Python
 future = m.make_future_dataframe(periods=1826)
 future['cap'] = 8.5
 fcst = m.predict(future)
-m.plot(fcst);
+fig = m.plot(fcst)
 ```
  
 ![png](/prophet/static/saturating_forecasts_files/saturating_forecasts_13_0.png) 
@@ -91,7 +88,7 @@ future['floor'] = 1.5
 m = Prophet(growth='logistic')
 m.fit(df)
 fcst = m.predict(future)
-m.plot(fcst);
+fig = m.plot(fcst)
 ```
  
 ![png](/prophet/static/saturating_forecasts_files/saturating_forecasts_16_0.png) 

docs/_docs/uncertainty_intervals.md

@@ -15,39 +15,39 @@ One property of this way of measuring uncertainty is that allowing higher flexib
 
 The width of the uncertainty intervals (by default 80%) can be set using the parameter `interval_width`:
 
-```python
-# Python
-forecast = Prophet(interval_width=0.95).fit(df).predict(future)
-```
 ```R
 # R
 m <- prophet(df, interval.width = 0.95)
 forecast <- predict(m, future)
 ```
+```python
+# Python
+forecast = Prophet(interval_width=0.95).fit(df).predict(future)
+```
 Again, these intervals assume that the future will see the same frequency and magnitude of rate changes as the past. This assumption is probably not true, so you should not expect to get accurate coverage on these uncertainty intervals.
 
 ### Uncertainty in seasonality
-By default Prophet will only return uncertainty in the trend and observation noise. To get uncertainty in seasonality, you must do full Bayesian sampling. This is done using the parameter `mcmc.samples` (which defaults to 0). We do this here for the Peyton Manning data from the Quickstart:
+By default Prophet will only return uncertainty in the trend and observation noise. To get uncertainty in seasonality, you must do full Bayesian sampling. This is done using the parameter `mcmc.samples` (which defaults to 0). We do this here for the first six months of the Peyton Manning data from the Quickstart:
 
-```python
-# Python
-m = Prophet(mcmc_samples=300)
-forecast = m.fit(df).predict(future)
-```
 ```R
 # R
 m <- prophet(df, mcmc.samples = 300)
 forecast <- predict(m, future)
 ```
-This replaces the typical MAP estimation with MCMC sampling, and takes much longer - think 10 minutes instead of 10 seconds. If you do full sampling, then you will see the uncertainty in seasonal components when you plot them:
-
 ```python
 # Python
-m.plot_components(forecast);
+m = Prophet(mcmc_samples=300)
+forecast = m.fit(df).predict(future)
 ```
+This replaces the typical MAP estimation with MCMC sampling, and can take much longer depending on how many observations there are - expect several minutes instead of several seconds. If you do full sampling, then you will see the uncertainty in seasonal components when you plot them:
+
 ```R
 # R
-prophet_plot_components(m, forecast);
+prophet_plot_components(m, forecast)
+```
+```python
+# Python
+fig = m.plot_components(forecast)
 ```
  
 ![png](/prophet/static/uncertainty_intervals_files/uncertainty_intervals_10_0.png) 

docs/index.md

@@ -4,7 +4,7 @@ title: Prophet
 id: home
 ---
 
-Prophet is a procedure for forecasting time series data.  It is based on an additive model where non-linear trends are fit with yearly and weekly seasonality, plus holidays. It works best with daily periodicity data with at least one year of historical data. Prophet is robust to missing data, shifts in the trend, and large outliers.
+Prophet is a procedure for forecasting time series data based on an additive model where non-linear trends are fit with yearly, weekly, and daily seasonality, plus holiday effects. It works best with time series that have strong seasonal effects and several seasons of historical data. Prophet is robust to missing data and shifts in the trend, and typically handles outliers well.
 
 Prophet is [open source software](https://code.facebook.com/projects/) released by Facebook's [Core Data Science team](https://research.fb.com/category/data-science/).  It is available for download on [CRAN](https://cran.r-project.org/package=prophet) and [PyPI](https://pypi.python.org/pypi/fbprophet/).
 

notebooks/non-daily_data.ipynb

@@ -506,7 +506,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The seasonality has low uncertainty at the start of each month where there are data points, but has very high posterior variance in between. When fitting Prophet to monthly data, only make monthly forecasts, which can be done by passing the frequency into make_future_dataframe:"
+    "The seasonality has low uncertainty at the start of each month where there are data points, but has very high posterior variance in between. When fitting Prophet to monthly data, only make monthly forecasts, which can be done by passing the frequency into `make_future_dataframe`:"
    ]
   },
   {
@@ -570,7 +570,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython2",
-   "version": "2.7.14+"
+   "version": "2.7.13"
   }
  },
  "nbformat": 4,

notebooks/quick_start.ipynb

@@ -394,7 +394,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "More details about the options available for each method are available in the docstrings, for example, via `help(Prophet)` or `help(Prophet.fit)`."
+    "More details about the options available for each method are available in the docstrings, for example, via `help(Prophet)` or `help(Prophet.fit)`. The [R reference manual](https://cran.r-project.org/web/packages/prophet/prophet.pdf) on CRAN provides a concise list of all of the available functions, each of which has a Python equivalent."
    ]
   },
   {
@@ -612,7 +612,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython2",
-   "version": "2.7.14+"
+   "version": "2.7.13"
   }
  },
  "nbformat": 4,

notebooks/seasonality,_holiday_effects,_and_regressors.ipynb

@@ -357,9 +357,7 @@
   {
    "cell_type": "code",
    "execution_count": 10,
-   "metadata": {
-    "output_hidden": true
-   },
+   "metadata": {},
    "outputs": [
     {
      "data": {
@@ -380,7 +378,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Individual holidays can be plotted using the `plot_forecast_component` method (Python) or function (R). For example, `m.plot_forecast_component(forecast, 'superbowl')` in Python and `plot_forecast_component(forecast, 'superbowl')` in R to plot just the superbowl holiday component."
+    "Individual holidays can be plotted using the `plot_forecast_component` function (imported from `fbprophet.plot` in Python) like `plot_forecast_component(forecast, 'superbowl')` to plot just the superbowl holiday component."
    ]
   },
   {
@@ -511,7 +509,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Increasing the number of Fourier terms allows the seasonality to fit faster changing cycles, but can also lead to overfitting: $N$ Fourier terms corresponds to $2N$ variables used for modeling the cycle\n",
+    "Increasing the number of Fourier terms allows the seasonality to fit faster changing cycles, but can also lead to overfitting: N Fourier terms corresponds to 2N variables used for modeling the cycle\n",
     "\n",
     "### Specifying Custom Seasonalities\n",
     "\n",
@@ -801,6 +799,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "\n",
     "### Additional regressors\n",
     "Additional regressors can be added to the linear part of the model using the `add_regressor` method or function. A column with the regressor value will need to be present in both the fitting and prediction dataframes. For example, we can add an additional effect on Sundays during the NFL season. On the components plot, this effect will show up in the 'extra_regressors' plot:"
    ]
@@ -915,7 +914,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython2",
-   "version": "2.7.14+"
+   "version": "2.7.13"
   }
  },
  "nbformat": 4,