Package 'gratis'

Launch the gratis Shiny application

Description

Launch a local Shiny application for generating time series with controllable features.

Usage

app_gratis()

Value

Called for its side effect of launching a Shiny application. Returns the value from runApp().

Examples

## Not run: 
app_gratis()

## End(Not run)

---

Specify an ARIMA model

Description

Construct a Gaussian ARIMA$(p,d,q)(P,D,Q)_m$ model that can be used with simulate.Arima() or generate.Arima(). Any omitted argument is randomly selected from the supported parameter space.

Usage

arima_model(
  frequency = 1,
  p = NULL,
  d = NULL,
  q = NULL,
  P = NULL,
  D = NULL,
  Q = NULL,
  constant = NULL,
  phi = NULL,
  theta = NULL,
  Phi = NULL,
  Theta = NULL,
  sigma = NULL
)

Arguments

frequency	The length of the seasonal period (e.g., 12 for monthly data).
p	Non-seasonal autoregressive order.
d	Non-seasonal differencing order.
q	Non-seasonal moving-average order.
P	Seasonal autoregressive order.
D	Seasonal differencing order.
Q	Seasonal moving-average order.
constant	Intercept term.
phi	A numeric p-vector containing the AR parameters.
theta	A numeric q-vector containing the MA parameters.
Phi	A numeric P-vector containing the seasonal AR parameters.
Theta	A numeric Q-vector containing the seasonal MA parameters.
sigma	The standard deviation of the noise.

Details

When orders are omitted, p and q are sampled from $\{0,1,2,3\}$, P and Q from $\{0,1,2\}$, d from $\{0,1,2\}$, and D from $\{0,1\}$, with the restriction $d + D \le 2$. If constant is omitted, it is sampled from $(-3,3)$ unless $d + D = 2$, in which case it is set to zero. AR and MA parameters are sampled so the stationary and invertible parts of the process are valid, and sigma is sampled from $(1,5)$.

Value

An Arima object compatible with the forecast package's simulation methods.

Author(s)

Rob J Hyndman

See Also

simulate.Arima

Examples

# An AR(2) model with random parameters
model1 <- arima_model(p = 2, d = 0, q = 0)
# An AR(2) model with specific parameters
model2 <- arima_model(p = 2, d = 0, q = 0, phi = c(1.34, -0.64), sigma = 15)
# Seasonal ARIMA model with randomly selected parameters
model3 <- arima_model(frequency = 4)
# Simulate from each model and plot the results
plot(simulate(model1, 100))
plot(simulate(model2, 100))
plot(simulate(model3, 100))

---

Specify an ETS model

Description

Construct an ETS state space model that can be used with simulate.ets() or generate.ets(). Any omitted argument is randomly selected from the supported parameter space.

Usage

ets_model(
  frequency = 1,
  error = NULL,
  trend = NULL,
  seasonal = NULL,
  alpha = NULL,
  beta = NULL,
  gamma = NULL,
  phi = NULL,
  level = NULL,
  slope = NULL,
  season = NULL,
  damped = NULL,
  sigma = NULL
)

Arguments

frequency	The length of the seasonal period (e.g., 12 for monthly data).
error	Character string specifying the error component: "A" for additive or "M" for multiplicative.
trend	Character string specifying the trend component: "N" for none or "A" for additive.
seasonal	Character string specifying the seasonal component: "N" for none, "A" for additive, or "M" for multiplicative.
alpha	Smoothing parameter for the level.
beta	Smoothing parameter for the trend.
gamma	Smoothing parameter for seasonality.
phi	Damping parameter.
level	Initial level $\ell_0$.
slope	Initial slope $b_0$.
season	Numeric vector of initial seasonal states $s_{1-m},\dots,s_0$.
damped	Logical value indicating whether an additive trend is damped.
sigma	The standard deviation of the noise.

Details

