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. This repository also contains a Python implementation under `python/`, with source
code in `python/gratis`.

## 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")
```

### Python package

The Python package is developed from the `python/` subdirectory:

``` sh
python -m pip install -e ./python
```

Install the Python development dependencies when running the Python tests:

``` sh
python -m pip install -e "./python[dev]"
```

The Python package depends on `statsmodels` for ARIMA and ETS simulation and `matplotlib` for plotting. The Python source is intentionally excluded from
`R CMD build`; see `python/README.md` for Python-specific usage and testing notes.

## 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(27)
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) %>%
 reframe(value = my_features(value), 
           feature=c("entropy","acf1", "acf2")
           )
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/)

## Python usage

The Python API mirrors the main model constructors from the R package and returns NumPy arrays.

``` python
import numpy as np
import gratis

model = gratis.mar_model(
    phi=np.array([[0.8, 0.6], [0.0, 0.3]]),
    d=0,
    sigmas=[1.0, 2.0],
    weights=[0.8, 0.2],
)

series = gratis.simulate(model, n=100, rng=1)
many = gratis.generate(model, length=100, nseries=5, rng=1)
gratis.plot_series(many, title="Generated MAR series")
```

Python ARIMA and ETS models use `statsmodels` by default. Local NumPy simulators remain available with `backend = "numpy"`.

## 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.