R/RcppExports.R

In gamalamboy/stresstest: Implement the ETI Stress Testing Simulation

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Calculate conditional posterior variance
#'
#' This function computes the scale matrix for the Wishart conditional 
#' posterior in the Independent Normal-Wishart Bayesian VAR Model. 
#' 
#' This function uses the following formula for updating the previous value:
#' 
#' \deqn{\hat{\Sigma} = (V_{0} + \sum_{t=1}^{\tau}(Y - Z\beta)(Y - 
#' Z\beta)^{T} )^{-1}}
#' 
#' Where \eqn{V_{0}} is the prior Scale Matrix, \eqn{Y} is a column vector of
#' dependent variables, and \eqn{Z} are the Seemingly Unrelated Regression 
#' (SUR) representation of the lagged dependent variables and external
#' regressors.
#' 
#' This function \emph{ is not meant to be used directly by the user}. Instead,
#' it is used by function \code{Gibbs} in its recursive estimation.
#' 
#' @param beta the sampled mean for the \eqn{ N( \beta, V_{\beta})} distribution.
#' It is updated for each run of the Gibbs sampler.
#' @param prior_var the prior (\eqn{k \times k}) scale matrix for the model. 
#' @param Y a structure of class \code{Ymat} containing the dependent variable 
#' vector for each year.
#' @param Z a structure of class \code{Zmat} containing the SUR representation
#' of the lagged and exogenous regressors in a VAR.
#' 
#' @return An updated Bayesian estimate of the precision matrix of the Normal-
#' Wishart prior used in the model.
#' 
#' @export
St <- function(beta, prior_var, Y, Z) {
    .Call(`_stresstest_St`, beta, prior_var, Y, Z)
}

#' Update covariance matrix of parameters
#' 
#' This function computes the covariance matrix of the parameters, given
#' a prior parameter precision matrix and an estimate of the prior variance.
#'
#' The model uses the following formula for updating the previous value:
#' 
#' \deqn{ V_\beta = \left( V_{\beta_0}^{-1} + \sum_{t=1}^{\tau} Z_{t}^{T} 
#' \hat{\Sigma}^{-1} Z_{t} \right)^{-1} }
#'
#' Where \eqn{ V_{ \beta_{0} }^{-1}} is the inverse of the prior coefficient
#' variance, \eqn{Z_{t}} is the model matrix at time \eqn{t}, and \eqn{ 
#' \hat{\Sigma}^{-1}} is an estimated precision matrix.
#' 
#' @param prior_vbeta_inv the prior precision matrix (inverse of covariance).
#' @param var_inv an estimated precision matrix for the model (\eqn{\Sigma}).
#' @param Z the model matrix, as per Koop and Korobilis (2012).
#' 
#' @return The covariance matrix of the parameters.
#' 
#' @export
Vbeta <- function(prior_vbeta_inv, var_inv, Z) {
    .Call(`_stresstest_Vbeta`, prior_vbeta_inv, var_inv, Z)
}

#' Bayesian estimate of VAR parameters
#' 
#' This function produces an estimated mean for the VAR parameters, based
#' upon a) prior information, and b) the data matrices Y and Z. It is a
#' weighted mean of the prior and the data estimate, using
#' the precision matrices as weights.
#' 
#' The model uses the following formula to generate the estimate of 
#' \eqn{\beta}:
#'
#' \deqn{ V_{\beta} ( V_{\beta_{0} }^{-1} \beta_{0} + \sum_{t=1}^{\tau} 
#' Z_{t}^{T} \Sigma^{-1} Z_{t} ) }
#' 
#' @param prior_beta the prior parameter means.
#' @param prior_vbeta_inv the prior precision matrix of the parameters.
#' @param vbeta the updated covariance matrix of the parameters
#' @param var_inv the updated precision matrix of the model
#' @param Y a list of the model vectors for the dependent variable.
#' @param Z the list of model matrices for \eqn{t=1,\ldots,\tau}.
#'
#' @return An updated Bayesian estimate of the model parameters.
#' 
#' @export
Beta <- function(prior_beta, prior_vbeta_inv, vbeta, var_inv, Y, Z) {
    .Call(`_stresstest_Beta`, prior_beta, prior_vbeta_inv, vbeta, var_inv, Y, Z)
}

