Time Series Part 3: Forecasting with Facebook Prophet: An Intro

This tutorial introduces Facebook Prophet forecasting algorithm.

In this third tutorial about time series we explore the Facebook Prophet forecasting algorithm. Similarly to the previous tutorial about SARIMAX models we do so in a way that you can start applying it and go further exploring it with different use cases.

The code of this tutoriall can be found at 03-Forecasting_with_Facebook_Prophet.ipynb on GitHub.

After completing this tutorial, you will know: 
  1. How to apply Facebook Prophet for forecasting
  2. How to search for the best model using hyperparameter fine tunning
  3. How to evaluate the obtained model
  4. How to save the chosen model for future use

If you didn’t check yet the other tutorials about time series, they are available at:

Introduction to Facebook Prophet

In this section we introduce Facebook Prophet. Here you get the basics for building your first model with Facebook’s advanced forecasting tool and go further exploring it.

To illustrate how Prophet works we apply it to forecast sales using the same dataset used in the tutorial where we introduced SARIMAX models.

Facebook Prophet

Facebook Prophet  is open-source library released by Facebook’s Core Data Science team. It is available in R and Python.

Prophet is a procedure for univariate (one variable) time series forecasting data based on an additive model, and the implementation supports trends, seasonality, and holidays. 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.

It is specially interesting for new users because of its easy use and capacity of find automatically a good set of hyperparameters for  the model. Therefore, it allows users without prior knowledge or experience of forecasting time series data start using it and get reasonably good results that are often equal or sometimes even better than the ones produced by the experts.

Forecasting with Facebook Prophet


Prepare Data for Prophet

Prophet requires as input a dataframe with two columns:

  • ds: datetime column.
  • y: numeric column which represents the measurement we wish to forecast.

Our data is almost ready. We just need to rename columns date and sales, respectively, as ds and y.

Renaming columns for Prophet.

Train Model

To train a model in Prophet, first we create an instance of the model class and then we call the fit method.

In principle, you don’t need to specify any hyparameters. One important exception is seasonality_mode. It is important to set this parameter to multiplicative if your model is multiplicative since Prophet is based on an additive model. As we saw previously, the seasonality in our model follows an additive behavior. Therefore, there is no need to set seasonality_mode as multiplicative.

Although Prophet is able to find automatically a good set of hyperparameters, we will see later that some fine tuning can improve performance. Specially, applying your knowledge of the business case might make a huge difference even if Prophet has the power of handling many things by itself.

Just to exemplify, I’ll include the parameter interval_width that sets the confidence interval.

To know more about how to tweak those parameters in your favor check Prophet documentation.


In order to forecast we first need to create a dataframe that will save our predictions. Method make_future_dataframe builds a dataframe that extends into the future a specified number of days. In our case, we will predict 90 days into the future.

By default the dataframe created includes the dates from the history, so we see the model fit as well.

Dataframe created to save predictions. Includes dates of historical data and 90 days ahead.

To make predictions we apply method predict on the future dataframe that we have just generated.

Forecast Dataframe

The forecast dataframe contains Prophet’s prediction for sales. Because we’ve also passed historical dates, it provides an in-sample fit that we can use to evaluate our model.

As you can see, forecast includes a column yhat with the forecast, as well as columns for components and uncertainty intervals

Forecast Plot

To plot the forecast you just need to call method .plot() on your forecast dataframe.

In the forecast plot above, deep blue line is forecast sales forecast[‘y_hat’], black dots are actual sales forecast[‘y’]. The light blue shade is 95% confidence interval around the forecast. The uncertainty interval in this region is bounded by forecast[‘yhat_lower’] and forecast[‘yhat_upper’] values.

Trend Changepoints

Real life time series such as this one, frequently have abrupt changes in their trajectories. These changepoints sign abrupt changes in the time series caused, for instances, by new product launch, unforeseen calamity. Prophet will automatically detect these changepoints and will allow the trend to adapt appropriately. At these points, the growth rate is allowed to change making the model more flexible. This may cause overfitting or underfitting.

A parameter called changepoint_prior_scale could be used to adjust the trend flexibility and tackle overfitting and underfitting. Higher value fits a more flexible curve to the time series.

By default changepoints are only inferred for the first 80% of the time series, but you can change it by making use of the changepoint_range argument of the model.

It is also possible to add your own changepoints manually, using the changepoints argument.

If you want to know more about changepoints and Prophet check this out.

In the plot below, the dotted lines represent the changepoints for the given time series.

Component Plots

We can observe the following on the forecast components plotted above:

Trend component: Trend upwards. 

Weekly seasonality component: The weekly seasonality shows that people buy more on weekends. In particular, we observe a drop on sales from Sunday to Monday. This might point to a holiday effect.

Yearly seasonality component: As observed previously the volume of sales is higher in July and lower in January. This peak in sales in July might mean seasonal sales with high discount prices.

Holidays, special events, as well as seasonality can be explored to improve your model. For more information on how to use this information check Prophet’s documentation section Seasonality, Holiday Effects, And Regressors.

Evaluate model

How this model is performing?

The forecast dataframe includes predictions made on the training data dates. Therefore, we can use this in-sample fit to evaluate our model.

To evaluate this model we will be using MAE and MAPE, as done previously for the SARIMAX models. These are popular metrics which you will come often across when evaluating forecasting models.

