README.Rmd

---
output: github_document
---

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

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

# gratis <img src="man/figures/logo.PNG" align="right" height="210"/>

<!-- badges: start -->
[![R build status](https://github.com/ykang/gratis/workflows/R-CMD-check/badge.svg)](https://github.com/ykang/gratis/actions)
[![](https://cranlogs.r-pkg.org/badges/gratis)](https://CRAN.R-project.org/package=gratis)
<!-- badges: end -->

The R package `gratis` (previously known as `tsgeneration`) provides efficient algorithms for generating time series with
diverse and controllable characteristics.

## Installation

### [CRAN version]( https://CRAN.R-project.org/package=gratis)

```r
install.packages("gratis")
```

### Development version

You can install the **development** version of `gratis` package from [GitHub
Repository](https://github.com/ykang/gratis) with:

``` r
devtools::install_github("ykang/gratis")
```

## Usage

### Tutorial video

Watch [this Youtube video](https://www.youtube.com/watch?v=F3lWECtFa44) provided by [Prof. Rob Hyndman](https://robjhyndman.com/).

### Load the package

```{r, message=FALSE}
library(gratis)
library(feasts)
```

### Generate diverse time series

```{r}
set.seed(1)
mar_model(seasonal_periods=12) %>%
  generate(length=120, nseries=2) %>%
  autoplot(value)
```

### Generate mutiple seasonal time series

```{r}
mar_model(seasonal_periods=c(24, 24*7)) %>%
  generate(length=24*7*10, nseries=12) %>%
  autoplot(value)
```

### Generate time series with controllable features

```{r, message=FALSE}
library(dplyr)
# Function to return spectral entropy, and ACF at lags 1 and 2
# given a numeric vector input
my_features <- function(y) {
  c(tsfeatures::entropy(y), acf = acf(y, plot = FALSE)$acf[2:3, 1, 1])
}
# Produce series with entropy = 0.5, ACF1 = 0.9 and ACF2 = 0.8
df <- generate_target(
  length = 60, feature_function = my_features, target = c(0.5, 0.9, 0.8)
)
df %>% 
 as_tibble() %>%
 group_by(key) %>%
 summarise(value = my_features(value), 
           feature=c("entropy","acf1", "acf2"),
           .groups = "drop")
autoplot(df)
```

### Web application

You can also run the time series generation procedure in a shiny app

``` r
app_gratis()
```

Or visit our [online Shiny APP](https://ebsmonash.shinyapps.io/tsgeneration/)

## See also

- R package `tsfeatures` from [GitHub Repository](https://github.com/robjhyndman/tsfeatures).

## References

- Kang, Y., Hyndman, R.J, and Li, F. (2020). **GRATIS**: **G**ene**RA**ting **TI**me **S**eries with
diverse and controllable characteristics. [Statistical Analysis and Data Mining](https://doi.org/10.1002/sam.11461).

## License

This package is free and open source software, licensed under GPL-3.

## Acknowledgements

Feng Li and Yanfei Kang are supported by the National Natural Science Foundation of China
(No. 11501587 and No. 11701022 respectively). Rob J Hyndman is supported by the Australian
Centre of Excellence in Mathematical and Statistical Frontiers.