STVAR() R function from [sstvars]

Create a class 'stvar' object defining a reduced form or structural smooth transition VAR model

STVAR creates a class 'stvar' object that defines a reduced form or structural smooth transition VAR model


STVAR(
  data,
  p,
  M,
  d,
  params,
  weight_function = c("relative_dens", "logistic", "mlogit", "exponential", "threshold",
    "exogenous"),
  weightfun_pars = NULL,
  cond_dist = c("Gaussian", "Student", "ind_Student", "ind_skewed_t"),
  parametrization = c("intercept", "mean"),
  identification = c("reduced_form", "recursive", "heteroskedasticity",
    "non-Gaussianity"),
  AR_constraints = NULL,
  mean_constraints = NULL,
  weight_constraints = NULL,
  B_constraints = NULL,
  penalized = FALSE,
  penalty_params = c(0.05, 1),
  allow_unstab = FALSE,
  calc_std_errors = FALSE
)

## S3 method for class 'stvar'
logLik(object, ...)

## S3 method for class 'stvar'
residuals(object, ...)

## S3 method for class 'stvar'
summary(object, ..., digits = 2, standard_error_print = FALSE)

## S3 method for class 'stvar'
plot(x, ..., plot_type = c("trans_weights", "cond_mean"))

## S3 method for class 'stvar'
print(x, ..., digits = 2, summary_print = FALSE, standard_error_print = FALSE)

Arguments

data: a matrix or class 'ts' object with d>1 columns. Each column is taken to represent a single times series. NA values are not supported. Ignore if defining a model without data is desired.
p: a positive integer specifying the autoregressive order
M: a positive integer specifying the number of regimes
d: number of times series in the system, i.e. ncol(data). This can be used to define STVAR models without data and can be ignored if data is provided.
params: a real valued vector specifying the parameter values. Should have the form $\theta = (\phi_{1,0},...,\phi_{M,0},\varphi_1,...,\varphi_M,\sigma,\alpha,\nu)$ , where (see exceptions below):
- $\phi_{m,0} =$ the $(d \times 1)$ intercept (or mean) vector of the $m$ th regime.
- $\varphi_m = (vec(A_{m,1}),...,vec(A_{m,p}))$ $(pd^2 \times 1)$ .
- - if cond_dist="Gaussian" or "Student":: $\sigma = (vech(\Omega_1),...,vech(\Omega_M))$
```
  $(Md(d + 1)/2 \times 1)$.
```
  - if cond_dist="ind_Student" or "ind_skewed_t":: $\sigma = (vec(B_1),...,vec(B_M)$ $(Md^2 \times 1)$ .
- $\alpha =$ the $(a\times 1)$ vector containing the transition weight parameters (see below).
- - if cond_dist = "Gaussian"):: Omit $\nu$ from the parameter vector.
  - if cond_dist="Student":: $\nu \> 2$ is the single degrees of freedom parameter.
  - if cond_dist="ind_Student":: $\nu = (\nu_1,...,\nu_d)$ $(d \times 1)$ , $\nu_i \> 2$ .
  - if cond_dist="ind_skewed_t":: $\nu = (\nu_1,...,\nu_d,\lambda_1,...,\lambda_d)$ $(2d \times 1)$ , $\nu_i \> 2$ and $\lambda_i \in (0, 1)$ .
