fitbsSSTVAR: Internal estimation function for estimating STVAR model when...

In sstvars: Toolkit for Reduced Form and Structural Smooth Transition Vector Autoregressive Models

Internal estimation function for estimating STVAR model when bootstrapping confidence bounds for IRFs in linear_IRF

Description

fitbsSSTVAR uses a robust method and a variable metric algorithm to estimate a structural STVAR model based on preliminary estimates.

Usage

fitbsSSTVAR(
  data,
  p,
  M,
  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,
  other_constraints = NULL,
  robust_method = c("Nelder-Mead", "SANN", "none"),
  penalized = FALSE,
  penalty_params = c(0.05, 0.2),
  allow_unstab = FALSE,
  minval = NULL,
  maxit = 1000,
  maxit_robust = 1000,
  seed = NULL
)

Arguments

data	a matrix or class 'ts' object with d>1 columns. Each column is taken to represent a univariate time series. Missing values are not supported.
p	a positive integer specifying the autoregressive order
M	a positive integer specifying the number of regimes
params	a real valued vector specifying the parameter values. Should have the form \theta = (\phi_{1},...,\phi_{M},\varphi_1,...,\varphi_M,\sigma,\alpha,\nu), where (see exceptions below): \phi_{m} = the (d \times 1) intercept (or mean) vector of the mth 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 mth 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},...,\phi_{M} 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} is the intercept parameter, A_{m,i} denotes the ith coefficient matrix of the mth regime, \Omega_{m} denotes the positive definite error term covariance matrix of the mth regime, and B_m is the invertible (d\times d) impact matrix of the mth regime. \nu_m is the degrees of freedom parameter of the mth regime. If parametrization=="mean", just replace each \phi_{m} 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": \alpha_{m,t}= \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 mth 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 ith variable, c is a location parameter, and \gamma > 0 is a scale parameter. "mlogit": \alpha_{m,t}=\frac{\exp\lbrace \gamma_m'z_{t-1} \rbrace} {\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 ith 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 ith 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} 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.
other_constraints	A list containing internally used additional type of constraints (see the options below). $fixed_lambdas (only if identification="heteroskedasticity"): a length d(M-1) numeric vector (\lambda_{2},..., \lambda_{M}) with elements strictly larger than zero specifying the fixed parameter values for the parameters \lambda_{mi} should be constrained to. $B1_constraints (only if identification="non-Gaussianity"): set to the string "fixed_sign_and_order" to impose the constraints that the elements of the first impact matrix B_1 are strictly positive and that they are in a decreasing order.
robust_method	Should some robust estimation method be used in the estimation before switching to the gradient based variable metric algorithm? See details.
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".
minval	the value that will be returned if the parameter vector does not lie in the parameter space (excluding the identification condition).
maxit	the maximum number of iterations in the variable metric algorithm.
maxit_robust	the maximum number of iterations on the first phase robust estimation, if employed.
seed	the seed for the random number generator (relevant when using SANN).

Details

Used internally in the functions linear_IRF for estimating the model in each bootstrap replication.

Employs the estimation function optim from the package stats that implements the optimization algorithms.

Value

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},...,\phi_{M},\varphi_1,...,\varphi_M,\alpha (intercepts replaced by unconditional means if mean parametrization is used), if applicable.

warning

No argument checks!

References

• Kilian L., Lütkepohl H. 20017. Structural Vector Autoregressive Analysis. 1st edition. Cambridge University Press, Cambridge.

• Lütkepohl H., Netšunajev A. 2017. Structural vector autoregressions with smooth transition in variances. Journal of Economic Dynamics & Control, 84, 43-57.

• Virolainen S. 2025. Identification by non-Gaussianity in structural threshold and smooth transition vector autoregressive models. Unpublished working paper, available as arXiv:2404.19707.

See Also

linear_IRF, optim

sstvars documentation built on April 11, 2025, 5:47 p.m.