How facebook/prophet works
1. Repository purpose
- This is the Prophet forecasting library, maintained as a multi-language package repo.
- The core product is the same statistical model exposed through two primary APIs: an R package under R/ and a Python package under python/.
- A third compatibility layer exists in python_shim/ for the older fbprophet package name.
2. Core modeling boundary
- The real modeling engine is a Stan time-series model stored in R/inst/stan/prophet.stan and python/stan/prophet.stan.
- Both language frontends prepare data, invoke Stan, and then post-process results; neither contains the forecasting logic itself.
- This makes the architecture “thin language wrapper + shared probabilistic model.”
3. R package subsystem
- R/R/ contains the public R API and internal helpers: the main prophet() object, fitting/prediction methods, plotting, diagnostics, holiday generation, and Stan-backend selection.
- R/NAMESPACE, R/DESCRIPTION, R/man/, and R/tests/ indicate a conventional CRAN package structure.
- R/src/ and the configure scripts support package compilation and platform-specific build setup, including Windows handling.
4. Python package subsystem
- python/prophet/ is the Python implementation with the main Prophet class in forecaster.py, diagnostics, plotting, serialization, utilities, and holiday generation.
- python/pyproject.toml and python/setup.py show it is packaged as a standard Python distribution.
- python/prophet/tests/ contains unit and regression tests, including serialized model fixtures for backward compatibility checks.
5. Shared data preparation pipeline
- In both languages, the user-facing API takes a time series table with date and value columns, validates it, scales/normalizes inputs, constructs seasonal features, holiday indicators, regressors, and changepoints, then sends the result to Stan.
- After Stan returns posterior samples or point estimates, the libraries compute trend, seasonal components, uncertainty intervals, and final forecasts.
- This preprocessing/postprocessing pipeline is the main data-flow backbone of the repo.
6. Holidays and country calendars
- Holiday support is a distinct subsystem, with generated holiday datasets and code for constructing holiday feature matrices.
- The R side keeps generated holiday sources in R/data-raw/, while Python has generation scripts in python/scripts/generate_holidays_file.py.
- Holiday functionality is shared conceptually but implemented separately in each language binding.
7. Diagnostics and evaluation
- Both implementations include cross-validation and forecast metric utilities, which are not just helpers but a separate analytical layer on top of the model.
- This layer generates cutoff-based backtests, computes metrics such as MAE/MSE/RMSE/MAPE/SMAPE, and supports plots of performance over forecast horizon.
- It depends on the fitted model output rather than directly on Stan.
8. Visualization layer
- Plotting is handled in each frontend, with R plotting functions in R/R/plot.R and Python plotting in python/prophet/plot.py.
- These functions consume forecast objects and diagnostic outputs to produce decomposition plots, forecast plots, seasonality views, and component breakdowns.
- Plotting is therefore a read-only presentation boundary over fitted model artifacts.
9. Serialization and interoperability
- Python includes serialize.py and several serialized test fixtures, indicating explicit support for saving/loading models across versions.
- This is an important boundary for model portability and long-term compatibility, separate from training and prediction.
- The R package also contains internal loading/model helper routines, but Python’s serialization surface is more explicit in the tree.
10. Backend/runtime abstraction
- The R package includes stan_backends.R and stanmodels.R, and the README calls out rstan plus an experimental cmdstanr backend.
- On the Python side, the historical shift is to cmdstanpy/CmdStan-based execution, with packaging logic that can compile or repackage CmdStan binaries.
- So the repo has an abstraction layer for “how Stan runs,” separate from the forecasting model itself.
11. Documentation and examples
- docs/ is a full static documentation site with markdown docs, generated assets, layouts, styles, and hosted tutorials.
- notebooks/ and examples/ provide reproducible end-to-end usage flows and sample datasets.
- These are not part of the runtime, but they document the intended data flow from input time series to forecast output.
12. Build, release, and CI
- GitHub Actions workflows, Travis config, Docker support, and package build files indicate a CI/release system for multiple artifacts.
- The repo builds R source packages, Python wheels/sdist artifacts, and documentation, with platform-specific packaging concerns.
- This matters architecturally because model compilation and binary distribution are part of the delivery pipeline, not just development tooling.
13. Compatibility layer
- python_shim/ mirrors the older fbprophet package namespace and implementation surface.
- This is a migration/compatibility boundary that preserves older imports and package expectations while the main Python package lives under prophet.
- It is separate from the primary Python package but shares the same conceptual API.
14. Overall architecture summary
- The repo is best drawn as three main layers: language frontends (R, Python, shim), shared statistical model in Stan, and supporting services around holidays, diagnostics, plotting, serialization, docs, and packaging.
- Data flows from user time series input into preprocessing, through Stan inference, and back into forecast objects consumed by diagnostics/visualization/serialization layers.
- The main architectural boundary is between the host language APIs and the Stan inference engine.
Main entry points: forecaster.py Python API · prophet.R R API · index.md Docs site · example_air_passengers.csv Examples
Components 18
Shared model
Common Stan inference engine used by both language frontends.
- R Stan · Embedded Stan model source used by the R package.
R/inst/stan/prophet.stan - Python Stan · Embedded Stan model source used by the Python package.
python/stan/prophet.stan
R package
CRAN-style R frontend and package internals.
- R API · Public R entry points and forecast object methods.
R/R/prophet.R - R prep · Input validation, scaling, seasonal features, changepoints, and helper utilities.
R/R/utilities.R - R backend · Backend selection and Stan model wiring for R execution.
R/R/stan_backends.R - R metrics · Cross-validation and forecast evaluation utilities.
R/R/diagnostics.R - R plots · Forecast, component, and seasonality plotting functions.
R/R/plot.R - R holidays · Holiday feature construction and generated holiday data.
R/R/make_holidays.R
Python package
Modern Python frontend and distribution.
- Python API · Main Prophet class and package entry surface.
python/prophet/forecaster.py - Python prep · Validation, scaling, feature building, and forecast object assembly.
python/prophet/utilities.py - Python backend · CmdStan-oriented model execution and backend abstraction.
python/prophet/models.py - Python metrics · Cross-validation, horizon metrics, and performance analysis.
python/prophet/diagnostics.py - Python plots · Forecast and component plotting functions.
python/prophet/plot.py - Python serialize · Model save/load and versioned serialization support.
python/prophet/serialize.py - Python holidays · Holiday feature generation and country calendar support.
python/prophet/make_holidays.py
Supporting layers
Compatibility, docs, examples, and release tooling around the model.
- fbprophet API · Legacy namespace compatibility layer for older imports.
python_shim/fbprophet/forecaster.py - Docs site · Static documentation, tutorials, and rendered examples.
docs/index.md - Examples · Sample datasets and notebooks demonstrating end-to-end forecasting.
examples/example_air_passengers.csv
Connections 20
- R API → R prep: prepares · The R API validates and transforms user time series before fitting.
- R API → R backend: fits via · The R API delegates inference to the Stan backend layer.
- R backend → R Stan: runs · R backend executes the shared Stan model.
- R API → R metrics: evaluates · Forecast objects feed cross-validation and metrics routines.
- R API → R plots: renders · Forecast output is consumed by plotting helpers.
- R API → R holidays: adds holidays · Holiday features are composed into the R model inputs.
- Python API → Python prep: prepares · The Python API validates, scales, and builds model features.
- Python API → Python backend: fits via · The Python API delegates execution to the backend layer.
- Python backend → Python Stan: runs · Python backend executes the shared Stan model.
- Python API → Python metrics: evaluates · Fitted forecasts feed diagnostics and backtesting.
- Python API → Python plots: renders · Forecast objects feed plotting and decomposition views.
- Python API → Python holidays: adds holidays · Holiday features are generated for Python model inputs.
- Python API → Python serialize: serializes · Python exposes explicit model persistence boundaries.
- fbprophet API → Python API: maps to · The legacy fbprophet namespace mirrors the modern Python API.
- Docs site → R API: documents · Docs describe the R user-facing forecasting flow.
- Docs site → Python API: documents · Docs describe the Python user-facing forecasting flow.
- Examples → R API: demonstrates · Examples and notebooks show the forecasting API in practice.
- Examples → Python API: demonstrates · Examples and notebooks show the Python workflow in practice.
- R holidays → Python holidays: conceptually shared · Holiday support is implemented separately but follows the same idea.
- R metrics → Python metrics: parallel layer · Both frontends provide similar cross-validation and metric utilities.