Update documentation
Ben Letham
|
|
@ -63,6 +63,12 @@ Make sure compilers (gcc, g++, build-essential) and Python development tools (py
|
|||
|
||||
## Changelog
|
||||
|
||||
### Version 0.5 (2019.05.14)
|
||||
|
||||
- Conditional seasonalities
|
||||
- Plotly plot in Python
|
||||
- Bugfixes
|
||||
|
||||
### Version 0.4 (2018.12.18)
|
||||
|
||||
- Added holidays functionality
|
||||
|
|
|
|||
|
|
@ -71,45 +71,45 @@ df_cv.head()
|
|||
<tr>
|
||||
<th>0</th>
|
||||
<td>2010-02-16</td>
|
||||
<td>8.957184</td>
|
||||
<td>8.438130</td>
|
||||
<td>9.431683</td>
|
||||
<td>8.956572</td>
|
||||
<td>8.460049</td>
|
||||
<td>9.460400</td>
|
||||
<td>8.242493</td>
|
||||
<td>2010-02-15</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>1</th>
|
||||
<td>2010-02-17</td>
|
||||
<td>8.723619</td>
|
||||
<td>8.228941</td>
|
||||
<td>9.225985</td>
|
||||
<td>8.723004</td>
|
||||
<td>8.200557</td>
|
||||
<td>9.236561</td>
|
||||
<td>8.008033</td>
|
||||
<td>2010-02-15</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2</th>
|
||||
<td>2010-02-18</td>
|
||||
<td>8.607378</td>
|
||||
<td>8.086717</td>
|
||||
<td>9.125563</td>
|
||||
<td>8.606823</td>
|
||||
<td>8.070835</td>
|
||||
<td>9.123754</td>
|
||||
<td>8.045268</td>
|
||||
<td>2010-02-15</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>3</th>
|
||||
<td>2010-02-19</td>
|
||||
<td>8.529250</td>
|
||||
<td>8.053584</td>
|
||||
<td>9.056437</td>
|
||||
<td>8.528688</td>
|
||||
<td>8.034782</td>
|
||||
<td>9.042712</td>
|
||||
<td>7.928766</td>
|
||||
<td>2010-02-15</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>4</th>
|
||||
<td>2010-02-20</td>
|
||||
<td>8.271228</td>
|
||||
<td>7.748368</td>
|
||||
<td>8.756539</td>
|
||||
<td>8.270706</td>
|
||||
<td>7.754891</td>
|
||||
<td>8.739012</td>
|
||||
<td>7.745003</td>
|
||||
<td>2010-02-15</td>
|
||||
</tr>
|
||||
|
|
@ -168,49 +168,49 @@ df_p.head()
|
|||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>3297</th>
|
||||
<th>0</th>
|
||||
<td>37 days</td>
|
||||
<td>0.481970</td>
|
||||
<td>0.694241</td>
|
||||
<td>0.502930</td>
|
||||
<td>0.058371</td>
|
||||
<td>0.673367</td>
|
||||
<td>0.495378</td>
|
||||
<td>0.703831</td>
|
||||
<td>0.505713</td>
|
||||
<td>0.058593</td>
|
||||
<td>0.680448</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>35</th>
|
||||
<td>37 days</td>
|
||||
<td>0.480991</td>
|
||||
<td>0.693535</td>
|
||||
<td>0.502007</td>
|
||||
<td>0.058262</td>
|
||||
<td>0.675879</td>
|
||||
<th>1</th>
|
||||
<td>38 days</td>
|
||||
<td>0.501134</td>
|
||||
<td>0.707908</td>
|
||||
<td>0.510680</td>
|
||||
<td>0.059169</td>
|
||||
<td>0.679077</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2207</th>
|
||||
<td>37 days</td>
|
||||
<td>0.480936</td>
|
||||
<td>0.693496</td>
|
||||
<td>0.501928</td>
|
||||
<td>0.058257</td>
|
||||
<td>0.675879</td>
|
||||
<th>2</th>
|
||||
<td>39 days</td>
|
||||
<td>0.523334</td>
|
||||
<td>0.723418</td>
|
||||
<td>0.516755</td>
|
||||
<td>0.059766</td>
|
||||
<td>0.677707</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2934</th>
|
||||
<td>37 days</td>
|
||||
<td>0.481455</td>
|
||||
<td>0.693870</td>
|
||||
<td>0.502999</td>
|
||||
<td>0.058393</td>
|
||||
<td>0.675879</td>
|
||||
<th>3</th>
|
||||
<td>40 days</td>
|
||||
<td>0.530625</td>
|
||||
<td>0.728440</td>
|
||||
<td>0.519645</td>
|
||||
<td>0.060075</td>
|
||||
<td>0.678849</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>393</th>
|
||||
<td>37 days</td>
|
||||
<td>0.483990</td>
|
||||
<td>0.695694</td>
|
||||
<td>0.503418</td>
|
||||
<td>0.058494</td>
|
||||
<td>0.675879</td>
|
||||
<th>4</th>
|
||||
<td>41 days</td>
|
||||
<td>0.538117</td>
|
||||
<td>0.733565</td>
|
||||
<td>0.520663</td>
|
||||
<td>0.060156</td>
|
||||
<td>0.686386</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
|
|
|||
|
|
@ -202,37 +202,37 @@ forecast[['ds', 'yhat', 'yhat_lower', 'yhat_upper']].tail()
|
|||
<tr>
|
||||
<th>3265</th>
|
||||
<td>2017-01-15</td>
|
||||
<td>8.199274</td>
|
||||
<td>7.489884</td>
|
||||
<td>8.969065</td>
|
||||
<td>8.212942</td>
|
||||
<td>7.463560</td>
|
||||
<td>8.937215</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>3266</th>
|
||||
<td>2017-01-16</td>
|
||||
<td>8.524244</td>
|
||||
<td>7.790682</td>
|
||||
<td>9.266504</td>
|
||||
<td>8.537993</td>
|
||||
<td>7.790259</td>
|
||||
<td>9.267492</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>3267</th>
|
||||
<td>2017-01-17</td>
|
||||
<td>8.311615</td>
|
||||
<td>7.553025</td>
|
||||
<td>9.049803</td>
|
||||
<td>8.325428</td>
|
||||
<td>7.525675</td>
|
||||
<td>9.059391</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>3268</th>
|
||||
<td>2017-01-18</td>
|
||||
<td>8.144232</td>
|
||||
<td>7.428174</td>
|
||||
<td>8.864747</td>
|
||||
<td>8.158059</td>
|
||||
<td>7.433634</td>
|
||||
<td>8.883627</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>3269</th>
|
||||
<td>2017-01-19</td>
|
||||
<td>8.156091</td>
|
||||
<td>7.395160</td>
|
||||
<td>8.883232</td>
|
||||
<td>8.170046</td>
|
||||
<td>7.431801</td>
|
||||
<td>8.840703</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
|
@ -262,6 +262,18 @@ fig2 = m.plot_components(forecast)
|
|||
|
||||
|
||||
|
||||
An interactive figure of the forecast can be created with plotly:
|
||||
|
||||
|
||||
```python
|
||||
# Python
|
||||
from fbprophet.plot import plot_plotly
|
||||
import plotly.offline as py
|
||||
py.init_notebook_mode()
|
||||
|
||||
fig = plot_plotly(m, forecast) # This returns a plotly Figure
|
||||
py.iplot(fig)
|
||||
```
|
||||
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.
|
||||
|
||||
|
||||
|
|
@ -338,7 +350,7 @@ You can use the generic `plot` function to plot the forecast, by passing in the
|
|||
plot(m, forecast)
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
You can use the `prophet_plot_components` function to see the forecast broken down into trend, weekly seasonality, and yearly seasonality.
|
||||
|
|
@ -349,7 +361,7 @@ You can use the `prophet_plot_components` function to see the forecast broken do
|
|||
prophet_plot_components(m, forecast)
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
An interactive plot of the forecast using Dygraphs can be made with the command `dyplot.prophet(m, forecast)`.
|
||||
|
|
|
|||
|
|
@ -12,6 +12,8 @@ subsections:
|
|||
id: fourier-order-for-seasonalities
|
||||
- title: Specifying Custom Seasonalities
|
||||
id: specifying-custom-seasonalities
|
||||
- title: Seasonalities that depend on other factors
|
||||
id: seasonalities-that-depend-on-other-factors
|
||||
- title: Prior scale for holidays and seasonality
|
||||
id: prior-scale-for-holidays-and-seasonality
|
||||
- title: Additional regressors
|
||||
|
|
@ -135,62 +137,62 @@ forecast[(forecast['playoff'] + forecast['superbowl']).abs() > 0][
|
|||
<tr>
|
||||
<th>2190</th>
|
||||
<td>2014-02-02</td>
|
||||
<td>1.229999</td>
|
||||
<td>1.176410</td>
|
||||
<td>1.217571</td>
|
||||
<td>1.230312</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2191</th>
|
||||
<td>2014-02-03</td>
|
||||
<td>1.900543</td>
|
||||
<td>1.486962</td>
|
||||
<td>1.898042</td>
|
||||
<td>1.466063</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2532</th>
|
||||
<td>2015-01-11</td>
|
||||
<td>1.229999</td>
|
||||
<td>1.217571</td>
|
||||
<td>0.000000</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2533</th>
|
||||
<td>2015-01-12</td>
|
||||
<td>1.900543</td>
|
||||
<td>1.898042</td>
|
||||
<td>0.000000</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2901</th>
|
||||
<td>2016-01-17</td>
|
||||
<td>1.229999</td>
|
||||
<td>1.217571</td>
|
||||
<td>0.000000</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2902</th>
|
||||
<td>2016-01-18</td>
|
||||
<td>1.900543</td>
|
||||
<td>1.898042</td>
|
||||
<td>0.000000</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2908</th>
|
||||
<td>2016-01-24</td>
|
||||
<td>1.229999</td>
|
||||
<td>1.217571</td>
|
||||
<td>0.000000</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2909</th>
|
||||
<td>2016-01-25</td>
|
||||
<td>1.900543</td>
|
||||
<td>1.898042</td>
|
||||
<td>0.000000</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2922</th>
|
||||
<td>2016-02-07</td>
|
||||
<td>1.229999</td>
|
||||
<td>1.176410</td>
|
||||
<td>1.217571</td>
|
||||
<td>1.230312</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>2923</th>
|
||||
<td>2016-02-08</td>
|
||||
<td>1.900543</td>
|
||||
<td>1.486962</td>
|
||||
<td>1.898042</td>
|
||||
<td>1.466063</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
|
@ -252,7 +254,7 @@ m$train.holiday.names
|
|||
[9] "Columbus Day" "Veterans Day"
|
||||
[11] "Veterans Day (Observed)" "Thanksgiving"
|
||||
[13] "Christmas Day" "Independence Day (Observed)"
|
||||
[15] "New Year's Day (Observed)" "Christmas Day (Observed)"
|
||||
[15] "Christmas Day (Observed)" "New Year's Day (Observed)"
|
||||
|
||||
|
||||
|
||||
|
|
@ -263,21 +265,21 @@ m.train_holiday_names
|
|||
|
||||
|
||||
|
||||
0 New Year's Day
|
||||
0 playoff
|
||||
1 superbowl
|
||||
2 Thanksgiving
|
||||
3 Veterans Day (Observed)
|
||||
4 Veterans Day
|
||||
5 Washington's Birthday
|
||||
6 Martin Luther King, Jr. Day
|
||||
7 Christmas Day
|
||||
8 Independence Day (Observed)
|
||||
9 Memorial Day
|
||||
10 Independence Day
|
||||
11 Labor Day
|
||||
2 New Year's Day
|
||||
3 Martin Luther King, Jr. Day
|
||||
4 Washington's Birthday
|
||||
5 Memorial Day
|
||||
6 Independence Day
|
||||
7 Labor Day
|
||||
8 Columbus Day
|
||||
9 Veterans Day
|
||||
10 Thanksgiving
|
||||
11 Christmas Day
|
||||
12 Christmas Day (Observed)
|
||||
13 Columbus Day
|
||||
14 playoff
|
||||
13 Veterans Day (Observed)
|
||||
14 Independence Day (Observed)
|
||||
15 New Year's Day (Observed)
|
||||
dtype: object
|
||||
|
||||
|
|
@ -299,10 +301,6 @@ As above, the country-level holidays will then show up in the components plot:
|
|||
forecast <- predict(m, future)
|
||||
prophet_plot_components(m, forecast)
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
```python
|
||||
# Python
|
||||
forecast = m.predict(future)
|
||||
|
|
@ -394,6 +392,73 @@ fig = m.plot_components(forecast)
|
|||
|
||||
|
||||
|
||||
<a id="seasonalities-that-depend-on-other-factors"> </a>
|
||||
|
||||
### Seasonalities that depend on other factors
|
||||
|
||||
In some instances the seasonality may depend on other factors, such as a weekly seasonal pattern that is different during the summer than it is during the rest of the year, or a daily seasonal pattern that is different on weekends vs. on weekdays. These types of seasonalities can be modeled using conditional seasonalities.
|
||||
|
||||
|
||||
|
||||
Consider the Peyton Manning example from the Quickstart. The default weekly seasonality assumes that the pattern of weekly seasonality is the same throughout the year, but we'd expect the pattern of weekly seasonality to be different during the on-season (when there are games every Sunday) and the off-season. We can use conditional seasonalities to construct separate on-season and off-season weekly seasonalities.
|
||||
|
||||
|
||||
|
||||
First we add a boolean column to the dataframe that indicates whether each date is during the on-season or the off-season:
|
||||
|
||||
|
||||
```R
|
||||
# R
|
||||
is_nfl_season <- function(ds) {
|
||||
dates <- as.Date(ds)
|
||||
month <- as.numeric(format(dates, '%m'))
|
||||
return(month > 8 | month < 2)
|
||||
}
|
||||
df$on_season <- is_nfl_season(df$ds)
|
||||
df$off_season <- !is_nfl_season(df$ds)
|
||||
```
|
||||
```python
|
||||
# Python
|
||||
def is_nfl_season(ds):
|
||||
date = pd.to_datetime(ds)
|
||||
return (date.month > 8 or date.month < 2)
|
||||
|
||||
df['on_season'] = df['ds'].apply(is_nfl_season)
|
||||
df['off_season'] = ~df['ds'].apply(is_nfl_season)
|
||||
```
|
||||
Then we disable the built-in weekly seasonality, and replace it with two weekly seasonalities that have these columns specified as a condition. This means that the seasonality will only be applied to dates where the `condition_name` column is `True`. We must also add the column to the `future` dataframe for which we are making predictions.
|
||||
|
||||
|
||||
```R
|
||||
# R
|
||||
m <- prophet(weekly.seasonality=FALSE)
|
||||
m <- add_seasonality(m, name='weekly_on_season', period=7, fourier.order=3, condition.name='on_season')
|
||||
m <- add_seasonality(m, name='weekly_off_season', period=7, fourier.order=3, condition.name='off_season')
|
||||
m <- fit.prophet(m, df)
|
||||
|
||||
future$on_season <- is_nfl_season(future$ds)
|
||||
future$off_season <- !is_nfl_season(future$ds)
|
||||
forecast <- predict(m, future)
|
||||
prophet_plot_components(m, forecast)
|
||||
```
|
||||
```python
|
||||
# Python
|
||||
m = Prophet(weekly_seasonality=False)
|
||||
m.add_seasonality(name='weekly_on_season', period=7, fourier_order=3, condition_name='on_season')
|
||||
m.add_seasonality(name='weekly_off_season', period=7, fourier_order=3, condition_name='off_season')
|
||||
|
||||
future['on_season'] = future['ds'].apply(is_nfl_season)
|
||||
future['off_season'] = ~future['ds'].apply(is_nfl_season)
|
||||
forecast = m.fit(df).predict(future)
|
||||
fig = m.plot_components(forecast)
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
Both of the seasonalities now show up in the components plots above. We can see that during the on-season when games are played every Sunday, there are large increases on Sunday and Monday that are completely absent during the off-season.
|
||||
|
||||
|
||||
<a id="prior-scale-for-holidays-and-seasonality"> </a>
|
||||
|
||||
### Prior scale for holidays and seasonality
|
||||
|
|
@ -576,13 +641,17 @@ forecast = m.predict(future)
|
|||
fig = m.plot_components(forecast)
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
NFL Sundays could also have been handled using the "holidays" interface described above, by creating a list of past and future NFL Sundays. The `add_regressor` function provides a more general interface for defining extra linear regressors, and in particular does not require that the regressor be a binary indicator. Another time series could be used as a regressor, although its future values would have to be known.
|
||||
|
||||
|
||||
|
||||
[This notebook](https://nbviewer.jupyter.org/github/nicolasfauchereau/Auckland_Cycling/blob/master/notebooks/Auckland_cycling_and_weather.ipynb) shows an example of using weather factors as extra regressors in a forecast of bicycle usage, and provides an excellent illustration of how other time series can be included as extra regressors.
|
||||
|
||||
|
||||
|
||||
The `add_regressor` function has optional arguments for specifying the prior scale (holiday prior scale is used by default) and whether or not the regressor is standardized - see the docstring with `help(Prophet.add_regressor)` in Python and `?add_regressor` in R. Note that regressors must be added prior to model fitting.
|
||||
|
||||
|
||||
|
|
|
|||
BIN
docs/static/diagnostics_files/diagnostics_11_0.png
vendored
|
Before Width: | Height: | Size: 67 KiB After Width: | Height: | Size: 67 KiB |
BIN
docs/static/diagnostics_files/diagnostics_12_0.png
vendored
|
Before Width: | Height: | Size: 65 KiB After Width: | Height: | Size: 66 KiB |
BIN
docs/static/diagnostics_files/diagnostics_3_0.png
vendored
|
Before Width: | Height: | Size: 52 KiB After Width: | Height: | Size: 52 KiB |
BIN
docs/static/quick_start_files/quick_start_27_0.png
vendored
|
Before Width: | Height: | Size: 86 KiB |
BIN
docs/static/quick_start_files/quick_start_29_0.png
vendored
|
Before Width: | Height: | Size: 41 KiB After Width: | Height: | Size: 86 KiB |
BIN
docs/static/quick_start_files/quick_start_31_0.png
vendored
Normal file
|
After Width: | Height: | Size: 41 KiB |
|
Before Width: | Height: | Size: 50 KiB After Width: | Height: | Size: 50 KiB |
|
Before Width: | Height: | Size: 62 KiB After Width: | Height: | Size: 61 KiB |
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 56 KiB |
|
Before Width: | Height: | Size: 64 KiB After Width: | Height: | Size: 64 KiB |
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 16 KiB |
|
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 28 KiB |
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 17 KiB |
|
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 43 KiB |
|
Before Width: | Height: | Size: 53 KiB After Width: | Height: | Size: 53 KiB |
|
After Width: | Height: | Size: 56 KiB |
|
After Width: | Height: | Size: 70 KiB |
|
Before Width: | Height: | Size: 55 KiB After Width: | Height: | Size: 55 KiB |
|
Before Width: | Height: | Size: 63 KiB After Width: | Height: | Size: 63 KiB |
|
|
@ -66,7 +66,9 @@
|
|||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 3,
|
||||
"metadata": {},
|
||||
"metadata": {
|
||||
"output_hidden": true
|
||||
},
|
||||
"outputs": [
|
||||
{
|
||||
"name": "stderr",
|
||||
|
|
@ -533,7 +535,9 @@
|
|||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 15,
|
||||
"metadata": {},
|
||||
"metadata": {
|
||||
"output_hidden": true
|
||||
},
|
||||
"outputs": [
|
||||
{
|
||||
"data": {
|
||||
|
|
@ -810,7 +814,9 @@
|
|||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 35,
|
||||
"metadata": {},
|
||||
"metadata": {
|
||||
"output_hidden": true
|
||||
},
|
||||
"outputs": [
|
||||
{
|
||||
"name": "stderr",
|
||||
|
|
@ -1198,6 +1204,7 @@
|
|||
}
|
||||
],
|
||||
"metadata": {
|
||||
"celltoolbar": "Edit Metadata",
|
||||
"kernelspec": {
|
||||
"display_name": "Python 3",
|
||||
"language": "python",
|
||||
|
|
@ -1213,7 +1220,7 @@
|
|||
"name": "python",
|
||||
"nbconvert_exporter": "python",
|
||||
"pygments_lexer": "ipython3",
|
||||
"version": "3.7.2"
|
||||
"version": "3.7.3"
|
||||
}
|
||||
},
|
||||
"nbformat": 4,
|
||||
|
|
|
|||