FIESTA Manual - Module Estimates

Estimates

Estimation Filters

Filters subset the area of the sample population for the desired output. Filters do no change the population data used for estimate (e.g., number of plots, strata weights). Some filters are defined internally, depending on the dataset, such as land area of interest (landarea) or inclusion of ACI (All Condition Inventory) data. Others are specified according to the input table, such as pfilter or cfilter. The nonsamp.filter is for removing nonsampled conditions and is applied, internally, unless otherwise stated. All filter expressions must be in R syntax.

• landarea - A predefined cond filter depending on desired sample land area {ALL, FOREST (COND_STATUS_CD=1), TIMBERLAND (SITECLCD in(1:6) & RESERVCD=0)}.
• pcfilter - Plot/Condition-level filter.

Tree information for tree estimates - modGBtree()

Tree information is used for calculating estimates for derived tree data, such as basal area (BA), volume (e.g., VOLCFNET), or number of trees (i.e., TPA_UNADJ). All variables except number of tree variables are extrapolated to the acre plot size by multiplying by TPA_*).

• estvar - Name of estimate variable in tree (e.g., VOLCFNET, TPA_UNADJ).
• estvar.filter - Tree-level filter (e.g., ‘STATUS_CD == 1 & DIA >= 5.0’).
• estvar.name - A name for aggregated estvar (Default = estvar’_SUM’).

Tree information for ratio estimates - modGBratio()

Tree information is used for calculating per-acre ratio estimates (numerator) and per-tree ratio estimates (numerator and denominator) from derived tree data, such as basal area (BA), volume (e.g., VOLCFNET), or number of trees (i.e., TPA_UNADJ). All variables except number of tree variables are extrapolated to the acre plot size by multiplying by TPA_*).

• ratiotype - If ratio estimate, the ratio type (“PERACRE”, “PERTREE”).
• estvar(n) - Numerator - Name of estimate variable (e.g., VOLCFNET, TPA_UNADJ)
• estvar(n).filter - Numerator - Tree-level filter(s).
• estvar(n).name - Numerator - A name for aggregated estvar (Default = estvar(n)’_SUM’).
• estvard - Denominator - Name of estimate variable (e.g., VOLCFNET, TPA_UNADJ)
• estvard.filter - Denominator - Tree-level filter(s).
• estvard.name - Denominator - A name for aggregated estvar (Default = estvard’_SUM’).

Table estimates

Estimates can be broken down by categorical domains for further detail about a population. These details are presented as rows or rows and columns in a matrix table, with a separate, associated sampling error for each cell in the table. If the area of interest (i.e., population) has more than one estimation unit (i.e., subpopulation), estimates may be presented by estimation unit or summed to the population.

• rowvar - Name of row variable (domain). If area estimate, rowvar must be from cond (e.g., FORTYPCD). If tree or ratio estimate, rowvar can be from cond or tree (e.g., SPCD).
• colvar - Name of column variable (domain). If area estimate, colvar must be from cond (e.g., FORTYPCD). If tree or ratio estimate, colvar can be from cond or tree (e.g, SPCD).
• sumunits - TRUE, sum estimates by estimation units (sub-populations) into one estimate (e.g., Counties to State).

Other

• returntitle - TRUE, return table titles (See title_opts for more title parameters)
• savedata - TRUE, save data to outfolder (See savedata_opts for more savedata parameters).

Output table options (table_opts)

The following parameters provide more detail about the presentation and aesthetics of the final output table, including: using code names instead of codes; applying specific ordering; adding categories not in the data set with 0 values; displaying percent standard errors and estimates together or separate; and rounding options. These parameters are set by supplying a list to the table_opts parameter. The possible parameters that can be set within the table_opts parameter can be seen by running help(table_options).

• row.FIAname - TRUE, gets FIA reference name for rowvar, if available (FIESTA::getRefcodes(rowvar) for availability).
• col.FIAname - TRUE, gets FIA reference name for colvar, if available (FIESTA::getRefcodes(rowvar) for availability).
• row.orderby - Name of variable to order values of rowvar (if row.FIAname=FALSE).
• col.orderby - Name of variable to order values of colvar (if col.FIAname=FALSE).
• row.add0 - TRUE, add 0 value in table for row values that occur in FIESTA::getRefcodes(rowvar) or in rowlut, but are not in final estimate.
• col.add0 - TRUE, add 0 value in table for column values that occur in FIESTA::getRefcodes(colvar) or in collut, but are not in final estimate.
• rowlut - A lookup table with variable codes and descriptions to include in rows of output table (See note following for more details).
• collut - A lookup table with specific variable codes and descriptions to include in columns of output table (See note following for more details).
• rawonly - If TRUE, only raw data are returned (this option is more efficient for estimates with many estimation units, rows, and/columns).
• raw.keep0 - If TRUE, keeps 0 values in raw data tables. If FALSE, removes 0 values for efficient output.
• allin1 - TRUE, table cells include: estimates (% sample error).
• metric - TRUE, output is returned in metric units.
• estround - Number of digits to round estimates to.
• pseround - Number of digits to round percent sample error (pse) to.
• estnull - Number or character to indicate ‘not sampled’ for estimate.
• psenull - Number or character to indicate ‘not sampled’ for percent sample error (pse).
• divideby - Conversion of output numbers (‘hundred’, ‘thousand’, ‘million’).

Note: 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.

Title parameters (title_opts)