The error component is sampled from "A" and "M", the trend component from "N" and "A", and the seasonal component from "N", "A", and "M" when frequency > 1. Smoothing parameters are sampled until they satisfy the ETS admissibility conditions. The innovation variance is sampled from $(1,5)$ for additive errors and from $(0.0001,0.05)$ for multiplicative errors. Initial states are sampled from ranges appropriate to the selected components.

Value

An ets object compatible with the forecast package's simulation methods.

Author(s)

Rob J Hyndman

See Also

simulate.ets

Examples

# An ETS(A,A,N) model with random parameters
model1 <- ets_model(error = "A", trend = "A", seasonal = "N")
# An ETS(A,A,N) model with specific parameters
model2 <- ets_model(
  error = "A", trend = "A", seasonal = "N",
  alpha = 0.3, beta = 0.2, level = 0, slope = 1, sigma = 2
)
# A quarterly seasonal ETS model with random admissible parameters
model3 <- ets_model(error = "A", trend = "N", seasonal = "A", frequency = 4)
# Simulate from each model and plot the results
plot(simulate(model1, 100))
plot(simulate(model2, 100))
plot(simulate(model3, 100))

---

Generate a random multiple-seasonal MAR time series

Description

This function is deprecated. Use mar_model() with generate.mar() or simulate.mar() instead.

Usage

generate_msts(
  seasonal.periods = c(7, 365),
  n = 800,
  nComp = NULL,
  output_format = "list"
)

Arguments

seasonal.periods	Numeric vector of seasonal periods.
n	Length of the generated series.
nComp	Number of mixture components. If NULL, this is sampled randomly for each generated component series.
output_format	Output format: "list" for the historical msts result or "tsibble" for a tsibble.

Value

A multiple-seasonal time series when output_format = "list", or a tsibble when output_format = "tsibble".

Examples

x <- generate_msts(seasonal.periods = c(7, 365), n = 800, nComp = 2, output_format = "list")
forecast::autoplot(x)

---

Generate random MAR time series

Description

This function is deprecated. Use mar_model() with generate.mar() or simulate.mar() instead.

Usage

generate_ts(n.ts = 1, freq = 1, nComp = NULL, n = 120, output_format = "list")

Arguments

n.ts	Number of time series to generate.
freq	Seasonal period of the generated series.
nComp	Number of mixture components. If NULL, this is sampled randomly for each generated series.
n	Length of each generated series.
output_format	Output format: "list" for the historical list format or "tsibble" for a list of tsibbles.

Value

When output_format = "list", a list containing generated time series and the parameters used for each series. When output_format = "tsibble", a list of tsibbles.

Author(s)

Yanfei Kang and Feng Li

References

Wong, CS & WK Li (2000).

Examples

x <- generate_ts(n.ts = 2, freq = 12, nComp = 2, n = 120)
x$N1$pars
forecast::autoplot(x$N1$x)

---

Generate time series with target features

Description

This function is deprecated. Use generate_target() instead.

Usage

generate_ts_with_target(
  n,
  ts.length,
  freq,
  seasonal,
  features,
  selected.features,
  target,
  parallel = TRUE,
  output_format = "list"
)

Arguments

n	Number of time series to generate.
ts.length	Length of each generated time series.
freq	Seasonal frequency, or seasonal periods for multiple-seasonal data.
seasonal	Integer seasonality flag: 0 for non-seasonal data, 1 for single-seasonal data, and 2 for multiple-seasonal data.
features	Character vector of feature function names passed to tsfeatures().
selected.features	Character vector naming the features to match.
target	Numeric vector of target feature values in the same order as selected.features.
parallel	Logical value or parallel backend specification indicating whether the genetic algorithm should evaluate candidates in parallel.
output_format	Output format: "list" for a ts or msts object, or "tsibble" for a tsibble.

Value

Generated time series in the requested output_format.

Author(s)

Yanfei Kang

Examples

