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

In FIESTA: Forest Inventory Estimation and Analysis

Small area module - Generate small area tree estimates.

Description

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

Usage

modSAtree(
  SApopdatlst = NULL,
  prednames = NULL,
  SApackage = "JoSAE",
  SAmethod = "area",
  estseed = "none",
  woodland = "Y",
  largebnd.unique = NULL,
  landarea = "FOREST",
  pcfilter = NULL,
  estvar = NULL,
  estvar.filter = 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')
estseed	String. Use seedling data only or add to tree data. Seedling estimates are only for counts (estvar='TPA_UNADJ')-('none', 'only', 'add').
woodland	String. If woodland = 'Y', include woodland tree species where measured. If woodland = 'N', only include timber species. See FIESTA::ref_species$WOODLAND ='Y/N'. If woodland = 'only', only include woodland species.
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.
estvar	String. Name of the tree estimate variable.
estvar.filter	String. A tree filter for estimate variable. Must be R syntax (e.g., "STATUSCD == 1").
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 (e.g. 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.
estvar	String. Name of estimation variable.
estvar.filter	String. Logical filter specified for tree data.
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.

Common tree filters for estvar.filter:

	FILTER	DESCRIPTION
	"STATUSCD == 1"	Live trees
	"STATUSCD == 2"	Dead trees
	"TPAMORT_UNADJ > 0"	Mortality trees
	"STATUSCD == 2 & DIA >= 5.0"	Dead trees >= 5.0 inches diameter
	"STATUSCD == 2 & AGENTCD == 30"	Dead trees from fire

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

# Use an area level Fay-Herriot model to estimate total net cubic-foot volume 
# of live trees (at least 5 inches diameter) 
modSAtree(SApopdatlst = SApopdat,
          SApackage = "JoSAE",        
          SAmethod = "unit",           
          landarea = "FOREST",      
          estvar = "VOLCFNET",         
          estvar.filter = "STATUSCD == 1")   
          
# Use a unit level EBLUP to estimate basal area of live trees (at least 5
# inches diameter) 
modSAtree(SApopdatlst = SApopdat,    
          SApackage = "JoSAE",        
          SAmethod = "unit",         
          landarea = "FOREST",      
          estvar = "BA",              
          estvar.filter = "STATUSCD == 1")  

FIESTA documentation built on Nov. 22, 2023, 1:07 a.m.