nlfh (version 0.1.0)

fit_fh_linear: Fit a Linear Fay-Herriot Model

Description

Fits the basic Bayesian Fay-Herriot model with a linear mean function and area-level random effects.

Usage

fit_fh_linear(
  y = NULL,
  x = NULL,
  sampling_variance = NULL,
  formula = NULL,
  data = NULL,
  X = NULL,
  prior_beta_variance = 10000^2,
  prior_shape = 0.1,
  prior_rate = 0.1,
  n_iter = 1000,
  burn_in = 500,
  scale = FALSE,
  progress = TRUE
)

Value

An object of class nlfh_linear_fit and nlfh_fit, a list with posterior draws for predictions, random_effect_variance, 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. The formula interface requires data.

data

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

prior_beta_variance

Positive scalar prior variance for the regression coefficients.

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.

Examples

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