## Not run: 
library(tsfeatures)
x <- generate_ts_with_target(
  n = 1, ts.length = 60, freq = 1, seasonal = 0,
  features = c("entropy", "stl_features"), selected.features = c("entropy", "trend"),
  target = c(0.6, 0.9), parallel = FALSE
)
forecast::autoplot(x)

## End(Not run)

---

Generate a tsibble of synthetic time series

Description

Generate one or more synthetic time series from a fitted or specified model. Methods are provided for mar_model() objects, ETS objects from ets_model(), and ARIMA objects from arima_model(). Each series is produced by repeatedly calling the corresponding simulate() method.

Usage

## S3 method for class 'mar'
generate(x, length = 100, nseries = 10, ...)

## S3 method for class 'ets'
generate(x, length = 100, nseries = 10, ...)

## S3 method for class 'Arima'
generate(x, length = 100, nseries = 10, ...)

Arguments

x	A model object of class mar, ets, or Arima.
length	Length of each series to generate.
nseries	Number of series to generate.
...	Other arguments passed to the relevant simulate() method. For mar objects these are passed to simulate.mar().

Details

The generated series are returned as a tsibble. The index is inferred from the model frequency or seasonal periods where possible, with special handling for common weekly, hourly, half-hourly, quarter-hourly, and minute data.

Value

A tsibble containing the generated values. For multiple series the output has length * nseries rows and includes a key column identifying each series.

Author(s)

Rob J Hyndman

References

Feng Li, Mattias Villani, and Robert Kohn. (2010). Flexible Modeling of Conditional Distributions using Smooth Mixtures of Asymmetric Student T Densities, Journal of Statistical Planning and Inference, 140(12), pp. 3638-3654.

See Also

mar_model, arima_model, ets_model, simulate.mar

Examples

# MAR model with constant variances
phi <- cbind(c(0.8, 0), c(0.6, 0.3))
weights <- c(0.8, 0.2)
model1 <- mar_model(phi = phi, sigmas = c(1, 2), weights = weights)
generate(model1, nseries = 5)

# MAR model for hourly data with daily and weekly periods
hourly_model <- mar_model(seasonal_periods = c(24, 24*7))
generate(hourly_model, length = 24 * 7, nseries = 2)

# ARIMA and ETS models also work
generate(arima_model(p = 1, d = 0, q = 0, phi = 0.5), length = 20, nseries = 2)
generate(ets_model(error = "A", trend = "N", seasonal = "N"), length = 20, nseries = 2)

---

Specify a mixture autoregressive model

Description

Construct a mixture autoregressive (MAR) model made up of $k$ Gaussian ARIMA$(p,d,0)(P,D,0)_m$ components. The resulting mar object can be passed to simulate.mar() to simulate one series or to generate.mar() to generate a tsibble of several series.

Usage

mar_model(
  k = NULL,
  p = NULL,
  d = NULL,
  phi = NULL,
  P = NULL,
  D = NULL,
  Phi = NULL,
  constants = NULL,
  sigmas = NULL,
  weights = NULL,
  seasonal_periods = 1L
)

Arguments

k	Number of mixture components.
p	Non-negative integer vector giving the non-seasonal AR orders $p_i$. Ignored when phi is supplied.
d	Non-negative integer vector giving the non-seasonal differencing orders $d_i$.
phi	Numeric matrix of non-seasonal AR parameters. Column $i$ contains the parameters for component $i$.
P	Non-negative integer vector giving the seasonal AR orders $P_i$. Ignored when all seasonal_periods are 1 or when Phi is supplied.
D	Non-negative integer vector giving the seasonal differencing orders $D_i$. Ignored when all seasonal_periods are 1.
Phi	Numeric matrix of seasonal AR parameters. Column $i$ contains the parameters for component $i$. Ignored when all seasonal_periods are 1.
constants	Numeric vector of length k containing the component constants $c_1,\dots,c_k$.
sigmas	Numeric vector of length k, or a list of k GARCH specifications created by garchSpec().
weights	Positive numeric vector of length k containing the component probabilities $\alpha_1,\dots,\alpha_k$. Values are normalized to sum to 1.
seasonal_periods	Scalar seasonal period applied to every component, or a numeric vector of length k giving the seasonal period for each component.

