JoSAE (version 0.3.0)

sae.ul.f: Unit-level small area estimation under heteroscedasticity.

Description

The only function that should be used is sae.ul.f which wraps the data preparation (ul.data.prep.f), parameter estimation (ul.reml.f), and EBLUP and MSE estimation (ul.est.f) functions. The other functions are helpers that do not need to be called by the user directly.

Usage

sae.ul.f(...)

ul.data.prep.f(k.ij, samp.data, population.data, formula, domain.col,
sample.id.col, neg.sfrac, pop.r, sum.i.k.ij.sq.r, N.i, ...)

ul.reml.f(samp.data, formula, samp.agg.X.pop, y.name, X.names, ...)

ul.est.f(samp.data, samp.agg.X.pop, X.names, y.name, beta.hat,
cov.beta.hat, sig.sq.e, sig.sq.v, V.bar.ee, V.bar.vv, V.bar.ve,
neg.sfrac, resid = F, ...)

Arguments

samp.data

Data frame of unit-level sample data of the response and explanatory variables. Transformations of x have to be calculated before hand, not using formula.

k.ij

Vector of the same length and corresponding to samp.data containing the k_ij values for modeling heteroscedasticity. A vector of 1's if heteroscedasticity is not considered. k_ij is squared and used as the input to the varFix variance function in lme.

population.data

Data frame of domain-level means of the explanatory variables. Names have to match to sample data.

formula

The fixed effects formula to be used in the mixed model using lme.

domain.col

Character string identifying the column name in sample.data and population.data containing unique domain IDs.

sample.id.col

Character string identifying the column name in sample.data containing unique sample IDs.

neg.sfrac

Boolean. Are sampling fractions negligible?

pop.r

Only required if neg.sfrac is FALSE. Same as population.data but calculated with the sample elements removed.

sum.i.k.ij.sq.r

Only required if neg.sfrac is FALSE. Same as the values in the population.k.column but calculated with the sample elements removed.

N.i

Only required if neg.sfrac is FALSE. Number of elements within domain i.

samp.agg.X.pop

Data frame containing the aggregated sample data and domain-level explanatory variables.

y.name

Character string identifying the column name of the response.

X.names

Vector of character strings identifying the column names of the explanatory variables.

beta.hat

Vector of estimated fixed effects.

cov.beta.hat

Covariance matrix of fixed effects.

sig.sq.e

Residual variance.

sig.sq.v

Random effect variance.

V.bar.ee

Assymptotic variance of the residual variance.

V.bar.vv

Assymptotic variance of the random effect variance.

V.bar.ve

Assymptotic covariance of the residual and random effect variance.

resid

Boolean. Should residuals be returned?

…

Parameters forwarded to other functions.

Value

est

List of point estimates and standard errors based on different estimators. est: Point estimates of EBLUP, SRS, GREG, Survey regression (svreg), and EBLUP synthetic estimators. Also contains random effects. se: Standard errors. EBLUP global was used in the reference publication. resids: Different forms of raw and transformed residuals.

var.pars

List of estimated variance parameters. Among others the lme object fitted to the data. See list of arguments above.

data

List of data frames in the format required by the other functions.

Details

These functions can also be used for eblups without heteroskedasticity as the the older functions around eblup.mse.f.wrap.

References

Breidenbach et al. (2018) Unit-level and area-level small area estimation under heteroscedasticity using digital aerial photogrammetry data. Remote Sensing of Environment.

Examples

# NOT RUN {
library(nlme)
#sample data
data(ulal.sub.samp.dat)
#domain means of x
data(ulal.sub.dom.dat)

#eblup under homoskedasticity
res <-
    sae.ul.f(samp.data=ulal.sub.samp.dat,
             population.data=ulal.sub.dom.dat,
             k.ij=ulal.sub.samp.dat[,"k.ij.one"],
             formula=w.VMPRHA ~ elev.mean + elev.mean.sq,
             domain.col="stand.ID",
             sample.id.col="plot.ID",
             neg.sfrac=TRUE)

#eblup under heteroskedasticity
res <-
    sae.ul.f(samp.data=ulal.sub.samp.dat,
             population.data=ulal.sub.dom.dat,
             k.ij=ulal.sub.samp.dat[,"k.ij.em.0.48"],
             formula=w.VMPRHA ~ elev.mean + elev.mean.sq,
             domain.col="stand.ID",
             sample.id.col="plot.ID",
             neg.sfrac=TRUE)
# }