Everything you need to know when starting out with Facebook’s time series forecasting tool (w/ walk-thru Example & Repo)

Winston Robson
Jul 9 · 9 min read

Blocked by “paywall”? Click here or open the “Friend Link” in a new tab — please don’t forget to ‘clap’, share, or follow if you enjoy — Thanks for reading!

Time series forecasting, though not exactly the big sexy when one discusses “Artificial Intelligence,” the “Internet of Things,” or other media buzzwords, finds wide application in data analytics and machine learning.

“Time series forecasting is the use of a model to predict future values based on previously observed values.”

— Wikipeida

Accurate predictions of the future can be extremely valuable. For example, imagine knowing the 1, 5, 10, or 20-year outcome(s) of the following trends:

  • Assessed/market value of financial asset(s)
  • User engagement and/or the time of/on (app/site)
  • Housing demand and/or appreciation
  • Population change and/or infrastructure requirements

Could be worth a few dollars, no?

In this Story, we will break down and examine Prophet, a procedure for forecasting time series data open-sourced by Facebook in February 2017 with v0.4 released in December 2018.


  1. What is Facebook Prophet ?
  2. How does Prophet work?
  3. Practice with Prophet
  • 3.1 Installation & Imports
  • 3.2 Data & Exploration
  • 3.3 Making a forecast
  • 3.4 Breaking Down the Forecast
  • 3.5 Forecast Quality Evaluation

4. Summary / TLDR

What is Facebook Prophet?

While advancements in data science often increase the infamous “skills gap” surrounding the field, Prophet was intentionally designed to lower the cost of entry for “analysts” — who possess an “in-the-loop” understanding of the problems they are trying to solve — via automation of time series forecasting.

Prophet is a procedure for forecasting time series data based on an additive model where non-linear trends are fit with yearly, weekly, and daily seasonality, plus holiday effects.

It works best with time series that have strong seasonal effects and several seasons of historical data. Prophet is robust to missing data and shifts in the trend, and typically handles outliers well.

Introducing Prophet in “Forecasting at Scale,” project leads, Sean J. Taylor and Benjamin Letham, noted “not focusing on the typical considerations of scale: computation and storage.”

We have found the computational and infrastructure problems of forecasting a large number of time series to be relatively straightforward — typically these fitting procedures parallelize quite easily and forecasts are not difficult to store in relational databases.

The actual problems of scale we have observed in practice involve the complexity introduced by the variety of forecasting problems and building trust in a large number of forecasts once they have been produced.

— Facebook (paper)

How does Prophet work?

The procedure makes use of a decomposable time series model with three main model components: trend, seasonality, and holidays.

y(t) = g(t) + s(t) + h(t) + e(t)


  • trend models non-periodic changes; linear or logistic


  • seasonality represents periodic changes; i.e. weekly, monthly, yearly


  • ties in effects of holidays; on potentially irregular schedules ≥ 1 day(s)

The error term e(t) represents any idiosyncratic changes which are not accommodated by the model; later we will make the parametric assumption that e(t) is normally distributed.

Similar to a generalized additive model (GAM), with time as a regressor, Prophet fits several linear and non-linear functions of time as components.

Modeling seasonality as an additive component is the same approach taken by exponential smoothing… The GAM formulation has the advantage that it decomposes easily and accommodates new components as necessary, for instance when a new source of seasonality is identified.

Prophet is “framing the forecasting problem as a curve-fitting exercise” rather than looking explicitly at the time based dependence of each observation.

For more on the equation behind the model — diving in to understand Trend, Seasonality, and Holidays — check out The Math of Prophet.

Practice with Prophet

3.1 Installation & Imports

Installation of Prophet for Python can easily be accomplished;

$ pip install fbprophet

If encountering any issues installing via pip (or if using Anaconda), look here for help; for instillation using R, please refer to the documentation for details.

Next it’s time to import the modules that we will need, and initialize our environment;

3.2 Data & Exploration

Today we aim to utilize historical data from Yahoo Finance in order to forecast Walmart ($WMT) share price. The repo for this story can be found here.

Start by loading in the data;

# load walmart ($wmt) historical stock data
wmt = pd.read_csv('examples/WMT.csv')

Next run some initial EDA;

# what's the sitch
# let's see

From those displays, we can see the data contains records from 11,815 days of trading (starting the 25th of August 1972), and provides continuous relative measurements of share price via Adj Close.

Prophet looks for two fields from input data: time ds and values y; knowing this we can make our time series frame with Date and Adj Close like;

# forge new dataframe w/ date & adj closing price
wmt = wmt[['Date','Adj Close']]

Align the column names to Prophet compliance with;

# column names for prophet compliance
wmt.columns = ['ds','y']

And remember that .info() told us the dates are currently strings by;

# convert dates from string to datetime
wmt.ds = pd.to_datetime(wmt.ds)

Now let’s check out the adjustments;

# display adjustments

Looks good! Before jumping into the forecast, it would be wise to take a quick look at the data plotted out, adjusted closing price across time;

3.3 Making a forecast

In this introduction we will work with standard parameters and minimal adjustment regarding the Prophet model.