Details

Component $i$ has the form

$(1-B)^{d_i}(1-B^{m_i})^{D_i} (1-\phi_i(B))(1-\Phi_i(B)) y_t = c_i + \sigma_{i,t}\epsilon_t$

and is selected with probability $\alpha_i$. Here $B$ is the backshift operator, $m_i$ is the seasonal period, $\epsilon_t$ is a standard normal variate, and $\phi_i(B)$ and $\Phi_i(B)$ are the non-seasonal and seasonal autoregressive polynomials.

Any missing model argument is randomly selected. Randomly selected non-seasonal AR orders are sampled from $\{0,1,2,3\}$, non-seasonal differences from $\{0,1,2\}$, seasonal AR orders from $\{0,1,2\}$, and seasonal differences from $\{0,1\}$. AR parameters are sampled from the stationary region, constants from $(-3,3)$, sigmas from $(1,5)$, and mixture weights from $(0,1)$ before normalization. If k is omitted, the number of components is sampled from $\{1,2,3,4,5\}$, unless it can be inferred from another argument.

Value

An object of class mar. The object stores the component orders, coefficients, constants, sigmas, normalized weights, seasonal periods, and the expanded AR recursion coefficients used by simulate.mar().

Author(s)

Rob J Hyndman

See Also

simulate.mar

Examples

# Quarterly MAR model with randomly selected parameters
model1 <- mar_model(seasonal_periods = 4)

# Daily MAR model with randomly selected parameters
model2 <- mar_model(seasonal_periods = c(7, 365))

# MAR model with constant variances and user-specified coefficients
phi <- cbind(c(0.8, 0), c(0.6, 0.3))
weights <- c(0.8, 0.2)
model3 <- mar_model(phi = phi, d = 0, sigmas = c(1, 2), weights = weights)

# MAR model with heteroskedastic errors
if (requireNamespace("fGarch", quietly = TRUE)) {
  sigmas_spec <- list(
    fGarch::garchSpec(model = list(alpha = c(0.05, 0.06))),
    fGarch::garchSpec(model = list(alpha = c(0.05, 0.05)))
  )
  model4 <- mar_model(phi = phi, sigmas = sigmas_spec, weights = weights)
}

---

Compute AR recursion coefficients from SARIMA coefficients

Description

Convert SARIMA coefficients into the equivalent infinite-order AR recursion coefficients, truncated after the last coefficient whose absolute value is greater than tol. These coefficients are used internally by mar_model() and are also exported for users who need the same conversion.

Usage

pi_coefficients(
  ar = 0,
  d = 0L,
  ma = 0,
  sar = 0,
  D = 0L,
  sma = 0,
  m = 1L,
  tol = 1e-07
)

Arguments

ar	Non-seasonal AR coefficients.
d	Number of non-seasonal differences.
ma	Non-seasonal MA coefficients.
sar	Seasonal AR coefficients.
D	Number of seasonal differences.
sma	Seasonal MA coefficients.
m	Seasonal period.
tol	Tolerance used for truncation. Coefficients are returned through the last position whose absolute value exceeds tol.

Value

A numeric vector of AR recursion coefficients.

Author(s)

Rob J Hyndman

Examples

pi_coefficients(ar = 0.8)
pi_coefficients(ar = c(0.4, -0.2), d = 1)
pi_coefficients(ar = 0.3, sar = 0.2, D = 1, m = 12)

---

Generate random values from a mixture of multivariate normal distributions

Description

Draw random values from a finite mixture of $k$ multivariate normal distributions, each with dimension $q$. For univariate mixtures, means and sigmas may be supplied as vectors.

