modMAtree: Model-Assisted module - Generate model-assisted tree...

In FIESTA: Forest Inventory Estimation and Analysis

Model-Assisted module - Generate model-assisted tree estimates.

Description

Generates tree estimates by estimation unit. Estimates are calculated from McConville et al. (2018)'s mase R package.

Usage

modMAtree(
  MApopdat,
  MAmethod,
  estvar,
  estvar.filter = NULL,
  estseed = "none",
  woodland = "Y",
  landarea = "FOREST",
  pcfilter = NULL,
  rowvar = NULL,
  colvar = NULL,
  prednames = NULL,
  modelselect = FALSE,
  FIA = TRUE,
  bootstrap = FALSE,
  returntitle = FALSE,
  savedata = FALSE,
  table_opts = NULL,
  title_opts = NULL,
  savedata_opts = NULL,
  gui = FALSE,
  modelselect_bydomain = FALSE,
  ...
)

Arguments

MApopdat	List. Population data objects returned from modMApop().
MAmethod	String. mase (i.e., model-assisted) method to use ('greg', 'gregEN', 'ratio').
estvar	String. Name of the tree-level estimate variable (e.g., 'VOLCFNET').
estvar.filter	String. A tree-level filter for estvar. Must be R syntax (e.g., 'STATUSCD == 1').
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.
landarea	String. The condition-level filter for defining land area ('ALL', 'FOREST', 'TIMBERLAND'). If landarea='FOREST', COND_STATUS_CD = 1; if landarea='TIMBERLAND', SITECLCD in(1:6) & RESERVCD = 0.
pcfilter	String. A filter for plot or cond attributes (including pltassgn). Must be R logical syntax.
rowvar	String. Optional. Name of domain variable to group estvar by for rows in table output. Rowvar must be included in an input data frame (i.e., plt, cond, tree). If no rowvar is included, an estimate is returned for the total estimation unit. Include colvar for grouping by 2 variables.
colvar	String. Optional. If rowvar != NULL, name of domain variable to group estvar by for columns in table output. Colvar must be included in an input data frame (i.e., plt, cond, tree).
prednames	String vector. Name(s) of predictor variables to include in model.
modelselect	Logical. If TRUE, an elastic net regression model is fit to the entire plot level data, and the variables selected in that model are used for the proceeding estimation.
FIA	Logical. If TRUE, the finite population term is removed from estimator to match FIA estimates.
bootstrap	Logical. If TRUE, returns bootstrap variance estimates, otherwise uses Horvitz-Thompson estimator under simple random sampling without replacement.
returntitle	Logical. If TRUE, returns title(s) of the estimation table(s).
savedata	Logical. If TRUE, saves table(s) to outfolder.
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.
gui	Logical. If gui, user is prompted for parameters.
modelselect_bydomain	Logical. If TRUE, modelselection will occur at the domain level as specified by rowvar and/or colvar and not at the level of the entire sample.
...	Parameters for modMApop() if MApopdat 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 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 (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.
	pltassgn	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

If FIA=TRUE or unitvar=NULL and colvar=NULL, one data frame is returned with tree estimates and percent sample errors. Otherwise, a list is returned with tree estimates in one data frame (est) and percent sample errors in another data frame (est.pse). If rawdata=TRUE, another list is returned including raw data used in the estimation process. If addtitle=TRUE and returntitle=TRUE, the title for est/pse is returned. If savedata=TRUE, all data frames are written to outfolder.

est	Data frame. Tree estimates by rowvar, colvar (and estimation unit). If FIA=TRUE or one estimation unit and colvar=NULL, estimates and percent sampling error are in one data frame.
pse	Data frame. Percent sampling errors for estimates by rowvar and colvar (and estimation unit).
titlelst	List with 1 or 2 string vectors. If returntitle=TRUE a list with table title(s). The list contains one title if est and pse are in the same table and two titles if est and pse are in separate tables.
raw	List of data frames. If rawdata=TRUE, a list including: number of plots by plot status, if in dataset (plotsampcnt); number of conditions by condition status (condsampcnt); data used for post-stratification (stratdat); and 1-8 tables with calculated variables used for processing estimates and percent sampling error for table cell values and totals (See processing data below).

Raw data

plotsampcnt	Table. Number of plots by plot status (ex. sampled forest on plot, sampled nonforest, nonsampled).
condsampcnt	DF. Number of conditions by condition status (forest land, nonforest land, noncensus water, census water, nonsampled).
stratdat	Data frame. Strata information by estimation unit.

	Variable	Description
	ESTUNIT	estimation unit
	STRATA	strata
	ACRES	area by strata for estimation unit
	n.strata	number of plots in strata (and estimation unit)
	n.total	number of plots for estimation unit
	TOTACRES	total area for estimation unit
	strwt	proportion of area (or number of plots) by strata (strata weight)
	expfac.strata	expansion factor (in area unit (e.g., acres) by strata (areavar/n.strata)

processing data

Data frames. Separate data frames containing calculated variables used in estimation process. The number of processing tables depends on the input parameters. The tables include: total by estimation unit (unit.totest); rowvar totals (unit.rowest), and if colvar is not NULL, colvar totals, (unit.colvar); and a combination of rowvar and colvar (unit.grpvar). If FIA=TRUE, the raw data for the summed estimation units are also included (totest, rowest, colest, grpest, respectively). These tables do not included estimate proportions (nhat and nhat.var). The data frames include the following information: Variable Description nhat estimated proportion of trees nhat.var estimated variance of estimated proportion of trees ACRES total area for estimation unit est estimated area of trees nhat*ACRES est.var estimated variance of estimated area of trees nhat.var*areavar^2 est.se standard error of estimated area of trees sqrt(est.var) est.cv coefficient of variation of estimated area of trees est.se/est pse percent sampling error of estimate est.cv*100 CI99left left tail of 99 percent confidence interval for estimated area CI99right right tail of 99 percent confidence interval for estimated area CI95left left tail of 95 percent confidence interval for estimated area CI95right right tail of 95 percent confidence interval for estimated area CI67left left tail of 67 percent confidence interval for estimated area CI67right right tail of 67 percent confidence interval for estimated area

Table(s) are also written to outfolder.

Note

ADJUSTMENT FACTOR:
The adjustment factor is necessary to account for nonsampled conditions. It is calculated for each estimation unit by strata. by summing the unadjusted proportions of the subplot, microplot, and macroplot (i.e. *PROP_UNADJ) and dividing by the number of plots in the strata/estimation unit).

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.

sumunits:
An estimation unit is a population, or area of interest, with known area and number of plots. Individual counties or combined Super-counties are common estimation units for FIA. An estimation unit may also be a subpopulation of a larger population (e.g., Counties within a State). Subpopulations are mutually exclusive and independent within a population, therefore estimated totals and variances are additive. For example, State-level estimates are generated by summing estimates from all subpopulations within the State (Bechtold and Patterson. 2005. Chapter 2). Each plot must be assigned to only one estimation unit.

stratcombine:
If MAmethod='PS', and stratcombine=TRUE, and less than 2 plots in any one estimation unit, all estimation units with 10 or less plots are combined. The current method for combining is to group the estimation unit with less than 10 plots with the estimation unit following in consecutive order (numeric or alphabetical), restrained by survey unit (UNITCD) if included in dataset, and continuing until the number of plots equals 10. If there are no estimation units following in order, it is combined with the estimation unit previous in order.

autoxreduce:
If MAmethod='GREG', and autoxreduce=TRUE, and there is an error because of multicolinearity, a variable reduction method is applied to remove correlated variables. The method used is based on the variance-inflation factor (vif) from a linear model. The vif estimates how much the variance of each x variable is inflated due to mulitcolinearity in the model.

rowlut/collut:
There are several objectives for including rowlut/collut look-up tables: 1) to include descriptive names that match row/column codes in the input table; 2) to use number codes that match row/column names in the input table for ordering rows; 3) to add rows and/or columns with 0 values for consistency. No duplicate names are allowed.