#' Gibbs Sampler
#' 
#' This function implements a basic Gibbs Sampler simulating between \eqn{
#' P( \theta \mid Z,Y,\Sigma) } and \eqn{ P( \Sigma \mid Z, Y, \theta )}.
#' 
#' @param Z the list of model matrices for \eqn{ t=1,\ldots,\tau}.
#' @param Y the list of dependent variable vectors.
#' @param params a three-component list, containing:
#' \enumerate{
#' \item{ \emph{InvPriorVbeta}, the prior precision matrix for the
#' parameters.}
#' \item{ \emph{PriorBeta}, the prior mean for the parameters.}
#' \item{ \emph{InvVar}, the prior precision matrix for the parameters.}
#' }
#' @param iters the number of sampling iterations. It must be remembered that
#' the burn-in period must be accounted for in selecting the number of
#' iterations.
#' 
#' @return An object of class \code{Gibbs}, containing:
#' \enumerate{
#' \item{ the simulated runs for \eqn{\theta}. }
#' \item{ the simulated runs for \eqn{ \Sigma} and \eqn{ \Sigma^{-1}}.}
#' \item{ the simulated covariance matrix of the parameters ( \eqn{ V_{\beta}} 
#' )}
#' }
#' This object is a list, containing three arrays of matrices and a matrix.
#' @export
Gibbs <- function(Z, Y, params, iters) {
    .Call(`_stresstest_Gibbs`, Z, Y, params, iters)
}

#' Create One-Step Forecast of Dependent Variables
#' 
#' This function returns a single value sampled from the posterior predictive
#' distribution of the calculated VAR. This is a \eqn{ N\left( Z_{t} \beta, 
#' \Sigma \right) } distribution, for \eqn{ t=T+1,T+2,\ldots}. This function 
#' is a helper function for the \code{ forecast.Gibbs } method.
#'  
#' @param Zt the model matrix to be used.
#' @param gibbs_mean the mean of the predictive distribution.
#' @param gibbs_var the covariance matrix of the predictive distribution.
#' @export
Ofore <- function(Zt, gibbs_mean, gibbs_var) {
    .Call(`_stresstest_Ofore`, Zt, gibbs_mean, gibbs_var)
}

#' Create forecast design matrices
#' 
#' This performs the workhorse creation of an array with design matrices
#' for use in the forecasting exercises. It creates an RcppArmadillo cube
#' with each slice being a design matrix whose lagged values are updated
#' with the Bayesian posterior predictive distribution's sampled values.
#' 
#' @param datindex a linear index mapping the data columns to the model
#' structure. It is generally a product of \code{sub2inds()}.
#' @param datarows the data rows used for creating the design matrix, of size
#' <lag length of VAR(p)> + 1.
#' @param Zindex a linear index which maps the non-zero entries in the new
#' design matrix.
#' @param Zmat a fixed design matrix template.
#' 
#' @return an array of design matrices.
#' 
#' @export
Zarray <- function(datindex, datarows, Zindex, Zmat) {
    .Call(`_stresstest_Zarray`, datindex, datarows, Zindex, Zmat)
}

#' Return the forecast for one of the given sample points of the posterior
#' 
#' This function creates the forecast path for the given period as a sequence
#' of 1-step forecasts, given a parameter vector \eqn{ \left( \beta_{i}, 
#' \Sigma_{i} \right)}.
#' 
#' \strong{Do not call this function directly}. It is made to be used within
#' \code{ ForecastGibbs() }.
#' 
#' @param dats_withexo this function accepts a \code{matrix} containing 1)
#' the historical data, and 2) the projected forecast space with NA's in all
#' values except for exogenous variables.
#' @param Zmat a template for the design matrix.
#' @param nuyears the number of years to forecast.
#' @param nulags the lag length of the VAR(p).
#' @param gibbs_mean a vector of estimated parameter means \eqn{\beta}.
#' @param gibbs_var an estimated covariance matrix \eqn{\Sigma}.
#' @param ofore_index a linear index mapping the data columns with
#' the variables to be forecasted.
#' @param datindex a linear index mapping the data columns to the model 
#' structure.
#' @param Zindex a linear index mapping the nonzero entries of the design
#' matrix.
#' @return a matrix with the estimated forecasts for each value, of dimension
#' (<number_of_forecasted_years>, <number_of_equations>).
#' @export
OneStep <- function(dats_withexo, Zmat, nuyears, nulags, gibbs_mean, gibbs_var, ofore_index, datindex, Zindex) {
    .Call(`_stresstest_OneStep`, dats_withexo, Zmat, nuyears, nulags, gibbs_mean, gibbs_var, ofore_index, datindex, Zindex)
}

#' Generate a Random Wishart Matrix
#' 
#' This code instantiates a random matrix from the Wishart distribution
#' with degrees of freedom \code{df} and support matrix \code{Sigma}.
#' 
#' @param df an integer, specifying the degrees of freedom.
#' @param Sigma the support matrix.
#' @return an instance of a Random Wishart Matrix.
#' @export
RWishart <- function(df, Sigma) {
    .Call(`_stresstest_RWishart`, df, Sigma)
}

#' Generate Multivariate Normal Vectors
#' 
#' @param n the number of vectors to create.
#' @param mu the mean.
#' @param Sigma the covariance matrix.
#' @export
Mvrnorm <- function(n, mu, Sigma) {
    .Call(`_stresstest_Mvrnorm`, n, mu, Sigma)
}