Usage

rmixnorm(n, means, sigmas, weights)

Arguments

n	Number of observations to generate.
means	A $q \times k$ matrix of component means, or a vector of length $k$ for univariate mixtures.
sigmas	A $q \times q \times k$ array of component covariance matrices, or a vector of length $k$ for univariate mixtures.
weights	Numeric vector of component probabilities. Values are used as sampling probabilities for the mixture components.

Value

An $n \times q$ matrix of generated data, or a numeric vector when $q = 1$.

Author(s)

Feng Li, Central University of Finance and Economics.

References

Villani et al 2009.

Examples

out <- rmixnorm(
  n = 1000, means = c(-5, 0, 5), sigmas = c(1, 1, 3),
  weights = c(0.3, 0.4, 0.3)
)
hist(out, breaks = 100, freq = FALSE)

---

Simulate a mixture-normal autoregressive process

Description

Simulate a univariate process whose conditional distribution is a finite mixture of Gaussian distributions. The conditional mean of each component is an autoregressive process with its own parameter vector.

Usage

rmixnorm_ts(n, means.ar.par.list, sigmas.list, weights, yinit = 0)

Arguments

n	Number of observations to generate.
means.ar.par.list	List of component AR parameter vectors. The first element of each vector is the intercept, followed by lag coefficients.
sigmas.list	List of component variance or volatility vectors, each of length n.
weights	Numeric vector of component probabilities.
yinit	Initial value used to seed the recursion.

Value

A ts object of length n.

Author(s)

Feng Li, Central University of Finance and Economics.

References

Feng Li, Mattias Villani, and Robert Kohn. (2010). Flexible Modeling of Conditional Distributions using Smooth Mixtures of Asymmetric Student T Densities, Journal of Statistical Planning and Inference, 140(12), pp. 3638-3654.

Examples

if (requireNamespace("fGarch", quietly = TRUE)) {
n <- 1000
means.ar.par.list <- list(c(0, 0.8), c(0, 0.6, 0.3))
sigmas.spec <- list(
  fGarch::garchSpec(model = list(alpha = c(0.05, 0.06)), cond.dist = "norm"),
  fGarch::garchSpec(model = list(alpha = c(0.05, 0.05)), cond.dist = "norm")
)
sigmas.list <- lapply(
  lapply(sigmas.spec, fGarch::garchSim, extended = TRUE, n = n),
  function(x) x$sigma
)
weights <- c(0.8, 0.2)
y <- rmixnorm_ts(
  n = n, means.ar.par.list = means.ar.par.list, sigmas.list = sigmas.list,
  weights = weights
)
plot(y)
}

---

Generate time series with target features

Description

Search for MAR model parameters that produce time series with feature values close to a user-specified target. simulate_target() returns one generated series, while generate_target() repeats the search to return several generated series in a tsibble.

Usage

simulate_target(
  length = 100,
  seasonal_periods = 1,
  feature_function,
  target,
  k = ifelse(length(seasonal_periods) == 1, 3, length(seasonal_periods)),
  tolerance = 0.05,
  trace = FALSE,
  parallel = FALSE
)

generate_target(
  length = 100,
  nseries = 10,
  seasonal_periods = 1,
  feature_function,
  target,
  k = ifelse(length(seasonal_periods) == 1, 3, length(seasonal_periods)),
  tolerance = 0.05,
  trace = FALSE,
  parallel = FALSE
)

Arguments

length	Length of each generated time series.
seasonal_periods	Scalar seasonal period, or a numeric vector of seasonal periods for multiple-seasonal data.
feature_function	Function that accepts a time series and returns a numeric vector of features.
target	Numeric vector of target feature values. It must have the same length and order as the vector returned by feature_function().
k	Number of MAR components to use. The default is 3 for single-seasonal or non-seasonal data, and the number of seasonal periods for multiple-seasonal data.
tolerance	Average absolute feature tolerance. Larger values usually return faster but less precise results.
trace	Logical value indicating whether to show genetic algorithm progress.
parallel	Logical value or parallel backend specification passed to the genetic algorithm. Use TRUE to run fitness evaluations in parallel.
nseries	Number of series to generate