Include 2 columns in the table:
1-the merging variable with same name as the variable in the input merge table;
2-the ordering or descriptive variable.
If the ordering variable is the rowvar/colvar in the input table and the descriptive variable is in rowlut/collut, set row.orderby/col.orderby equal to rowvar/colvar. If the descriptive variable is the rowvar/colvar in the input table, and the ordering code variable is in rowlut/collut, set row.orderby/col.orderby equal to the variable name of the code variable in rowlut/collut.

UNITS:
The following variables are converted from pounds (from FIA database) to short tons by multiplying the variable by 0.0005. DRYBIO_AG, DRYBIO_BG, DRYBIO_WDLD_SPP, DRYBIO_SAPLING, DRYBIO_STUMP, DRYBIO_TOP, DRYBIO_BOLE, DRYBIOT, DRYBIOM, DRYBIOTB, JBIOTOT, CARBON_BG, CARBON_AG

MORTALITY:
For Interior-West FIA, mortality estimates are mainly based on whether a tree has died within the last 5 years of when the plot was measured. If a plot was remeasured, mortality includes trees that were alive the previous visit but were dead in the next visit. If a tree was standing the previous visit, but was not standing in the next visit, no diameter was collected (DIA = NA) but the tree is defined as mortality.

Common tree filters:

	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

References

Kelly McConville, Becky Tang, George Zhu, Shirley Cheung, and Sida Li (2018). mase: Model-Assisted Survey Estimation. R package version 0.1.2 https://cran.r-project.org/package=mase

Examples

# Set up population dataset (see ?modMApop() for more information)
MApopdat <- modMApop(popTabs = list(tree = FIESTA::WYtree,
                                    cond = FIESTA::WYcond),
                     pltassgn = FIESTA::WYpltassgn,
                     pltassgnid = "CN",
                     unitarea = FIESTA::WYunitarea,
                     unitvar = "ESTN_UNIT",
                     unitzonal = FIESTA::WYunitzonal,
                     prednames = c("dem", "tcc", "tpi", "tnt"),
                     predfac = "tnt")
                     
# Use GREG Estimator to Estimate cubic foot volume of live trees in our
# population
mod1 <- modMAtree(MApopdat = MApopdat,
          MAmethod = "greg",
          estvar = "VOLCFNET",
          estvar.filter = "STATUSCD == 1")
          
str(mod1)
          
# Use GREG Elastic Net Estimator to Estimate basal area of live trees in our
# population
mod2 <- modMAtree(MApopdat = MApopdat,
          MAmethod = "gregEN",
          estvar = "BA",
          estvar.filter = "STATUSCD == 1")
          
str(mod2)

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