fsvsample simulates from the joint posterior distribution and returns
the MCMC draws. It is the main workhorse to conduct inference for factor
stochastic volatility models in this package.
fsvsample(
y,
factors = 1,
draws = 1000,
thin = 1,
burnin = 1000,
restrict = "none",
zeromean = TRUE,
priorfacloadtype = "rowwiseng",
priorfacload = 0.1,
facloadtol = 1e-18,
priorng = c(1, 1),
priormu = c(0, 10),
priorphiidi = c(10, 3),
priorphifac = c(10, 3),
priorsigmaidi = 1,
priorsigmafac = 1,
priorh0idi = "stationary",
priorh0fac = "stationary",
priorbeta = c(0, 10000),
keeptime = "last",
heteroskedastic = TRUE,
priorhomoskedastic = NA,
runningstore = 6,
runningstorethin = 10,
runningstoremoments = 2,
signident = TRUE,
signswitch = FALSE,
interweaving = 4,
quiet = FALSE,
samplefac = TRUE,
startfac,
startpara,
startlogvar,
startlatent,
startlogvar0,
startlatent0,
startfacload,
startfacloadvar,
expert
)The value returned is a list object of class fsvdraws holding
facload: Array containing draws from the posterior distribution of the factor loadings matrix.
fac: Array containing factor draws from the posterior distribution.
logvar: Array containing idiosyncratic and factor initial log variance draws.
logvar0: Array containing idiosyncratic and factor log variance draws.
para: Array containing parameter draws form the posterior distribution.
y: Matrix containing the data supplied.
latestauxiliary: List containing the latest draws of auxiliary quantities used for sampling the factor loadings matrix.
runningstore: List whose elements contain ergodic moments of certain
variables of interest. See argument
runningstore for details about what
is being stored here.
config: List containing information on configuration parameters.
priors: List containing prior hyperparameter values.
identifier: Matrix containing the indices of the series used for
ex-post sign-identification along with the corresponding minimum distances to zero.
See signident for details.
To display the output, use print, plot, and in particular specialized
extractors and printing functions.
The print method prints a high-level overview; specialized extractors such as
covmat or runningcovmat are also available.
The plot method invokes a simple covariance matrix plot; specialized plotting
functions are linked in the documentation of plot.fsvdraws.
Data matrix. Each of m columns is assumed to contain a single
(univariate) series of length n.
Number of latent factors to be estimated.
Number of MCMC draws kept after burn-in.
Single number greater or equal to 1, coercible to integer.
Every thinth MCMC draw is kept and returned. The default value
is 1, corresponding to no thinning of the draws, i.e. every draw is
stored.
Number of initial MCMC draws to be discarded.
Either "upper", "none", or "auto", indicating whether
the factor loadings
matrix should be restricted to have zeros above the diagonal ("upper"),
whether all elements should be estimated from the data ("none"), or
whether the function findrestrict should be invoked for a
priori finding suitable zeros. Setting
restrict to "upper" or "auto" often stabilizes MCMC
estimation and can be important for identifying the factor loadings matrix,
however, it generally is a strong prior assumption. Setting
restrict to "none" is usually the preferred option if identification
of the factor loadings matrix is of less concern but covariance estimation
or prediction is the goal. Alternatively, restrict can be a
logical matrix
of dimension c(m, r) indicating which elements should be unrestricted
(where restrict is FALSE) or zero (where restrict is
TRUE).
Logical. If FALSE, a constant mean is included in
the model for each of the m univariate series.
If TRUE, the mean is not modeled. Defaults to TRUE.
Can be "normal", "rowwiseng",
"colwiseng".
"normal": Normal prior. The value of priorfacload
is interpreted as the standard deviations of the
Gaussian prior distributions for the factor loadings.
"rowwiseng": Row-wise Normal-Gamma prior. The value of priorfacload
is interpreted as the shrinkage parameter a.
"colwiseng": Column-wise Normal-Gamma prior. The value of priorfacload
is interpreted as the shrinkage parameter a.
For details please see Kastner (2019).
Either a matrix of dimensions m times factors
with positive elements or a single number (which will be recycled accordingly).
The meaning of priorfacload depends on the setting of priorfacloadtype
and is explained there.
Minimum number that the absolute value of a factor loadings draw can take. Prevents numerical issues that can appear when strong shrinkage is enforced if chosen to be greater than zero.
Two-element vector with positive entries indicating the Normal-Gamma
prior's hyperhyperparameters c and d.
Vector of length 2 denoting prior mean and standard deviation for unconditional levels of the idiosyncratic log variance processes.
Vector of length 2, indicating the shape parameters for the
Beta prior distributions of the transformed parameters (phi+1)/2, where
phi denotes the persistence of the idiosyncratic log variances.
Vector of length 2, indicating the shape parameters for the
Beta prior distributions of the transformed parameters (phi+1)/2, where
phi denotes the persistence of the factor log variances.
Vector of length m containing the
prior volatilities of log variances. If priorsigmaidi has exactly
one element, it will be recycled for all idiosyncratic log variances.
Vector of length factors containing the
prior volatilities of log variances. If priorsigmafac has exactly
one element, it will be recycled for all factor log variances.
Vector of length 1 or m, containing
information about the Gaussian prior for the initial idiosyncratic
log variances.
If an element of priorh0idi is a nonnegative number, the conditional
prior of the corresponding initial log variance h0 is assumed to be Gaussian
with mean 0 and standard deviation priorh0idi times $sigma$.
If an element of
priorh0idi is the string 'stationary', the prior of the corresponding
initial log volatility is taken to be from the stationary distribution, i.e.
h0 is assumed to be Gaussian with mean 0 and variance $sigma^2/(1-phi^2)$.
Vector of length 1 or factors, containing
information about the Gaussian prior for the initial factor
log variances.
If an element of priorh0fac is a nonnegative number, the conditional
prior of the corresponding initial log variance h0 is assumed to be Gaussian
with mean 0 and standard deviation priorh0fac times $sigma$.
If an element of
priorh0fac is the string 'stationary', the prior of the corresponding
initial log volatility is taken to be from the stationary distribution, i.e.
h0 is assumed to be Gaussian with mean 0 and variance $sigma^2/(1-phi^2)$.
numeric vector of length 2, indicating the mean and
standard deviation of the Gaussian prior for the regression parameters. The
default value is c(0, 10000), which constitutes a very vague prior
for many common datasets. Not used if zeromean is TRUE.
Either a number coercible to a positive integer, or a string
equal to "all" or "last". If a number different from 1 is provided, only every
keeptimeth latent log-volatility is being monitored. If, e.g.,
keeptime = 3, draws for the latent log variances
h_1,h_4,h_7,... will
be kept. If keeptime is set to "all", this is equivalent to setting it
to 1. If
keeptime is set to "last" (the default), only draws for the very last
latent log variances h_n are kept.
Vector of length 1, 2, or m + factors,
containing logical values indicating whether time-varying
(heteroskedastic = TRUE) or constant (heteroskedastic = FALSE)
variance should be estimated.
If heteroskedastic is of length 2 it will be recycled accordingly,
whereby the first element is used for all idiosyncratic variances and
the second element is used for all factor variances.
Only used if at least one element of
heteroskedastic is set to FALSE. In that case,
priorhomoskedastic must be a matrix with positive entries
and dimension c(m, 2). Values in column 1 will be interpreted as the
shape and values in column 2 will be interpreted as the rate parameter
of the corresponding inverse gamma prior distribution of the idisyncratic
variances.
Because most machines these days do not have enough memory
to store all draws for all points in time, setting runningstore to an
integer greater than 0 will cause fsvsample to store the first
runningstoremoments
ergodic moments of certain variables of interest. More specifically, mean,
variance, skewness, etc. will be stored for certain variables
if runningstore is set to a value...
>= 1: Latent log variances h_1,h_2,...,h_(n+r).
>= 2: Latent factors f_1,...,f_r.
>= 3: Latent volatilities sqrt(exp(h_1,h_2,...,h_(n+r))).
>= 4: Conditional covariance matrix and the square roots of its diagonal elements.
>= 5: Conditional correlation matrix.
>= 6: Communalities, i.e. proportions of variances explained through the common factors.
How often should the calculation of running moments be conducted? Set to a value > 1 if you want to avoid time consuming calculations at every MCMC iteration.
Selects how many running moments (up to 4) should be calculated.
If set to FALSE, no ex-post sign-identification is
performed. Defaults to TRUE.
Set to TRUE to turn on a random sign switch of
factors and loadings. Note that the signs of each factor loadings matrix column
and the corresponding factor cannot be identified from the likelihood.
The following values for interweaving the factor loadings are accepted:
No interweaving.
Shallow interweaving through the diagonal entries.
Deep interweaving through the diagonal entries.
Shallow interweaving through the largest absolute entries in each column.
Deep interweaving through the largest absolute entries in each column.
For details please see Kastner et al. (2017). A value of 4 is the highly recommended default.
Logical value indicating whether the progress bar and other
informative output during sampling should be omitted. The default
value is FALSE, implying verbose output.
If set to FALSE, the factors are not sampled (but
remain at their starting values forever). This might be useful if one
wants to include observed factors instead of latent ones.
optional numeric matrix of dimension
c(factors, n), containing the starting values of the
latent factors.
In case of a single factor model, a numeric vector of length n is also accepted.
optional numeric matrix of dimension
c(3, m + factors), containing the starting values
for the parameter draws. The first m columns must contain
parameters values corresponding to the idiosyncratic volatilities,
the subsequent factor columns must contain parameter values
corresponding to the factor volatilities. The first row of startpara
corresponds to mu, the level of the log variances (can be arbitrary
numerical values), the second row corresponds to phi, the persistence
parameters of the log variances (numeric values between -1 and 1),
and the third row corresponds to sigma (positive numeric values).
optional numeric matrix of dimension
c(n, m + factors), containing the starting values of the
latent log variances.
The first m rows correspond to the idiosyncratic log variances,
the subsequent factor rows correspond to the factor log variances.
Was previously called startlatent.
Deprecated. Please use startlogvar instead.
optional numeric vector of length
m + factors, containing the starting values of the initial latent
log variances.
The first m elements correspond to the idiosyncratic log variances,
the subsequent factor elements correspond to the factor log variances.
Was previously called startlatent0.
Deprecated. Please use startlogvar0 instead.
optional numeric matrix of dimension
c(m, factors), containing the starting values of the
factor loadings.
In case of a single factor model, a numeric vector of length n is also accepted.
optional numeric matrix of dimension
c(m, factors), containing the starting values of the
factor loadings variances \(\tau_{ij}^2\). Used only when the normal-gamma
prior is employed (priorfacloadtype != "normal") while ignored when static
loadings variances are used (priorfacloadtype == "normal").
optional named list of expert parameters for the
univariate SV models (will be transformed and passed to the stochvol package). For most
applications, the default values probably work best. Interested users are
referred to Kastner and Frühwirth-Schnatter (2014), the package vignette, and Kastner (2016). If
expert is provided, it may contain the following named elements:
parameterization: Character string equal to "centered",
"noncentered", "GIS_C", or "GIS_NC". Defaults to
"GIS_C".
mhcontrol: Single numeric value controlling the proposal
density of a Metropolis-Hastings (MH) update step when sampling
sigma. If mhcontrol is smaller than 0, an independence
proposal will be used, while values greater than zero control the
stepsize of a log-random-walk proposal. Defaults to -1.
gammaprior: Single logical value indicating whether a Gamma
prior for sigma^2 should be used. If set to FALSE,
an Inverse Gamma prior is employed. Defaults to TRUE.
truncnormal: Single logical value indicating whether a
truncated Gaussian distribution should be used as proposal for
draws of phi. If set to FALSE, a regular Gaussian
prior is employed and the draw is immediately discarded when values
outside the unit ball happen to be drawn. Defaults to FALSE.
mhsteps: Either 1, 2, or 3. Indicates
the number of blocks used for drawing from the posterior of the
parameters. Defaults to 2.
proposalvar4sigmaphi: Single positive number indicating the
conditional prior variance of sigma*phi in the ridge
proposal density for sampling (mu, phi).
Defaults to 10^8.
proposalvar4sigmatheta: Single positive number indicating
the conditional prior variance of sigma*theta in the ridge
proposal density for sampling (mu, phi).
Defaults to 10^12.
For details concerning the factor SV algorithm please see Kastner et al. (2017), details about the univariate SV estimation can be found in Kastner and Frühwirth-Schnatter (2014).
Kastner, G., Frühwirth-Schnatter, S., and Lopes, H.F. (2017). Efficient Bayesian Inference for Multivariate Factor Stochastic Volatility Models. Journal of Computational and Graphical Statistics, 26(4), 905--917, tools:::Rd_expr_doi("10.1080/10618600.2017.1322091").
Kastner, G. (2019). Sparse Bayesian Time-Varying Covariance Estimation in Many Dimensions Journal of Econometrics, 210(1), 98--115, tools:::Rd_expr_doi("10.1016/j.jeconom.2018.11.007")
Kastner, G. (2016). Dealing with stochastic volatility in time series using the R package stochvol. Journal of Statistical Software, 69(5), 1--30, tools:::Rd_expr_doi("10.18637/jss.v069.i05").
Kastner, G. and Frühwirth-Schnatter, S. (2014). Ancillarity-Sufficiency Interweaving Strategy (ASIS) for Boosting MCMC Estimation of Stochastic Volatility Models. Computational Statistics & Data Analysis, 76, 408--423, tools:::Rd_expr_doi("10.1016/j.csda.2013.01.002").
# \donttest{
# Load exchange rate data (ships with stochvol):
data(exrates, package = "stochvol")
exrates$date <- NULL
# Compute the percentage log returns:
dat <- 100 * logret(exrates)
# We are going to fit a one-factor model so the ordering is irrelevant
# NOTE that these are very few draws, you probably want more...
res <- fsvsample(dat, factors = 2, draws = 2000, burnin = 1000,
runningstore = 6, zeromean = FALSE)
voltimeplot(res)
corimageplot(res, nrow(dat), plotCI = 'circle')
oldpar <- par(ask = TRUE)
plot(res)
par(oldpar)
pairs(t(res$beta[1:4, ]))
# }
Run the code above in your browser using DataLab