Type: | Package |
Title: | Markov-Switching GARCH Models |
Version: | 2.51 |
Date: | 2022-12-05 |
Maintainer: | Keven Bluteau <Keven.Bluteau@usherbrooke.ca> |
Description: | Fit (by Maximum Likelihood or MCMC/Bayesian), simulate, and forecast various Markov-Switching GARCH models as described in Ardia et al. (2019) <doi:10.18637/jss.v091.i04>. |
License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
BugReports: | https://github.com/keblu/MSGARCH/issues |
URL: | https://github.com/keblu/MSGARCH |
Imports: | Rcpp, coda, methods, zoo, expm, fanplot, MASS, numDeriv |
LinkingTo: | Rcpp, RcppArmadillo |
Suggests: | mcmc, testthat |
RoxygenNote: | 7.1.1 |
NeedsCompilation: | yes |
Encoding: | UTF-8 |
Packaged: | 2022-12-05 16:08:40 UTC; Keven |
Author: | David Ardia |
Repository: | CRAN |
Date/Publication: | 2022-12-05 18:32:30 UTC |
The R package MSGARCH
Description
The R package MSGARCH implements a comprehensive
set of functionalities for Markov-switching GARCH (Haas et al. 2004a) and Mixture of GARCH (Haas et al. 2004b) models,
This includes fitting, filtering, forecasting, and simulating.
Other functions related to Value-at-Risk and Expected-Shortfall are also available.
The main functions of the package are coded
in C++
using Rcpp (Eddelbuettel and Francois, 2011)
and RcppArmadillo (Eddelbuettel and Sanderson, 2014).
MSGARCH focuses on the conditional variance (and higher moments) process.
Hence, there is no equation for the mean.
Therefore, you must pre-filter via AR(1) before applying the model.
The MSGARCH package implements a variety of GARCH specifications together with several conditional distributions.
This allows for a rich modeling
environment for Markov-switching GARCH models. Each single-regime process
is a one-lag process (e.g., GARCH(1,1)).
When optimization is performed, we ensure that the variance in each regime is covariance-stationary
and strictly positive (refer to the vignette for more information).
We refer to Ardia et al. (2019a) for a detailed
introduction to the package and its usage. Refer to Ardia et al. (2018) and Ardia et al. (2019b) for
further applications.
The authors acknowledge Google for financial support via the Google Summer of Code 2016 & 2017,
the International Institute of Forecasters and Industrielle-Alliance.
Note
By using MSGARCH you agree to the following rules:
You must cite Ardia et al. (2019a) in working papers and published papers that use MSGARCH. Use
citation("MSGARCH")
.You must place the following URL in a footnote to help others find MSGARCH: https://CRAN.R-project.org/package=MSGARCH.
You assume all risk for the use of MSGARCH.
Author(s)
Maintainer: Keven Bluteau Keven.Bluteau@usherbrooke.ca (ORCID)
Authors:
David Ardia david.ardia.ch@gmail.com (ORCID)
Leopoldo Catania leopoldo.catania@econ.au.dk (ORCID)
Denis-Alexandre Trottier denis-alexandre.trottier.1@ulaval.ca
Other contributors:
Kris Boudt kris.boudt@ugent.be (ORCID) [contributor]
Alexios Ghalanos alexios@4dscape.com [contributor]
Brian Peterson brian@braverock.com [contributor]
References
Ardia, D. Bluteau, K. Boudt, K. Catania, L. (2018). Forecasting risk with Markov-switching GARCH models: A large-scale performance study. International Journal of Forecasting, 34(4), 733-747. doi: 10.1016/j.ijforecast.2018.05.004
Ardia, D. Bluteau, K. Boudt, K. Catania, L. Trottier, D.-A. (2019a). Markov-switching GARCH models in R: The MSGARCH package. Journal of Statistical Software, 91(4), 1-38. doi: 10.18637/jss.v091.i04
Ardia, D. Bluteau, K. Ruede, M. (2019b). Regime changes in Bitcoin GARCH volatility dynamics. Finance Research Letters, 29, 266-271. doi: 10.1016/j.frl.2018.08.009
Eddelbuettel, D. & Francois, R. (2011).
Rcpp: Seamless R and C++
integration.
Journal of Statistical Software, 40, 1-18.
doi: 10.18637/jss.v040.i08
Eddelbuettel, D. & Sanderson, C. (2014).
RcppArmadillo: Accelerating R with high-performance C++
linear algebra.
Computational Statistics & Data Analysis, 71, 1054-1063.
doi: 10.1016/j.csda.2013.02.005
Haas, M. Mittnik, S. & Paolella, MS. (2004). A new approach to Markov-switching GARCH models. Journal of Financial Econometrics, 2, 493-530. doi: 10.1093/jjfinec/nbh020
Haas, M. Mittnik, S. & Paolella, M. S. (2004b). Mixed normal conditional heteroskedasticity. Journal of Financial Econometrics, 2, 211-250. doi: 10.1093/jjfinec/nbh009
See Also
Useful links:
Model specification.
Description
Creates a model specification before fitting and using the MSGARCH functionalities.
Usage
CreateSpec(
variance.spec = list(model = c("sGARCH", "sGARCH")),
distribution.spec = list(distribution = c("norm", "norm")),
switch.spec = list(do.mix = FALSE, K = NULL),
constraint.spec = list(fixed = list(), regime.const = NULL),
prior = list(mean = list(), sd = list())
)
Arguments
variance.spec |
|
distribution.spec |
|
switch.spec |
|
constraint.spec |
|
prior |
|
Details
The Markov-Switching specification is based on the
Haas et al. (2004a) MSGARCH specification. It is a MSGARCH model that is separated
in K single-regime specifications which are updated in parallel. Under the Haas et al. (2004a)
specification, the conditional variance is a function of past data and the current state.
The Mixture of GARCH option (do.mix = TRUE
) is based on Haas et al. (2004b). A Mixture of GARCH is a mixture of distributions
where the variance process of each distribution is a single-regime process.
For the models, "sARCH"
is the ARCH(1) model (Engle, 1982), "sGARCH"
the GARCH(1,1) model
(Bollerslev, 1986), "eGARCH"
the EGARCH(1,1) model (Nelson, 1991), "gjrGARCH"
the GJR(1,1) model (Glosten et al., 1993), and "tGARCH"
the TGARCH(1,1) model (Zakoian, 1994).
For the distributions, "norm"
is the Normal distribution, "std"
the
Student-t distribution, and "ged"
the GED distribution.
Their skewed version, implemented via the Fernandez and & Steel (1998) transformation,
are "snorm"
, "sstd"
and "sged"
.
Please see Ardia et al. (2019) for more details on the models and distributions.
The user must choose between fixed
or regime.const
in contraint.spec
as both cannot be set at the same time. The list
fixed.pars
will ensure that the chosen fixed parameters will be fixed during optimization according to
the values set by the user.
Thus only the non-fixed parameters are optimized. The vector regime.const
will
ensure that the chosen parameters will be the same across regime during optimization.
The list
mean
and sd
in prior
will adjust the prior mean and
prior standard deviation of the truncated Normal prior for MCMC
estimation via FitMCMC
according to the inputed prior mean and standard deviation.
Those prior means and standard deviations that are not set will take on preset default values (a mean
of zero and a variance of 1,000).
Value
A list of class MSGARCH_SPEC
with the following elements:
-
par0
: Vector (of size d) of default parameters. -
is.mix
: Logical indicating if the specification is a mixture. -
K
: Number of regimes. -
lower
: Vector (of size d) of lower parameters' bounds. -
upper
: Vector (of size d) of upper parameters' bounds. -
n.params
: Vector (of size K) of the total number of parameters by regime including distributions' parameters. -
n.params.vol
: Vector (of size K) of the total number of parameters by regime excluding distributions' parameters. -
label
: Vector (of size d) of parameters' labels. -
name
: Vector (of size K) of model specifications' names. -
func
: List of internally used R functions. -
rcpp.func
: List of internally usedRcpp
functions. -
fixed.pars
: List of user inputed fixed parameters. -
regime.const.pars
: Vector of user imputed parameter set equal across regimes. -
regime.fixed.pars
: Logical indicating if there is any fixed parameteter set by the user. -
regime.const.pars.bool
: Logical indicating if there is any parameteters equal across regime set by the user.
The MSGARCH_SPEC
class has the following methods:
-
simulate
: Simulation. -
Volatility
: In-sample conditional volatility. -
predict
: Forecast of the conditional volatility (and predictive distribution). -
UncVol
: Unconditional volatility. -
PredPdf
: Predictive density (pdf). -
PIT
: Probability Integral Transform. -
Risk
: Value-at-Risk and Expected-Shortfall. -
State
: State probabilities (smoothed, filtered, predictive, Viterbi). -
FitML
: Maximum Likelihood estimation. -
FitMCMC
: Bayesian estimation. -
print
andsummary
: Summary of the created specification.
References
Ardia, D. Bluteau, K. Boudt, K. Catania, L. Trottier, D.-A. (2019). Markov-switching GARCH models in R: The MSGARCH package. Journal of Statistical Software, 91(4), 1-38. doi: 10.18637/jss.v091.i04
Engle, R. (1982). Autoregressive conditional heteroscedasticity with estimates of the variance of United Kingdom inflation Econometrica, 50, 987-1008.
Bollerslev, T. (1986). Generalized autoregressive conditional heteroskedasticity. Journal of Econometrics, 31, 307-327. doi: 10.1016/0304-4076(86)90063-1
Fernandez, C. & Steel, M. F. (1998). On Bayesian modeling of fat tails and skewness. Journal of the American Statistical Association, 93, 359-371. doi: 10.1080/01621459.1998.10474117
Glosten, L. R. Jagannathan, R. & Runkle, D. E. (1993). On the relation between the expected value and the volatility of the nominal excess return on stocks. Journal of Finance, 48, 1779-1801. doi: 10.1111/j.1540-6261.1993.tb05128.x
Haas, M. Mittnik, S. & Paolella, M. S. (2004a). A new approach to Markov-switching GARCH models. Journal of Financial Econometrics, 2, 493-530. doi: 10.1093/jjfinec/nbh020
Haas, M. Mittnik, S. & Paolella, M. S. (2004b). Mixed normal conditional heteroskedasticity. Journal of Financial Econometrics, 2, 211-250. doi: 10.1093/jjfinec/nbh009
Nelson, D. B. (1991). Conditional heteroskedasticity in asset returns: A new approach. Econometrica, 59, 347-370.
Zakoian, J.-M. (1994). Threshold heteroskedastic models. Journal of Economic Dynamics and Control, 18, 931-955. doi: 10.1016/0165-1889(94)90039-6
Examples
# create a Markov-switching specification
# MS-GARCH(1,1)-GJR(1,1)-Student
spec <- CreateSpec(variance.spec = list(model = c("sGARCH","gjrGARCH")),
distribution.spec = list(distribution = c("std","std")),
switch.spec = list(do.mix = FALSE))
print(spec)
# create a 3-regime Markov-switching specification with the help of variable K
# MS(3)-GARCH(1,1)- Student
spec <- CreateSpec(variance.spec = list(model = c("sGARCH")),
distribution.spec = list(distribution = c("std")),
switch.spec = list(do.mix = FALSE, K = 3))
print(spec)
# create a mixture specification
# MIX-GARCH(1,1)-GJR(1,1)-Student
spec <- CreateSpec(variance.spec = list(model = c("sGARCH","gjrGARCH")),
distribution.spec = list(distribution = c("std","std")),
switch.spec = list(do.mix = TRUE))
print(spec)
# setting fixed parameter for the sGARCH beta parameter
# MS-GARCH(1,1)-GJR(1,1)-Student with beta_1 fixed to 0
spec <- CreateSpec(variance.spec = list(model = c("sGARCH","gjrGARCH")),
distribution.spec = list(distribution = c("std","std")),
switch.spec = list(do.mix = FALSE),
constraint.spec = list(fixed = list(beta_1 = 0)))
print(spec)
# setting restriction for the shape parameter of the Student-t across regimes
# MS-GARCH(1,1)-GJR(1,1)-Student with shape parameter constraint across regime
spec <- CreateSpec(variance.spec = list(model = c("sGARCH","gjrGARCH")),
distribution.spec = list(distribution = c("std","std")),
switch.spec = list(do.mix = FALSE),
constraint.spec = list(regime.const = c("nu")))
print(spec)
# setting custom parameter priors for the beta parameters
# MS-GARCH(1,1)-GJR(1,1)-Student with prior modification
spec <- CreateSpec(variance.spec = list(model = c("sGARCH","gjrGARCH")),
distribution.spec = list(distribution = c("std","std")),
switch.spec = list(do.mix = FALSE),
prior = list(mean = list(beta_1 = 0.9, beta_2 = 0.3),
sd = list(beta_1 = 0.05, beta_2 = 0.01)))
print(spec)
Deviance Information Criterion (DIC).
Description
Method which computes the Deviance Information Criterion (DIC) from a fit object of type
MSGARCH_MCMC_FIT
created with FitMCMC
.
Usage
DIC(fit)
## S3 method for class 'MSGARCH_MCMC_FIT'
DIC(fit)
Arguments
fit |
Fit object of type |
Details
Computes the Deviance information criterion of Spiegelhalter et al. (2002).
Value
A list with the following elements:
-
DIC
: Deviance Information Criterion. -
IC
: Bayesian Predictive Information Criterion (IC = 2 * pV + D.bar). -
pV
: Effective number of parameters (pV = var(D)/2). -
D.bar
: Expected value of the deviance over the posterior.
References
Spiegelhalter, David J., et al. (2002). Bayesian measures of model complexity and fit. Journal of the Royal Statistical Society: Series B, 64, 583-639 doi: 10.1111/1467-9868.00353
Examples
# create model specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# fit the model on data by MCMC
set.seed(123)
fit <- FitMCMC(spec = spec, data = SMI, ctr = list(nburn = 500L, nmcmc = 500L))
# compute DIC
DIC(fit)
Single-regime model extractor.
Description
Extracts each regime from a fitted multiple regime specificaton and creates a fitted object for each extracted regime.
Usage
ExtractStateFit(object)
## S3 method for class 'MSGARCH_ML_FIT'
ExtractStateFit(object)
## S3 method for class 'MSGARCH_MCMC_FIT'
ExtractStateFit(object)
Arguments
object |
Fit object of type |
Value
A list of K
elements where each element is a fit object of type MSGARCH_ML_FIT
or
MSGARCH_MCMC_FIT
.
Examples
# create model specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# fit the model on the data with ML estimation
fit <- FitML(spec = spec, data = SMI)
SR.fit <- ExtractStateFit(fit)
print(SR.fit)
MCMC/Bayesian estimation.
Description
Method that performs MCMC/Bayesian estimation of
a MSGARCH_SPEC
object on a set of observations.
Usage
FitMCMC(spec, data, ctr = list())
Arguments
spec |
Model specification of class |
data |
Vector (of size T) of observations. |
ctr |
A list of control parameters:
|
Details
The total number of draws is equal to nmcmc / nthin
.
The MCMC/Bayesian estimation relies on an Rcpp implementation of the adaptive sampler of Vihola (2012).
The implementation is based on the R package adaptMCMC (Andreas, 2012).
Starting values when par0
is not provided are chosen automatically
before sampling (see Ardia et al. (2019) for more details).
SamplerFUN
allows for a custom sampler to be used. The function
must take the form:
function(f_posterior, data, spec, par0, ctr)
,
where f_posterior
is the function to optimize, data
is
the data, spec
is the specification,
par0
are the starting parameters, and ctr
are the control
parameters. The inputs spec
and data
,
must be passed as inputs in the sampler (see *Examples*).
The custom sampler must output a matrix containing the MCMC chain.
When do.sort = TRUE
, sorting of each MCMC draw conditional on the unconditional variance is done across homogeneous regime specification.
Value
A list of class MSGARCH_MCMC_FIT
with the following elements:
-
par
: The MCMC chain (matrix from the R packagecoda
(Plummer et al., 2006) of sizenmcmc
/nthin
x d). -
accept
: Acceptance rate of the sampler. -
spec
: Model specification of classMSGARCH_SPEC
created withCreateSpec
. -
data
: Vector (of size T) of observations. -
ctr
:list
of the control used for the fit.
The MSGARCH_MCMC_FIT
with the following methods:
-
DIC
: Deviance Information Criterion (DIC). -
simulate
: Simulation. -
Volatility
: In-sample conditional volatility. -
predict
: Forecast of the conditional volatility (and predictive distribution). -
UncVol
: Unconditional volatility. -
PredPdf
: Predictive density (pdf). -
PIT
: Probability Integral Transform. -
Risk
: Value-at-Risk and Expected-Shortfall. -
State
: State probabilities (smoothed, filtered, predictive, Viterbi). -
ExtractStateFit
: Single-regime model extractor. -
summary
: Summary of the fit.
References
Andreas, S. (2012).
adaptMCMC
: Implementation of a generic adaptive Monte Carlo Markov chain sampler.
https://cran.r-project.org/package=adaptMCMC
Ardia, D. Bluteau, K. Boudt, K. Catania, L. Trottier, D.-A. (2019). Markov-switching GARCH models in R: The MSGARCH package. Journal of Statistical Software, 91(4), 1-38. doi: 10.18637/jss.v091.i04
Geweke J (2007). Interpretation and Inference in Mixture Models: Simple MCMC Works. Computational Statistics & Data Analysis, 51(7), 3529-3550. doi: 10.1016/j.csda.2006.11.026
MacDonald, I.L., Zucchini, W. (1997). Hidden Markov and other models for discrete-valued time series. CRC press.
Plummer, M. Best, N. Cowles, K. & Vines, K. (2006).
coda
: Convergence diagnosis and output analysis for MCMC.
R News, 6, 7-11.
https://cran.r-project.org/package=coda
Vihola, M. (2012). Robust adaptive Metropolis algorithm with coerced acceptance rate. Statistics and Computing, 22, 997-1008. doi: 10.1007/s11222-011-9269-5
Examples
# create model specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# fit the model on the data by MCMC
set.seed(123)
fit <- FitMCMC(spec = spec, data = SMI, ctr = list(nburn = 500L, nmcmc = 500L, nthin = 1L))
summary(fit)
# custom sampler example
## Not run:
library("mcmc")
f_MCMC <- function(f_posterior, data, spec, par0, ctr){
par <- mcmc::metrop(f_posterior, initial = par0, nbatch = ctr$nmcmc + ctr$nburn,
data = data, spec = spec)$batch
colnames(par) = names(par0)
return(par)
}
set.seed(123)
fit <- FitMCMC(spec, data = SMI, ctr = list(SamplerFUN = f_MCMC,
nburn = 500L, nmcmc = 500L, nthin = 1L))
summary(fit)
## End(Not run)
Maximum Likelihood estimation.
Description
Method that performs Maximum Likelihood estimation
of a MSGARCH_SPEC
object on a set of observations.
Usage
FitML(spec, data, ctr = list())
Arguments
spec |
Model specification created with |
data |
Vector (of size T) of observations. |
ctr |
A list of control parameters:
|
Details
By default, OptimFUN
is set such that optimization is done via the well-known Broyden-
Fletcher-Goldfarb-Shanno (BFGS) algorithm using the optim
function with method =
"BFGS"
.
Starting values when par0
is not provided are chosen automatically
before optimization (see Ardia et al. (2019) for more details)
OptimFUN
allows for a custom optimizer to be used. The function must take
the form:
function(vPw, f_nll, spec, data, do.plm)
,
where vPw
are starting parameters (transformed), f_nll
is the function
to be minimize, spec
is the specification, data
is the data,
and do.plm
the originally inputed or default do.plm
.
The inputs spec
, data
, and do.plm
must be passed as inputs in the optimizer (see *Examples*).
It must output a list with the following elements:
-
value
: Optimal negative log-likelihood. -
par
: Optimal parameters.
Value
A list of class MSGARCH_ML_FIT
with the following elements:
-
par
: Vector (of size d) of optimal parameters. -
loglik
: Log-likelihood ofy
given the optimal parameters. -
Inference
:list
with elementsMatCoef
andHessian
.MatCoef
is a matrix (of size d x 4) with optimal parameter estimates, standard errors, t-stats, and p-values.Hessian
is the Hessian (matrix of size d x d) of the negative log-likelihood function evaluated at the optimal parameter estimatespar
. -
spec
: Model specification of classMSGARCH_SPEC
created withCreateSpec
. -
data
: Vector (of size T) of observations. -
ctr
:list
of the control used for the fit.
The MSGARCH_ML_FIT
with the following methods:
-
AIC
: Akaike Information Criterion (AIC). -
BIC
: Bayesian Information Criterion (BIC). -
simulate
: Simulation. -
Volatility
: In-sample conditional volatility. -
predict
: Forecast of the conditional volatility (and predictive distribution). -
UncVol
: Unconditional volatility. -
PredPdf
: Predictive density (pdf). -
PIT
: Probability Integral Transform. -
Risk
: Value-at-Risk and Expected-Shortfall. -
State
: State probabilities (smoothed, filtered, predictive, Viterbi). -
ExtractStateFit
: Single-regime model extractor. -
summary
: Summary of the fit.
References
Ardia, D. Bluteau, K. Boudt, K. Catania, L. Trottier, D.-A. (2019). Markov-switching GARCH models in R: The MSGARCH package. Journal of Statistical Software, 91(4), 1-38. doi: 10.18637/jss.v091.i04
Examples
# create model specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# fit the model on the data by ML
fit <- FitML(spec = spec, data = SMI)
summary(fit)
# custom optimizer example
## Not run:
f_custom_optim <- function(vPw, f_nll, spec, data, do.plm){
out <- stats::optim(vPw, f_nll, spec = spec, data = data,
do.plm = do.plm, method = "Nelder-Mead")
return(out)
}
set.seed(123)
fit <- FitML(spec, data = SMI, ctr = list(OptimFUN = f_custom_optim))
summary(fit)
## End(Not run)
Probability integral transform.
Description
Method returning the probability integral transform (PIT).
Usage
PIT(object, ...)
## S3 method for class 'MSGARCH_SPEC'
PIT(
object,
x = NULL,
par = NULL,
data = NULL,
do.norm = FALSE,
do.its = FALSE,
nahead = 1L,
do.cumulative = FALSE,
ctr = list(),
...
)
## S3 method for class 'MSGARCH_ML_FIT'
PIT(
object,
x = NULL,
newdata = NULL,
do.norm = TRUE,
do.its = FALSE,
nahead = 1L,
do.cumulative = FALSE,
ctr = list(),
...
)
## S3 method for class 'MSGARCH_MCMC_FIT'
PIT(
object,
x = NULL,
newdata = NULL,
do.norm = TRUE,
do.its = FALSE,
nahead = 1L,
do.cumulative = FALSE,
ctr = list(),
...
)
Arguments
object |
Model specification of class |
... |
Not used. Other arguments to |
x |
Vector (of size n). Used when |
par |
Vector (of size d) or matrix (of size |
data |
Vector (of size T) of observations. |
do.norm |
Logical indicating if the PIT values are transformed
into standard Normal variate. (Default: |
do.its |
Logical indicating if the in-sample PIT is returned. (Default: |
nahead |
Scalar indicating the number of step-ahead evaluation.
Valid only when |
do.cumulative |
Logical indicating if the PIT is computed on the cumulative simulations (typically log-returns, as they can be aggregated).
Only available for |
ctr |
A list of control parameters:
|
newdata |
Vector (of size T*) of new observations. (Default: |
Details
If a matrix of MCMC posterior draws is given, the
Bayesian probability integral transform is calculated.
Two or more step-ahead probability integral
transform are estimated via simulation of nsim
paths up to t = T + T* + nahead
.
The empirical probability integral transforms is then inferred from these simulations.
If do.its = FALSE
, the vector x
are evaluated as t = T + T* + 1, ... ,t = T + T* + nahead
realizations.
If do.its = TRUE
, x
is evaluated
at each time t
up to time t = T + T*
.
Finally if x = NULL
the vector data
is evaluated for sample evaluation of the PIT.
The do.norm
argument transforms the PIT value into Normal variates so that normality test can be done.
Value
A vector or matrix of class MSGARCH_PIT
.
If do.its = FALSE
: Probability integral transform of the
points x
at
t = T + T* + 1, ... ,t = T + T* + nahead
or Normal variate derived from the probability
integral transform of x
(matrix of size nahead
x n).
If do.its = TRUE
: In-sample probability integral transform or Normal variate
derived from the probability integral transform of data
if x = NULL
(vector of
size T + T*) or in-sample probability integral transform or Normal variate
derived from the probability integral transform of x
(matrix of size (T + T*) x n).
Examples
# create model specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# fit the model on the data by ML
fit <- FitML(spec = spec, data = SMI)
# run PIT method in-sample
pit.its <- PIT(object = fit, do.norm = TRUE, do.its = TRUE)
# diagnostic of PIT with qqnorm
qqnorm(pit.its)
qqline(pit.its)
# simulate a serie from the model
set.seed(123)
sim.series <- simulate(object = spec, par = fit$par, nahead= 1000L, nsim = 1L)
sim.series <- as.vector(sim.series$draw)
# run PIT method on the simualed serie with the true par
pit.x <- PIT(object = spec, par = fit$par, data = sim.series, do.norm = TRUE, do.its = TRUE)
qqnorm(pit.x)
qqline(pit.x)
Predictive density.
Description
Method returning the predictive density (pdf).
Usage
PredPdf(object, ...)
## S3 method for class 'MSGARCH_SPEC'
PredPdf(
object,
x = NULL,
par = NULL,
data = NULL,
log = FALSE,
do.its = FALSE,
nahead = 1L,
do.cumulative = FALSE,
ctr = list(),
...
)
## S3 method for class 'MSGARCH_ML_FIT'
PredPdf(
object,
x = NULL,
newdata = NULL,
log = FALSE,
do.its = FALSE,
nahead = 1L,
do.cumulative = FALSE,
ctr = list(),
...
)
## S3 method for class 'MSGARCH_MCMC_FIT'
PredPdf(
object,
x = NULL,
newdata = NULL,
log = FALSE,
do.its = FALSE,
nahead = 1L,
do.cumulative = FALSE,
ctr = list(),
...
)
Arguments
object |
Model specification of class |
... |
Not used. Other arguments to |
x |
Vector (of size n). Used when |
par |
Vector (of size d) or matrix (of size |
data |
Vector (of size T) of observations. |
log |
Logical indicating if the log-density is returned. (Default: |
do.its |
Logical indicating if the in-sample predictive is returned. (Default: |
nahead |
Scalar indicating the number of step-ahead evaluation.
Valid only when |
do.cumulative |
Logical indicating if predictive density is computed on the
cumulative simulations (typically log-returns, as they can be aggregated).
Only available for |
ctr |
A list of control parameters:
|
newdata |
Vector (of size T*) of new observations. (Default |
Details
If a matrix of MCMC posterior draws is given, the Bayesian
predictive probability density is calculated.
Two or more step-ahead predictive probability density are estimated via simulation of nsim
paths up to
t = T + T* + nahead
. The predictive distribution are then inferred from these
simulations via a Gaussian Kernel density.
If do.its = FALSE
, the vector x
are evaluated as t = T + T* + 1, ... ,t = T + T* + nahead
realization.
If do.its = TRUE
and x
is evaluated
at each time t
up top time t = T + T*
.
Finally, if x = NULL
the vector data
is evaluated for sample
evaluation of the predictive denisty ((log-)likelihood of each sample points).
Value
A vector or matrix of class MSGARCH_PRED
.
If do.its = FALSE
: (Log-)predictive of
the points x
at t = T + T* + 1, ... ,t = T + T* + nahead
(matrix of
size nahead
x n).
If do.its = TRUE
: In-sample predictive of data
if x = NULL
(vector of size T + T*) or in-sample predictive of x
(matrix of size (T + T*) x n).
Examples
# create model specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# fit the model on the data by ML
fit <- FitML(spec = spec, data = SMI)
# run PredPdf method in-sample
pred.its <- PredPdf(object = fit, log = TRUE, do.its = TRUE)
# create a mesh
x <- seq(-3,3,0.01)
# run PredPdf method on mesh at T + 1
pred.x <- PredPdf(object = fit, x = x, log = TRUE, do.its = FALSE)
Value-at-Risk and Expected-shortfall.
Description
Method returning the Value-at-Risk and Expected-shortfall risk measures.
Usage
Risk(object, ...)
## S3 method for class 'MSGARCH_SPEC'
Risk(
object,
par,
data,
alpha = c(0.01, 0.05),
nahead = 1L,
do.es = TRUE,
do.its = FALSE,
do.cumulative = FALSE,
ctr = list(),
...
)
## S3 method for class 'MSGARCH_ML_FIT'
Risk(
object,
newdata = NULL,
alpha = c(0.01, 0.05),
do.es = TRUE,
do.its = FALSE,
nahead = 1L,
do.cumulative = FALSE,
ctr = list(),
...
)
## S3 method for class 'MSGARCH_MCMC_FIT'
Risk(
object,
newdata = NULL,
alpha = c(0.01, 0.05),
do.es = TRUE,
do.its = FALSE,
nahead = 1L,
do.cumulative = FALSE,
ctr = list(),
...
)
Arguments
object |
Model specification of class |
... |
Not used. Other arguments to |
par |
Vector (of size d) or matrix (of size |
data |
Vector (of size T) of observations. |
alpha |
Vector (of size R) of Value-at-risk and Expected-shortfall levels. |
nahead |
Scalar indicating the number of step-ahead evaluation. (Default: |
do.es |
Logical indicating if Expected-shortfall is also calculated.
(Default: |
do.its |
Logical indicating if the in-sample risk estimators are returned.
(Default: |
do.cumulative |
Logical indicating if the risk measures are computed on the
cumulative simulations (typically log-returns, as they can be aggregated).
Only available for |
ctr |
A list of control parameters:
|
newdata |
Vector (of size T*) of new observations. (Default |
Details
If a matrix of MCMC posterior draws is given, the
Bayesian Value-at-Risk and Expected-shortfall are calculated.
Two or more step ahead risk measures are estimated via simulation of nsim
paths up to
t = T + T* + nahead
.
If do.its = FALSE
, the risk estimators at t = T + T* + 1, ... ,t = T + T* + nahead
are computed. do.cumulative = TRUE
indicate the function to compute the risk meausre
over aggregated period up to nahead
period using the cumsum
function on the simulated data.
Value
A list of class MSGARCH_RISK
with the following elements:
-
VaR
:
Ifdo.its = FALSE
: Value-at-Risk att = T + T* + 1, ... ,t = T + T* + nahead
at the chosen levels (matrix of sizenahead
x R).
Ifdo.its = TRUE
: In-sample Value-at-Risk at the chosen levels (Matrix of size (T + T*) x R). -
ES
:
Ifdo.its = FALSE
: Expected-shortfall att = T + T* + 1, ... ,t = T + T* + nahead
at the chosen levels (matrix of sizenahead
x R).
Ifdo.its = TRUE
: In-sample Expected-shortfall at the chosen levels (Matrix of size (T + T*) x R).
The MSGARCH_RISK
contains the plot
method.
Note that the MCMC/Bayesian risk estimator can take long time to calculate
depending on the size of the MCMC chain.
Examples
# create specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# risk from specification
par <- c(0.1, 0.1, 0.8, 0.2, 0.1, 0.8, 0.99, 0.01)
set.seed(1234)
risk <- Risk(object = spec, par = par, data = SMI, nahead = 5L)
head(risk)
plot(risk)
# risk from ML fit
fit <- FitML(spec = spec, data = SMI)
set.seed(1234)
risk <- Risk(object = fit, nahead = 5L)
head(risk)
plot(risk)
## Not run:
# risk from MCMC fit
set.seed(1234)
fit <- FitMCMC(spec = spec, data = SMI)
risk <- Risk(object = fit, nahead = 5L)
head(risk)
plot(risk)
## End(Not run)
Swiss market index dataset
Description
See Mullen et al. (2011) for a description of this dataset.
Usage
data("SMI")
Format
zoo
object containing 2,500 observations ranging from 1990-11-12 to 2000-10-20.
Source
DEoptim
package
References
Mullen, K.M, Ardia, D., Gil, D., Windover, D., Cline, J. (2011).
DEoptim
: An R Package for Global Optimization by Differential Evolution.
Journal of Statistical Software, 40(6), 1-26.
doi: 10.18637/jss.v040.i06
State probabilities.
Description
Method returning the filtered, predictive, and smoothed probabilities of the states, and the most probable path computed with the Viterbi algorithm.
Usage
State(object, ...)
## S3 method for class 'MSGARCH_SPEC'
State(object, par, data, ...)
## S3 method for class 'MSGARCH_ML_FIT'
State(object, newdata = NULL, ...)
## S3 method for class 'MSGARCH_MCMC_FIT'
State(object, newdata = NULL, ...)
Arguments
object |
Model specification of class |
... |
Not used. Other arguments to |
par |
Vector (of size d) or matrix (of size |
data |
Vector (of size T) of observations. |
newdata |
Vector (of size T*) of new observations. (Default |
Details
If a matrix of parameter estimates is given, each parameter estimate (each row) is evaluated individually.
Value
A list of class MSGARCH_PSTATE
with the following elements:
-
FiltProb
: Filtered probabilities (array of size (T + T*) x (nmcmc or 1
) x K). -
PredProb
: Predictive probabilities (array of size (T + T* + 1) x (nmcmc or 1
) x K). -
SmoothProb
: Smoothed probabilities (array of size (T + T* + 1) x (nmcmc or 1
) x K). -
Viterbi
: Most likely path (matrix of size (T + T*) x (nmcmc
or 1)).
The class MSGARCH_PSTATE
contains the plot
method. The plot method contains
as input type.prob
which is one of "filtered", "predictive", "smoothed", "viterbi"
.
(Default: type.prob = "smoothed"
)
Examples
# create specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# state from specification
par <- c(0.1, 0.1, 0.8, 0.2, 0.1, 0.8, 0.99, 0.01)
state <- State(object = spec, par = par, data = SMI)
plot(state, type.prob = "filtered")
# state from ML fit
fit <- FitML(spec = spec, data = SMI)
state <- State(object = fit)
plot(state, type.prob = "smoothed")
## Not run:
# state from MCMC fit
set.seed(1234)
fit <- FitMCMC(spec = spec, data = SMI)
state <- State(object = fit)
plot(state, type.prob = "smoothed")
## End(Not run)
Transition matrix.
Description
Method returning the transition matrix.
Usage
TransMat(object, ...)
## S3 method for class 'MSGARCH_SPEC'
TransMat(object, par = NULL, nahead = 1L, ...)
## S3 method for class 'MSGARCH_ML_FIT'
TransMat(object, nahead = 1L, ...)
Arguments
object |
Model specification of class |
... |
Not used. Other arguments to |
par |
Vector (of size d) of parameter estimates (not required when using a fit object) where d must have the same length as the default parameters of the specification. |
nahead |
Number of steps ahead. (Default: |
Value
A matrix (of size K x K) in the case of a Markov-Switching model or a vector (of size K) in the case of a Mixture of GARCH model. The row indicates the starting states while the columns indicates the transition states.
Examples
# create model specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# fit the model on the data by ML
fit <- FitML(spec = spec, data = SMI)
# Extract the transition matrix 10 steps ahead
trans.mat <- TransMat(fit, nahead = 10)
print(trans.mat)
Unconditional volatility.
Description
Method returning the unconditional volatility of the process.
Usage
UncVol(object, ...)
## S3 method for class 'MSGARCH_SPEC'
UncVol(object, par = NULL, ctr = list(), ...)
## S3 method for class 'MSGARCH_ML_FIT'
UncVol(object, ctr = list(), ...)
## S3 method for class 'MSGARCH_MCMC_FIT'
UncVol(object, ctr = list(), ...)
Arguments
object |
Model specification of class |
... |
Not used. Other arguments to |
par |
Vector (of size d) or matrix (of size |
ctr |
A list of control parameters:
|
Details
If a matrix of MCMC posterior draws is given, the
Bayesian unconditional volatility is calculated.
The unconditional volatility is estimated by first simulating nsim
paths up to nburn + nahead
,
calculating a forecast of the conditional volatility at each step ahead,
discarding the first nburn
step ahead conditional volatilities forecasts,
and computing the mean of the remaining nahead - nburn
conditional
volatilites forecasts. This method is based on the fact that
the conditional volatility forecast will converge to the unconditional volatilty
the further the forecast his from the starting point.
We take the average as a way to remove the noise that comes with the simulation process.
Overall, this method allows to compute the unconditional volatilty complex models.
Value
A scalar
of unconditional volatility.
Examples
# create specification
spec <- CreateSpec()
## Not run:
# unconditional volatility from specification
par <- c(0.1, 0.1, 0.8, 0.2, 0.1, 0.8, 0.99, 0.01)
UncVol(object = spec, par = par)
# load data
data("SMI", package = "MSGARCH")
# unconditional volatility from ML fit
fit <- FitML(spec = spec, data = SMI)
UncVol(object = fit)
var(SMI)
# unconditional volatility from MCMC fit
set.seed(1234)
fit <- FitMCMC(spec = spec, data = SMI)
UncVol(object = fit)
## End(Not run)
Volatility filtering.
Description
Method returning the in-sample conditional volatility.
Usage
Volatility(object, ...)
## S3 method for class 'MSGARCH_SPEC'
Volatility(object, par, data, ...)
## S3 method for class 'MSGARCH_ML_FIT'
Volatility(object, newdata = NULL, ...)
## S3 method for class 'MSGARCH_MCMC_FIT'
Volatility(object, newdata = NULL, ...)
Arguments
object |
Model specification of class |
... |
Not used. Other arguments to |
par |
Vector (of size d) or matrix (of size |
data |
Vector (of size T) of observations. |
newdata |
Vector (of size T*) of new observations. (Default |
Details
If a matrix of MCMC posterior draws is given, the Bayesian predictive conditional volatility is calculated.
Value
In-sample condititional volatility (vector of size T + T*) of class MSGARCH_CONDVOL
.
The MSGARCH_CONDVOL
class contains the plot
method.
Examples
# create specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# in-sample volatility from specification
par <- c(0.1, 0.1, 0.8, 0.2, 0.1, 0.8, 0.99, 0.01)
vol <- Volatility(object = spec, par = par, data = SMI)
head(vol)
plot(vol)
# in-sample volatility from ML fit
fit <- FitML(spec = spec, data = SMI)
vol <- Volatility(object = fit)
head(vol)
plot(vol)
## Not run:
# in-sample volatility from MCMC fit
set.seed(1234)
fit <- FitMCMC(spec = spec, data = SMI)
vol <- Volatility(object = fit)
head(vol)
plot(vol)
## End(Not run)
DEM/GBP exchange rate log-returns
Description
The vector
dem2gbp
contains daily observations of the Deutschmark vs British Pound foreign exchange
rate log-returns. This dataset has been promoted as an informal benchmark for GARCH
time-series software validation. See McCullough and Renfro (1999), and Brooks, Burke, and Persand
(2001) for details. The nominal returns are expressed in percent as in Bollerslev and Ghysels
(1996). The sample period is from January 3, 1984, to December 31, 1991, for a total of 1974
observations.
Usage
data("dem2gbp")
Format
vector
of size 1,974.
References
Bollerslev T., Ghysels, E. (1996) Periodic autoregressive conditional heteroscedasticity. Journal of Business and Economic Statistics, 14, 139-151.
Brooks C., Burke S. P., Persand G. (2001) International Journal of Forecasting, 17, 45-57. doi: 10.1016/S0169-2070(00)00070-4
McCullough B. D., Renfro C. G. (1999) Benchmarks and software standards: A case study of GARCH procedures. Journal of Economic and Social Measurement, 25, 59-71. doi: 10.3233/JEM-1999-0160
predict method.
Description
Conditional volatility (and predictive distribution) forecasts.
Usage
## S3 method for class 'MSGARCH_SPEC'
predict(
object,
newdata = NULL,
nahead = 1L,
do.return.draw = FALSE,
par = NULL,
do.cumulative = FALSE,
ctr = list(),
...
)
## S3 method for class 'MSGARCH_ML_FIT'
predict(
object,
newdata = NULL,
nahead = 1L,
do.return.draw = FALSE,
do.cumulative = FALSE,
ctr = list(),
...
)
## S3 method for class 'MSGARCH_MCMC_FIT'
predict(
object,
newdata = NULL,
nahead = 1L,
do.return.draw = FALSE,
do.cumulative = FALSE,
ctr = list(),
...
)
Arguments
object |
Model specification of class |
newdata |
Vector (of size T*) of new observations. (Default |
nahead |
Scalar indicating the number of step-ahead evaluation. |
do.return.draw |
Are simulation draws from the predictive distribution
returned? (Default |
par |
Vector (of size d) or matrix (of size |
do.cumulative |
Logical indicating if the conditional volatility
prediction is computed on the cumulative simulations (typically log-returns, as they can be aggregated).
(Default: |
ctr |
A list of control parameters:
|
... |
Not used. Other arguments to |
Details
If a matrix of MCMC posterior draws is given, the Bayesian predictive conditional volatility (and predictive distribution) forecasts are returned.
Value
A list of class MSGARCH_FORECAST
with the following elements:
-
vol
: Condititional volatility forecast (vector of sizenahead
). -
draw
: Ifdo.return.draw = TRUE
:
Draws sampled from the predictive distributions (matrix of sizenahead
xnsim
).
Ifdo.return.draw = FALSE
:
NULL
The MSGARCH_FORECAST
class contains the plot
method.
Examples
# create specification
spec <- CreateSpec()
# load data
data("SMI", package = "MSGARCH")
# predict from specification
par <- c(0.1, 0.1, 0.8, 0.2, 0.1, 0.8, 0.99, 0.01)
set.seed(1234)
pred <- predict(object = spec, par = par, newdata = SMI, nahead = 5L)
head(pred)
plot(pred)
# predict from ML fit
fit <- FitML(spec = spec, data = SMI)
set.seed(1234)
pred <- predict(object = fit, nahead = 5L, do.return.draw = TRUE)
head(pred)
plot(pred)
## Not run:
set.seed(1234)
fit <- FitMCMC(spec = spec, data = SMI)
pred <- predict(object = fit, nahead = 5L, do.return.draw = TRUE)
plot(pred)
## End(Not run)
Simulation of MSGARCH processes.
Description
Method for simulating MSGARCH
processes.
Usage
## S3 method for class 'MSGARCH_SPEC'
simulate(
object,
nsim = 1L,
seed = NULL,
nahead = 1L,
par = NULL,
nburn = 500L,
...
)
## S3 method for class 'MSGARCH_ML_FIT'
simulate(object, nsim = 1L, seed = NULL, nahead = 1L, nburn = 500L, ...)
## S3 method for class 'MSGARCH_MCMC_FIT'
simulate(object, nsim = 1L, seed = NULL, nahead = 1L, nburn = 500L, ...)
Arguments
object |
Model specification of class |
nsim |
Number of simulations. (Default: |
seed |
Integer indicating if and how the random number generator should be initialized.
If |
nahead |
Simulation length. (Default: |
par |
Vector (of size d) or matrix (of size |
nburn |
Burnin period discarded (first simulation draws). |
... |
Not used. Other arguments to |
Details
If a matrix of parameters estimates is provided, nsim
simuations will be done for each row.
Value
A list of class MSGARCH_SIM
with the following elements:.
-
draw
: Matrix (of sizenahead
xnsim
) of simulated draws. -
state
: Matrix (of sizenahead
xnsim
) of simulated states. -
CondVol
: Array (of sizenahead
xnsim
x K) of simulated conditional volatilities.
The MSGARCH_SIM
class contains the plot
method.
Examples
# create specification
spec <- CreateSpec()
# simulation from specification
par <- c(0.1, 0.1, 0.8, 0.2, 0.1, 0.8, 0.99, 0.01)
set.seed(1234)
sim <- simulate(object = spec, nsim = 1L, nahead = 1000L,
nburn = 500L, par = par)
head(sim)
plot(sim)
# load data
data("SMI", package = "MSGARCH")
# simulation from ML fit
fit <- FitML(spec = spec, data = SMI)
set.seed(1234)
sim <- simulate(object = fit, nsim = 1L, nahead = 1000L,
nburn = 500L)
head(sim)
plot(sim)
## Not run:
# simulation from MCMC fit
fit <- FitMCMC(spec = spec, data = SMI)
set.seed(1234)
sim <- simulate(object = fit, nahead = 100L, nburn = 500L)
head(sim)
plot(sim)
## End(Not run)