For models with...
- weight_function="relative_dens":: $\alpha = (\alpha_1,...,\alpha_{M-1})$
```
  $(M - 1 \times 1)$, where $\alpha_m$ $(1\times 1), m=1,...,M-1$ are the transition weight parameters.
```
- weight_function="logistic":: $\alpha = (c,\gamma)$
```
  $(2 \times 1)$, where $c\in\mathbb{R}$ is the location parameter and $\gamma >0$ is the scale parameter.
```
- weight_function="mlogit":: $\alpha = (\gamma_1,...,\gamma_M)$ $((M-1)k\times 1)$ , where $\gamma_m$ $(k\times 1)$ , $m=1,...,M-1$ contains the multinomial logit-regression coefficients of the $m$ th regime. Specifically, for switching variables with indices in $I\subset\lbrace 1,...,d\rbrace$ , and with $\tilde{p}\in\lbrace 1,...,p\rbrace$ lags included, $\gamma_m$ contains the coefficients for the vector $z_{t-1} = (1,\tilde{z}_{\min\lbrace I\rbrace},...,\tilde{z}_{\max\lbrace I\rbrace})$ , where $\tilde{z}_{i} =(y_{it-1},...,y_{it-\tilde{p}})$ , $i\in I$ . So $k=1+|I|\tilde{p}$
```
 where $|I|$ denotes the number of elements in $I$.
```
- weight_function="exponential":: $\alpha = (c,\gamma)$
```
  $(2 \times 1)$, where $c\in\mathbb{R}$ is the location parameter and $\gamma >0$ is the scale parameter.
```
- weight_function="threshold":: $\alpha = (r_1,...,r_{M-1})$
```
  $(M-1 \times 1)$, where $r_1,...,r_{M-1}$ are the thresholds.
```
- weight_function="exogenous":: Omit $\alpha$ from the parameter vector.
- AR_constraints:: Replace $\varphi_1,...,\varphi_M$ with $\psi$ as described in the argument AR_constraints.
- mean_constraints:: Replace $\phi_{1,0},...,\phi_{M,0}$ with $(\mu_{1},...,\mu_{g})$ where $\mu_i, \ (d\times 1)$ is the mean parameter for group $i$ and $g$ is the number of groups.
- weight_constraints:: If linear constraints are imposed, replace $\alpha$ with $\xi$ as described in the argument weigh_constraints. If weight functions parameters are imposed to be fixed values, simply drop $\alpha$
```
 from the parameter vector.
```
- identification="heteroskedasticity":: $\sigma = (vec(W),\lambda_2,...,\lambda_M)$ , where $W$ $(d\times d)$ and $\lambda_m$ $(d\times 1)$ , $m=2,...,M$ , satisfy $\Omega_1=WW'$ and $\Omega_m=W\Lambda_mW'$ , $\Lambda_m=diag(\lambda_{m1},...,\lambda_{md})$ , $\lambda_{mi}>0$ , $m=2,...,M$ , $i=1,...,d$ .
- B_constraints:: For models identified by heteroskedasticity, replace $vec(W)$ with $\tilde{vec}(W)$
```
 that stacks the columns of the matrix $W$ in to vector so that the elements that are constrained to zero are not included. For models identified by non-Gaussianity, replace $vec(B_1),...,vec(B_M)$ with similarly with vectorized versions $B_m$ so that the elements that are constrained to zero are not included.
```
Above, $\phi_{m,0}$ is the intercept parameter, $A_{m,i}$ denotes the $i$ th coefficient matrix of the $m$ th regime, $\Omega_{m}$ denotes the positive definite error term covariance matrix of the $m$ th regime, and $B_m$

is the invertible $(d\times d)$ impact matrix of the $m$ th regime. $\nu_m$ is the degrees of freedom parameter of the $m$ th regime. If parametrization=="mean", just replace each $\phi_{m,0}$ with regimewise mean $\mu_{m}$ . $vec()$ is vectorization operator that stacks columns of a given matrix into a vector. $vech()$ stacks columns of a given matrix from the principal diagonal downwards (including elements on the diagonal) into a vector. $Bvec()$

