modGBratio: Green-Book module - Generate ratio estimates.

In FIESTA: Forest Inventory Estimation and Analysis

Green-Book module - Generate ratio estimates.

Description

Generates per-acre and per-tree estimates by domain and/or tree domain (and estimation unit). Calculations are based on chapter 4 of Scott et al. 2005 ('the green-book') for mapped forest inventory plots. The ratio estimator for estimating per-acre or per-tree by stratum and domain is used, referred to as Ratio of Means (ROM).

Usage

modGBratio(
  GBpopdat,
  estseed = "none",
  ratiotype = "PERACRE",
  woodland = "Y",
  landarea = "FOREST",
  pcfilter = NULL,
  estvarn = NULL,
  estvarn.filter = NULL,
  estvard = NULL,
  estvard.filter = NULL,
  rowvar = NULL,
  colvar = NULL,
  sumunits = TRUE,
  returntitle = FALSE,
  savedata = FALSE,
  table_opts = NULL,
  title_opts = NULL,
  savedata_opts = NULL,
  gui = FALSE,
  ...
)

Arguments

GBpopdat	List. Population data objects returned from modGBpop().
estseed	String. Use seedling data only or add to tree data. Seedling estimates are only for counts (estvar='TPA_UNADJ')-('none', 'only', 'add').
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.
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").
rowvar	String. Name of the row domain variable in cond or tree. If only one domain, rowvar = domain variable. If more than one domain, include colvar. If no domain, rowvar = NULL.
colvar	String. Name of the column domain variable in cond or 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.
...	Parameters for modGBpop() if GBpopdat is NULL.

Details

If variable = NULL, then it will prompt user for input.

Necessary variables:

	Data	Variable	Description
	tree	tuniqueid	Unique identifier for each plot, to link to pltassgn (ex. 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 (ex. 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.

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

Value

A list with estimates with percent sampling error for rowvar (and colvar). If sumunits=TRUE or unitvar=NULL and colvar=NULL, one data frame is returned. Otherwise, a list object is returned with the following information. If savedata=TRUE, all data frames are written to outfolder.

est	Data frame. Tree estimates by rowvar, colvar (and estimation unit). If sumunits=TRUE or one estimation unit and colvar=NULL, estimates and percent sampling error are in one data frame.
pse	Data frame. Percent sampling errors (Confidence level 68 colvar (and estimation unit). Note: for 95 percent sampling error by 1.96.
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 the processing data used for estimation including: number of plots and conditions; stratification information; and 1 to 8 tables with calculated values for table cells 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.
stratdat	Data frame. Strata information by estimation unit.

	Variable	Description
	unitvar	estimation unit
	strvar	stratum value
	strwtvar	number of pixels by strata and estimation unit
	n.strata	number of plots in strata (after totally nonsampled plots removed)
	n.total	number of plots for estimation unit
	strwt	proportion of area (or plots) by strata and estimation unit (i.e., strata weight)
	CONDPROP_UNADJ_SUM	summed condition proportion by strata and estimation unit
	CONDPROP_ADJFAC	adjusted condition proportion by strata after nonsampled plots removed

processing data

Data frames. Separate data frames of variables used in estimation process for the rowvar, colvar and combination of rowvar and colvar (if colvar is not NULL), and grand total by estimation unit (unit.rowest, unit.colest, unit.grpest, unit.totest, respectively) and summed estimation units, if sumunits=TRUE (roweset, colest, grpest, totest, respectively). The data frames include the following information: Variable Description nhat estimated proportion of trees for numerator nhat.var variance estimate of estimated proportion of trees for numerator dhat estimated proportion of trees for denominator dhat.var variance estimate of estimated proportion of trees for denominator covar covariance for ratio NBRPLT.gt0 Number of non-zero plots used in estimates ACRES total area for estimation unit estn estimated area of trees, for numerator nhat*ACRES estn.var variance estimate of estimated area of trees nhat.var*areavar^2 estd estimated area of land (ratiotype="PERACRE"), for denominator dhat*areavar estd.var variance of estimated area, for denominator dhat.var*areavar^2 estd.covar estimated covariance of numerator and denominator covar*areavar^2 rhat estimated ratio estn/estd rhat.var variance estimate of estimation ratio estn.var+rhat^2*estd.var-2*rhat*est.covar)/estd^2 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.

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.

STRATA:
Stratification is used to reduce variance in population estimates by partitioning the population into homogenous classes (strata), such as forest and nonforest. For stratified sampling methods, the strata sizes (weights) must be either known or estimated. Remotely-sensed data is often used to generate strata weights with proporation of pixels by strata. If stratification is desired (strata=TRUE), the required data include: stratum assignment for the center location of each plot, stored in either pltassgn or cond; and a look-up table with the area or proportion of the total area of each strata value by estimation unit, making sure the name of the strata (and estimation unit) variable and values match the plot assignment name(s) and value(s).

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.

If sumunits=TRUE, estimates are generated by estimation unit, summed together, and returned as one estimate. If rawdata=TRUE, estimates by individual estimation unit are also returned.

If sumunits=FALSE, estimates are generated and returned by estimation unit as one data frame. If savedata=TRUE, a separate file is written for each estimation unit.

stratcombine:
If 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.

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 (in NIMS) 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, Paul L. Patterson, Elizabeth A. Freeman

References

Scott, Charles T.; Bechtold, William A.; Reams, Gregory A.; Smith, William D.; Westfall, James A.; Hansen, Mark H.; Moisen, Gretchen G. 2005. Sample-based estimators used by the Forest Inventory and Analysis national information management system. Gen. Tech. Rep. SRS-80. Asheville, NC: U.S. Department of Agriculture, Forest Service, Southern Research Station, p.53-77.

Examples

GBpopdat <- modGBpop(
popTabs = list(cond = FIESTA::WYcond,  
               tree = FIESTA::WYtree,        
               seed = FIESTA::WYseed),      
popTabIDs = list(cond = "PLT_CN"),            
pltassgn = FIESTA::WYpltassgn,  
pltassgnid = "CN",        
pjoinid = "PLT_CN",         
unitarea = FIESTA::WYunitarea,
unitvar = "ESTN_UNIT",        
strata = TRUE,           
stratalut = WYstratalut,    
strata_opts = strata_options(getwt = TRUE)   
)

## Total net cubic-foot volume of live trees (at least 5 inches diameter), Wyoming, 2011-2013 
ratio1.1 <- modGBratio(
GBpopdat = GBpopdat,         # pop - population calculations
landarea = "TIMBERLAND",     # est - forest land filter
sumunits = TRUE,             # est - sum estimation units to population
estvarn = "VOLCFNET",               # est - net cubic-foot volume, numerator
estvarn.filter = "STATUSCD == 1",   # est - live trees only, numerator
returntitle = TRUE           # out - return title information
)
str(ratio1.1, max.level = 1)

ratio1.2 <- modGBratio(
GBpopdat = GBpopdat,         # pop - population calculations
landarea = "TIMBERLAND",     # est - forest land filter
sumunits = TRUE,             # est - sum estimation units to population
estvarn = "VOLCFNET",               # est - net cubic-foot volume
estvarn.filter = "STATUSCD == 1",   # est - live trees only
rowvar = "FORTYPCD",         # est - row domain 
returntitle = TRUE           # out - return title information
)
str(ratio1.2, max.level = 1)

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