nlfh (version 0.1.0)

fit_fh_rnn: Fit a Random-Weight Neural Network Fay-Herriot Model

Description

Fits a Bayesian Fay-Herriot model whose mean function is represented by a fixed random hidden layer with logistic activation and sampled output-layer coefficients.

Usage

fit_fh_rnn(
  y = NULL,
  x = NULL,
  sampling_variance = NULL,
  formula = NULL,
  data = NULL,
  X = NULL,
  n_hidden = 200,
  prior_beta_variance = NULL,
  prior_shape = 0.1,
  prior_rate = 0.1,
  n_iter = 1000,
  burn_in = 500,
  scale = TRUE,
  progress = TRUE
)

Value

An object of class nlfh_rnn_fit and nlfh_fit, a list with posterior draws for predictions, random_effect_variance, coefficient_variance, hidden-layer coefficients, mean, 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. Include an intercept column if one is desired.

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.

n_hidden

Positive integer number of hidden nodes in the random-weight neural network.

prior_beta_variance

Optional positive scalar prior variance for the output-layer coefficients. When NULL, the coefficient variance is sampled with the original inverse-gamma update.

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.

scale

Logical; if TRUE, center and scale non-intercept covariates before fitting. Intercept columns named (Intercept), Intercept, or intercept are not 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. An intercept is included when the formula includes one, which is the default; matrix inputs are used as supplied. For this nonlinear method, the formula specifies the available predictors and does not impose an additive linear mean structure. The model estimates an unknown function f(X).

The response and sampling variances are standardized internally before fitting the RNN. Posterior predictions, mean function draws, coefficients, random-effect variances, and DIC are transformed back to the original response scale before being returned.

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")

Examples

data(acs_dat)
acs_small <- as.data.frame(acs_dat[1:500, ])
fit <- fit_fh_rnn(
  MedInc ~ .,
  sampling_variance = MedIncSE^2,
  data = acs_small,
  n_iter = 50,
  burn_in = 25,
  progress = FALSE
)
summary(fit)