nlfh (version 0.1.0)

fit_fh_bart: Fit a BART Fay-Herriot Model

Description

Fits a Bayesian Fay-Herriot model whose mean function is represented with Bayesian additive regression trees via the dbarts package.

Usage

fit_fh_bart(
  y = NULL,
  x = NULL,
  sampling_variance = NULL,
  formula = NULL,
  data = NULL,
  X = NULL,
  prior_shape = 0.01,
  prior_rate = 0.01,
  n_iter = 1000,
  burn_in = 500,
  n_bart_samples = 10,
  n_trees = 50,
  scale = FALSE,
  progress = TRUE
)

Value

An object of class nlfh_bart_fit and nlfh_fit, a list with posterior draws for predictions, the BART mean function mean, random effects random_effects, random-effect variance random_effect_variance, variable_importance, the scalar dic, and MCMC metadata.

Arguments

y

Numeric vector of area-level direct estimates for the matrix interface. If the first argument is a formula, it is treated as formula.

x, X

Numeric matrix or data frame of area-level covariates for the matrix interface. Rows must correspond to entries of y. The first column is treated as a baseline/intercept column and excluded from the BART splitting variables and variable_importance.

sampling_variance

Numeric vector of known sampling variances for y. With the formula interface, this may also be an unquoted column name from data or a length-one character string naming a column in data.

formula

Optional model formula such as y ~ x1 + x2. For nonlinear models, the formula specifies the predictors available to the model; it does not imply an additive linear mean structure.

data

Optional data frame containing variables used by formula and, optionally, sampling_variance.

prior_shape

Non-negative scalar shape parameter for the inverse-gamma prior on the random-effect variance.

prior_rate

Non-negative scalar rate parameter for the inverse-gamma prior on the random-effect variance.

n_iter

Positive integer number of MCMC iterations.

burn_in

Positive integer number of initial MCMC iterations to discard.

n_bart_samples

Positive integer number of BART samples to draw per outer MCMC iteration.

n_trees

Positive integer number of trees used by dbarts.

scale

Logical; if TRUE, center and scale covariates after the first baseline/intercept column before fitting. The first column is never scaled.

progress

Logical; if TRUE, display a progress bar.

Details

Formula inputs are parsed with stats::model.frame() and stats::model.matrix(). Factors are expanded using R's standard contrast and dummy-variable rules. Formula inputs must include an intercept, which is the default. For this nonlinear method, the formula specifies the available predictors and does not impose an additive linear mean structure. The BART mean component estimates an unknown function f(X).

The first model-matrix column is treated as a baseline/intercept column and is excluded from BART splitting variables. With the formula interface this is the default (Intercept) column; formulas that omit the intercept with 0 + or - 1 are rejected. With the matrix interface, put the baseline or intercept column first. BART variable importance is computed only for the remaining columns.

References

Parker, P. A. and Eideh, A. (2026). BART-FH: Flexible Nonlinear Modeling for Small Area Estimation. Journal of Survey Statistics and Methodology, 00, 1-18. tools:::Rd_expr_doi("10.1093/jssam/smaf050")

Examples

data(acs_dat)
acs_small <- as.data.frame(acs_dat[1:500, ])
fit <- fit_fh_bart(
  MedInc ~ SNAPRate + PovRate + White,
  sampling_variance = MedIncSE^2,
  data = acs_small,
  n_iter = 50,
  burn_in = 25,
  progress = FALSE
)
summary(fit)
fit$variable_importance