fit_sae: Fitting a Small Area Model

In tipsae: Tools for Handling Indices and Proportions in Small Area Estimation

Fitting a Small Area Model

Description

fit_sae() is used to fit Beta-based small area models, such as the classical Beta, zero and/or one inflated Beta and Flexible Beta models. The random effect part can incorporate either a temporal and/or a spatial dependency structure devoted to the prior specification settings. In addition, different prior assumptions can be specified for the unstructured random effects, allowing for robust and shrinking priors and different parametrizations can be set up.

Usage

fit_sae(
  formula_fixed,
  data,
  domains = NULL,
  disp_direct,
  type_disp = c("neff", "var"),
  domain_size = NULL,
  household_size = NULL,
  likelihood = c("beta", "flexbeta", "Infbeta0", "Infbeta1", "Infbeta01", "ExtBeta"),
  prior_coeff = c("normal", "HorseShoe"),
  p0_HorseShoe = NULL,
  prior_reff = c("normal", "t", "VG"),
  spatial_error = FALSE,
  spatial_df = NULL,
  domains_spatial_df = NULL,
  temporal_error = FALSE,
  temporal_variable = NULL,
  scale_prior = list(Unstructured = 2.5, Spatial = 2.5, Temporal = 2.5, Coeff. = 2.5),
  adapt_delta = 0.95,
  max_treedepth = 10,
  init = "0",
  ...
)

Arguments

formula_fixed	An object of class "formula" specifying the linear regression fixed part at the linking level.
data	An object of class "data.frame" containing all relevant quantities.
domains	Data column name displaying the domain names. If NULL (default), the domains are denoted with a progressive number.
disp_direct	Data column name displaying given values of sampling dispersion for each domain. In out-of-sample areas, dispersion must be NA.
type_disp	Parametrization of the dispersion parameter. The choices are variance ("var") or \phi_d + 1 ("neff") parameter.
domain_size	Data column name indicating domain sizes (optional). In out-of-sample areas, sizes must be NA.
household_size	Data column name indicating the number of sampled households. Required for the ExtBeta likelihood option.
likelihood	Sampling likelihood to be used. The choices are "beta" (default), "flexbeta", ExtBeta, "Infbeta0", "Infbeta1" and "Infbeta01".
prior_coeff	Prior distribution of the regression coefficients. The choices are ⁠"normal⁠ or HorseShoe.
p0_HorseShoe	If prior_coeff = "HorseShoe", it requires the expected number of relevant covariates.
prior_reff	Prior distribution of the unstructured random effect. The choices are: "normal", "t", "VG".
spatial_error	Logical indicating whether to include a spatially structured random effect.
spatial_df	Object of class SpatialPolygonsDataFrame or sf with the shapefile of the studied region. Required if spatial_error = TRUE.
domains_spatial_df	Column name of the spatial_df object displaying the domain names. Required if spatial_error = TRUE.
temporal_error	Logical indicating whether to include a temporally structured random effect.
temporal_variable	Data column name indicating temporal variable. Required if temporal_error = TRUE.
scale_prior	List with the values of the prior scales. 4 named elements must be provided: "Unstructured", "Spatial", "Temporal", "Coeff.". Default: all equal to 2.5.
adapt_delta	HMC option: target average proposal acceptance probability. See stan documentation.
max_treedepth	HMC option: target average proposal acceptance probability. See stan documentation.
init	Initial values specification. See the detailed documentation for the init argument in stan.
...	Arguments passed to sampling (e.g. iter, chains).

Value

A list of class fitsae containing the following objects:

model_settings

A list summarizing all the assumptions of the model: sampling likelihood, presence of intercept, dispersion parametrization, random effects priors and possible structures.

data_obj

A list containing input objects including in-sample and out-of-sample relevant quantities.

stanfit

A stanfit object, outcome of sampling function containing full posterior draws. For details, see stan documentation.

pars_interest

A vector containing the names of parameters whose posterior samples are stored.

call

Image of the function call that produced the fitsae object.

References

\insertRef

janicki2020propertiestipsae

\insertRef

carpenter2017stantipsae

\insertRef

morris2019bayesiantipsae

\insertRef

DeNicolo2021tipsae

\insertRef

JSStipsae

See Also

sampling for sampler options and summary.fitsae for handling the output.

Examples

library(tipsae)

# loading toy cross sectional dataset
data("emilia_cs")

# fitting a cross sectional model
fit_beta <- fit_sae(formula_fixed = hcr ~ x, data = emilia_cs, domains = "id",
                    type_disp = "var", disp_direct = "vars", domain_size = "n",
                    # MCMC setting to obtain a fast example. Remove next line for reliable results.
                    chains = 1, iter = 150, seed = 0)


# Spatio-temporal model: it might require time to be fitted
## Not run: 
# loading toy panel dataset
data("emilia")
# loading the shapefile of the concerned areas
data("emilia_shp")

# fitting a spatio-temporal model
fit_ST <- fit_sae(formula_fixed = hcr ~ x,
                  domains = "id",
                  disp_direct = "vars",
                  type_disp = "var",
                  domain_size = "n",
                  data = emilia,
                  spatial_error = TRUE,
                  spatial_df = emilia_shp,
                  domains_spatial_df = "NAME_DISTRICT",
                  temporal_error = TRUE,
                  temporal_variable = "year",
                  max_treedepth = 15,
                  seed = 0)

## End(Not run)

tipsae documentation built on Sept. 13, 2024, 5:07 p.m.