R: Small area module - Generate small area tree estimates.

modSAarea {FIESTA}

R Documentation

Small area module - Generate small area tree estimates.

Description

Generates small area estimates by domain and/or tree domain (and estimation unit).

Usage

modSAarea(
  SApopdatlst = NULL,
  prednames = NULL,
  SApackage = "JoSAE",
  SAmethod = "area",
  largebnd.unique = NULL,
  landarea = "FOREST",
  pcfilter = NULL,
  rowvar = NULL,
  modelselect = FALSE,
  prior = function(x) 1/(sqrt(x) * (1 + x)),
  na.fill = "NONE",
  savedata = FALSE,
  savesteps = FALSE,
  multest = TRUE,
  addSAdomsdf = TRUE,
  SAdomvars = NULL,
  savemultest = FALSE,
  returntitle = FALSE,
  table_opts = NULL,
  title_opts = NULL,
  savedata_opts = NULL,
  multest_opts = NULL,
  save4testing = FALSE,
  gui = FALSE,
  ...
)

Arguments

`SApopdatlst`	List. List of population data objects returned from modSApop().
`prednames`	String vector. Name(s) of predictor variables to use in model.
`SApackage`	String. Small area package to use ('JoSAE', 'sae', 'hbsae')
`SAmethod`	String. Small area method to use ('unit', 'area')
`largebnd.unique`	String. Name of the large boundary unique identifer to define plots within a model extent. If NULL, all plots are used for model extent.
`landarea`	String. The sample area filter for estimates ('ALL', 'FOREST', 'TIMBERLAND'). If landarea=FOREST, filtered to COND_STATUS_CD = 1; If landarea=TIMBERLAND, filtered to SITECLCD in(1:6) and RESERVCD = 0.
`pcfilter`	String. A filter for plot or cond attributes (including pltassgn). Must be R logical syntax.
`rowvar`	String. Name of the row domain variable in cond or tree. If only one domain, rowvar = domain variable. If more than one domain, include colvar. If no domain, rowvar = NULL.
`modelselect`	Logical. If TRUE, selects useful predictors using mase:ElasticNet.
`prior`	Function. A prior function to use for hbsae models.
`na.fill`	String. An estimate to fill in for NA values (i.e., when model is unstable or no predictors are selected). Choose from the following list that does not include SApackage used ('NONE', 'DIR', 'JoSAE', 'sae', 'hbsae'). DIR is suggested value for no NA values.
`savedata`	Logical. If TRUE, saves table(s) to outfolder.
`savesteps`	Logical. Saves graphs of predictors and response with labels whether selected or not for both area- and unit-level models.
`multest`	Logical. If TRUE, returns a data frame of SA estimates using both unit-level and area-level estimates.
`addSAdomsdf`	Logical. If TRUE, appends SAdomdf to unit.multest table for output.
`SAdomvars`	String vector. List of attributes from SAdoms to include in multest output.
`savemultest`	Logical. If TRUE, save table with area- and unit-level estimates.
`returntitle`	Logical. If TRUE, returns title(s) of the estimation table(s).
`table_opts`	List. See help(table_options()) for a list of options.
`title_opts`	List. See help(title_options()) for a list of options.
`savedata_opts`	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE.
`multest_opts`	List. See help(multest_options()) for a list of options. Only used when multest = TRUE.
`save4testing`	Logical. If TRUE, saves intermediate steps as R objects to outfolder for testing (pdomdat, dunitlut).
`gui`	Logical. If gui, user is prompted for parameters.
`...`	Parameters for modSApop if SApopdat is NULL.

Details

If variables are NULL, then it will prompt user to input variables.

Necessary variables:

Data	Variable	Description
tree	tuniqueid	Unique identifier for each plot, to link to pltstrat (e.g., PLT_CN).
	CONDID	Unique identifier of each condition on plot, to link to cond. Set CONDID=1, if only 1 condition per plot.
	TPA_UNADJ	Number of trees per acre each sample tree represents (ex. DESIGNCD=1: TPA_UNADJ=6.018046 for trees on subplot; 74.965282 for trees on microplot).