A follow-up Story will offer more insights regarding more in-depth features — e.g. changepoint_range, holidays, add_seasonality.

Prophet’s API is very similar to sklearn’s API; first we create a model, then .fit(our data), and, finally, make a forecast. The input to the fit method is a DataFrame with two columns:

  • ds (‘datestamp’) must be of type date or datetime
  • y is a measured (numeric) value to be predicted

Our data has already been sorted for compliance, so let’s get to making that model with;

We can now fit our data to the model;

# fit $wmt data to model

Then build a dataframe on which to fit daily predictions for the next 5 years of prices;

And after all that time and effort (a whole 3 lines!!), we’re finally ready to make some predictions;

# forecast future df w/ model
forecast = prophet.predict(build_forecast)

Done. That’s all there is to building and enacting a Prophet forecasting model! Easy, right?

Run the following prophet.plot and matplotlib integration to visualize the forecast;

Bam! There we go;

In the plot above, the

  • black dots represent actual measurements
  • blue line displays Prophet’s forecast
  • light blue window indicates uncertainty intervals

Prophet’s uncertainty intervals are not expected to hold exact coverage. The intervals are, “however, a useful indication of the level of uncertainty, and especially an indicator of overfitting.”

3.4 Breaking Down the Forecast

The above was great, but what does it mean? Luckily, the team that developed Prophet made it pretty simple to find out.

We can overview a breakdown of the forecast’s elements with;

# tell us more about the forecast

In short, the components indicate it would be wise to buy $WMT some time in the fall on not-Tuesday, and that the rate of change in price has historically continued to increase positively.

Other than a spurt around 1995–2001, Walmart’s share price has been trending on its highest rate of growth for the past number of years (which — depending on one’s perspective — may not be the best indicator to buy now).

To explore the actual price predictions, we can;

And see that the model predicts the price of one share to Walmart to be,

  • $91.45 at close on the 20th of July 2019 (+4.50, -$5)
  • $95.82 at close on the 8th of April 2020 (+- $5)
  • $115.75 at close on the 10th of December 2023 (+$17, -$14)

3.5 Forecast Quality Evaluation

Once again, the above was great! BUT, how accurate is this forecast? Well, as it turns out, you’re not the first to ask.

Prophet has a built in method for assessment of forecast accuracy. Determination of model precision is achieved with cross_validation on historical data, forecasting a given horizon (e.g. 365 days) every period (e.g. 180 days) after initial data (e.g. 730 days) has been considered.

Calculations begin on shorter forecast periods and build up to a final forecast with the full horizon window length.

Here we allow 30 years of data to build before cross validating a 365-day forecast every 180 days;

Next, extract measures of performance with;

wmt_pm = performance_metrics(wmt_cv)

And display the final inaccuracies;


It is covered in the Prophet Paper that Facebook’s team prefers mean absolute percentage error (MAPE) when determining the accuracy of a forecast.

Fresh out the box, Prophet was able to achieve a 16.95% MAPE on a 365-day forecast of the $WMT data.

Taking a closer look, we can visualize MAPE over varying horizon lengths by;

# visualize mape across horizon 
fig = plot_cross_validation_metric(wmt_cv, metric=’mape’)

The model’s error could likely be improved by adjusting parameters including growth and holidays — intricacies we will examine in another Story.

4. Summary / TLDR

In this Story, we covered:

  • how Prophet calculates these forecasts — trend, seasonality, holidays
  • installing Prophet with pip — pip install fbprophet
  • molding data to .fit() the model — ds, y
  • calling a model, fitting data, and making a simple forecast
  • understanding weekly, yearly, & overall trend.plot_components()
  • examining accuracy with cross_validation & performance_metrics

Too Long, Didn’t Read

In short, Prophet is a tool anyone with a basic understanding of

  • Python (or R)
  • the business question(s) at hand

can utilize with time series data to quickly generate forecasts.

Prophet was able to score a 16.95% mean absolute percentage error on the historical $WMT data with virtually no adjustments.

More Info

If you’re looking for an even more in-depth understanding of Prophet, make sure to read The Math of Propheta story which breaks down the equation behind prophet and explores trend options linear vs logistic from a mathematical standpoint.

Furthermore, here’s co-author of the Prophet Paper, Sean J. Taylor, speaking on why Facebook developed Prophet at the 2018 New York R Conference:

And be on the lookout for a follow up story — picking apart Prophet’s parameters — in the next few weeks.

Thank you for stopping by, don’t hesitate to leave your questions or comments below. If you enjoyed, “claps” are always appreciated. Thanks.

You can find this story’s Jupyter Notebook in the GitHub repository here.

Continued Reading


  1. Taylor SJ, Letham B. 2017. Forecasting at scale. PeerJ Preprints 5:e3190v2 https://doi.org/10.7287/peerj.preprints.3190v2
  2. Robson, Winston A. “The Math of Prophet — Future Vision.” Medium, Future Vision, 17 June 2019, https://medium.com/future-vision/the-math-of-prophet-46864fa9c55a

Future Vision

A publication centered around high quality storytelling

Winston Robson

Written by

Terrible in onset. Swift in execution. winstonrobson.com

Future Vision

A publication centered around high quality storytelling

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade