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

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

modMAratio(
  MApopdat,
  ratiotype = "PERACRE",
  woodland = "Y",
  landarea = "FOREST",
  estseed = "none",
  pcfilter = NULL,
  estvarn = NULL,
  estvarn.filter = NULL,
  estvard = NULL,
  estvard.filter = NULL,
  prednames = NULL,
  FIA = TRUE,
  rowvar = NULL,
  colvar = NULL,
  sumunits = TRUE,
  returntitle = FALSE,
  savedata = FALSE,
  table_opts = NULL,
  title_opts = NULL,
  savedata_opts = NULL,
  gui = FALSE,
  bootstrap = FALSE,
  modelselect = FALSE,
  ...
)

Arguments

MApopdat

List. Population data objects returned from modMApop().

ratiotype

String. The type of ratio estimates ("PERACRE", "PERTREE").

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 sample area filter for estimates ("FOREST", "TIMBERLAND"). If landarea=FOREST, filtered to COND_STATUS_CD = 1; If landarea=TIMBERLAND, filtered to SITECLCD in(1:6) and RESERVCD = 0.

estseed

String. Use seedling data only or add to tree data. Seedling estimates are only for counts (estvar='TPA_UNADJ')-('none', 'only', 'add').

pcfilter

String. A filter for plot or cond attributes (including pltassgn). Must be R logical syntax.

estvarn

String. Name of the tree estimate variable (numerator).

estvarn.filter

String. A tree filter for the estimate variable (numerator). Must be R syntax (e.g., "STATUSCD == 1").

estvard

String. Name of the tree estimate variable (denominator).

estvard.filter

String. A tree filter for the estimate variable (denominator). Must be R syntax (e.g., "STATUSCD == 1").

prednames

String vector. Name(s) of predictor variables to include in model.

FIA

Logical. If TRUE, the finite population term is removed from estimator to match FIA estimates.

rowvar

String. Optional. Name of domain variable to group estvarn and estvard 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 estvarn and estvard by for columns in table output. Colvar must be included in an input data frame (i.e., plt, cond, tree).

sumunits

Logical. If TRUE, estimation units are summed and returned in one table.

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.

bootstrap

Logical. If TRUE, returns bootstrap variance estimates, otherwise uses Horvitz-Thompson estimator under simple random sampling without replacement.

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.

...

Parameters for modMApop() if MApopdat is NULL.

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

unitarea

DF. Area by estimation unit.

expcondtab

DF. Condition-level area expansion factors.

tdomdat

DF. Final data table used for estimation.

The data frames include the following information:

	Variable	Description
	rhat	estimated ratio estn/estd
	rhat.var	variance estimate of estimated ratio estn/estd
	NBRPLT Number of plots used in estimates
NBRPLT.gt0	Number of non-zero plots used in estimates
ACRES	total area for estimation unit
rhat.se	estimated standard error of ratio sqrt(rhat.var)
rhat.cv	estimated coefficient of variation of ratio rhat.se/rhat
rhat.pse	estimated percent standard error or ratio rhat.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.

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

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.

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

References

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

Author

Josh Yamamoto