ggdemetra: extending ggplot2 to perform seasonal adjustment with RJDemetra

Alain Quartier-la-Tente


ggdemetra is an extension of ggplot2 to add seasonal adjustment statistics to your plots. The seasonal adjustment process is done with RJDemetra that is an R interface to JDemetra+, the seasonal adjustment software officially recommended to the members of the European Statistical System (ESS) and the European System of Central Banks. RJDemetra implements the two leading seasonal adjustment methods TRAMO/SEATS+ and X-12ARIMA/X-13ARIMA-SEATS.

There are 4 main functionalities in ggdemetra depending of what you want to add in the graphic:

Note ts objects cannot be directly used in ggplot2. To convert ts or mts object to data.frame, you can use the ts2df() function. For example, the data ipi_c_eu_df used in this package is obtained by applying the ts2df()function to the ipi_c_eu data available in RJDemetra:

ipi_c_eu_df <- ts2df(ipi_c_eu)

Seasonal adjustment specification

All the functions have some common parameters and especially those to defined the seasonal adjustment method:

In the following examples, the data used is the French industrial production index. By default, the seasonal adjustment will then be processed with X-13ARIMA with a pre-defined specification "RSA5c (automatic log detection, automatic ARIMA and outliers detection and trading day and easter adjustment). However, in the industrial production the working day effect has more economic sense than the trading day effect and a gradual effect for easter does not make economic sense for the aggregated series. The specification that should be used with X-13ARIMA is spec = RJDemetra::x13_spec("RSA3", tradingdays.option = "WorkingDays"). If no new data or seasonal adjustment specification is specified (method or specification), these parameters is inherited from the previous defined: therefore you only need to specify this parameter once.

p_ipi_fr <- ggplot(data = ipi_c_eu_df, mapping = aes(x = date, y = FR)) +
    geom_line() +
    labs(title = "Seasonal adjustment of the French industrial production index",
         x = NULL, y = NULL)

Add the result of the seasonal adjusment

By default geom_sa() adds the seasonal adjusted time series:

spec <- RJDemetra::x13_spec("RSA3", tradingdays.option = "WorkingDays")
p_ipi_fr +
    geom_sa(color = "#155692",
            spec = spec)
#> Frequency used: 12

To add other components of the seasonal adjustment, use the component parameter of geom_sa() (see ?RJDemetra::user_defined_variables() for the availables parameters). For example, to add the forecasts of the input data and of the seasonal adjusted series:

p_sa <- p_ipi_fr +
    geom_sa(component = "y_f", linetype = 2, message = FALSE,
            spec = spec) + 
    geom_sa(component = "sa", color = "#155692") +
    geom_sa(component = "sa_f", color = "#155692", linetype = 2)

Add the outliers to the plot

There are four differents geometrics to add to the plot the names of the outliers used in the pre-adjustment process:

In our example, there are 3 outliers:

p_sa + geom_outlier(geom = "label")

They can be plotted in more readable way using the parameters of ggrepel::geom_label_repel:

p_sa + 
    geom_outlier(geom = "label_repel",
                 ylim = c(NA, 65), 
                 arrow = arrow(length = unit(0.03, "npc"),
                               type = "closed", ends = "last"))

Use the parameters first_date and last_date to only have the outliers in a precise time interval. For example, to only plot the outliers from 2009 use first_date = 2009:

p_sa + 
    geom_outlier(geom = "label_repel",
                 first_date = 2009,
                 ylim = c(NA, 65), 
                 arrow = arrow(length = unit(0.03, "npc"),
                               type = "closed", ends = "last"))