Bayesian Hierarchical Linear Model with HART Prior

rhierLinearMixture implements an MCMC algorithm for a Bayesian hierarchical linear regression model with a Hierarchical Additive Regression Trees (HART) prior. HART is a hierarchical nonparametric prior that allows for flexible modeling of the representative unit as a function of potentially many observed characteristics. Prior$bart allows for modeling the conditional mean of the normal prior.

Usage

rhierLinearMixture(Data, Prior, Mcmc, r_verbose = TRUE)

Arguments

Data

A list containing:

regdata: A list of length nreg. Each element regdata[[i]] must be a list with:
- y: n_i x 1 vector of responses.
- X: n_i x nvar design matrix.
Z (optional): nreg x nz matrix of unit-level covariates. If omitted, drawdelta is set to FALSE and no second-stage covariates are used.

Prior

A list containing prior parameters:

ncomp (required): Number of components. Must be 1.
nu.e (optional): Degrees of freedom for error variance prior (default: 3).
ssq (optional): Scale for error variance prior, nreg x 1 vector (default: var(y_i)).
mubar (optional): 1 x nvar prior mean vector for the normal prior (default: 0).
Amu (optional): 1 x 1 prior precision for the normal prior (default: 0.01).
nu (optional): Degrees of freedom for IW prior on the normal prior covariance (default: nvar + 3).
V (optional): nvar x nvar location matrix for IW prior (default: nu * I).
Ad (optional): Prior precision for vec(Delta) (default: 0.01 * I). Only used when drawdelta = TRUE and useBART = FALSE.
deltabar (optional): Prior mean for vec(Delta) (default: 0). Only used when drawdelta = TRUE and useBART = FALSE.
bart (optional): List of HART prior parameters. See Details.
vartree (optional, experimental extension beyond Wiemann 2025): List of parameters enabling heteroscedastic covariance $\Sigma(Z_i)$ via product-of-trees variance models on the Modified Cholesky diagonal $d_j(\cdot)$. Requires bart to also be specified and ncomp = 1. When nvar > 1, the package automatically promotes to the full-Cholesky structure described under phitree. See "Heteroscedastic Covariance" in Details.
phitree (optional, experimental extension beyond Wiemann 2025): List of parameters enabling sum-of-trees regression models on the Modified Cholesky off-diagonals $\phi_{jk}(\cdot)$. Requires vartree. Auto-enabled when vartree is supplied and nvar > 1.

Mcmc

A list containing MCMC parameters:

R: Number of MCMC iterations (required).
keep (optional): Thinning parameter (default: 1).
nprint (optional): Print progress every nprint draws (default: 100, 0 for none).

r_verbose

Logical. Print startup messages? Default TRUE.

Value

A list of class "rhierLinearMixture" containing:

betadraw: nreg x nvar x (R/keep) array of unit-level beta draws.
taudraw: (R/keep) x nreg matrix of error variance draws.
loglike: (R/keep) x 1 vector of log-likelihoods.
nmix: Legacy list containing prior draws (omitted under heter-cov).
If drawdelta and non-BART: Deltadraw.
If BART: bart_models, varcount, varprob.
If heter-cov (additional class "rhierLinearMixtureHeterCov"): var_models, phi_models (jagged or NULL), mu_draw, var_varcount, var_varprob.

Details

Model Specification

$y_i = X_i \beta_i + \epsilon_i$, $\epsilon_i \sim N(0, \tau_i I)$

The unit-level coefficients are modeled as: $\beta_i = Z_i \Delta + u_i$
$u_i \sim N(0, \Sigma_i)$

HART Prior Details

If Prior$bart is a list, $\Delta(Z_i)$ is modeled via a sum-of-trees (BART) prior instead of a linear hierarchical specification. See rhierMnlRwMixture for complete details and hyperparameter definitions.

Heteroscedastic Covariance $\Sigma(Z_i)$ (experimental extension)

When Prior$vartree is supplied, the homoscedastic prior covariance $\Sigma$ is replaced with a unit-specific modified Cholesky decomposition where the components are modeled as tree ensembles. See rhierMnlRwMixture for complete details.

When this extension is active, the returned object additionally inherits classes "rhierLinearMixtureHeterCov" and "bayesm.HART.HeterCov". predict() dispatches on these classes to evaluate $\Sigma(Z^*)$ at any new $Z^*$.

Note

Currently, only ncomp = 1 is supported.

Author

Peter Rossi, Wayne Taylor (original bayesm code), Thomas Wiemann (HART modifications).

Examples

# \donttest{
set.seed(20260513)
sim <- bayesm.HART::sim_hier_linear(
  nreg = 30, nobs = 12, nvar = 1, nz = 2,
  const = TRUE, het_observed = "linear",
  target_var_betabar = 1.0, target_var_eps = 0.5,
  sigma_sq = 0.5)
Prior <- list(ncomp = 1L,
              bart    = list(num_trees = 20),
              vartree = list(num_trees = 20))
Mcmc  <- list(R = 200L, keep = 1L, nprint = 0L)
fit   <- bayesm.HART::rhierLinearMixture(
  Data = list(regdata = sim$regdata, Z = sim$Z),
  Prior = Prior, Mcmc = Mcmc, r_verbose = FALSE)
str(fit, max.level = 1)
#> List of 11
#>  $ mu_draw     : 'bayesm.mat' num [1:200, 1:2] 0.27 0.143 0.535 0.326 0.269 ...
#>   ..- attr(*, "mcpar")= num [1:3] 1 200 1
#>  $ varcount    : num [1:2, 1:2, 1:200] 6 6 7 6 8 9 9 8 9 8 ...
#>  $ varprob     : num [1:2, 1:2, 1:200] 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 ...
#>  $ var_varcount: num [1:2, 1:2, 1:200] 5 3 6 11 8 6 5 11 10 8 ...
#>  $ var_varprob : num [1:2, 1:2, 1:200] 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 ...
#>  $ bart_models :List of 2
#>  $ var_models  :List of 2
#>  $ phi_models  :List of 2
#>  $ betadraw    : 'bayesm.hcoef' num [1:30, 1:2, 1:200] 0.84302 -0.00799 -0.05016 1.20736 0.76022 ...
#>  $ loglike     : num [1:200, 1] -410 -386 -385 -376 -379 ...
#>  $ taudraw     : 'bayesm.mat' num [1:200, 1:30] 1.253 0.858 1.298 1.089 1.346 ...
#>   ..- attr(*, "mcpar")= num [1:3] 1 200 1
#>  - attr(*, "class")= chr [1:3] "rhierLinearMixtureHeterCov" "bayesm.HART.HeterCov" "rhierLinearMixture"
#>  - attr(*, "hart_cache")=List of 6
# }