Prophet Time Series Decomposition: Separate Trend, Seasonality, and Holidays

The Prophet model decomposes time series into trend, seasonality, and holidays. It suits business data with strong seasonal patterns. Upload a CSV with dates and a numeric target, and get a decomposition report (changepoint candidates, weekly and yearly seasonal effects, forecasts with uncertainty intervals, and AI-generated insights).

Worked Example (Simulated): A Trend and a Day Pattern

Question: Does a made-up daily count rise over time, and does it vary by day?

Inputs: Simulated data, seed 41. The script makes 180 daily values. Each value has a rising line, a set day effect, and random noise. The slope (0.12 per day) and the day effects (-8 to 10) are set in the script, so the fit can be checked against them. Day 0 is the base day.

Method: Fit a line for time and day effects with least squares. The code and its printed output are below.

import numpy as np

SEED = 41
N_DAYS = 180
rng = np.random.default_rng(SEED)
t = np.arange(N_DAYS, dtype=float)
weekday = np.arange(N_DAYS) % 7
# Built in: a slope of 0.12 per day and day effects from -8 to 10.
weekday_effect = np.array([-8.0, -5.0, -2.0, 2.0, 6.0, 10.0, -3.0])
y = 100.0 + 0.12 * t + weekday_effect[weekday] + rng.normal(0.0, 4.0, N_DAYS)

# Additive least-squares model: intercept + linear trend + weekday terms.
X = np.column_stack([np.ones(N_DAYS), t]
                    + [(weekday == d).astype(float) for d in range(1, 7)])
beta, _, _, _ = np.linalg.lstsq(X, y, rcond=None)
fitted = X @ beta
mae = np.mean(np.abs(y - fitted))

print(f"Simulated data, seed {SEED}")
print(f"Observations: {N_DAYS} daily values")
print("Model: intercept + linear trend + weekday effects; least squares")
print(f"Estimated trend: {beta[1]:.3f} units per day")
print(f"Mean absolute in-sample error: {mae:.3f} units")
print("Estimated weekday effects (relative to day 0):")
for d in range(7):
    effect = 0.0 if d == 0 else beta[1 + d]
    print(f"  day {d}: {effect:+.3f} units")

Printed output:

Simulated data, seed 41
Observations: 180 daily values
Model: intercept + linear trend + weekday effects; least squares
Estimated trend: 0.114 units per day
Mean absolute in-sample error: 3.030 units
Estimated weekday effects (relative to day 0):
  day 0: +0.000 units
  day 1: +3.484 units
  day 2: +5.670 units
  day 3: +10.647 units
  day 4: +14.467 units
  day 5: +18.745 units
  day 6: +6.315 units

Result: The fitted trend is 0.114 units per day, close to the 0.12 set in the script. The fitted day effects (3.484, 5.670, 10.647, 14.467, 18.745, 6.315) are within about 1.3 units of the set values (3, 6, 10, 14, 18, 5), and day 5 has the largest effect over day 0. This example is a plain least-squares fit, not Prophet. It shows the idea of splitting a series into a trend and a day pattern.

Limit: These are made-up values. The error (3.030 units) is measured on the same data used to fit the model, so it does not show how well the fit predicts new days. Day labels are index labels, not real names of the week.

Sources

• Taylor S, Letham B (2018). Forecasting at Scale. The American Statistician, doi 10.1080/00031305.2017.1380080. Cited for the description of the Prophet model only, not for any number on this page.

What Is Prophet Decomposition?

Prophet is a forecasting model that splits a time series into interpretable components. It is described in Taylor S, Letham B (2018). Forecasting at Scale. The American Statistician, doi 10.1080/00031305.2017.1380080. Instead of treating your data as a single opaque signal, Prophet pulls it apart into three pieces: the underlying trend (is the number going up or down over time?), recurring seasonal patterns (what repeats every week or every year?), and the effects of holidays or one-off events. Each component is estimated separately and then added back together to explain the observed data and produce forecasts.

To explore a forecast for your own metric, try the time series forecasting tool.

The core idea is an additive model: y(t) = trend(t) + seasonality(t) + holidays(t) + error(t). The trend component uses a piecewise linear function that can change slope at candidate changepoints, dates where the fitted trend bends. Seasonality is modeled using Fourier series, which means the algorithm learns the shape of your weekly and yearly patterns from the data rather than imposing a rigid template. Holiday effects are handled as separate additive terms, allowing specific dates to have their own estimated impact.

What makes Prophet particularly useful for business data is its robustness to missing values, its tolerance for outliers, and its ability to handle the messy realities of operational time series. You do not need evenly spaced observations. You do not need to manually specify where trend changes happen. And you get uncertainty intervals on every forecast, so you know how confident the model is about its predictions.

When to Use Prophet Decomposition

Prophet decomposition is the right tool when you need to understand the structure of a time series, not just predict its next value. Here are the most common scenarios where it excels:

