stan_ssm: Fitting an Additive linear State space model.
In bayesforecast: Bayesian Time Series Modeling with Stan

stan_ssm

R Documentation

Fitting an Additive linear State space model.

Description

Fitting an Additive linear State space model in Stan.

Usage

stan_ssm(
  ts,
  trend = FALSE,
  damped = FALSE,
  seasonal = FALSE,
  xreg = NULL,
  period = 0,
  genT = FALSE,
  chains = 4,
  iter = 2000,
  warmup = floor(iter/2),
  adapt.delta = 0.9,
  tree.depth = 10,
  prior_sigma0 = NULL,
  prior_level = NULL,
  prior_level1 = NULL,
  prior_trend = NULL,
  prior_trend1 = NULL,
  prior_damped = NULL,
  prior_seasonal = NULL,
  prior_seasonal1 = NULL,
  prior_breg = NULL,
  prior_df = NULL,
  series.name = NULL,
  ...
)

Arguments

`ts`	a numeric or ts object with the univariate time series.
`trend`	a bool value to specify a trend local level model. By default is `FALSE`.
`damped`	a boolvalue to specify a damped trend local level model. By default is `FALSE`. If `trend` option is `FALSE` then `damped` is set to `FALSE` automatically.
`seasonal`	a bool value to specify a seasonal local level model. By default is `FALSE`.
`xreg`	Optionally, a numerical matrix of external regressors, which must have the same number of rows as ts. It should not be a data frame.
`period`	an integer specifying the periodicity of the time series by default the value frequency(ts) is used.
`genT`	a bool value to specify for a generalized t-student SSM model.
`chains`	an integer of the number of Markov Chains chains to be run. By default, `chains = 4`.
`iter`	an integer of total iterations per chain including the warm-up. By default, `iter = 2000`.
`warmup`	a positive integer specifying number of warm-up (aka burn-in) iterations. This also specifies the number of iterations used for step-size adaptation, so warm-up samples should not be used for inference. The number of warm-up iteration should not be larger than `iter`.By default, `warmup = iter/2`.
`adapt.delta`	an optional real value between 0 and 1, the thin of the jumps in a HMC method. By default, is 0.9.
`tree.depth`	an integer of the maximum depth of the trees evaluated during each iteration. By default, is 10.
`prior_sigma0`	The prior distribution for the scale parameter in an ARIMA model. By default, declares a `student(7,0,1)` prior.
`prior_level`	The prior distribution for the level parameter in a SSM model. By default, sets a `normal(0,0.5)` prior.
`prior_level1`	The prior distribution for the initial level parameter in a SSM model. By default, sets a `student(6,0,2.5)` prior.
`prior_trend`	The prior distribution for the trend parameter in a SSM model. By default, sets a `normal(0,0.5)` prior.
`prior_trend1`	The prior distribution for the initial trend parameter in a SSM model. By default, sets a `student(6,0,2.5)` prior.
`prior_damped`	The prior distribution for the damped trend parameter in a SSM model. By default, sets a `normal(0,0.5)` prior.
`prior_seasonal`	The prior distribution for the seasonal parameter in a SSM model. By default, sets a `normal(0,0.5)` prior.
`prior_seasonal1`	The prior distribution for the initial seasonal parameters in a SSM model. The prior is specified for the first m seasonal parameters, where `m` is the periodicity of the defined time series. By default, sets a `normal(0,0.5)` prior.
`prior_breg`	The prior distribution for the regression coefficient parameters in an ARIMAX model. By default, sets `student(7,0,1)` priors.
`prior_df`	The prior distribution for the degree freedom parameters in a t-student innovations SSM model. By default, sets a `gamma(2,0.1)` prior
`series.name`	an optional string vector with the series names.
`...`	Further arguments passed to `varstan` function.

Details

The function returns a varstan object with the fitted model.

By default the ssm() function generates a local-level, ets("A","N","N"), or exponential smoothing model from the forecast package. When trend = TRUE the SSM transforms into a local-trend, ets("A","A","N"), or the equivalent Holt model. For damped trend models set damped = TRUE. If seasonal = TRUE, the model is a seasonal local level model, or ets("A","N","A") model. Finally, the Holt-Winters method (ets("A","A","A")) is obtained by setting both Trend = TRUE and seasonal = TRUE.

The genT = TRUE option generates a t-student innovations SSM model. For a detailed explanation, check Ardia (2010); or Fonseca, et. al (2019).

The default priors used in a ssm model are:

level ~ normal(0,0.5)
Trend ~ normal(0,0.5)
damped~ normal(0,0.5)
Seasonal ~ normal(0,0.5)
sigma0 ~ t-student(0,1,7)
level1 ~ normal(0,1)
trend1 ~ normal(0,1)
seasonal1 ~ normal(0,1)
dfv ~ gamma(2,0.1)
breg ~ t-student(0,2.5,6)

For changing the default prior use the function set_prior().

Value

A varstan object with the fitted SSM model.

Author(s)

Asael Alonzo Matamoros.

References

Fonseca, T. and Cequeira, V. and Migon, H. and Torres, C. (2019). The effects of degrees of freedom estimation in the Asymmetric GARCH model with Student-t Innovations. arXiv doi: arXiv: 1910.01398.

Examples


 # Declaring a local level model for the ipc data.
 sf1 = stan_ssm(ipc,iter = 500,chains = 1)

 # Declaring a Holt model for the ipc data.
 sf2 = stan_ssm(ipc,trend = TRUE,damped = TRUE,iter = 500,chains = 1)

bayesforecast documentation built on June 8, 2025, 10:42 a.m.