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",
  fig.dim = c(7, 4) * 1.4,
  out.width = "100%"
)
```

# `rjd3highfreq` <a href="https://rjdverse.github.io/rjd3highfreq/"><img src="man/figures/logo.png" align="right" height="150" style="float:right; height:150px;"/></a>

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/rjd3highfreq)](https://CRAN.R-project.org/package=rjd3highfreq)

[![R-CMD-check](https://github.com/rjdverse/rjd3highfreq/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/rjdverse/rjd3highfreq/actions/workflows/R-CMD-check.yaml)
[![lint](https://github.com/rjdverse/rjd3highfreq/actions/workflows/lint.yaml/badge.svg)](https://github.com/rjdverse/rjd3highfreq/actions/workflows/lint.yaml)

[![GH Pages built](https://github.com/rjdverse/rjd3highfreq/actions/workflows/pkgdown.yaml/badge.svg)](https://github.com/rjdverse/rjd3highfreq/actions/workflows/pkgdown.yaml)
<!-- badges: end -->


rjd3highfreq provides functions for seasonal adjustment of high-frequency data displaying multiple, non integer periodicities. Pre-adjustment with extended airline model and Arima Model Based decomposition.


## Installation

Running rjd3 packages requires **Java 17 or higher**. How to set up such a configuration in R is explained [here](https://jdemetra-new-documentation.netlify.app/#Rconfig)


### Latest release

To get the current stable version (from the latest release):

- From GitHub:

```{r, echo = TRUE, eval = FALSE}
# install.packages("remotes")
remotes::install_github("rjdverse/rjd3highfreq@*release")
```

- From [r-universe](https://rjdverse.r-universe.dev/rjd3highfreq):

```{r, echo = TRUE, eval = FALSE}
install.packages("rjd3highfreq", repos = c("https://rjdverse.r-universe.dev", "https://cloud.r-project.org"))
```


### Development version

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

```{r, echo = TRUE, eval = FALSE}
# install.packages("remotes")
remotes::install_github("rjdverse/rjd3highfreq")
```


## Demonstration with the daily french births

```{r import packages, echo = TRUE, eval = TRUE}
library("rjd3highfreq")
```


```{r import data, echo = TRUE, eval = TRUE}
## Import of data
df_daily <- read.csv2("https://raw.githubusercontent.com/TanguyBarthelemy/Tsace_RJD_Webinar_Dec22/b5fcf6b14ae47393554950547ef4788a0068a0f6/Data/TS_daily_births_franceM_1968_2020.csv")

# Creation of log variables to multiplicative model
df_daily$log_births <- log(df_daily$births)
df_daily$date <- as.Date(df_daily$date)
``` 


Plot of the raw series:

```{r raw data plot, echo = FALSE, eval = TRUE}
# Plot of the raw data ----------------------------------------------------
rjd3highfreq::.plot_jd(x = df_daily$date, y = list(df_daily$births),
                       col = "#f1ba1d", main = "French daily birth",
                       ylab = "Nbr birth")
```

Preparation of the calendar with the package **rjd3toolkit**:

```{r calendar creation, echo = TRUE, eval = TRUE}
# French calendar
frenchCalendar <- rjd3toolkit::national_calendar(days = list(
  rjd3toolkit::fixed_day(7, 14), # Bastille Day
  rjd3toolkit::fixed_day(5, 8, validity = list(start = "1982-05-08")), # End of 2nd WW
  rjd3toolkit::special_day('NEWYEAR'),
  rjd3toolkit::special_day('MAYDAY'), # 1st may
  rjd3toolkit::special_day('EASTERMONDAY'),
  rjd3toolkit::special_day('ASCENSION'),
  rjd3toolkit::special_day('WHITMONDAY'),
  rjd3toolkit::special_day('ASSUMPTION'),
  rjd3toolkit::special_day('ALLSAINTSDAY'), # Toussaint
  rjd3toolkit::special_day('ARMISTICE'), # End of 1st WW
  rjd3toolkit::special_day('CHRISTMAS'))
)
```

Creation of the calendar regressor in a matrix with the package **rjd3toolkit**:

```{r regressor matrix creation, echo = TRUE, eval = TRUE}
# Calendar regressor matrix
cal_reg <- rjd3toolkit::holidays(
    calendar = frenchCalendar,
    start = "1968-01-01", length = nrow(df_daily),
    type = "All", nonworking = 7L)

