modSApop: Small area module - Compile population data for SA module.

In FIESTA: Forest Inventory Estimation and Analysis

Small area module - Compile population data for SA module.

Description

Compile population data for input to the modSA* modules.

Usage

modSApop(
  popType = "VOL",
  popTabs = popTables(),
  popTabIDs = popTableIDs(),
  popFilter = popFilters(),
  pltassgn = NULL,
  pltassgnid = "PLT_CN",
  dsn = NULL,
  pjoinid = "CN",
  areawt = "CONDPROP_UNADJ",
  adjplot = TRUE,
  dunitvar = NULL,
  dunitarea = NULL,
  areavar = "ACRES",
  dunitzonal = NULL,
  prednames = NULL,
  predfac = NULL,
  returndata = TRUE,
  savedata = FALSE,
  saveobj = FALSE,
  objnm = "SApopdat",
  unit_opts = NULL,
  savedata_opts = NULL,
  SAdoms = NULL,
  smallbnd = NULL,
  smallbnd.domain = NULL,
  SAdata = NULL,
  pltdat = NULL,
  auxdat = NULL,
  gui = FALSE,
  ...
)

Arguments

popType	String. Type of evaluation(s) to include in population data. Note: currently only c('CURR', 'VOL', 'LULC') are available. See details below for descriptions of each.
popTabs	List of population tables the user would like returned. See help(popTables) for a list of options.
popTabIDs	List of unique IDs corresponding to the population tables that the user has requested. See help(popTableIDs) for a list of options.
popFilter	List of population filters. See help(popFilters) for a list of options.
pltassgn	DF/DT, comma-separated values (CSV) file(*.csv), or layer in dsn, Can also be a shapefile(*.shp) with one record per plot, a spatial layer in dsn, or a sf R object. Plot-level assignment of estimation unit and/or strata. Optional.
pltassgnid	String. Unique identifier of plot in pltassgn.
dsn	String. Name of database where tree, cond, and pltassgn tables reside. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html).
pjoinid	String. Join variable in plot to match pltassgnid. Does not need to be uniqueid. If using most current XY coordinates for plot assignments, use identifier for plot (e.g., PLOT_ID).
areawt	String. Name of variable for summarizing area weights (e.g., CONDPROP_UNADJ).
adjplot	Logical. If TRUE, adjusts for nonresponse at plot-level.
dunitvar	String. Name of the domain unit variable in cond, plt, or pltassgn with domain unit assignment for each plot.
dunitarea	Numeric or DF. Total area by domain unit.
areavar	String. Name of area variable in unitarea. Default="ACRES".
dunitzonal	DF/DT. Data frame with zonal auxiliary information by domain unit. For continuous data, means by domain unit; for categorical data, proportion of class by domain unit.
prednames	String vector. Name(s) of predictor variables to use in model.
predfac	String vector. Name(s) of factor predictor variables to use in model. Names will change in output depending on number of categories.
returndata	Logical. If TRUE, returns data objects.
savedata	Logical. If TRUE, saves table(s) to outfolder.
saveobj	Logical. If TRUE, saves returned list object to outfolder.
objnm	String. Name of *.rds object.
unit_opts	List. See help(unit_options()) for a list of options.
savedata_opts	List. See help(savedata_options()) for a list of options.
SAdoms	sf object. SA domains with attributes for joining.
smallbnd	sf object. small bound.
smallbnd.domain	String. Name of attribute defining domain attribute.
SAdata	R List object. Output data list components from FIESTA::SAdata().
pltdat	R List object. Output data list components from FIESTA::spGetPlots().
auxdat	R List object. Output data list components from FIESTA::spGetAuxiliary().
gui	Logical. If gui, user is prompted for parameters.
...	For extendibility.

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 pltassgn (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 pltassgn (e.g. 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.
	pltassgn	puniqueid	Unique identifier for each plot, to link to cond (e.g. 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.

For available reference tables: sort(unique(FIESTAutils::ref_codes$VARIABLE))

Value

A list with population data for Small-Area estimates.

SAdomsdf	Data frame. Attribute table from SAdoms spatial layer. Includes DOMAIN and AOI attributes. DOMAIN represents modeling domains. AOI identifies the small area of interest.
condx	Data frame. Condition-level data with condition proportions, domain and predictor assignments, and adjusted condition proportions, if adjplot = TRUE.
pltcondx	Data frame. Plot/Condition data used for estimation.
cuniqueid	String. Unique identifier of plot in condx and pltcondx.
condid	String. Unique identifier of condition in condx and pltcondx.
treex	Data frame. If esttype='TREE', tree-level data, including adjustment factors, if adjplot = TRUE.
tuniqueid	String. If esttype='TREE', unique identifier of plot in treex.
ACI.filter	String. If ACI=FALSE, ACI.filter="COND_STATUS_CD == 1" .
dunitarea	Data frame. Area by model domain unit.
areavar	String. Name of area variable in dunitarea.
dunitvar	String. Name of variable defining model domain units in dunitarea.
dunitlut	Data frame. Table of model domain units with zonal statistics of predictor values, number of plots by domain unit.
prednames	String vector. Name of variables in dunitlut and condx defining potential predictors for small area estimation.
plotsampcnt	Data frame. Number of plots by PLOT_STATUS_CD.
condsampcnt	Data frame. Number of conditions by COND_STATUS_CD.
states	String. State names in dataset.
invyrs	String. Range of inventory years in dataset.
adjtree	Logical. If TRUE, treex includes adjustment factors.

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

Examples

# NOTE: FIA data objects used in these examples are stored in `FIESTA`, but
# can be generated for populations of interest by the user with functions in
# `FIESTA` such as `spGetPlots()`, `spGetAuxiliary()`, etc. For more
# information, see `FIESTA`'s extensive vignettes.
 
# Population data for counties in Wyoming
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")
         
# Adding seedling data as well
modSApop(popTabs = list(tree = FIESTA::WYtree,
                        cond = FIESTA::WYcond,
                        seed = FIESTA::WYseed),
         pltassgn = FIESTA::WYpltassgn,
         pltassgnid = "CN",
         dunitarea = FIESTA::WYunitarea,
         dunitvar = "ESTN_UNIT",
         dunitzonal = FIESTA::WYunitzonal,
         prednames = c("dem", "tcc", "tpi", "tnt"),
         predfac = "tnt")

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