|
| 1 | + |
| 2 | +#' @title Bayesian estimation of a Bayesian Hierarchical Panel Vector |
| 3 | +#' Autoregression with fixed or estimated country grouping |
| 4 | +#' |
| 5 | +#' @description Estimates the Bayesian Hierarchical Panel VAR |
| 6 | +#' with fixed or estimated country grouping using the Gibbs |
| 7 | +#' sampler proposed by Sanchez-Martinez & Woźniak (2024). |
| 8 | +#' |
| 9 | +#' @details |
| 10 | +#' The Bayesian Hierarchical Panel Vector Autoregressive model with fixed or |
| 11 | +#' estimated country grouping is estimated using the Gibbs sampler. In this |
| 12 | +#' estimation procedure all the parameters of the model are estimated jointly. |
| 13 | +#' The list of parameters of the model includes: |
| 14 | +#' \describe{ |
| 15 | +#' \item{\eqn{\mathbf{A}_c}}{a \code{KxN} country-specific autoregressive |
| 16 | +#' parameters matrix for each of the countries \eqn{c = 1,\dots,C}} |
| 17 | +#' \item{\eqn{\mathbf{\Sigma}_c}}{an \code{NxN} country-specific covariance |
| 18 | +#' matrix for each of the countries \eqn{c = 1,\dots,C}} |
| 19 | +#' \item{\eqn{\mathbf{A}}}{a \code{KxN} global autoregressive parameters matrix} |
| 20 | +#' \item{\eqn{\mathbf{\Sigma}}}{an \code{NxN} global covariance matrix} |
| 21 | +#' \item{\eqn{\mathbf{V}}}{a \code{KxK} covariance matrix of prior for global autoregressive parameters} |
| 22 | +#' \item{\eqn{\nu}}{prior degrees of freedom parameter} |
| 23 | +#' \item{\eqn{m}}{prior average global persistence parameter} |
| 24 | +#' \item{\eqn{w}}{prior scaling parameter} |
| 25 | +#' \item{\eqn{s}}{prior scaling parameter} |
| 26 | +#' } |
| 27 | +#' Parameters \eqn{\mathbf{A}_c} and \eqn{\mathbf{\Sigma}_c} are subject to |
| 28 | +#' country grouping which sets them to the group-specific values. |
| 29 | +#' |
| 30 | +#' \strong{Gibbs sampler} |
| 31 | +#' is an algorithm to sample random draws from the posterior distribution of the |
| 32 | +#' parameters of the model given the data. The algorithm is briefly explained |
| 33 | +#' on an example of a two-parameter model with parameters \eqn{\theta_1} and |
| 34 | +#' \eqn{\theta_2}. In order to sample from the joint posterior distribution |
| 35 | +#' \eqn{p(\theta_1,\theta_2|\mathbf{Y})} the Gibbs sampler proceeds by sampling |
| 36 | +#' from full-conditional posterior distributions of each parameter given data |
| 37 | +#' and all the other parameters, denoted by \eqn{p(\theta_1|\theta_2,\mathbf{Y})} |
| 38 | +#' and \eqn{p(\theta_2|\theta_1,\mathbf{Y})}. These distributions are available |
| 39 | +#' from derivations and should be in a form of distributions that are easy to |
| 40 | +#' sample random numbers from. |
| 41 | +#' |
| 42 | +#' To obtain \code{S} draws from the posterior distribution: |
| 43 | +#' \enumerate{ |
| 44 | +#' \item Set the initial values of the parameters \eqn{\theta_2^{(0)}} |
| 45 | +#' \item At each of the \code{s} iterations: |
| 46 | +#' \enumerate{ |
| 47 | +#' \item Sample \eqn{\theta_1^{(s)}} from \eqn{p(\theta_1|\theta_2^{(s-1)},\mathbf{Y})} |
| 48 | +#' \item Sample \eqn{\theta_2^{(s)}} from \eqn{p(\theta_2|\theta_1^{(s)},\mathbf{Y})} |
| 49 | +#' } |
| 50 | +#' \item Repeat step 2. \code{S} times. Return \eqn{\{\theta_1^{(s)},\theta_2^{(s)}\}_{s=1}^{S}} |
| 51 | +#' as a sample drawn from the posterior distribution \eqn{p(\theta_1,\theta_2|\mathbf{Y})}. |
| 52 | +#' } |
| 53 | +#' The \code{estimate()} function returns the draws from the posterior distribution |
| 54 | +#' of the parameters of the hierarchical panel VAR model listed above. |
| 55 | +#' |
| 56 | +#' \strong{Thinning.} |
| 57 | +#' Thinning is a procedure to reduce the dependence in the returned sample from |
| 58 | +#' the posterior distribution. It is obtained by returning every \code{thin} |
| 59 | +#' draw in the final sample. This procedure reduces the number of draws returned |
| 60 | +#' by the \code{estimate()} function. |
| 61 | +#' |
| 62 | +#' @param specification an object of class \code{BVARGROUPPANEL} generated using the |
| 63 | +#' \code{specify_bvarPANEL$new()} function. |
| 64 | +#' @param S a positive integer, the number of posterior draws to be generated |
| 65 | +#' @param thin a positive integer, specifying the frequency of MCMC output thinning |
| 66 | +#' @param show_progress a logical value, if \code{TRUE} the estimation progress |
| 67 | +#' bar is visible |
| 68 | +#' |
| 69 | +#' @return An object of class \code{PosteriorBVARGROUPPANEL} containing the Bayesian |
| 70 | +#' estimation output and containing two elements: |
| 71 | +#' |
| 72 | +#' \describe{ |
| 73 | +#' \item{\code{posterior}}{a list with a collection of \code{S} draws from the |
| 74 | +#' posterior distribution generated via Gibbs sampler. Elements of the list |
| 75 | +#' correspond to the parameters of the model listed in section \strong{Details} |
| 76 | +#' and are named respectively: |
| 77 | +#' \code{A_c}, \code{Sigma_c}, \code{A}, \code{Sigma}, |
| 78 | +#' \code{V}, \code{nu}, \code{m}, \code{w}, \code{s}. |
| 79 | +#' } |
| 80 | +#' \item{\code{last_draw}}{an object of class \code{BVARGROUPPANEL} with the last draw of the |
| 81 | +#' current MCMC run as the starting value to be passed to the continuation of |
| 82 | +#' the MCMC estimation using the \code{estimate()} method. } |
| 83 | +#' } |
| 84 | +#' |
| 85 | +#' @seealso \code{\link{bvarPANELs}}, \code{\link{specify_bvarGroupPANEL}}, |
| 86 | +#' \code{\link{specify_posterior_bvarGroupPANEL}}, \code{\link{summary.PosteriorBVARPANEL}} |
| 87 | +#' |
| 88 | +#' @author Tomasz Woźniak \email{wozniak.tom@pm.me} |
| 89 | +#' |
| 90 | +#' @method estimate BVARGROUPPANEL |
| 91 | +#' |
| 92 | +#' @examples |
| 93 | +#' data(ilo_dynamic_panel) # load the data |
| 94 | +#' data(ilo_exogenous_variables) # load the exogenous variables |
| 95 | +#' set.seed(123) |
| 96 | +#' # specify the model |
| 97 | +#' specification = specify_bvarGroupPANEL$new( |
| 98 | +#' data = ilo_dynamic_panel, |
| 99 | +#' exogenous = ilo_exogenous_variables, |
| 100 | +#' group_allocation = rep(1:2, length.out = 189) |
| 101 | +#' ) |
| 102 | +#' burn_in = estimate(specification, 10) # run the burn-in; use say S = 10000 |
| 103 | +#' posterior = estimate(burn_in, 10) # estimate the model; use say S = 10000 |
| 104 | +#' |
| 105 | +#' @export |
| 106 | +estimate.BVARGROUPPANEL <- function( |
| 107 | + specification, |
| 108 | + S, |
| 109 | + thin = 1L, |
| 110 | + show_progress = TRUE |
| 111 | +) { |
| 112 | + |
| 113 | + # get the inputs to estimation |
| 114 | + prior = specification$prior$get_prior() |
| 115 | + starting_values = specification$starting_values$get_starting_values() |
| 116 | + data_matrices = specification$data_matrices$get_data_matrices() |
| 117 | + adaptiveMH = specification$adaptiveMH |
| 118 | + estimate_groups = specification$estimate_groups |
| 119 | + G = specification$G |
| 120 | + |
| 121 | + # estimation |
| 122 | + qqq = .Call(`_bvarPANELs_bvarGroupPANEL`, S, data_matrices$Y, data_matrices$X, prior, starting_values, thin, show_progress, adaptiveMH, estimate_groups) |
| 123 | + |
| 124 | + specification$starting_values$set_starting_values(qqq$last_draw) |
| 125 | + output = specify_posterior_bvarGroupPANEL$new(specification, qqq$posterior) |
| 126 | + |
| 127 | + return(output) |
| 128 | +} # END estimate.BVARGROUPPANEL |
| 129 | + |
| 130 | + |
| 131 | + |
| 132 | +#' @inherit estimate.BVARGROUPPANEL |
| 133 | +#' |
| 134 | +#' @method estimate PosteriorBVARGROUPPANEL |
| 135 | +#' |
| 136 | +#' @param specification an object of class \code{PosteriorBVARGROUPPANEL} generated using |
| 137 | +#' the \code{estimate.BVARGROUPPANEL()} function. This setup facilitates the |
| 138 | +#' continuation of the MCMC sampling starting from the last draw of the previous |
| 139 | +#' run. |
| 140 | +#' |
| 141 | +#' @export |
| 142 | +estimate.PosteriorBVARGROUPPANEL <- function( |
| 143 | + specification, |
| 144 | + S, |
| 145 | + thin = 1, |
| 146 | + show_progress = TRUE |
| 147 | +) { |
| 148 | + |
| 149 | + # get the inputs to estimation |
| 150 | + prior = specification$last_draw$prior$get_prior() |
| 151 | + starting_values = specification$last_draw$starting_values$get_starting_values() |
| 152 | + data_matrices = specification$last_draw$data_matrices$get_data_matrices() |
| 153 | + adaptiveMH = specification$last_draw$adaptiveMH |
| 154 | + estimate_groups = specification$last_draw$estimate_groups |
| 155 | + G = specification$last_draw$G |
| 156 | + |
| 157 | + # estimation |
| 158 | + qqq = .Call(`_bvarPANELs_bvarGroupPANEL`, S, data_matrices$Y, data_matrices$X, prior, starting_values, thin, show_progress, adaptiveMH, estimate_groups) |
| 159 | + |
| 160 | + specification$last_draw$starting_values$set_starting_values(qqq$last_draw) |
| 161 | + output = specify_posterior_bvarGroupPANEL$new(specification$last_draw, qqq$posterior) |
| 162 | + |
| 163 | + return(output) |
| 164 | +} # END estimate.PosteriorBVARGROUPPANEL |
0 commit comments