The package gratis 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

R CRAN version

install.packages("gratis")

R Development version

You can install the development version of gratis package from GitHub Repository with:

devtools::install_github("ykang/gratis")

Python package

The Python package is developed from the python/ subdirectory:

python -m pip install -e ./python

Install the Python development dependencies when running the Python tests:

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.

R Usage

Tutorial video for R users

Watch this YouTube video provided by Prof. Rob Hyndman.

Load the package in R

library(gratis)
library(feasts)

Generate diverse time series

set.seed(27)
mar_model(seasonal_periods=12) %>%
  generate(length=120, nseries=2) %>%
  autoplot(value)

Generate mutiple seasonal time series

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

Generate time series with controllable features

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")
           )
#> # A tibble: 30 × 3
#>    key       value feature
#>    <chr>     <dbl> <chr>  
#>  1 Series 1  0.509 entropy
#>  2 Series 1  0.906 acf1   
#>  3 Series 1  0.787 acf2   
#>  4 Series 10 0.465 entropy
#>  5 Series 10 0.896 acf1   
#>  6 Series 10 0.775 acf2   
#>  7 Series 2  0.483 entropy
#>  8 Series 2  0.901 acf1   
#>  9 Series 2  0.812 acf2   
#> 10 Series 3  0.504 entropy
#> # ℹ 20 more rows
autoplot(df)

Web application

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

app_gratis()

Or visit our online Shiny APP

Python usage

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

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.

References

• Kang, Y., Hyndman, R.J, and Li, F. (2020). GRATIS: GeneRAting TIme Series with diverse and controllable characteristics. Statistical Analysis and Data Mining.

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.