prophet

Prophet is Meta’s (formerly Facebook’s) open-source forecasting procedure for time series data with multiple seasonal patterns - daily, weekly, yearly - plus holiday effects and non-linear growth. It fits an additive regression model (trend + seasonality + holidays) via Stan, using either MAP point estimation or full Bayesian MCMC sampling, and is designed to be robust to missing data, outliers, and shifts in trend without requiring manual tuning from the analyst.

The library exposes a deliberately small, scikit-learn-style API - instantiate Prophet(), call .fit() on a two-column dataframe, then .predict() - while still allowing fine control through methods like add_seasonality(), add_regressor(), and add_country_holidays(). As of v1.4.0 (2026), the project is in maintenance mode: only bug fixes and dependency updates are accepted, with development focus shifted to keeping the Python and R packages at parity.

What You Get

• Additive forecasting model combining trend, yearly/weekly/daily seasonality, and holiday effects, fit via Stan (MAP or full MCMC)
• Automatic changepoint detection for non-linear/piecewise trend shifts, with linear, logistic, and flat growth modes
• Built-in country holiday calendars (via the holidays package) plus support for custom holiday and regressor effects
• Cross-validation and performance-metric utilities (diagnostics.py) for rolling-origin backtesting, optionally parallelized with Dask
• Matplotlib-based plotting for forecasts and component decomposition (trend/seasonality/holidays)
• JSON model serialization for saving and reloading a fitted model without re-running Stan

Common Use Cases

• Retail and demand forecasting with strong weekly/yearly seasonal patterns
• Capacity planning for infrastructure or traffic metrics with holiday-driven spikes
• Business KPI forecasting (revenue, signups) for planning and reporting
• Series with missing data, outliers, or trend shifts that break naive ARIMA/exponential-smoothing setups

Under The Hood

Architecture Prophet’s core is a facade class, Prophet (in forecaster.py, ~2,300 lines), that owns data preprocessing - scaling y, generating Fourier-series seasonality features, selecting changepoints - and delegates the actual parameter fitting to a pluggable IStanBackend abstraction (models.py), currently implemented by CmdStanPyBackend, which compiles and drives a Stan probabilistic program (stan/prophet.stan) for either MAP optimization or MCMC sampling. Cross-validation (diagnostics.py), plotting (plot.py), and serialization (serialize.py) are cleanly split into separate modules built on top of the public Prophet API rather than folded into the core class, so swapping the fitting backend or extending diagnostics doesn’t require touching feature engineering code. The main coupling risk is that forecaster.py itself is a large, multi-responsibility class tightly bound to pandas/numpy.

Tech Stack Python 3.10+ with cmdstanpy wrapping CmdStan (a C++ Bayesian inference engine using L-BFGS optimization or Hamiltonian Monte Carlo), numpy and pandas for data handling, matplotlib for plotting, the holidays package for country holiday calendars, and tqdm for progress reporting; an optional parallel extra adds dask/distributed for parallelized cross-validation. The probabilistic model itself is written in Stan, a domain-specific modeling language compiled to native C++ binaries at build time - the project ships a Dockerized wheel-building pipeline to repackage those binaries across platforms.

Code Quality The prophet/tests/ suite covers roughly 80 test cases across four modules (core fit/predict behavior, diagnostics/cross-validation, serialization round-trips, and utilities), using pytest fixtures and parametrized cases across scaling and growth modes, with versioned serialized-model fixtures to guard backward compatibility. The codebase is extensively type-hinted (dataclasses, Literal types, numpy.typing, a py.typed marker) and CI runs the test suite across macOS/Linux/Windows on both Intel and ARM, plus a dedicated typecheck job. No dedicated linter config was found, but the type-checking job substitutes for a meaningful chunk of static analysis.

API Design The public surface is deliberately minimal and scikit-learn-shaped: construct Prophet(), call .fit(df) on a two-column ds/y dataframe, then .predict(future) to get a forecast dataframe with uncertainty intervals - no manual differencing, order selection, or feature engineering required. Extensibility is opt-in via named methods (add_seasonality, add_regressor, add_country_holidays) rather than constructor parameter sprawl, and every constructor argument is documented in the class docstring itself, making the docstring double as living reference documentation.