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
```