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

modSApop {FIESTA}

R Documentation

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,
  addxy = FALSE,
  returndata = TRUE,
  savedata = FALSE,
  saveobj = FALSE,
  objnm = "SApopdat",
  unit_opts = NULL,
  savedata_opts = NULL,
  SAdoms = NULL,
  smallbnd = NULL,
  smallbnd.domain = NULL,
  largebnd.unique = 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.
`addxy`	Logical. If TRUE, adds X/Y attributes to pltassgn.
`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.
`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.
`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")

[Package FIESTA version 3.6.4 Index]