README.Rmd

# ggseas R package
seasonal adjustment on the fly extension for ggplot2

Convenience functions that let you easily do seasonal adjustment on the fly with ggplot.

Depends on the [`seasonal` package](https://cran.r-project.org/web/packages/seasonal/index.html) to give you access to X13-SEATS-ARIMA.

[![Travis-CI Build Status](https://travis-ci.org/ellisp/ggseas.svg?branch=master)](https://travis-ci.org/ellisp/ggseas)
[![CRAN version](http://www.r-pkg.org/badges/version/ggseas)](http://www.r-pkg.org/pkg/ggseas)
[![CRAN RStudio mirror downloads](http://cranlogs.r-pkg.org/badges/ggseas)](http://www.r-pkg.org/pkg/ggseas)


## Installation
Install the stable version the usual way from CRAN:

```{r, eval = FALSE}
install.packages("ggseas")
```


or the latest version (bugs and all) from GitHub:
```{r, eval = FALSE}
devtools::install_github("ellisp/ggseas/pkg")
```


## Usage - seasonal adjustment on the fly
So far there are three types of seasonal adjustment possible to be incorporated
into a usual ggplot() command, substituting for where you'd normally have geom_line().

### X13-SEATS-ARIMA
```{r}
library(ggseas)
# make demo data with the convenience "time series to data.frame" function tsdf()
ap_df <- tsdf(AirPassengers)

# SEATS with defaults
ggplot(ap_df, aes(x = x, y = y)) +
   geom_line(colour = "grey80") +
   stat_seas() +
   ggtitle("SEATS seasonal adjustment - international airline passengers") +
   ylab("International airline passengers per month")

# X11 with no outlier treatment
ggplot(ap_df, aes(x = x, y = y)) +
   geom_line(colour = "grey80") +
   stat_seas(x13_params = list(x11 = "", outlier = NULL)) +
   ggtitle("X11 seasonal adjustment - international airline passengers") +
   ylab("International airline passengers per month")

ggplot(ldeaths_df, aes(x = YearMon, y = deaths, colour = sex)) +
   geom_point(colour = "grey50") +
   geom_line(colour = "grey50") +
   facet_wrap(~sex) +
   stat_seas(size = 2) +
   ggtitle("Seasonally adjusted lung deaths in the UK 1974 - 1979") +
   ylab("Deaths") +
   xlab("(light grey shows original data;\ncoloured line is seasonally adjusted)") +
   theme(legend.position = "none")
```

### STL (LOESS-based decomposition)
```{r}
# periodic if fixed seasonality; doesn't work well:
ggplot(ap_df, aes(x = x, y = y)) +
   geom_line(colour = "grey80") +
   stat_stl(s.window = "periodic")

# seasonality varies a bit over time, works better:
ggplot(ap_df, aes(x = x, y = y)) +
   geom_line(colour = "grey80") +
   stat_stl(s.window = 7)
```

### Classical decomposition
```{r}
# default additive decomposition (doesn't work well in this case!):
ggplot(ap_df, aes(x = x, y = y)) +
   geom_line(colour = "grey80") +
   stat_decomp()

# multiplicative decomposition, more appropriate:
ggplot(ap_df, aes(x = x, y = y)) +
   geom_line(colour = "grey80") +
   stat_decomp(type = "multiplicative")
```

## Usage - seasonal decomposition on the fly
From version 0.2.0 I introduce a summary graphic decomposition, similar to what
you'd get with plot(stats::decompose(x)), but in the ggplot2 environment.  As well
as allowing ggplot2 look and feel of plots, you can also map a variable to the 
colour (or color) aesthetic, to allow two difference decompositions on the same
graphic.
```{r}
ggsdc(ap_df, aes(x = x, y = y), method = "decompose") +
   geom_line()


ggsdc(ap_df, aes(x = x, y = y), method = "stl", s.window = 7) +
   labs(x = "", y = "Air passenger numbers") +
   geom_point()

ggsdc(ldeaths_df, aes(x = YearMon, y = deaths, colour = sex), method = "seas") +
      geom_line()

library(scales) # for label= comma
serv <- subset(nzbop, Account == "Current account" & 
                  Category %in% c("Services; Exports total", "Services; Imports total"))

ggsdc(serv, aes(x = TimePeriod, y = Value, colour = Category),
      method = "seas", start = c(1971, 2), frequency = 4) +
   geom_line() +
   scale_y_continuous("NZ$ millions\ndecomposition by X13-SEATS-ARIMA", label = comma) +
   labs(x = "") +
   ggtitle("New Zealand services balance of payments -\ngreater seasonality in exports than imports") +
   theme_light()

```

Coming in 0.5.0 - control facet titles during seasonal decomposition on the fly

```{r}
   ggsdc(serv, aes(x = TimePeriod, y = Value, colour = Category),
         method = "stl", s.window = 7, frequency = 4,
         facet.titles = c("The original series", "The underlying trend", "Regular seasonal patterns", "All the randomness left")) +
      geom_line()
```