GO — Healthy across the board

• Last commit 1d ago
• 32+ active contributors
• Distributed ownership (top contributor 43% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Prophet is an open-source time series forecasting library developed by Meta that fits additive models with non-linear trends, multiple seasonalities (yearly, weekly, daily), and holiday effects using Stan-based Bayesian inference. It's optimized for business metrics and real-world data that may contain missing values, trend shifts, and outliers, requiring minimal domain expertise to produce production-grade forecasts. Dual-language monorepo: Python core (fbprophet package, ~255KB) with cmdstanpy/pystan backends; R bindings (R/ directory) wrap the Python internals via Rcpp and include pre-compiled Stan models (R/inst/stan/prophet.stan). Models are serialized via pickle; forecast logic lives in fbprophet/, diagnostics in fbprophet/diagnostics.py, and R wrappers in R/R/*.R.

Data scientists and analysts at enterprises who need to forecast business metrics (revenue, traffic, inventory) without extensive statistical tuning; the dual Python/R implementation serves both research and production-focused practitioners who want robust defaults and built-in uncertainty quantification.

Production-ready and actively maintained. The project has high GitHub visibility (referenced in Meta's research), dual package distribution (PyPI + CRAN), comprehensive CI/CD via GitHub Actions (.github/workflows/build-and-test.yml and wheel.yml), and a 2023 roadmap blog post confirming ongoing investment. The Stan backend and holiday datasets are regularly updated.

Low-to-moderate risk: The project is well-established with institutional backing, but depends on RStan/CmdStanR for Bayesian inference, which can be finicky to compile across platforms (note the configure and configure.win scripts in R/). The dual-language codebase (Python primary + R binding) means changes must maintain parity. Check the 2023 blog post for any deprecations, but no signs of abandonment.

Active maintenance focused on backend flexibility—the 2023 roadmap signals a shift toward CmdStanR as the preferred R backend and modernization of the Python CLI. Holiday calendars are being refreshed (R/data-raw/generated_holidays.csv). GitHub Actions workflows suggest ongoing builds for multiple Python versions. No major architectural overhauls visible, but incremental stability improvements.

Clone and install: git clone https://github.com/facebook/prophet.git && cd prophet/python && pip install -e . or cd prophet/R && R CMD INSTALL . for R. Requires Stan toolchain (C++ compiler + system dependencies). For quick testing without compilation: pip install prophet from PyPI or CRAN, then import and call Prophet().fit().predict().

Daily commands: Python: from fbprophet import Prophet; m = Prophet(); m.fit(df); forecast = m.predict(future). R: library(prophet); m <- prophet(df); forecast(m, future). For development: cd python && python setup.py develop or make test from root (invokes pytest and R check). CI validates via GitHub Actions on push.

• R/R/prophet.R — Core Prophet class initialization and main model interface—all forecasting workflows start here
• R/inst/stan/prophet.stan — Stan probabilistic program that defines the entire generative model; changes here affect all inference
• R/R/plot.R — Visualization and diagnostics layer that renders forecasts and components; heavily used in validation
• R/R/diagnostics.R — Cross-validation and performance metric computation; critical for model evaluation
• R/R/make_holidays.R — Holiday feature engineering and country-specific holiday definitions; core to seasonality modeling
• R/R/utilities.R — Shared utility functions for feature construction and data transformations used across all modules
• R/R/stan_backends.R — Interface to Stan samplers (RStan, CmdStanR); abstracts inference engine selection and execution

• Prophet class (prophet.R) (R S3 class, ggplot2 integration) — Orchestrates entire workflow: initialization, feature setup, Stan interface, prediction
  • Failure mode: Invalid input validation (dates, column names) causes cryptic Stan errors; malformed seasonality config crashes fit()
• Stan model (prophet.stan) — Defines generative

Add a New Built-in Seasonality

1. Modify R/R/prophet.R add_seasonality() method to accept your seasonality config (period, fourier_order, prior_scale) (R/R/prophet.R)
2. Update R/R/utilities.R make_seasonality_features() to generate Fourier features for the new period (R/R/utilities.R)
3. Add prior definition in R/inst/stan/prophet.stan for the seasonality component coefficients (R/inst/stan/prophet.stan)
4. Test in R/tests/testthat/ with cross_validation() to verify hindcast skill (R/tests/testthat)

Add a New Holiday Dataset

1. Generate country holiday CSV and add to R/data-raw/generated_holidays.csv (R/data-raw/generated_holidays.csv)
2. Update R/data-raw/generated_holidays.R to parse and document the new country (R/data-raw/generated_holidays.R)
3. Rebuild sysdata.rda by running the generation script (see R/DESCRIPTION dependencies) (R/R/sysdata.rda)
4. Expose via add_country_holidays() in R/R/make_holidays.R (R/R/make_holidays.R)

Add a Custom Metric for Cross-Validation

1. Define new metric function in R/R/diagnostics.R alongside mae(), mape(), rmse() (R/R/diagnostics.R)
2. Register metric in performance_metrics() function so cross_validation() computes it automatically (R/R/diagnostics.R)
3. Add test case in R/tests/testthat/ verifying metric computation on mock forecast data (R/tests/testthat)

Add a New Plot or Diagnostic Visualization

1. Implement plot function in R/R/plot.R, following naming pattern plot_*.prophet() (R/R/plot.R)
2. Use ggplot2 and helper functions (seasonality_plot_df(), df_for_plotting()) to prepare data (R/R/plot.R)
3. Add documentation in R/man/ with roxygen2 tags (@param, @export, @examples) (R/man)
4. Integrate into plot.prophet() or prophet_plot_components() for discovery (R/R/plot.R)

• Stan (probabilistic programming language) — Enables flexible, interpretable Bayesian time-series modeling with proper uncertainty quantification via MCMC
• Fourier series (sine/cosine basis) — Compactly captures multiple seasonality patterns (daily, weekly, yearly) without explicit periodicity assumptions
• Piecewise linear/logistic trend with changepoints — Allows growth structure to adapt at key inflection points while remaining interpretable
• ggplot2 (R graphics) — Provides publication-quality time-series visualizations and component decomposition plots
• RStan / CmdStanR backends — Abstracts Stan sampling engine; allows user to choose inference backend (faster CmdStanR or stable RStan)

• MCMC sampling instead of variational inference

  • Why: Variational inference would be faster (~seconds), but MCMC provides more reliable uncertainty estimates critical for forecasting
  • Consequence: Longer fit times (minutes to hours for large datasets); user must tune chains/iterations for convergence

• Fixed Fourier order for seasonality

  • Why: Simpler, more interpretable, and avoids overfitting compared to automatic order selection
  • Consequence: User must manually set fourier_order; misspecification reduces forecast accuracy

• Manual changepoint specification or automatic detection

  • Why: Automatic detection avoids data leakage but requires post-hoc inspection; manual allows domain expertise
  • Consequence: Requires iterative tuning; automatic detection may miss subtle regime changes

• R + Stan hybrid (no pure Python binding in R package)

  • Why: Leverages R's strengths in statistics and plotting; Stan handles inference portably
  • Consequence: Requires Stan + Rcpp toolchain; separate Python package exists (pystan + cmdstanpy); two codebases to maintain

• Real-time or online forecasting (requires model refit; not streaming)
• Automatic hyperparameter tuning (user must tune seasonality, changepoints, priors via cross-validation)
• Multi-step ahead hierarchical/grouped forecasting (single series only; no top-down reconciliation built-in)
• Handling missing data in regressors (expects complete feature matrix)
• GPU acceleration for inference (Stan uses CPU-based HMC only)

Stan compilation can fail silently on fresh installs if C++ toolchain is missing (Windows users must install Rtools; macOS needs Xcode CLT). The R package uses reticulate to call Python fbprophet, so Python must be on PATH and virtual environment gotchas are common. Serialized models (pickle) are version-sensitive; upgrading Prophet may break old forecasts. cmdstanpy requires internet access on first run to download Stan binaries. Fit time scales nonlinearly with data size and changepoint_prior_scale; no warning if MCMC divergences occur (check the diagnostics manually).

• Additive decomposition — Prophet's core assumption is that y(t) = trend(t) + seasonality(t) + holidays(t) + noise(t); understanding this separation is critical to knowing when Prophet will succeed or fail on your data
• Bayesian inference with MCMC — Prophet fits its model using Stan's Hamiltonian Monte Carlo sampler; the posterior samples give you credible intervals on forecasts, not just point estimates, which is crucial for risk quantification in production systems
• Fourier series for periodic components — Seasonality in Prophet is modeled using Fourier series (sine/cosine basis functions); the order of the series (yearly_seasonality_fourier_order, etc.) controls flexibility vs. overfitting
• Piecewise linear trend with changepoints — Prophet's trend is not smooth; it allows sudden shifts (changepoints) which are inferred from data or specified manually; this allows the model to adapt when business conditions change
• Regularization via prior distributions — Prophet uses Stan priors (changepoint_prior_scale, seasonality_prior_scale) to control model complexity; tuning these hyperparameters is the main way to prevent overfitting without explicit cross-validation
• Cross-validation on time series (blocked) — Prophet's cross_validation() function uses blocked (expanding window) splits rather than random shuffling, because time series are autocorrelated; misunderstanding this leads to overly optimistic error estimates
• Holiday bump modeling — Prophet allows each holiday (or holiday window) to have its own multiplicative or additive effect on the forecast; this requires specifying holidays.R and holidays.ds columns to capture special calendar events

• statsmodels/statsmodels — Python statsmodels.tsa provides ARIMA, ExponentialSmoothing, and other classical forecasting methods; Prophet users often compare/benchmark against these baselines
• uber/orbit — Uber's Orbit is a modern Bayesian forecasting library with similar goals (seasonality, trend, regressors) but simpler API; key alternative in the same ecosystem
• stan-dev/stan — Prophet depends entirely on Stan for inference; understanding Stan probabilistic programs is essential for debugging or extending the model
• cmdstanpy/cmdstanpy — Modern Python-Stan interface; Prophet is shifting away from pystan toward cmdstanpy as the default backend, so this repo tracks cutting-edge changes
• sktime/sktime — sktime provides a unified scikit-learn-compatible interface for time series; Prophet can be wrapped as a sktime forecaster for pipelining with other sklearn tools

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for R/R/stan_backends.R

The stan_backends.R file handles critical logic for switching between RStan and CmdStanR backends, but there are no dedicated test files visible in the repo structure. This is a core integration point that affects all R users. Adding tests would ensure backend switching, argument passing, and model compilation work correctly across both backends.

• [ ] Create R/tests/testthat/test-stan_backends.R with tests for get_stan_backend() function
• [ ] Add tests for .stan_args() logic with different backend configurations
• [ ] Add integration tests for .fit() with both RStan and CmdStanR backends
• [ ] Verify tests run in CI via .github/workflows/build-and-test.yml

Add missing documentation for R seasonality helper functions in R/R/utilities.R

The file structure shows R/man/ contains many .Rd files, but parse_seasonality_args.Rd exists while other utility functions in utilities.R likely lack corresponding documentation files. This creates gaps for R users trying to understand seasonality parameter handling.

• [ ] Review R/R/utilities.R to identify exported functions without .Rd files
• [ ] Create missing .Rd files in R/man/ (e.g., for initialize_scales_fn.Rd if it wraps an undocumented utility)
• [ ] Add @export and @rdname roxygen2 tags to corresponding functions in R/R/utilities.R
• [ ] Run devtools::document() to regenerate NAMESPACE and verify documentation renders

Add GitHub Actions workflow for R package compatibility matrix testing

The .github/workflows/ shows build-and-test.yml and wheel.yml, but there's no dedicated R testing workflow. R users span multiple R versions (3.6+, 4.0+, 4.1+) and OS combinations. A matrix workflow would catch R-version-specific regressions early.

• [ ] Create .github/workflows/r-cmd-check.yml with matrix for R versions [3.6, 4.0, 4.1, latest]
• [ ] Configure matrix for OS: [ubuntu-latest, macos-latest, windows-latest]
• [ ] Use r-lib/actions/setup-r and rcmdcheck to validate R/DESCRIPTION and run R CMD check
• [ ] Ensure workflow runs on push to main and pull requests affecting R/ directory

• Add diagnostic plot tests: fbprophet/diagnostics.py lacks unit tests for plot_cross_validation_metric() and plot_components()—write pytest fixtures that validate plot outputs match expected structure (matplotlib Figure assertions).
• Document seasonality edge cases: R/R/seasonality.R and fbprophet/seasonality.py have no docstring examples for sub-daily seasonality or handling multiple seasonalities of the same period—add concrete examples showing what happens when you add_seasonality() twice for 'daily'.
• Extend holiday calendar coverage: R/data-raw/generated_holidays.csv is missing regional holidays for several countries (e.g., UK regional bank holidays, Chinese regional observances); write a script to auto-fetch from a canonical source and update the generated CSV, then file a PR with updated tests in R/tests/testthat/test-holidays.R.

The Prophet codebase exhibits moderate security concerns, primarily centered on infrastructure and dependency management rather than application logic. The most critical issues are: (1) use of an outdated, unmaintained Python base image with numerous known CVEs, (2) unverified dependency installation without version pinning, and (3) overly permissive Docker configuration. The application itself (time series forecasting library) has low injection risk due to its mathematical/statistical nature, but the deployment pipeline poses significant supply chain and runtime security risks. Immediate action should focus on modernizing the Docker environment and implementing strict dependency management practices.

• High · Outdated Python Base Image with Known Vulnerabilities — Dockerfile (line 1). The Dockerfile uses Python 3.7-stretch, which is based on Debian Stretch (released 2017). This image contains numerous known CVEs and is no longer receiving security updates. Python 3.7 itself reached end-of-life on June 27, 2023. Fix: Upgrade to a modern, actively maintained Python version (3.11+) with a current base image such as python:3.11-slim or python:3.12-slim. Use minimal images to reduce attack surface.
• High · Insecure pip Installation Without Hash Verification — Dockerfile (lines 5, 10). The Dockerfile installs packages using 'pip install -e' without hash verification or locked dependency versions. This creates vulnerability to dependency confusion attacks, typosquatting, and compromised package repositories. Fix: Use a requirements.txt with pinned versions and hash verification. Implement: 'pip install -r requirements.txt --require-hashes' or use a lock file generated by poetry/pipenv.
• Medium · Missing Security Headers and Isolation in Docker Compose — docker-compose.yml (volumes section). The docker-compose.yml mounts the entire repository as a volume with default permissions, potentially exposing sensitive files, configuration, and source code. No security restrictions are defined. Fix: Use read-only mounts where possible: 'volumes: - .:/usr/src/app:ro'. Run containers as non-root user with restricted capabilities. Implement proper secret management for sensitive data.
• Medium · Unrestricted apt-get Installation — Dockerfile (line 3). The Dockerfile runs 'apt-get -y install' without pinning package versions. This can lead to unexpected updates with breaking changes or security patches that weren't tested with the application. Fix: Pin specific package versions and add version constraints. Example: 'libc-dev=2:2.24-11+deb9' or use a lock file. Also add '--no-install-recommends' to reduce image size.
• Low · Missing HEALTHCHECK Configuration — Dockerfile. No HEALTHCHECK instruction is defined in the Dockerfile, making it difficult to detect unhealthy containers in production environments. Fix: Add a HEALTHCHECK instruction to monitor container health status and enable orchestration systems to restart unhealthy instances.
• Low · No Non-Root User Defined — Dockerfile. The Dockerfile does not specify a non-root user, meaning the application runs as root by default. This increases the impact of potential container escapes or code execution vulnerabilities. Fix: Create and switch to a non-root user before running the application. Example: 'RUN useradd -m appuser' and 'USER appuser'.
• Low · Missing BuildKit Security Features — Dockerfile. The Dockerfile does not leverage Docker BuildKit optimizations and security features that could reduce vulnerability exposure. Fix: Enable BuildKit with 'DOCKER_BUILDKIT=1' environment variable. Consider using multi-stage builds to minimize final image size and exposure.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/facebook/prophet shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live facebook/prophet repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/facebook/prophet.

What it runs against: a local clone of facebook/prophet — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in facebook/prophet | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of facebook/prophet. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/facebook/prophet.git
#   cd prophet
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of facebook/prophet and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "facebook/prophet(\\.git)?\\b" \\
  && ok "origin remote is facebook/prophet" \\
  || miss "origin remote is not facebook/prophet (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "R/R/prophet.R" \\
  && ok "R/R/prophet.R" \\
  || miss "missing critical file: R/R/prophet.R"
test -f "R/inst/stan/prophet.stan" \\
  && ok "R/inst/stan/prophet.stan" \\
  || miss "missing critical file: R/inst/stan/prophet.stan"
test -f "R/R/plot.R" \\
  && ok "R/R/plot.R" \\
  || miss "missing critical file: R/R/plot.R"
test -f "R/R/diagnostics.R" \\
  && ok "R/R/diagnostics.R" \\
  || miss "missing critical file: R/R/diagnostics.R"
test -f "R/R/make_holidays.R" \\
  && ok "R/R/make_holidays.R" \\
  || miss "missing critical file: R/R/make_holidays.R"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/facebook/prophet"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.