gratis

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)

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. ARIMA also supports an explicit backend="numpy"; ETS uses one implementation. Statistical conventions and cross-language tests are described in the Python README.

Both implementations use sparse MAR lag evaluation and direct scalar mixture simulation. Python generate() reuses statsmodels preparation within each batch, and Python target searches support threads with reproducible candidate streams. Serial target search remains the default; threads are useful only for suitable feature callbacks. Conditional mixture densities are evaluated in vectorized form, and Python ARIMA uses statsmodels' ARMA filter rather than dense state-space simulation. Direct Python model classes validate their parameters too. R generate(..., seed=1) seeds the whole batch once, producing distinct, reproducible series while restoring the previous RNG state. Zero-order MAR mixtures are vectorized, and one-component MAR models use compiled AR filtering without changing random draws. R target search retains only the final population, not every generation's series history. Both languages use an adaptive impulse-energy burn-in estimate for ARIMA, including repeated poles. Random AR models allow all possible real-pole counts (not uniform coefficient sampling). ARIMA and ETS reject noise scales whose squared variance cannot be represented as a positive normal floating-point value. Python MAR arrays are owned and read-only; construct a new model to change them. MAR component stationarity does not ensure mixture stability, and the default 100-step MAR burn-in may be too short for persistent models. R GARCH specifications provide external volatility paths, not residual-coupled MAR-GARCH dynamics.

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.