Seasonal business forecasting. If you run an e-commerce store, a restaurant chain, or any business with predictable cycles, Prophet separates your growth trend from your seasonal swings. An online retailer might see a 40% revenue spike every November-December, but the real question is whether the underlying trend is growing at 8% or 15% per year once you strip away the holiday effect. Prophet estimates a trend and, when yearly seasonality is enabled, a yearly pattern from the data. These are model estimates, not exact measures of a true trajectory or cycle. This lets you forecast next quarter's revenue with seasonal adjustments baked in, rather than eyeballing it from a noisy chart.

Holiday impact analysis. Retailers, hospitality businesses, and media companies all experience spikes and dips around holidays, but quantifying the exact impact is surprisingly hard when holidays overlap with weekly patterns and longer-term trends. Prophet isolates the holiday effect as a separate component, so you can see an estimated Black Friday lift in daily revenue, or an estimated dip in daily signups on long weekends. This is actionable intelligence for staffing decisions, ad budget allocation, and inventory planning.

Trend change detection. When did your growth rate actually change? Was it when you launched the new product line in March, or when the competitor entered the market in June? Prophet estimates candidate dates where the trend may change slope. Check those dates against known events; they do not show what caused a change. This is invaluable for post-hoc analysis of strategic decisions. You can see whether a pricing change, a marketing campaign launch, or a product update actually bent the curve, and by how much. The changepoint prior scale parameter controls how sensitive the detection is, so you can tune it from conservative (only major shifts) to aggressive (catches subtle changes).

Prophet also works well for website traffic pattern analysis (separating real user growth from day-of-week effects), energy demand forecasting (weekly patterns overlaid on seasonal weather cycles), and any domain where you have daily or sub-daily data spanning at least a few months.

What Data Do You Need?

You need a CSV with at least two columns: a date column and a numeric target column. The date column should contain dates in a recognizable format (YYYY-MM-DD, MM/DD/YYYY, or similar). The target column holds the value you want to decompose: daily revenue, page views, order count, temperature, or any other numeric measurement over time.

You can optionally include a category column if you want to decompose multiple time series at once (for example, revenue by product line or traffic by channel). The tool will run separate decompositions for each category and let you compare them.

For reliable results, you need at least 30 observations, but more is better. For yearly seasonality to be meaningful, you need at least two years of data: otherwise the algorithm cannot distinguish a yearly pattern from a one-time event. Weekly seasonality requires at least two weeks, which is almost always available. Daily data works best, but weekly data is fine for trend and yearly seasonality analysis.

Prophet fits the dates you supply and does not need missing dates to be filled in. It does not invent values for the gaps, so large gaps mean less information about the pattern there. If your data has extreme outliers (a day where revenue was 10x normal due to a data error), Prophet is reasonably robust, but you will get better results by cleaning obvious errors before uploading.

How to Read the Report

The report is organized into slides, each focusing on a different aspect of the decomposition. Here is what each section tells you and how to use it.

Analysis Overview (Key Metrics and Data Overview)

The first slide gives you the headline numbers: the date range of your data, the number of observations, the overall trend direction, and key metrics like mean absolute error and R-squared for the model fit. The data overview card summarizes your input: how many rows, any missing values detected, and the frequency of your time series. Check this slide to confirm the tool interpreted your data correctly before diving into the components.

Primary Results (Trend and Forecast Plot)

This is the main visualization: your actual data overlaid with the fitted model and a forecast extending into the future. The shaded band around the forecast line represents the uncertainty interval for future values. Its coverage depends on the model and its assumptions, so read it as a rough range, not a promise. Look at where the forecast diverges from any simple mental projection you have. That is where the model's understanding of trend and seasonality differs from a naive extrapolation.

Data Distribution (Seasonality Components)

This slide breaks out the seasonal components, typically weekly and yearly patterns. The weekly seasonality plot shows how your metric varies by day of the week (for example, e-commerce revenue might peak on Mondays and dip on weekends). The yearly seasonality plot shows the month-by-month pattern (holiday spikes in December, summer lulls in August). These are the repeating patterns that Prophet has learned from your data. If a pattern looks noisy or erratic, it might mean there is not enough data to estimate that seasonality reliably.

Detailed Results (Results Table and Summary Table)

The results table shows the decomposed values for each date: the original observation, the trend value, the seasonal contribution, and any holiday effect. This is the data behind the charts, and it is useful for exporting or cross-referencing specific dates. The summary table provides the changepoint locations, the dates where the trend slope shifted, along with the magnitude of each change. These changepoints are dates where the fitted slope changes. They do not say why.

Model Diagnostics (Diagnostic Plot)

The diagnostic slide shows residual plots and fit quality checks. Residuals should look like random noise with no obvious patterns. If you see structure in the residuals (for example, the model consistently underestimates Fridays), it means the seasonality model is not fully capturing a pattern. Systematic residual patterns suggest you might need additional regressors or a different seasonality configuration.

Model Performance (Diagnostics and Performance Metrics)