Details

A genetic algorithm evaluates candidate MAR parameter vectors by simulating a series, scaling it, computing feature_function(), and comparing those features to target. Because each candidate series is scaled before feature evaluation, the target features should not depend on the absolute scale of the series.

Value

simulate_target() returns a msts object of length length. generate_target() returns a tsibble containing nseries generated series.

Author(s)

Yanfei Kang and Rob J Hyndman

Examples

## Not run: 
set.seed(1)
library(tsfeatures)
my_features <- function(y) {
  c(entropy(y), acf = acf(y, plot = FALSE)$acf[2:3, 1, 1])
}
# Simulate a ts with specified target features
y <- simulate_target(
  length = 60, feature_function = my_features, target = c(0.5, 0.9, 0.8)
)
my_features(y)
plot(y)

# Generate a tsibble with specified target features
df <- generate_target(
  length = 60, feature_function = my_features, target = c(0.5, 0.9, 0.8)
)
df %>% 
 as_tibble() %>%
 group_by(key) %>%
 dplyr::reframe(
           value = my_features(value), 
           feature=c("entropy","acf1", "acf2")
           )
autoplot(df)
# Simulate time series similar to an existing series
my_features <- function(y) {
  c(stl_features(y)[c("trend", "seasonal_strength", "peak", "trough")])
}
y <- simulate_target(
  length = length(USAccDeaths),
  seasonal_periods = frequency(USAccDeaths),
  feature_function = my_features, target = my_features(USAccDeaths)
)
tsp(y) <- tsp(USAccDeaths)
plot(cbind(USAccDeaths, y))
cbind(my_features(USAccDeaths), my_features(y))

## End(Not run)

---

Simulate from a mixture autoregressive model

Description

Simulate one random sample path from a mixture of Gaussian autoregressive components created by mar_model(). At each time point, a component is sampled according to the model weights, that component's conditional mean and innovation variance are used, and the resulting series is returned after discarding a burn-in period.

Usage

## S3 method for class 'mar'
simulate(object, nsim = 100, seed = NULL, n.start = 100, ...)

Arguments

object	A mar object, usually created by mar_model().
nsim	Length of the generated series.
seed	Either NULL or an integer that will be used in a call to set.seed() before simulating the time series. The default, NULL, leaves the random number generator state unchanged.
n.start	Length of the burn-in period discarded before returning the simulated series.
...	Other arguments, not currently used.

Value

A msts object of length nsim. For single-seasonal or non-seasonal models this also behaves like a base ts object.

Author(s)

Rob J Hyndman

References

Feng Li, Mattias Villani, and Robert Kohn. (2010). Flexible Modeling of Conditional Distributions using Smooth Mixtures of Asymmetric Student T Densities, Journal of Statistical Planning and Inference, 140(12), pp. 3638-3654.

See Also

mar_model

Examples

# MAR model with constant variances
phi <- cbind(c(0.8, 0), c(0.6, 0.3))
weights <- c(0.8, 0.2)
model1 <- mar_model(phi = phi, sigmas = c(1, 2), weights = weights)
y <- simulate(model1, 100)
plot(y)

# MAR model with heteroskedastic errors
if (requireNamespace("fGarch", quietly = TRUE)) {
  sigmas_spec <- list(
    fGarch::garchSpec(model = list(alpha = c(0.05, 0.06))),
    fGarch::garchSpec(model = list(alpha = c(0.05, 0.05)))
  )
  model2 <- mar_model(phi = phi, sigmas = sigmas_spec, weights = weights)
  y <- simulate(model2, 100)
  plot(y)
}

---