cond	cuniqueid	Unique identifier for each plot, to link to pltstrat (ex. PLT_CN).
	CONDID	Unique identifier of each condition on plot. Set CONDID=1, if only 1 condition per plot.
	CONDPROP_UNADJ	Unadjusted proportion of condition on each plot. Set CONDPROP_UNADJ=1, if only 1 condition per plot.
	COND_STATUS_CD	Status of each forested condition on plot (i.e. accessible forest, nonforest, water, etc.)
	NF_COND_STATUS_CD	If ACI=TRUE. Status of each nonforest condition on plot (i.e. accessible nonforest, nonsampled nonforest)
	SITECLCD	If landarea=TIMBERLAND. Measure of site productivity.
	RESERVCD	If landarea=TIMBERLAND. Reserved status.
	SUBPROP_UNADJ	Unadjusted proportion of subplot conditions on each plot. Set SUBPROP_UNADJ=1, if only 1 condition per subplot.
	MICRPROP_UNADJ	If microplot tree attributes. Unadjusted proportion of microplot conditions on each plot. Set MICRPROP_UNADJ=1, if only 1 condition per microplot.
	MACRPROP_UNADJ	If macroplot tree attributes. Unadjusted proportion of macroplot conditions on each plot. Set MACRPROP_UNADJ=1, if only 1 condition per macroplot.
pltassign	puniqueid	Unique identifier for each plot, to link to cond (ex. CN).
	STATECD	Identifies state each plot is located in.
	INVYR	Identifies inventory year of each plot.
	PLOT_STATUS_CD	Status of each plot (i.e. sampled, nonsampled). If not included, all plots are assumed as sampled.

Reference names are available for the following variables:
ADFORCD, AGENTCD, CCLCD, DECAYCD, DSTRBCD, KINDCD, OWNCD, OWNGRPCD, FORTYPCD, FLDTYPCD, FORTYPCDCALC, TYPGRPCD, FORINDCD, RESERVCD, LANDCLCD, STDSZCD, FLDSZCD, PHYSCLCD, MIST_CL_CD, PLOT_STATUS_CD, STATECD, TREECLCD, TRTCD, SPCD, SPGRPCD

Value

`est`	Data frame. Tree estimates and percent sampling error by domain. Estimates are based on the SApackage and SAmethod parameters defined.
`titlelst`	List. List of titles used for table output.
`raw`	List of raw data. If rawdata=TRUE, a list including raw data components used for calculating estimate.
`dunit.multest`	Data frame. Table comparing different estimation strategies for SAE.

Raw data

`domdat`	Data frame. Domain-level data used for estimation.
`dunit.totest`	String. Table of estimates, including more details.

Note

ADJUSTMENT FACTOR:
The adjustment factor is necessary to account for nonsampled conditions. For model-based estimation, we calculate adjustment factors by plot.

It is calculated by dividing 1 / summed condition proportions by plot. An adjustment factor is determined for each tree based on the size of the plot it was measured on. This is identified using TPA_UNADJ as follows:

	PLOT SIZE	TPA_UNADJ
	SUBPLOT	6.018046
	MICROPLOT	74.965282
	MACROPLOT	0.999188

If ACI=FALSE, only nonsampled forest conditions are accounted for in the adjustment factor.
If ACI=TRUE, the nonsampled nonforest conditions are removed as well and accounted for in adjustment factor. This is if you are interested in estimates for all lands or nonforest lands in the All-Condition-Inventory.

Author(s)

Tracey S. Frescino, Paul L. Patterson, Elizabeth A. Freeman

References

Breidenbach, J. 2018. JoSAE: Unit-Level and Area-Level Small Area Estimation. R package version 0.3.0. https://CRAN.R-project.org/package=JoSAE.

Molina I, Marhuenda Y. 2015. sae: An R Package for Small Area Estimation. The R Journal 7(1), 81-98. https://journal.r-project.org/archive/2015/RJ-2015-007/RJ-2015-007.

Examples


# Set up population dataset (see ?modSApop() for more information)
SApopdat <- modSApop(popTabs = list(tree = FIESTA::WYtree,
                                    cond = FIESTA::WYcond),
                     pltassgn = FIESTA::WYpltassgn,
                     pltassgnid = "CN",
                     dunitarea = FIESTA::WYunitarea,
                     dunitvar = "ESTN_UNIT",
                     dunitzonal = FIESTA::WYunitzonal,
                     prednames = c("dem", "tcc", "tpi", "tnt"),
                     predfac = "tnt")

# Fit a unit level EBLUP with `JoSAE`
modSAarea(SApopdatlst = SApopdat,
          SApackage = "JoSAE",
          SAmethod = "unit") 
          
# Fit an area level Fay-Herriot hierarchical Bayesian model with `hbsae`
modSAarea(SApopdatlst = SApopdat,
          SApackage = "hbsae",
          SAmethod = "area") 

# Fit an area level Fay-Herriot EBLUP with `sae`, while using Elastic Net
# variable selection
modSAarea(SApopdatlst = SApopdat,
          SApackage = "sae",
          SAmethod = "area",
          modelselect = TRUE)

[Package FIESTA version 3.6.4 Index]