Like this, we can compare and find out which model is the best model.

For this model MAE = 4.275 and MAPE=0.169 which are better than the values obtained by our best SARIMAX model.

In addition, to calculating metrics let’s plot both actual and predicted data.

From the plot, it seems that the model is able to fit the data points well.

Prophet’s Diagnostic Tools

As part of the evaluation process we can make good use of some diagnostic tools provided by Prophet, such as Cross Validation and Hyperparameter tuning.

Cross Validation

Prophet includes functionality for time series cross validation to measure forecast error by comparing the predicted values with the actual values.

To apply the cross_validation function, we specify the forecast horizon (horizon), then optionally the size of the initial training period (initial) and the spacing between cutoff dates (period). You can also just set the horizon and let prophet choose the other parameters.

Left: Different metrics for different horizons (head and tail of performance_metrics dataframe). Right: Plot cross validation MAE (top) and MAPE (bottom).

The blue line shows the MAE (1st plot above) and MAPE (2nd plot above), where the mean is taken over a rolling window of the dots.

We see for this forecast that, considering MAPE, errors around 18.50% are typical for predictions 9 days into the future, and that errors decrease to around 17.20% for predictions that are 90 days out.

Fine tuning hyperparameters

Is it possible to make it better??

We can apply grid search and try to fine tune the hyperparameters. Let’s apply it and try to find hyperparameters that may give us lower MAPE.

Here we try different values of changepoint_prior_scale and seasonality_prior_scale. changepoint_prior_scale determines the flexibility of the trend, and in particular how much the trend changes at the trend changepoints. While seasonality_prior_scale controls the flexibility of the seasonality. For more details, check section Hyperparameter tuning of Prophet’s documentation.

The following image shows the smallest values for both MAE and MAPE:

MAE and MAPE for different values of changepoint_prior_scale and seasonality_prior_scale hyperparameters.

Then we apply the best model based on MAPE.

Best Model obtained by Fine-tuning Hyperparameters

Screenshot best model using best parameters pointed by fine-tuning hyperparameters.

Let’s compare the values of the metrics of the two models where Prophet_01 is our first model and Prophet_02 is the model with smallest MAPE provided by the fine-tuning process.

Comparison of Prophet models.

The model pointed out by fine-tuning (Prophet_02) gave us a slight improvement when compared with previous model (Prophet_01).

Best Model adding US Holidays

What if we include US-Holidays? Would it improve further the results obtained by our last model?
Let’s use for this add_country_holidays(country_name=’US’) provided by Prophet.

These are the US holidays included:

US holidays added to Prophet model by using add_country_holidays.

Note that now the plots of components include holidays.

Components plots of Prophet model that includes US holidays.

By adding holidays we’ve obtained a slightly better model (Prophet_03) when compared with previous models; considering both MAE and MAPE metrics.

Even if, in this case, the improvement was not significative, it shows that by changing hyperparameters based on our business case can play in our favor.

Comparison of Prophet models.

Saving and Loading the Best model

Now that you found your best model, it is time to save it for future use.

Saving Prophet models is a bit different than saving SARIMAX models. In Python, Prophet models should not be saved with pickle; the Stan backend attached to the model object will not pickle well, and will produce issues under certain versions of Python. Instead, you should use the built-in serialization functions to serialize the model to json.

Save Prophet model

Load Prophet model

Comparing all results – SARIMA models vs Prophet models

Below, we compare the performance of SARIMAX models (Time Series Tutorial Part 2) and Prophet models.

MAE and MAPE metrics of (S)ARIMA and Prophet models

The Prophet models present better accuracy than the (S)ARIMA models, as show by the lowest values of MAE and MAPE. The best Prophet model has a MAE 32.38% lower than the MAE of the best SARIMA model. The MAPE of the best Prophet is 21.13% which is lower than the MAPE of the best SARIMA model.

Conclusions about Facebook Prophet


In this third time series tutorial we presented Facebook Prophet. With our example we could observe that in fact Prophet is easy to use. In our first model we didn’t make any choice and by letting Prophet choose automatically the hyperparameters we have already obtained a model with better performance than the best SARIMA model from last tutorial.

By tweaking a bit the hyperparameters we have improved our results. Adding holidays showed to be useful even if the improvement, in this case, was small.

We have also explored some of the evaluation tools provided by Prophet: Cross validation and Hyperparameter tuning.

If you want to go deeper and learn even more about Prophet visit its official documentation page.

Thank you for reading!

Comments and questions are always welcome, feel free to get in touch via d.paes.barretto@tue.nl.

For tall code presented here as well as in the previous time series tutorial parts visit our GitHub repository.

Picture of Danielle Paes Barretto

Danielle Paes Barretto

Danielle has done the Master Data Science and Entrepreneurship at JADS. Her passion is to dive in and give meaning to it. She does that by giving tutorials and masterclasses to students at JADS. Clickhere to send her an e-mail.
Scroll naar boven
Scroll naar top

Bedankt voor je aanmelding!

Super leuk dat je bij ons lustrum aanwezig bent!
De inloop is vanaf 15:00 en om 15:30 zullen we beginnen met het programma.


9 juni 15:30

Wij hebben er zin in en kijken er naar uit jullie weer te zien!