is a vectorization operator that stacks the columns of a given impact matrix $B_m$ into a vector so that the elements that are constrained to zero by the argument B_constraints are excluded.
weight_function: What type of transition weights $\alpha_{m,t}$ should be used?
- "relative_dens":: c(" $\\alpha_{m,t}=\n$ ", " $\\frac{\\alpha_mf_{m,dp}(y_{t-1},...,y_{t-p+1})}{\\sum_{n=1}^M\\alpha_nf_{n,dp}(y_{t-1},...,y_{t-p+1})}$ "), where $\alpha_m\in (0,1)$ are weight parameters that satisfy $\sum_{m=1}^M\alpha_m=1$ and $f_{m,dp}(\cdot)$ is the $dp$ -dimensional stationary density of the $m$ th regime corresponding to $p$
```
 consecutive observations. Available for Gaussian conditional distribution only.
```
- "logistic":: $M=2$ , $\alpha_{1,t}=1-\alpha_{2,t}$ , and $\alpha_{2,t}=[1+\exp\lbrace -\gamma(y_{it-j}-c) \rbrace]^{-1}$ , where $y_{it-j}$ is the lag $j$
```
 observation of the $i$th variable, $c$ is a location parameter, and $\gamma > 0$ is a scale parameter.
```
- "mlogit":: c(" $\\alpha_{m,t}=\\frac{\\exp\\lbrace \\gamma_m'z_{t-1} \\rbrace}\n$ ", " ${\\sum_{n=1}^M\\exp\\lbrace \\gamma_n'z_{t-1} \\rbrace}$ "), where $\gamma_m$ are coefficient vectors, $\gamma_M=0$ , and $z_{t-1}$ $(k\times 1)$ is the vector containing a constant and the (lagged) switching variables.
- "exponential":: $M=2$ , $\alpha_{1,t}=1-\alpha_{2,t}$ , and $\alpha_{2,t}=1-\exp\lbrace -\gamma(y_{it-j}-c) \rbrace$ , where $y_{it-j}$ is the lag $j$
```
 observation of the $i$th variable, $c$ is a location parameter, and $\gamma > 0$ is a scale parameter.
```
- "threshold":: $\alpha_{m,t} = 1$ if $r_{m-1}<y_{it-j}\leq r_{m}$ and $0$ otherwise, where $-\infty\equiv r_0<r_1<\cdots <r_{M-1}<r_M\equiv\infty$ are thresholds $y_{it-j}$ is the lag $j$
```
 observation of the $i$th variable.
```
- "exogenous":: Exogenous nonrandom transition weights, specify the weight series in weightfun_pars.
See the vignette for more details about the weight functions.
weightfun_pars: - If weight_function == "relative_dens":: Not used.
- If weight_function %in% c("logistic", "exponential", "threshold"):: a numeric vector with the switching variable $i\in\lbrace 1,...,d \rbrace$ in the first and the lag $j\in\lbrace 1,...,p \rbrace$ in the second element.
- If weight_function == "mlogit":: a list of two elements:
```
 - **The first element `$vars`:**: a numeric vector containing the variables that should used as switching variables in the weight function in an increasing order, i.e., a vector with unique elements in $\lbrace 1,...,d \rbrace$.
 - **The second element `$lags`:**: an integer in $\lbrace 1,...,p \rbrace$ specifying the number of lags to be used in the weight function.
```
- If weight_function == "exogenous":: a size (nrow(data) - p x M) matrix containing the exogenous transition weights as [t, m] for time $t$ and regime $m$ . Each row needs to sum to one and only weakly positive values are allowed.
cond_dist: specifies the conditional distribution of the model as "Gaussian", "Student", "ind_Student", or "ind_skewed_t", where "ind_Student" the Student's $t$ distribution with independent components, and "ind_skewed_t" is the skewed $t$ distribution with independent components (see Hansen, 1994).
parametrization: "intercept" or "mean" determining whether the model is parametrized with intercept parameters $\phi_{m,0}$ or regime means $\mu_{m}$ , m=1,...,M.
identification: is it reduced form model or an identified structural model; if the latter, how is it identified (see the vignette or the references for details)?
- "reduced_form":: Reduced form model.
- "recursive":: The usual lower-triangular recursive identification of the shocks via their impact responses.
- "heteroskedasticity":: Identification by conditional heteroskedasticity, which imposes constant relative impact responses for each shock.
- "non-Gaussianity":: Identification by non-Gaussianity; requires mutually independent non-Gaussian shocks, thus, currently available only with the conditional distribution "ind_Student".
AR_constraints: a size $(Mpd^2 \times q)$ constraint matrix $C$ specifying linear constraints to the autoregressive parameters. The constraints are of the form $(\varphi_{1},...,\varphi_{M}) = C\psi$ , where $\varphi_{m} = (vec(A_{m,1}),...,vec(A_{m,p})) \ (pd^2 \times 1),\ m=1,...,M$ , contains the coefficient matrices and $\psi$ $(q \times 1)$ contains the related parameters. For example, to restrict the AR-parameters to be the identical across the regimes, set $C =$

[I:...:I]' $(Mpd^2 \times pd^2)$ where I = diag(p*d^2).
mean_constraints: Restrict the mean parameters of some regimes to be identical? Provide a list of numeric vectors such that each numeric vector contains the regimes that should share the common mean parameters. For instance, if M=3, the argument list(1, 2:3) restricts the mean parameters of the second and third regime to be identical but the first regime has freely estimated (unconditional) mean. Ignore or set to NULL if mean parameters should not be restricted to be the same among any regimes. This constraint is available only for mean parametrized models; that is, when parametrization="mean".
weight_constraints: a list of two elements, $R$ in the first element and $r$ in the second element, specifying linear constraints on the transition weight parameters $\alpha$ . The constraints are of the form $\alpha = R\xi + r$ , where $R$ is a known $(a\times l)$

