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.

Usage

modMAtree(
  MApopdat,
  MAmethod,
  estvar,
  estvar.filter = NULL,
  estvar.derive = 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,
  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').
estvar.derive: List. A derivation of a tree variable to estimate. Must be a named list with one element (e.g., list(SDI='SUM(POWER(DIA/10,1.605) * TPA_UNADJ)'). Set estvar = NULL.
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.
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.

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.

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.

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.2 https://cran.r-project.org/package=mase

Author

Tracey S. Frescino

Examples

# \donttest{
# 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")
#> variables are missing from dataset: STATECD, UNITCD, COUNTYCD, PLOT, PLOT_STATUS_CD, PLOT_NONSAMPLE_REASN_CD, INTENSITY, SUBCYCLE, MACRO_BREAKPOINT_DIA
#> SURVEY table does not exist in database... assuming annual inventory plots
#> INVYR not in input data...  no invyrs returned...
#> SUBCYCLE not in data... assuming all SUBCYCLE <> 99
#> removing nonsampled forest plots...
#> returning data needed for estimation...
#> there are 14 nonsampled conditions
                     
# 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")
#> generating estimates using mase::greg function...
#> using the following predictors...dem, tcc, tpi, tnt2
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> model resulted in negatives... indicating model instability
#> getting output...
          
str(mod1)
#> List of 4
#>  $ est    :'data.frame':	23 obs. of  3 variables:
#>   ..$ ESTN_UNIT             : chr [1:23] "1" "11" "13" "15" ...
#>   ..$ Estimate              : num [1:23] 9.45e+08 2.03e+09 1.05e+09 0.00 6.44e+08 ...
#>   ..$ Percent Sampling Error: num [1:23] 27.3 17 47.2 NaN 49.7 ...
#>  $ raw    :List of 13
#>   ..$ unit_totest  :'data.frame':	23 obs. of  17 variables:
#>   .. ..$ ESTN_UNIT : chr [1:23] "1" "11" "13" "15" ...
#>   .. ..$ nhat      : num [1:23] 343 1105 178 0 502 ...
#>   .. ..$ nhat.var  : num [1:23] 8760 35428 7052 0 62173 ...
#>   .. ..$ NBRPLT    : int [1:23] 24 26 53 2 8 22 2 38 7 2 ...
#>   .. ..$ NBRPLT.gt0: int [1:23] 23 26 46 0 5 21 2 37 5 2 ...
#>   .. ..$ AREAUSED  : num [1:23] 2757613 1837124 5930088 1428579 1283969 ...
#>   .. ..$ est       : num [1:23] 9.45e+08 2.03e+09 1.05e+09 0.00 6.44e+08 ...
#>   .. ..$ est.var   : num [1:23] 6.66e+16 1.20e+17 2.48e+17 0.00 1.02e+17 ...
#>   .. ..$ est.se    : num [1:23] 2.58e+08 3.46e+08 4.98e+08 0.00 3.20e+08 ...
#>   .. ..$ est.cv    : num [1:23] 0.273 0.17 0.472 NaN 0.497 ...
#>   .. ..$ pse       : num [1:23] 27.3 17 47.2 NaN 49.7 ...
#>   .. ..$ CI99left  : num [1:23] 2.81e+08 1.14e+09 0.00 0.00 0.00 ...
#>   .. ..$ CI99right : num [1:23] 1.61e+09 2.92e+09 2.34e+09 0.00 1.47e+09 ...
#>   .. ..$ CI95left  : num [1:23] 4.40e+08 1.35e+09 7.84e+07 0.00 1.65e+07 ...
#>   .. ..$ CI95right : num [1:23] 1.45e+09 2.71e+09 2.03e+09 0.00 1.27e+09 ...
#>   .. ..$ CI68left  : num [1:23] 6.89e+08 1.69e+09 5.59e+08 0.00 3.26e+08 ...
#>   .. ..$ CI68right : num [1:23] 1.20e+09 2.37e+09 1.55e+09 0.00 9.62e+08 ...
#>   ..$ domdat       :'data.frame':	590 obs. of  5 variables:
#>   .. ..$ PLT_CN               : chr [1:590] "40404729010690" "40404730010690" "40404737010690" "40404738010690" ...
#>   .. ..$ CONDID               : int [1:590] 1 1 2 1 1 1 2 1 1 1 ...
#>   .. ..$ TOTAL                : int [1:590] 1 1 1 1 1 1 1 1 1 1 ...
#>   .. ..$ TOTAL                : int [1:590] 1 1 1 1 1 1 1 1 1 1 ...
#>   .. ..$ VOLCFNET_TPA_ADJ_live: num [1:590] 41.8 1563 14.9 137.5 448.7 ...
#>   ..$ plotweights  :Classes ‘data.table’ and 'data.frame':	556 obs. of  5 variables:
#>   .. ..$ ESTN_UNIT  : Factor w/ 23 levels "1","3","5","7",..: 1 1 1 1 1 1 1 1 1 1 ...
#>   .. ..$ TOTAL      : int [1:556] 1 1 1 1 1 1 1 1 1 1 ...
#>   .. ..$ CN         : chr [1:556] "40404729010690" "40404730010690" "40404737010690" "40404738010690" ...
#>   .. ..$ weights    : num [1:556] 0.0854 0.0135 0.0375 0.0259 0.0997 ...
#>   .. ..$ areaweights: num [1:556] 5347694 844154 2347478 1618639 6240620 ...
#>   .. ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..$ estvar       : chr "VOLCFNET"
#>   ..$ estvar.filter: chr "STATUSCD == 1"
#>   ..$ module       : chr "MA"
#>   ..$ esttype      : chr "TREE"
#>   ..$ MAmethod     : chr "greg"
#>   ..$ predselectlst:List of 1
#>   .. ..$ totest:Classes ‘data.table’ and 'data.frame':	23 obs. of  6 variables:
#>   .. .. ..$ ESTN_UNIT: Factor w/ 23 levels "1","3","5","7",..: 1 2 3 4 5 6 7 8 9 10 ...
#>   .. .. ..$ TOTAL    : int [1:23] 1 1 1 1 1 1 1 1 1 1 ...
#>   .. .. ..$ dem      : num [1:23] -100 778 -211 357 -106 ...
#>   .. .. ..$ tcc      : num [1:23] 515 362.7 50.9 59.7 537.3 ...
#>   .. .. ..$ tpi      : num [1:23] 117.3 251.1 38.3 89.4 165 ...
#>   .. .. ..$ tnt2     : num [1:23] 117.9 181.1 -509.7 -360.4 72.9 ...
#>   .. .. ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..$ rowvar       : chr "TOTAL"
#>   ..$ colvar       : chr "NONE"
#>   ..$ areaunits    : chr "acres"
#>   ..$ estunits     : chr "cubic feet"
#>  $ statecd: int 56
#>  $ states : chr "Wyoming"
# }