If returntitle=TRUE, a default title is generated based on the estimation parameters above. The following parameters allow user-defined inputs for generating customized titles. These parameters are set by supplying a list to the title_opts parameter. The possible parameters that can be set within the title_opts parameter can be seen by running help(title_options).

• title.main - Full title for table.
• title.ref - The ending text for table title. If not NULL, included with title.main.
• title.rowvar - Pretty name for rowvar for table title (If NULL, default = rowvar).
• title.colvar - Pretty name for colvar for table title (If NULL, default = colvar).
• title.unitvar - Pretty name for unitvar for table title (If NULL and sumunits=FALSE, default = unitvar).
• title.estvar - Pretty name for estvar for table title (If NULL, default = estvar). For ratio estimates, title.estvarn (default = estvarn) and title.estvard (default = estvard).
• title.filter - Pretty name for any filters for table title.

Saving data specifications (savedata_opts)

If savedata=TRUE, output is saved using default settings. The following parameters specify different options for saving output. These parameters are set by supplying a list to the savedata_opts parameter. The possible parameters that can be set within the savedata_opts parameter can be seen by running help(savedata_options).

• outfolder - Name of folder to output data to (Default = working directory or window to browse).
• out_fmt - Format of output data tables (‘sqlite’, ‘gpkg’, ‘csv’, ‘gdb’).
• out_dsn - TRUE, data source name of database to output data tables.
• outfn.pre - Add a prefix to output name (e.g., ’01_*’).
• outfn.date - Add date (YYYYMMDD) to output name (e.g., ’*_20200220’).
• addtitle - TRUE, add title to tables.
• raw_fmt - Format of raw data tables (‘sqlite’, ‘gpkg’, ‘csv’, ‘gdb’).
• raw_dsn - TRUE, data source name of database to output raw data tables.
• overwrite_dsn - TRUE, overwrites existing data source name database files (e.g., sqlite).
• overwrite_layer - TRUE, overwrites layer within a database or file in outfolder, if exists.
• append_layer - TRUE, appends output to existing layer in database or file in outfolder.

Raw data used for producing estimates (If rawdata=TRUE, raw$):

The raw data includes the domain-level data set used for estimation and separate data frames with calculated variables used in estimation process. The number of processing tables depends on the input parameters. The tables include:

• raw$domdat - Plot domain data used for estimation.
• raw$unit_totest - Total by estimation unit
• raw$unit_rowest - If rowvar != NULL, rowvar totals by estimation unit
• raw$unit_colvar - If colvar != NULL, colvar totals by estimation unit
• raw$unit_grpvar - If colvar != NULL, a combination of rowvar and colvar by estimation unit
• If sumunits=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). See below for variable descriptions.
• raw$totest - Total by estimation unit, summed to population
• raw$rowest - If rowvar != NULL, rowvar totals by estimation unit, summed to population
• raw$colvar - If colvar != NULL, colvar totals by estimation unit, summed to population
• raw$grpvar - If colvar != NULL, a combination of rowvar and colvar by estimation unit, summed to population

Description of variables in nonratio tables.

Variable	Description
nhat	Estimated proportion
nhat.var	Variance estimate of estimated proportion
est	Estimated acres { nhat * ACRES }
est.var	Variance estimate of estimated acres { nhat * ACRES^2 }

Description of variables in nonratio tables.

Variable	Description
nhat	Estimated proportion of land, for numerator
nhat.var	Variance estimate of estimated proportion of land, for numerator
dhat	Estimated proportion of land, for denominator
dhat.var	Variance estimate of estimated proportion of land, for denominator
covar	Covariance of estimated proportion of numerator and denominator
estn	Estimated acres, for numerator
estd	Estimated acres, for denominator
estn.var	Variance estimate of estimate acres, for numerator
estn.se	Standard error estimated acres, for numerator
estn.cv	Coefficient of variation of estimated acres, for numerator
estn.pse	Percent sampling error of estimate, for numerator
estd.var	Variance estimate of estimate acres, for denominator
estd.se	Standard error estimated acres, for denominator
estd.cv	Coefficient of variation of estimated acres, for denominator
estd.pse	Percent sampling error of estimate, for denominator
est.covar	Covariance of estimated acres of numerator and denominator
rhat	Ratio of estimated proportions (numerator/denominator)
rhat.var	Variance of ratio of estimated proportions
rhat.se	Standard error of ratio of estimated proportions { rhat.se/rhat }
rhat.cv	Coefficient of variation of ratio of estimated proportions { sqrt(rhat.var) }
est	Estimated percent cover of land { rhat*100 }
est.var	Variance of estimated percent cover of land { rhat.var*100^2 }

Description of variables in nonratio and ratio tables.

Variable	Description
NBRPLT.gt0	Number of nonzero plots used in estimate
ACRES	Total acres for estimation unit
est.se	Standard error of estimated acres { sqrt(est.var) }
est.cv	Coefficient of variation of estimated acres { est.se/est }
pse	Percent sampling error of estimate { est.cv * 100 }
CI99left	Left tail of 99% confidence interval for estimate { est - (2.58*est.se) }
CI99right	Right tail of 99% confidence interval for estimate { est + (2.58*est.se) }
CI95left	Left tail of 95% confidence interval for estimate { est - (1.96*est.se) }
CI95right	Right tail of 95% confidence interval for estimate { est + (1.96*est.se) }
CI68left	Left tail of 68% confidence interval for estimate { est - (0.97*est.se) }
CI68right	Right tail of 68% confidence interval for estimate { est + (0.97*est.se) }