README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  fig.align = "center",
  out.width = "100%"
)
remotes::install_local()
```

## Seasonal adjustment and trending

A time series is a collection of well-defined data observed regularly through
time. Seasonal adjustment is an analytical method to estimate and remove
seasonal and calendar-related impacts from a time series. Trending is an
analytical method to estimate the long-term, underlying direction of a time
series.

The `sjx` package enables the comparison of the seasonal
adjustment and trending methods produced by the following three programs:

* [SEASABS](https://www.abs.gov.au/websitedbs/d3310114.nsf/4a256353001af3ed4b2562bb00121564/c890aa8e65957397ca256ce10018c9d8!OpenDocument) (used by Australia's national statistical agency)

* [JDemetra+](https://jdemetradocumentation.github.io/JDemetra-documentation/)
(used by many European statistical agencies and central banks)

* [X-13ARIMA-SEATS](https://www.census.gov/data/software/x13as.html) (used by
the United States Census Bureau)

Published seasonally adjusted and trend estimates of time series data from the
Australian Bureau of Statistics (generated via SEASABS) are compared against the
output generated by executing the JDemetra+ and X-13ARIMA-SEATS programs. Since
SEASABS is not freely available, the estimates are referenced directly via their
publications on the web. The other two programs are readily accessible however,
and are run via their R interfaces:

* The R package [`RJDemetra`](https://github.com/jdemetra/rjdemetra) is used to
run JDemetra+ (version 2)

* The R package [`seasonal`](http://www.seasonal.website/seasonal.html) is used
to run X-13ARIMA-SEATS

Importantly, the default values of both packages have been used when running the
seasonal adjustment and trending algorithms.

## ABS time series data

The [Australian Bureau of Statistics](https://www.abs.gov.au/) (ABS) produces
seasonally adjusted and trend estimates for various publications containing
original time series. The relevant data are contained in various tables as Excel
spreadsheets under the 'Data downloads' section of the desired publication.

An example is *Table 1. Inventories, chain volume measures* in the June quarter
2023 publication of 'Business Indicators, Australia' available at:

[https://www.abs.gov.au/statistics/economy/business-indicators/business-indicators-australia/jun-2023/5676001.xlsx](https://www.abs.gov.au/statistics/economy/business-indicators/business-indicators-australia/jun-2023/5676001.xlsx)

Each spreadsheet file contains the following sheets/tabs (any others are
ignored):

* **Index:** contains metadata about the time
series, such as the series type, units and frequency

* **Data1:** contains the original, seasonally adjusted and trend
estimates

Note that:

* the ABS does not necessarily publish seasonally adjusted and trend estimates
for all original time series;

* the ABS sometimes only publishes the seasonally adjusted and/or trend
estimates without the corresponding original series; and

* this package only works for ABS data containing monthly or quarterly
time series.

## Installation

You can install the development version of `sjx` from [GitHub](https://github.com/) with:

```{r install, eval=FALSE}
# install.packages("devtools")
devtools::install_github("a-s-russo/time-series-comparison@fusen")
```

Note that `RJDemetra` requires the [`rJava`](https://cran.r-project.org/web/packages/rJava/index.html)
package and Java SE version 8 or higher. For troubleshooting, consult the
[installation manual](https://github.com/jdemetra/rjdemetra/wiki/Installation-manual).

## Example

Compare the seasonally adjusted series for all employed persons in Australia
between SEASABS, JDemetra+, and X-13ARIMA-SEATS:

```{r example, message=FALSE, out.height="100%", out.width="100%"}
# Load the package
library(sjx)

# Construct a URL to download ABS labour force data
ABS <- "https://www.abs.gov.au/statistics/labour/" # ABS website (for labour statistics)
pub <- "employment-and-unemployment/labour-force-australia/" # Publication
ref <- "jul-2023/" # Reference period
cat <- "620200" # Catalogue number
tab <- "1" # Table number
ext <- ".xlsx" # File extension
URL <- paste0(ABS, pub, ref, cat, tab, ext)

# Download the series data and metadata
emp <- download_ts(URL)

# Plot the seasonally adjusted series
create_tsplot_comp(emp, "Employed total ;  Persons ;")$seas
```