constraint matrix of full column rank ( $a$ is the dimension of $\alpha$ ), $r$ is a known $(a\times 1)$ constant, and $\xi$ is an unknown $(l\times 1)$ parameter. Alternatively , set $R=0$ to constrain the weight parameters to the constant $r$ (in this case, $\alpha$ is dropped from the constrained parameter vector).
B_constraints: a $(d \times d)$ matrix with its entries imposing constraints on the impact matrix $B_t$ : NA indicating that the element is unconstrained, a positive value indicating strict positive sign constraint, a negative value indicating strict negative sign constraint, and zero indicating that the element is constrained to zero. Currently only available for models with identification="heteroskedasticity" or "non-Gaussianity" due to the (in)availability of appropriate parametrizations that allow such constraints to be imposed.
penalized: Perform penalized LS estimation that minimizes penalized RSS in which estimates close to breaking or not satisfying the usual stability condition are penalized? If TRUE, the tuning parameter is set by the argument penalty_params[2], and the penalization starts when the eigenvalues of the companion form AR matrix are larger than 1 - penalty_params[1].
penalty_params: a numeric vector with two positive elements specifying the penalization parameters: the first element determined how far from the boundary of the stability region the penalization starts (a number between zero and one, smaller number starts penalization closer to the boundary) and the second element is a tuning parameter for the penalization (a positive real number, a higher value penalizes non-stability more).
allow_unstab: If TRUE, estimates not satisfying the stability condition are allowed. Always FALSE if weight_function="relative_dens".
calc_std_errors: should approximate standard errors be calculated?
object: object of class 'stvar'.
...: currently not used.
digits: number of digits to be printed.
standard_error_print: if set to TRUE, instead of printing the estimates, prints the approximate standard errors using square roots of the diagonal of inverse of the observed information matrix.
x: an object of class 'stvar'.
plot_type: should the series be plotted with the estimated transition weights or conditional means?
summary_print: if set to TRUE then the print will include log-likelihood and information criteria values.

Returns

Returns an S3 object of class 'stvar' defining a smooth transition VAR model. The returned list contains the following components (some of which may be NULL depending on the use case): - data: The input time series data.

