nlfh (version 0.1.0)

fit_fh: Fit a Fay-Herriot Model

Description

Primary user-facing model fitting function for linear and nonlinear Fay-Herriot models. Use method to choose the mean-function model and control to pass method-specific tuning parameters.

Usage

fit_fh(
  y = NULL,
  x = NULL,
  sampling_variance = NULL,
  method = c("linear", "rnn", "bart"),
  control = list(),
  data = NULL,
  formula = NULL,
  X = NULL
)

Value

An object inheriting from nlfh_fit. The first class identifies the fitted method: nlfh_linear_fit, nlfh_rnn_fit, or nlfh_bart_fit.

Arguments

y

Numeric vector of area-level direct estimates for the matrix interface.

x, X

Numeric matrix or data frame of area-level covariates for the matrix interface. Rows must correspond to entries of y. Include an intercept column if one is desired. For method = "bart", the first column is treated as a baseline/intercept column and is 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.

method

Character string selecting the model. Options are "linear" for the linear Fay-Herriot model, "rnn" for the random-weight neural network Fay-Herriot model, and "bart" for the BART Fay-Herriot model.

control

Named list of control parameters. Common controls are n_iter, burn_in, progress, scale, prior_shape, and prior_rate. Linear-specific control: prior_beta_variance. RNN-specific controls: n_hidden and prior_beta_variance. BART-specific controls: n_bart_samples and n_trees.

data

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

formula

Optional model formula such as y ~ x1 + x2. If the first argument is a formula, it is treated as formula. For nonlinear methods, the formula specifies the predictors available to the model; it does not imply an additive linear mean structure. Nonlinearities and interactions may be learned implicitly by the selected model.

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. An intercept is included when the formula includes one, which is the default for formulas such as y ~ x1 + x2; use 0 + or - 1 in the formula to omit it. Matrix inputs are used as supplied, so include an intercept column manually if one is desired.

When scale = TRUE, non-intercept covariates are centered and scaled before fitting. The default is TRUE for method = "rnn" and FALSE for the linear and BART methods. For BART, the first baseline/intercept column is never scaled. The RNN method also standardizes the response and sampling variances internally, then transforms returned posterior quantities back to the original response scale.

For method = "rnn" and method = "bart", the formula identifies the predictors available to the nonlinear mean function. It does not impose an additive linear model. These methods estimate an unknown function f(X), and nonlinearities or interactions may be learned implicitly by the model. sampling_variance is always supplied separately from the formula. When sampling_variance names a column in data, that column is excluded from y ~ . expansion.

For method = "bart", the first column of the model matrix is treated as a baseline/intercept column. With the formula interface, this must be 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, so fit$variable_importance does not include the first column.

References

Parker, P. A. (2024). Nonlinear Fay-Herriot Models for Small Area Estimation Using Random Weight Neural Networks. Journal of Official Statistics, 40(2), 317-332. tools:::Rd_expr_doi("10.1177/0282423X241244671")

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, ])
example_control <- list(n_iter = 50, burn_in = 25, progress = FALSE)

fit_linear <- fit_fh(
  MedInc ~ SNAPRate + PovRate + White + Black + Hispanic + Asian,
  sampling_variance = MedIncSE^2,
  data = acs_small,
  method = "linear",
  control = example_control
)

X <- model.matrix(
  MedInc ~ SNAPRate + PovRate + White + Black + Hispanic + Asian,
  data = acs_small
)
fit_matrix <- fit_fh(
  y = acs_small$MedInc,
  X = X,
  sampling_variance = acs_small$MedIncSE^2,
  method = "linear",
  control = example_control
)

fit_rnn <- fit_fh(
  MedInc ~ .,
  sampling_variance = MedIncSE^2,
  data = acs_small,
  method = "rnn",
  control = example_control
)

fit_bart <- fit_fh(
  MedInc ~ SNAPRate + PovRate + White,
  sampling_variance = MedIncSE^2,
  data = acs_small,
  method = "bart",
  control = example_control
)

# The default formula intercept is the first model-matrix column and is not
# included in BART variable importance.
fit_bart$variable_importance