0
# Prophet
1
2
Prophet is a comprehensive time series forecasting library that implements an additive model where non-linear trends are fit with yearly, weekly, and daily seasonality, plus holiday effects. Developed by Facebook's Core Data Science team, it excels at forecasting time series with strong seasonal effects and multiple seasons of historical data, providing robust handling of missing data, trend shifts, and outliers.
3
4
## Package Information
5
6
- **Package Name**: prophet
7
- **Language**: Python
8
- **Installation**: `pip install prophet`
9
10
## Core Imports
11
12
```python
13
from prophet import Prophet
14
```
15
16
For plotting functionality:
17
18
```python
19
from prophet.plot import plot, plot_components
20
```
21
22
For diagnostics and cross-validation:
23
24
```python
25
from prophet.diagnostics import cross_validation, performance_metrics
26
```
27
28
## Basic Usage
29
30
```python
31
import pandas as pd
32
import numpy as np
33
from prophet import Prophet
34
35
# Prepare your data with 'ds' (datestamp) and 'y' (value) columns
36
df = pd.DataFrame({
37
'ds': pd.date_range('2020-01-01', periods=365, freq='D'),
38
'y': np.random.randn(365).cumsum() + 100
39
})
40
41
# Create and fit the model
42
model = Prophet()
43
model.fit(df)
44
45
# Make future dataframe for predictions
46
future = model.make_future_dataframe(periods=30) # 30 days into future
47
48
# Generate forecast
49
forecast = model.predict(future)
50
51
# Plot results
52
fig = model.plot(forecast)
53
fig_components = model.plot_components(forecast)
54
```
55
56
## Architecture
57
58
Prophet uses a decomposable time series model with three main components:
59
60
- **Trend**: Captures non-periodic changes (linear, logistic, or flat growth)
61
- **Seasonality**: Captures periodic changes (yearly, weekly, daily patterns using Fourier series)
62
- **Holidays**: Captures effects of user-provided holidays with custom windows
63
- **Error**: Captures idiosyncratic changes not accommodated by the model
64
65
The model equation: y(t) = g(t) + s(t) + h(t) + ε(t)
66
67
Prophet uses a Bayesian approach with Stan for parameter estimation, providing uncertainty intervals and allowing for incorporation of prior knowledge through hyperparameters.
68
69
## Capabilities
70
71
### Core Forecasting
72
73
The main Prophet class providing time series forecasting with trend, seasonality, and holiday modeling. Supports linear, logistic, and flat growth trends with automatic changepoint detection.
74
75
```python { .api }
76
class Prophet:
77
def __init__(
78
self,
79
growth='linear',
80
changepoints=None,
81
n_changepoints=25,
82
changepoint_range=0.8,
83
yearly_seasonality='auto',
84
weekly_seasonality='auto',
85
daily_seasonality='auto',
86
holidays=None,
87
seasonality_mode='additive',
88
seasonality_prior_scale=10.0,
89
holidays_prior_scale=10.0,
90
changepoint_prior_scale=0.05,
91
mcmc_samples=0,
92
interval_width=0.8,
93
uncertainty_samples=1000,
94
stan_backend=None,
95
scaling='absmax',
96
holidays_mode=None
97
): ...
98
99
def fit(self, df, **kwargs): ...
100
def predict(self, df=None, vectorized=True): ...
101
def make_future_dataframe(self, periods, freq='D', include_history=True): ...
102
```
103
104
[Core Forecasting](./core-forecasting.md)
105
106
### Plotting and Visualization
107
108
Comprehensive plotting functionality supporting both matplotlib and Plotly backends for forecast visualization, component decomposition, and seasonality analysis.
109
110
```python { .api }
111
def plot(m, fcst, ax=None, uncertainty=True, plot_cap=True, **kwargs): ...
112
def plot_components(m, fcst, uncertainty=True, plot_cap=True, **kwargs): ...
113
def plot_plotly(m, fcst, **kwargs): ...
114
def plot_components_plotly(m, fcst, **kwargs): ...
115
```
116
117
[Plotting and Visualization](./plotting.md)
118
119
### Model Diagnostics
120
121
Time series cross-validation and performance evaluation tools for model validation, including multiple performance metrics and rolling window analysis.
122
123
```python { .api }
124
def cross_validation(
125
model,
126
horizon,
127
period=None,
128
initial=None,
129
parallel=None,
130
cutoffs=None,
131
disable_tqdm=False,
132
extra_output_columns=None
133
): ...
134
135
def performance_metrics(df, metrics=None, rolling_window=0.1, monthly=False): ...
136
```
137
138
[Model Diagnostics](./diagnostics.md)
139
140
### Serialization
141
142
Model persistence functionality for saving and loading trained Prophet models using JSON serialization.
143
144
```python { .api }
145
def model_to_json(model): ...
146
def model_from_json(model_json): ...
147
def model_to_dict(model): ...
148
def model_from_dict(model_dict): ...
149
```
150
151
[Serialization](./serialization.md)
152
153
### Utilities
154
155
Helper functions for analyzing regressor coefficients, extracting model parameters, and supporting advanced model introspection.
156
157
```python { .api }
158
def regressor_coefficients(m): ...
159
def regressor_index(m, name): ...
160
def warm_start_params(m): ...
161
```
162
163
[Utilities](./utilities.md)
164
165
### Holiday Support
166
167
Built-in holiday calendars for multiple countries and functionality for creating custom holiday definitions with flexible windows and effects.
168
169
```python { .api }
170
def get_holiday_names(country): ...
171
def make_holidays_df(year_list, country, province=None, state=None): ...
172
```
173
174
[Holiday Support](./holidays.md)
175
176
## Types
177
178
```python { .api }
179
# Core data structures
180
class ModelInputData:
181
"""Input data structure for Stan model"""
182
183
class ModelParams:
184
"""Model parameters structure"""
185
186
# Enums
187
class TrendIndicator:
188
LINEAR = 0
189
LOGISTIC = 1
190
FLAT = 2
191
192
# Expected DataFrame formats
193
# Training data: DataFrame with 'ds' (datetime) and 'y' (numeric) columns
194
# Future data: DataFrame with 'ds' column, 'cap' for logistic growth, regressor columns
195
# Holidays: DataFrame with 'ds' and 'holiday' columns, optional 'lower_window', 'upper_window', 'prior_scale'
196
```