model: A list describing the model structure.
params: The parameters of the model.
std_errors: Approximate standard errors of the parameters, if calculated.
transition_weights: The transition weights of the model.
regime_cmeans: Conditional means of the regimes, if data is provided.
total_cmeans: Total conditional means of the model, if data is provided.
total_ccovs: Total conditional covariances of the model, if data is provided.
uncond_moments: A list of unconditional moments including regime autocovariances, variances, and means.
residuals_raw: Raw residuals, if data is provided.
residuals_std: Standardized residuals, if data is provided.
structural_shocks: Recovered structural shocks, if applicable.
loglik: Log-likelihood of the model, if data is provided.
IC: The values of the information criteria (AIC, HQIC, BIC) for the model, if data is provided.
all_estimates: The parameter estimates from all estimation rounds, if applicable.
all_logliks: The log-likelihood of the estimates from all estimation rounds, if applicable.
which_converged: Indicators of which estimation rounds converged, if applicable.
which_round: Indicators of which round of optimization each estimate belongs to, if applicable.
seeds: The seeds used in the estimation in fitSTVAR, if applicable.
LS_estimates: The least squares estimates of the parameters in the form $(\phi_{1,0},...,\phi_{M,0},\varphi_1,...,\varphi_M,\alpha$ (intercepts replaced by unconditional means if mean parametrization is used), if applicable.

Details

If data is provided, then also residuals are computed and included in the returned object.

The plot displays the time series together with estimated transition weights.

Functions

logLik(stvar): Log-likelihood method
residuals(stvar): residuals method to extract Pearson residuals
summary(stvar): summary method
plot(stvar): plot method for class 'stvar'
print(stvar): print method

About S3 methods

If data is not provided, only the print and simulate methods are available. If data is provided, then in addition to the ones listed above, predict method is also available. See ?simulate.stvar and ?predict.stvar for details about the usage.

Examples


# Below examples use the example data "gdpdef", which is a two-variate quarterly data
# of U.S. GDP and GDP implicit price deflator covering the period from 1959Q1 to 2019Q4.

# Gaussian STVAR p=1, M=2, model with the weighted relative stationary densities
# of the regimes as the transition weight function:
theta_122relg <- c(0.734054, 0.225598, 0.705744, 0.187897, 0.259626, -0.000863,
  -0.3124, 0.505251, 0.298483, 0.030096, -0.176925, 0.838898, 0.310863, 0.007512,
  0.018244, 0.949533, -0.016941, 0.121403, 0.573269)
mod122 <- STVAR(data=gdpdef, p=1, M=2, params=theta_122relg)
print(mod122) # Printout of the model
summary(mod122) # Summary printout
plot(mod122) # Plot the transition weights
plot(mod122, plot_type="cond_mean") # Plot one-step conditional means

# Logistic Student's t STVAR with p=1, M=2, and the first lag of the second variable
# as the switching variable:
params12 <- c(0.62906848, 0.14245295, 2.41245785, 0.66719269, 0.3534745, 0.06041779, -0.34909745,
  0.61783824, 0.125769, -0.04094521, -0.99122586, 0.63805416, 0.371575, 0.00314754, 0.03440824,
  1.29072533, -0.06067807, 0.18737385, 1.21813844, 5.00884263, 7.70111672)
fit12 <- STVAR(data=gdpdef, p=1, M=2, params=params12, weight_function="logistic",
  weightfun_pars=c(2, 1), cond_dist="Student")
summary(fit12) # Summary printout
plot(fit12) # Plot the transition weights

# Threshold STVAR with p=1, M=2, the first lag of the second variable as switching variable:
params12thres <- c(0.5231, 0.1015, 1.9471, 0.3253, 0.3476, 0.0649, -0.035, 0.7513, 0.1651,
 -0.029, -0.7947, 0.7925, 0.4233, 5e-04, 0.0439, 1.2332, -0.0402, 0.1481, 1.2036)
mod12thres <- STVAR(data=gdpdef, p=1, M=2, params=params12thres, weight_function="threshold",
  weightfun_pars=c(2, 1))
mod12thres # Printout of the model

# Student's t logistic STVAR with p=2, M=2 with the second lag of the second variable
# as the switching variable and structural shocks identified by heteroskedasticity;
# the model created without data:
params22log <- c(0.357, 0.107, 0.356, 0.086, 0.14, 0.035, -0.165, 0.387, 0.452,
 0.013, 0.228, 0.336, 0.239, 0.024, -0.021, 0.708, 0.063, 0.027, 0.009, 0.197,
  -0.03, 0.24, -0.76, -0.02, 3.36, 0.86, 0.1, 0.2, 7)
mod222logtsh <- STVAR(p=2, M=2, d=2, params=params22log, weight_function="logistic",
 weightfun_pars=c(2, 2), cond_dist="Student", identification="heteroskedasticity")
print(mod222logtsh) # Printout of the model

# STVAR p=2, M=2, model with exogenous transition weights and mutually independent
# Student's t shocks:
set.seed(1); tw1 <- runif(nrow(gdpdef)-2) # Transition weights of Regime 1
params22exoit <- c(0.357, 0.107, 0.356, 0.086, 0.14, 0.035, -0.165, 0.387, 0.452,
 0.013, 0.228, 0.336, 0.239, 0.024, -0.021, 0.708, 0.063, 0.027, 0.009, 0.197,
 -0.1, 0.2, -0.15, 0.13, 0.21, 0.15, 0.11, -0.09, 3, 4)
mod222exoit <- STVAR(p=2, M=2, d=2, params=params22exoit, weight_function="exogenous",
 weightfun_pars=cbind(tw1, 1-tw1), cond_dist="ind_Student")
print(mod222exoit) # Printout of the model

# Linear Gaussian VAR(p=1) model:
theta_112 <- c(0.649526, 0.066507, 0.288526, 0.021767, -0.144024, 0.897103,
  0.601786, -0.002945, 0.067224)
mod112 <- STVAR(data=gdpdef, p=1, M=1, params=theta_112)
summary(mod112) # Summary printout

References

Anderson H., Vahid F. 1998. Testing multiple equation systems for common nonlinear components. Journal of Econometrics, 84 :1, 1-36.
Hubrich K., Teräsvirta. T. 2013. Thresholds and Smooth Transitions in Vector Autoregressive Models. CREATES Research Paper 2013-18, Aarhus University.
Lanne M., Virolainen S. 2025. A Gaussian smooth transition vector autoregressive model: An application to the macroeconomic effects of severe weather shocks. Unpublished working paper, available as arXiv:2403.14216.
Kheifets I.L., Saikkonen P.J. 2020. Stationarity and ergodicity of Vector STAR models. Econometric Reviews, 39 :4, 407-414.
Lütkepohl H., Netšunajev A. 2017. Structural vector autoregressions with smooth transition in variances. Journal of Economic Dynamics & Control, 84 , 43-57.
Tsay R. 1998. Testing and Modeling Multivariate Threshold Models. Journal of the American Statistical Association, 93 :443, 1188-1202.
Virolainen S. 2025. Identification by non-Gaussianity in structural threshold and smooth transition vector autoregressive models. Unpublished working paper, available as arXiv:2404.19707.

STVAR function