This slide presents formal performance metrics: mean absolute error (MAE), mean absolute percentage error (MAPE), root mean squared error (RMSE), and R-squared. These tell you how well the decomposition explains the variation in your data. R-squared is one fit metric. Read it with the residual plots and other performance metrics; it does not by itself show whether the model is useful for a forecast. The diagnostics card also flags any assumption violations, for example, if the additive seasonality assumption appears violated (seasonal swings growing with the trend level).

Technical Details (Summary Stats and Methods)

This slide documents the exact parameters used: changepoint prior scale, seasonality mode (additive or multiplicative), which seasonalities were enabled, the number of Fourier terms, and the forecast interval width. The methods card explains the statistical approach in plain language, including the Fourier series order for each seasonality type and the regularization applied to changepoints. This is the section you share with a data scientist or statistician who wants to check the methodology.

Insights and Recommendations

The final slide provides AI-generated interpretation of the results in business language. It highlights the most important findings: the direction and strength of the trend, the dominant seasonal pattern, significant changepoints, and what the forecast suggests about the near future. It also includes actionable recommendations based on the patterns found, such as adjusting staffing for predictable weekly cycles or investigating the cause of a detected trend change.

Illustrative Scenarios

The examples below are hypothetical. They are not customer results and contain no real data.

E-commerce revenue decomposition. A direct-to-consumer brand uploads two years of daily revenue data. Prophet separates the year-over-year growth trend from the weekly pattern (Tuesdays and Wednesdays are the strongest days) and the yearly seasonality (a massive Q4 spike and a January dip). The changepoint analysis reveals that the growth rate accelerated in April after a product launch and decelerated in September when a key paid channel got more expensive. The brand could use the seasonal components to set monthly targets and the changepoint dates to evaluate past strategic decisions.

SaaS daily active users. A B2B software company tracks daily active users over 18 months. Prophet shows a steady upward trend with a clear weekly pattern, usage drops on weekends. The model detects two changepoints: a positive slope change after a major feature release, and a negative one three months later when a competitor launched a free tier. The forecast projects growth flattening over the next quarter under current conditions, giving the product team a clear signal to invest in retention features.

Restaurant foot traffic. A restaurant group with six locations uploads daily cover counts for three years. Using the optional category column, they get separate decompositions per location. One location shows a declining trend that started months earlier, before management noticed the problem from monthly reports. The yearly seasonality reveals that outdoor-seating locations have a much stronger summer peak than indoor-only locations. This drives a decision to invest in patio infrastructure for the underperforming location.

When to Use Something Else

If your time series is short (under 30 observations) or you only need a basic upward/downward trend line without seasonal decomposition, the simple trend analysis tool is faster and simpler. It fits a linear or polynomial trend and gives you a slope and confidence interval without the overhead of seasonal modeling.

If you need a traditional statistical forecasting model with formal significance tests, autoregressive terms, and differencing, ARIMA is the standard choice. ARIMA excels when the autocorrelation structure of the data matters (each value depends heavily on recent values) and when you need precise control over the model order. Prophet is generally easier to use and more robust to messy data, but ARIMA gives you more statistical rigor for well-behaved series.

Exponential smoothing (ETS) is another alternative, particularly good for data with multiplicative seasonality, where the seasonal swings grow proportionally with the level of the series. Prophet has a multiplicative seasonality mode, and ETS also models it natively. If your retail sales double from year to year and the December spike grows proportionally, ETS may give more accurate forecasts out of the box.

For purely exploratory trend analysis without forecasting, the simple trend tool strips away complexity. And if you want to compare Prophet's decomposition against a classical STL decomposition, the methodology section of the report explains the key differences so you can decide which approach is more appropriate for your data.

Key Assumptions and Limitations

Prophet uses an additive seasonality model by default, meaning it assumes the seasonal effect is a fixed number added to the trend, not a percentage of it. If your December spike is always $50,000 above baseline regardless of whether baseline revenue is $100,000 or $500,000, additive is correct. If the spike scales with revenue (always 40% above baseline), you should switch to multiplicative mode or log-transform your target variable before uploading.

The piecewise linear trend assumes that changes happen at discrete changepoints rather than as smooth curves. This works well for most business data (growth rate shifts when you launch a campaign, enter a new market, or lose a key client) but may not capture gradual S-curve dynamics. If your growth follows a logistic saturation pattern, the report notes this in the diagnostics.

Prophet needs at least two full cycles of any seasonal pattern to estimate it reliably. For yearly seasonality, that means two years of data. With only 14 months, the yearly seasonal component may look reasonable but has limited statistical support. The report flags when data is insufficient for a given seasonality type.

The R Code Behind the Analysis

Every report names its method and includes the R code that produced it, so you can reproduce, audit and cite it. The method code is fixed, not rewritten for each run, so the same data gives the same analysis every time.

The analysis uses the prophet R package, which implements the same algorithm as the Python version. The model fitting uses prophet() with configurable parameters for changepoint sensitivity (changepoint.prior.scale), seasonality mode, and Fourier order. Forecasts are generated via make_future_dataframe() and predict(), with uncertainty intervals. Seasonal components are extracted using prophet_plot_components(). Every step is visible in the code tab of your report, so you or a statistician can check what was done.