Compute BCF Posterior Credible Intervals

Compute posterior credible intervals for specified terms from a fitted BCF model. Supports intervals for prognostic forests, CATE forests, variance forests, random effects, and overall mean outcome predictions.

Usage

computeBCFPosteriorInterval(
  model_object,
  terms,
  level = 0.95,
  scale = "linear",
  X = NULL,
  Z = NULL,
  propensity = NULL,
  rfx_group_ids = NULL,
  rfx_basis = NULL
)

Arguments

model_object

A fitted BCF model object of class bcfmodel.

terms

A character string specifying the model term(s) for which to compute intervals. Options are "prognostic_function", "mu", "cate", "tau", "variance_forest", "rfx", or "y_hat".

The treatment effect terms follow a three-level hierarchy:

• "tau" returns tau_0 + tau(X): the parametric treatment intercept (if sampled) plus the treatment forest. This matches model$tau_hat_train / model$tau_hat_test.

• "cate" additionally folds in the random slope on treatment when random effects are fit with rfx_model_spec = "intercept_plus_treatment"; otherwise it is identical to "tau".

• The raw forest-only component (without tau_0) is not directly returned by this method; use model$forests_tau to access it.

Similarly for the prognostic term: "mu" returns the prognostic forest only, while "prognostic_function" additionally folds in the random intercept when rfx_model_spec is "intercept_only" or "intercept_plus_treatment"; otherwise the two are identical.

level

A numeric value between 0 and 1 specifying the credible interval level (default is 0.95 for a 95% credible interval).

scale

(Optional) Scale of mean function predictions. Options are "linear", which returns predictions on the original scale of the mean forest / RFX terms, and "probability", which transforms predictions into a probability of observing y == 1. "probability" is only valid for models fit with a probit outcome model. Default: "linear".

X

(Optional) A matrix or data frame of covariates at which to compute the intervals. Required if the requested term depends on covariates (e.g., prognostic forest, CATE forest, variance forest, or overall predictions).

Z

(Optional) A vector or matrix of treatment assignments. Required if the requested term is "y_hat" (overall predictions).

propensity

(Optional) A vector or matrix of propensity scores. Required if the underlying model depends on user-provided propensities.

rfx_group_ids

An optional vector of group IDs for random effects. Required if the requested term includes random effects.

rfx_basis

An optional matrix of basis function evaluations for random effects. Required if the requested term includes random effects.

Value

A list containing the lower and upper bounds of the credible interval for the specified term. If multiple terms are requested, a named list with intervals for each term is returned.

Examples

n <- 100
p <- 5
X <- matrix(rnorm(n * p), nrow = n, ncol = p)
pi_X <- pnorm(0.5 * X[,1])
Z <- rbinom(n, 1, pi_X)
mu_X <- X[,1]
tau_X <- 0.25 * X[,2]
y <- mu_X + tau_X * Z + rnorm(n)
bcf_model <- bcf(X_train = X, Z_train = Z, y_train = y,
                 propensity_train = pi_X)
intervals <- computeBCFPosteriorInterval(
 model_object = bcf_model,
 terms = c("prognostic_function", "cate"),
 X = X,
 Z = Z,
 propensity = pi_X,
 level = 0.90
)