colnames(cal_reg) <- c("14th_july", "8th_may", "1st_jan", "1st_may",
                       "east_mon", "asc", "pen_mon",
                       "15th_aug", "1st_nov", "11th_nov", "Xmas")
```

Preprocessing with the function `fractionalAirlineEstimation`:

```{r preprocessing, echo = TRUE, eval = TRUE}
pre_pro <- fractionalAirlineEstimation(
    y = df_daily$births,
    x = cal_reg,
    periods = 7, # weekly frequency
    outliers = c("ao", "wo"), log = TRUE, y_time = df_daily$date)

print(pre_pro)
```

```{r preprocessing plots, echo = TRUE, eval = TRUE}
plot(pre_pro, main = "French births")
plot(x = pre_pro,
     from = as.Date("2000-01-01"), to = as.Date("2000-12-31"),
     main = "French births in 2000")
```


Decomposition with the AMB (Arima Model Based) algorithm:

```{r amb, echo = TRUE, eval = TRUE}
# Decomposition with weekly pattern
amb.dow <- rjd3highfreq::fractionalAirlineDecomposition(
    y = pre_pro$model$linearized, # linearized series from preprocessing
    period = 7,
    log = TRUE, y_time = df_daily$date)

# Extract day-of-year pattern from day-of-week-adjusted linearised data
amb.doy <- rjd3highfreq::fractionalAirlineDecomposition(
    y = amb.dow$decomposition$sa, # DOW-adjusted linearised data
    period = 365.2425, # day of year pattern
    log = TRUE, y_time = df_daily$date)
```


Plot:

```{r amb plot 1, echo = TRUE, eval = TRUE}
plot(amb.dow, main = "Weekly pattern")
```

```{r amb plot 2, echo = TRUE, eval = TRUE}
plot(amb.dow, main = "Weekly pattern - January 2018",
     from = as.Date("2018-01-01"),
     to = as.Date("2018-01-31"))
```

```{r amb plot 3, echo = TRUE, eval = TRUE}
plot(amb.doy, main = "Yearly pattern")
```

```{r amb plot 4, echo = TRUE, eval = TRUE}
plot(amb.doy, main = "Weekly pattern - 2000 - 2002",
     from = as.Date("2000-01-01"),
     to = as.Date("2002-12-31"))
```

Perform an Arima Model Based (AMB) decomposition on several periodcities at once:

```{r amb.multi, echo = TRUE, eval = TRUE}
amb.multi <- rjd3highfreq::multiAirlineDecomposition(
  y = pre_pro$model$linearized, # input time series
  periods = c(7, 365.2425), # 2 frequency
  log = TRUE, y_time = df_daily$date)
```


Plot the comparison between the two AMB methods for the annual periodicity:

```{r plot amb.multi 1, echo = TRUE, eval = TRUE}
plot(amb.multi)
```

```{r plot amb.multi 2, echo = TRUE, eval = TRUE}
plot(amb.multi, main = "2012",
     from = as.Date("2012-01-01"),
     to = as.Date("2012-12-31"))
```


With the package [**rjd3x11plus**](https://github.com/rjdverse/rjd3x11plus), you can perform an X-11 like decomposition with any (non integer) periodicity.


## Package Maintenance and contributing

Any contribution is welcome and should be done through pull requests and/or issues.
pull requests should include **updated tests** and **updated documentation**. If functionality is changed, docstrings should be added or updated.


## Licensing

The code of this project is licensed under the [European Union Public Licence (EUPL)](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12).