From ad66aab8c33c0743517aafaa1abafb2fa9a8b658 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Wo=C5=BAniak?= Date: Thu, 18 Jan 2024 15:21:05 +1100 Subject: [PATCH] include estimate method --- NAMESPACE | 9 +++ R/estimate.BSVARSIGN.R | 106 +++++++++++++++++++++++++++++ man/estimate.BSVARSIGN.Rd | 62 +++++++++++++++++ man/estimate.PosteriorBSVARSIGN.Rd | 63 +++++++++++++++++ 4 files changed, 240 insertions(+) create mode 100644 R/estimate.BSVARSIGN.R create mode 100644 man/estimate.BSVARSIGN.Rd create mode 100644 man/estimate.PosteriorBSVARSIGN.Rd diff --git a/NAMESPACE b/NAMESPACE index a9f2505..14f39e0 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,6 +1,15 @@ # Generated by roxygen2: do not edit by hand +S3method(estimate,BSVARSIGN) +S3method(estimate,PosteriorBSVARSIGN) +export(specify_bsvarSIGN) +export(specify_data_matrices) +export(specify_identification_bsvarSIGNs) +export(specify_posterior_bsvarSIGN) +export(specify_prior_bsvarSIGN) +export(specify_starting_values_bsvarSIGN) import(RcppArmadillo) +import(RcppProgress) import(bsvars) importFrom(R6,R6Class) importFrom(Rcpp,sourceCpp) diff --git a/R/estimate.BSVARSIGN.R b/R/estimate.BSVARSIGN.R new file mode 100644 index 0000000..d615372 --- /dev/null +++ b/R/estimate.BSVARSIGN.R @@ -0,0 +1,106 @@ + +#' @title Bayesian estimation of a homoskedastic Structural Vector Autoregression via Gibbs sampler +#' +#' @description Estimates the homoskedastic SVAR using the Gibbs sampler proposed by Waggoner & Zha (2003) +#' for the structural matrix \eqn{B} and the equation-by-equation sampler by Chan, Koop, & Yu (2021) +#' for the autoregressive slope parameters \eqn{A}. Additionally, the parameter matrices \eqn{A} and \eqn{B} +#' follow a Minnesota prior and generalised-normal prior distributions respectively with the matrix-specific +#' overall shrinkage parameters estimated using a hierarchical prior distribution. +#' See section \bold{Details} for the model equations. +#' +#' @details +#' The homoskedastic SVAR model is given by the reduced form equation: +#' \deqn{Y = AX + E} +#' where \eqn{Y} is an \code{NxT} matrix of dependent variables, \eqn{X} is a \code{KxT} matrix of explanatory variables, +#' \eqn{E} is an \code{NxT} matrix of reduced form error terms, and \eqn{A} is an \code{NxK} matrix of autoregressive slope coefficients and parameters on deterministic terms in \eqn{X}. +#' +#' The structural equation is given by +#' \deqn{BE = U} +#' where \eqn{U} is an \code{NxT} matrix of structural form error terms, and +#' \eqn{B} is an \code{NxN} matrix of contemporaneous relationships. +#' +#' Finally, the structural shocks, \code{U}, are temporally and contemporaneously independent and jointly normally distributed with zero mean and unit variances. +#' +#' @param specification an object of class BSVAR generated using the \code{specify_bsvar$new()} function. +#' @param S a positive integer, the number of posterior draws to be generated +#' @param thin a positive integer, specifying the frequency of MCMC output thinning +#' @param show_progress a logical value, if \code{TRUE} the estimation progress bar is visible +#' +#' @return An object of class PosteriorBSVAR containing the Bayesian estimation output and containing two elements: +#' +#' \code{posterior} a list with a collection of \code{S} draws from the posterior distribution generated via Gibbs sampler containing: +#' \describe{ +#' \item{A}{an \code{NxKxS} array with the posterior draws for matrix \eqn{A}} +#' \item{B}{an \code{NxNxS} array with the posterior draws for matrix \eqn{B}} +#' \item{hyper}{a \code{5xS} matrix with the posterior draws for the hyper-parameters of the hierarchical prior distribution} +#' } +#' +#' \code{last_draw} an object of class BSVAR with the last draw of the current MCMC run as the starting value to be passed to the continuation of the MCMC estimation using \code{estimate()}. +#' +#' @author Tomasz Woźniak \email{wozniak.tom@pm.me} +#' +#' @references Sampling from the generalised-normal full conditional posterior distribution of matrix \eqn{B} is implemented using the Gibbs sampler by: +#' +#' Waggoner, D.F., and Zha, T., (2003) A Gibbs sampler for structural vector autoregressions. \emph{Journal of Economic Dynamics and Control}, \bold{28}, 349--366, \doi{https://doi.org/10.1016/S0165-1889(02)00168-9}. +#' +#' Sampling from the multivariate normal full conditional posterior distribution of each of the \eqn{A} matrix row is implemented using the sampler by: +#' +#' Chan, J.C.C., Koop, G, and Yu, X. (2021) Large Order-Invariant Bayesian VARs with Stochastic Volatility. +#' +#' @method estimate BSVARSIGN +#' +#' +#' @export +estimate.BSVARSIGN <- function(specification, S, thin = 10, show_progress = TRUE) { + + # get the inputs to estimation + prior = specification$prior$get_prior() + starting_values = specification$starting_values$get_starting_values() + VB = specification$identification$get_identification() + data_matrices = specification$data_matrices$get_data_matrices() + + # estimation + qqq = .Call(`_bsvarSIGNs_bsvar_sign_cpp`, S, data_matrices$Y, data_matrices$X, VB, prior, starting_values, thin, show_progress) + + specification$starting_values$set_starting_values(qqq$last_draw) + output = specify_posterior_bsvarSIGN$new(specification, qqq$posterior) + + # normalise output + BB = qqq$last_draw$B + BB = diag(sign(diag(BB))) %*% BB + normalise_posterior(output, BB) + + return(output) +} + + +#' @inherit estimate.BSVARSIGN +#' +#' @method estimate PosteriorBSVARSIGN +#' +#' @param specification an object of class PosteriorBSVARSIGN generated using the \code{estimate.BSVARSIGN()} function. +#' This setup facilitates the continuation of the MCMC sampling starting from the last draw of the previous run. +#' + +#' @export +estimate.PosteriorBSVARSIGN <- function(specification, S, thin = 10, show_progress = TRUE) { + + # get the inputs to estimation + prior = specification$last_draw$prior$get_prior() + starting_values = specification$last_draw$starting_values$get_starting_values() + VB = specification$last_draw$identification$get_identification() + data_matrices = specification$last_draw$data_matrices$get_data_matrices() + + # estimation + qqq = .Call(`_bsvarSIGNs_bsvar_sign_cpp`, S, data_matrices$Y, data_matrices$X, VB, prior, starting_values, thin, show_progress) + + specification$last_draw$starting_values$set_starting_values(qqq$last_draw) + output = specify_posterior_bsvarSIGN$new(specification$last_draw, qqq$posterior) + + # normalise output + BB = qqq$last_draw$B + BB = diag(sign(diag(BB))) %*% BB + normalise_posterior(output, BB) + + return(output) +} \ No newline at end of file diff --git a/man/estimate.BSVARSIGN.Rd b/man/estimate.BSVARSIGN.Rd new file mode 100644 index 0000000..9dfda61 --- /dev/null +++ b/man/estimate.BSVARSIGN.Rd @@ -0,0 +1,62 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimate.BSVARSIGN.R +\name{estimate.BSVARSIGN} +\alias{estimate.BSVARSIGN} +\title{Bayesian estimation of a homoskedastic Structural Vector Autoregression via Gibbs sampler} +\usage{ +\method{estimate}{BSVARSIGN}(specification, S, thin = 10, show_progress = TRUE) +} +\arguments{ +\item{specification}{an object of class BSVAR generated using the \code{specify_bsvar$new()} function.} + +\item{S}{a positive integer, the number of posterior draws to be generated} + +\item{thin}{a positive integer, specifying the frequency of MCMC output thinning} + +\item{show_progress}{a logical value, if \code{TRUE} the estimation progress bar is visible} +} +\value{ +An object of class PosteriorBSVAR containing the Bayesian estimation output and containing two elements: + + \code{posterior} a list with a collection of \code{S} draws from the posterior distribution generated via Gibbs sampler containing: + \describe{ + \item{A}{an \code{NxKxS} array with the posterior draws for matrix \eqn{A}} + \item{B}{an \code{NxNxS} array with the posterior draws for matrix \eqn{B}} + \item{hyper}{a \code{5xS} matrix with the posterior draws for the hyper-parameters of the hierarchical prior distribution} +} + +\code{last_draw} an object of class BSVAR with the last draw of the current MCMC run as the starting value to be passed to the continuation of the MCMC estimation using \code{estimate()}. +} +\description{ +Estimates the homoskedastic SVAR using the Gibbs sampler proposed by Waggoner & Zha (2003) +for the structural matrix \eqn{B} and the equation-by-equation sampler by Chan, Koop, & Yu (2021) +for the autoregressive slope parameters \eqn{A}. Additionally, the parameter matrices \eqn{A} and \eqn{B} +follow a Minnesota prior and generalised-normal prior distributions respectively with the matrix-specific +overall shrinkage parameters estimated using a hierarchical prior distribution. +See section \bold{Details} for the model equations. +} +\details{ +The homoskedastic SVAR model is given by the reduced form equation: +\deqn{Y = AX + E} +where \eqn{Y} is an \code{NxT} matrix of dependent variables, \eqn{X} is a \code{KxT} matrix of explanatory variables, +\eqn{E} is an \code{NxT} matrix of reduced form error terms, and \eqn{A} is an \code{NxK} matrix of autoregressive slope coefficients and parameters on deterministic terms in \eqn{X}. + +The structural equation is given by +\deqn{BE = U} +where \eqn{U} is an \code{NxT} matrix of structural form error terms, and +\eqn{B} is an \code{NxN} matrix of contemporaneous relationships. + +Finally, the structural shocks, \code{U}, are temporally and contemporaneously independent and jointly normally distributed with zero mean and unit variances. +} +\references{ +Sampling from the generalised-normal full conditional posterior distribution of matrix \eqn{B} is implemented using the Gibbs sampler by: + +Waggoner, D.F., and Zha, T., (2003) A Gibbs sampler for structural vector autoregressions. \emph{Journal of Economic Dynamics and Control}, \bold{28}, 349--366, \doi{https://doi.org/10.1016/S0165-1889(02)00168-9}. + +Sampling from the multivariate normal full conditional posterior distribution of each of the \eqn{A} matrix row is implemented using the sampler by: + +Chan, J.C.C., Koop, G, and Yu, X. (2021) Large Order-Invariant Bayesian VARs with Stochastic Volatility. +} +\author{ +Tomasz Woźniak \email{wozniak.tom@pm.me} +} diff --git a/man/estimate.PosteriorBSVARSIGN.Rd b/man/estimate.PosteriorBSVARSIGN.Rd new file mode 100644 index 0000000..84b8eba --- /dev/null +++ b/man/estimate.PosteriorBSVARSIGN.Rd @@ -0,0 +1,63 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimate.BSVARSIGN.R +\name{estimate.PosteriorBSVARSIGN} +\alias{estimate.PosteriorBSVARSIGN} +\title{Bayesian estimation of a homoskedastic Structural Vector Autoregression via Gibbs sampler} +\usage{ +\method{estimate}{PosteriorBSVARSIGN}(specification, S, thin = 10, show_progress = TRUE) +} +\arguments{ +\item{specification}{an object of class PosteriorBSVARSIGN generated using the \code{estimate.BSVARSIGN()} function. +This setup facilitates the continuation of the MCMC sampling starting from the last draw of the previous run.} + +\item{S}{a positive integer, the number of posterior draws to be generated} + +\item{thin}{a positive integer, specifying the frequency of MCMC output thinning} + +\item{show_progress}{a logical value, if \code{TRUE} the estimation progress bar is visible} +} +\value{ +An object of class PosteriorBSVAR containing the Bayesian estimation output and containing two elements: + + \code{posterior} a list with a collection of \code{S} draws from the posterior distribution generated via Gibbs sampler containing: + \describe{ + \item{A}{an \code{NxKxS} array with the posterior draws for matrix \eqn{A}} + \item{B}{an \code{NxNxS} array with the posterior draws for matrix \eqn{B}} + \item{hyper}{a \code{5xS} matrix with the posterior draws for the hyper-parameters of the hierarchical prior distribution} +} + +\code{last_draw} an object of class BSVAR with the last draw of the current MCMC run as the starting value to be passed to the continuation of the MCMC estimation using \code{estimate()}. +} +\description{ +Estimates the homoskedastic SVAR using the Gibbs sampler proposed by Waggoner & Zha (2003) +for the structural matrix \eqn{B} and the equation-by-equation sampler by Chan, Koop, & Yu (2021) +for the autoregressive slope parameters \eqn{A}. Additionally, the parameter matrices \eqn{A} and \eqn{B} +follow a Minnesota prior and generalised-normal prior distributions respectively with the matrix-specific +overall shrinkage parameters estimated using a hierarchical prior distribution. +See section \bold{Details} for the model equations. +} +\details{ +The homoskedastic SVAR model is given by the reduced form equation: +\deqn{Y = AX + E} +where \eqn{Y} is an \code{NxT} matrix of dependent variables, \eqn{X} is a \code{KxT} matrix of explanatory variables, +\eqn{E} is an \code{NxT} matrix of reduced form error terms, and \eqn{A} is an \code{NxK} matrix of autoregressive slope coefficients and parameters on deterministic terms in \eqn{X}. + +The structural equation is given by +\deqn{BE = U} +where \eqn{U} is an \code{NxT} matrix of structural form error terms, and +\eqn{B} is an \code{NxN} matrix of contemporaneous relationships. + +Finally, the structural shocks, \code{U}, are temporally and contemporaneously independent and jointly normally distributed with zero mean and unit variances. +} +\references{ +Sampling from the generalised-normal full conditional posterior distribution of matrix \eqn{B} is implemented using the Gibbs sampler by: + +Waggoner, D.F., and Zha, T., (2003) A Gibbs sampler for structural vector autoregressions. \emph{Journal of Economic Dynamics and Control}, \bold{28}, 349--366, \doi{https://doi.org/10.1016/S0165-1889(02)00168-9}. + +Sampling from the multivariate normal full conditional posterior distribution of each of the \eqn{A} matrix row is implemented using the sampler by: + +Chan, J.C.C., Koop, G, and Yu, X. (2021) Large Order-Invariant Bayesian VARs with Stochastic Volatility. +} +\author{ +Tomasz Woźniak \email{wozniak.tom@pm.me} +}