Package 'FIESTA'

EcoMap SpatialPolygonsDataFrame

Description

Contains regional geographic delineations for analysis of ecological relationships across ecological units. ECOMAP is the term used for a USDA Forest Service initiative to map ecological units and encourage their use in ecosystem-based approaches to forest land conservation and management. It is coordinated at the national and regional levels by USDA Forest Service staff and implemented in cooperation with State forestry agencies and others. ECOMAP mapping criteria are outlined in the National Hierarchical Framework of Ecological Units (https://www.ncrs.fs.fed.us/gla/reports/hierarch- y.htm). The framework systematically divides the country into progressively smaller areas of land and water that have similar physical and biological characteristics and ecological processes.

Details

The EcoMap Provinces feature class contains ecological province polygons attributed with names and descriptions. The EcomapSections 2007 data set describes the ecological sections within the conterminous United States. The EcomapSubections 2007 data set describes the ecological subsections within the conterminous United States.

Converted to simple feature
Transformed CRS from longlat(EPSG:4269) to Albers (EPSG:5070)
Saved to R object, with compression='xz'

FIESTA - Forest Inventory Estimation for Analysis

FIESTA is a research estimation tool for analysts that work with sample-based inventory data from the U.S. Department of Agriculture, Forest Service, Forest Inventory and Analysis (FIA) Program.

FIESTA can generate FIA's traditional state-wide estimates while also accommodate: unique population boundaries, different evaluation time periods, customized stratification schemes, non-standard variance equations, integration of multi-scale remotely-sensed data and other auxiliary information, and interaction with other modeling and estimation tools from CRAN's library of packages.

FIESTA contains a collection of functions that can query FIA databases, summarize and compile plot and spatial data, and generate estimates with associated sampling errors.

Author(s)

Tracey S. Frescino Maintainer: Tracey S. Frescino

References

Bechtold, William A.; Patterson, Paul L.; [Editors] 2005. The enhanced forest inventory and analysis program - national sampling design and estimation procedures. Gen. Tech. Rep. SRS-80. Asheville, NC: U.S. Department of Agriculture, Forest Service, Southern Research Station. 85p.

R Development Core Team (2011). R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria. ISBN 3-900051-07-0, URL http://www.R-project.org/.

Burrill, E.A., Wilson, A.M., Turner, J.A., Pugh, S.A., Menlove, J., Christiansen, G., Conkling, B.L., Winnie, D., 2018. Forest Inventory and Analysis Database [WWW Document]. St Paul MN US Dep. Agric. For. Serv. North. Res. Stn. URL http://apps.fs.fed.us/fiadb-downloads/datamart.html (accessed 3.6.21).

See Also

Useful links:

• https://usdaforestservice.github.io/FIESTA/

• https://github.com/USDAForestService/FIESTA

• Report bugs at https://github.com/USDAForestService/FIESTA/issues

---

Data - Generates frequency barplot.

Description

Generate a barplot of from a frequency data frame.

Usage

datBarplot(
  x,
  xvar = NULL,
  yvar = "FREQ",
  grpvar = NULL,
  errbars = FALSE,
  x.order = NULL,
  sevar = NULL,
  psevar = NULL,
  device.type = "dev.new",
  jpeg.res = 300,
  device.height = 5,
  device.width = 8,
  horiz = FALSE,
  toplabelvar = NULL,
  ylim = NULL,
  divideby = NULL,
  ylabel = NULL,
  xlabel = NULL,
  mar = NULL,
  addlegend = FALSE,
  main = NULL,
  cex.main = 1,
  cex.label = 1,
  cex.names = 0.8,
  las.xnames = 0,
  las.ynames = 1,
  savedata = FALSE,
  outfolder = NULL,
  outfn = NULL,
  outfn.pre = NULL,
  outfn.date = TRUE,
  overwrite = FALSE,
  ...
)

Arguments

x	Data frame or comma-delimited file (*.csv) - a frequency table.
xvar	String. Name of X variable.
yvar	String. Name of the y variable (e.g., FREQ).
grpvar	String. Name of the variable for grouping.
errbars	Logical. If TRUE, error bars are added to bar plot (sevar or psevar must also be populated).
x.order	String or Vector. Define order of xvar based on y values: descending ("DESC") or ascending ("ASC") or vector of row numbers. If NULL, the order of the input table is used.
sevar	String. Name of the variable with standard error values.
psevar	String. Name of the variable with percent standard error.
device.type	String. Type(s) of device for plotting ("dev.new", "jpg", "pdf").
jpeg.res	Integer. Resolution for jpeg image.
device.height	Integer. Height (in inches) of barplot, if writing to file.
device.width	Integer. Width (in inches) of barplot, if writing to file.
horiz	Logical. If TRUE, bars are drawn horizontally with first bar at the bottom. If FALSE, bars are drawn vertically with first bar to the left (barplot parameter).
toplabelvar	String. Name of variable in x for adding labels to place above each bar (e.g., NBRPLOTS.gt0).
ylim	Number. A vector of min and max values, c(min,max) for the y axis (or x axis if horiz=TRUE). If NULL, defaults to maximum y value. If errbars=TRUE, the ylim defaults to the maximum y value plus the standard error.
divideby	String. Conversion number for output ('hundred', 'thousand', 'million').
ylabel	String. Label for the y axis (same as ylab).
xlabel	String. Label for the x axis (same as xlab).
mar	See par.. A numerical vector representing number of lines for margins (c(bottom, left, top, right).
addlegend	Logical. If TRUE, adds legend to bar plot (only applicable if grouping).
main	String. Title for plot.
cex.main	Number. Expansion factor for title.
cex.label	Number. A number representing cex in barplot (size expansion of x and/or ylabels.
cex.names	Number. Expansion factor for axis names (bar labels) (e.g., 0.5 represents half the size.
las.xnames	Number. The direction of x variable names (0,1,3). 0:diagonal (Default), 1:horizontal; 3:vertical.
las.ynames	Number. The direction of y variable names (0,1,3). 0:diagonal (Default), 1:horizontal; 3:vertical.
savedata	Logical. If TRUE, writes output data to outfolder (jpg and pdf).
outfolder	String. The name of the output folder. If savedata=TRUE, all output saved to the outfolder. If savedata=FALSE, only a text file of input parameters is saved.
outfn	String. The name of the output file if savedata=TRUE (*.csv). Do not include extension. If NULL, the file will be named BARPLOT_'yvar_date'.csv
outfn.pre	String. Add a prefix to output name (e.g., "01").
outfn.date	Logical. If TRUE, add date to end of outfile (e.g., outfn_'date'.csv).
overwrite	Logical. If TRUE and exportshp=TRUE, overwrite files in outfolder.
...	additional arguments to pass to barplot(), including a list of arguments for legend() arguments (e.g., args.legend=list(x="topleft", bty="n"), for moving legend to topleft and removing box around legend).

Details

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

Value

Outputs barplot to display window.

Note

If savedata = TRUE, writes a jpg and pdf of barplot to outfolder.

To add legend parameters, add a parameter named args.legend, defined as a list of specific legend parameters (see ?legend)... e.g., args.legend=list(x="topright"). If specifying x and y, x defines the lower right corner of legend box and y defines the upper right corner of box.

Author(s)

Tracey S. Frescino

Examples

# Set up data frame for example
ftyptab <- data.frame(cbind(FORTYPCD = c(182, 184, 201, 221, 265),
                            FREQ = c(110, 7, 900, 410, 155),
                            SE = c(10, 11, 18, 14, 22)))
                            
# Create basic barplot                           
datBarplot(x = ftyptab, xvar = "FORTYPCD")
	
# Add standard errors to basic barplot
datBarplot(x = ftyptab, xvar = "FORTYPCD", errbars = TRUE, sevar = "SE")

---

Data - Generates frequency barplot.

Description

Generate a barplot of frequencies in order from most to least.

Usage

datBarStacked(
  x,
  main.attribute,
  sub.attribute,
  response = "phat",
  percent = FALSE,
  LUT.color = NULL,
  color = "rainbow",
  device.type = "default",
  jpeg.res = 300,
  device.width = 9,
  device.height = 6,
  mar = NULL,
  horiz = TRUE,
  bar.lim = NULL,
  bar.ratio = 1,
  ylabel = NULL,
  xlabel = NULL,
  las.xnames = NULL,
  main.order = NULL,
  sub.order = NULL,
  legend.fit = NULL,
  legend.cex = 0.8,
  legend.x = NULL,
  legend.y = NULL,
  legend.title = NULL,
  legend.bty = "o",
  legend.bg = par("bg"),
  legend.inset = 0,
  legend.xpd = par("xpd"),
  main = NULL,
  cex.main = 1,
  cex.label = 1,
  cex.names = 0.8,
  sub.add0 = FALSE,
  savedata = FALSE,
  outfolder = NULL,
  outfn = NULL,
  outfn.pre = NULL,
  outfn.date = TRUE,
  overwrite = FALSE,
  ...
)

Arguments

x	Data frame or comma-delimited file (*.csv) - table of values to be plotted.
main.attribute	String. The column to be used for each bar.
sub.attribute	String. The column to be used to subdivide each bar.
response	String. The column of values to be plotted. Currently defaults to "phat".
percent	Logical. If TRUE, values cover values in a stack are converted to percent of stack.
LUT.color	Data frame or comma-delimited file (*.csv) - look up table for colors. Must contain column with same name as sub.attribute.
color	String. Automated color selection ("rainbow", "topo", "heat", "terrain", "cm").
device.type	String. The type(s) of device for plotting ("default", "jpg", "pdf", or "ps").
jpeg.res	Integer. The resolution for jpeg image.
device.width	Integer. The width of output device (in inches)'
device.height	Integer. The height of output device (in inches)'
mar	See par.. A numerical vector representing number of lines for margins (c(bottom, left, top, right).
horiz	Logical. See barplot. If FALSE, the bars are drawn vertically with the first bar to the left. If TRUE, the bars are drawn horizontally with the first bar at the bottom.
bar.lim	Number vector. Equivalent to xlim or ylim, for whichever is the lengthwise axis in barcharts (ex. c(0,10)). Warning: for lower limits other than zero (ex. c(20,100), will behave strangely because par(xpd) is set to NA.
bar.ratio	Proportion of figure area taken up by barplot vs taken by legend.
ylabel	String. A label for the y axis (same as ylab).
xlabel	String. A label for the x axis (same as xlab).
las.xnames	Number. The direction of x variable names (0,1,2,3). 0:Default, parallel; 1:horizontal; 2:perpendicular; 3:vertical.
main.order	String vector. A vector of main.attribute names in desired order for bars. May also be 'DESC' or 'ASC'.
sub.order	String vector. Avector of sub.attribute names in desired order for stack, with the first name used as the column in each stack. If NULL, the order is based on the overall cover of each sub.attribute. May also be 'DESC' or 'ASC'.
legend.fit	Logical. Should bar.lim be changed to fit the legend of the plot. Will only be used if the legend is on the right side of a horizontal plot or the top of a vertical plot. (i.e. horiz=FALSE).
legend.cex	Number. Expansion factor for legend text.
legend.x	See legend. The x coordinate to be used to position the legend. If horiz=TRUE, suggested options include "topright" or "bottomright". If horiz=FALSE, suggested options include "topleft" or "topright".
legend.y	See legend. The y coordinate to be used to position the legend.
legend.title	See legend. A title for the legend.
legend.bty	See legend. the type of box to be drawn around the legend.
legend.bg	See legend. The background color for the legend box.
legend.inset	See legend. The distance from the margins as a fraction of the plot region.
legend.xpd	See legend.
main	String. Title for plot.
cex.main	Number. Expansion factor for title.
cex.label	Number. A number representing cex in barplot (size expansion of x and/or ylabels.
cex.names	Number. Expansion factor for axis names (bar labels). Ex. 0.5 represents half the size.
sub.add0	Logical. If TRUE, adds categories with 0 values to sub.attribute legend.
savedata	Logical. If TRUE, writes output data to outfolder (jpg and pdf).
outfolder	String. The name of the output folder. If savedata=TRUE, all output saved to the outfolder. If savedata=FALSE, only a text file of input parameters is saved.
outfn	String. The name of the output file if savedata=TRUE (*.csv). Do not include extension. If NULL, the file will be named BARPLOT_'yvar_date'.csv
outfn.pre	String. Add a prefix to output name (e.g., "01").
outfn.date	Logical. If TRUE, add date to end of outfile (e.g., outfn_'date'.csv).
overwrite	Logical. If TRUE and exportshp=TRUE, overwrite files in outfolder.
...	list of additional arguments to pass to barplot(); names of the list are used as argument names.

Details

# Note: This function uses a customized lengthwise axis (y axis if horiz=F, x axis if horiz=T) # Therefore to modify this axis by par commands (other than the # ones specifically included above) may require changing the function. For example par(yaxp) # may not work. # # # The arguments bar.lab and bar.lim are equivalent to xlab/ylab, xlim/ylim, controlling # whichever is the lengthwise axis in the bar charts (as determined by horiz). # # # bar.ratio is only used when bar.lim is specified, it controls what percentage of the # plot area will be occupied by the specified range of the chart itself. For example, setting # bar.lim=c(0,80) and bar.ratio=0.75 will result in the 80 region, leaving 25 the bars are taller than 80 bar.lim is not specified, the function will automatically scale the lengthwise axis so # that all the bars are as tall as possible, but none of the bars over lap the legend. # # The main purpose of specifying bar.lim is if you want multiple forest types to be shown at # the same scale, sacrificing individual forest type details to make the graphs comparable # across forest types. Then you may need to fiddle with bar.ratio till the plots all look good.

Value

Outputs stacked barplot to display window.

Note

If savedata = TRUE, writes a jpg and pdf of barplot to outfolder.

Author(s)

Elizabeth Freeman, Tracey S. Frescino

---

Data - Filters data table.

Description

Subsets a data table by specified filter(s).

Usage

datFilter(
  x,
  xfilter = NULL,
  xfiltervar = NULL,
  othertabnms = NULL,
  uniqueid = "PLT_CN",
  vardelete = NULL,
  title.filter = NULL,
  savedata = FALSE,
  filternm = NULL,
  stopifnull = FALSE,
  returnDT = TRUE,
  xnm = NULL,
  savedata_opts = NULL,
  gui = FALSE
)

Arguments

x	Data frame, sf data frame or comma-delimited file (*.csv). A data frame to filter.
xfilter	String. A filter expression. Must be R syntax. (e.g., "STATUSCD == 1", "INVYR within double quotes (e.g., "SPP == 'Lodgepole'"). If NULL, a window pops up to select filter variable(s) and filter value(s).
xfiltervar	String. The filtervar if you know what it is. If NULL, a window will pop up to select filter value(s).
othertabnms	String vector. Name(s) of the objects or comma-delimited files to subset. Names must be in quotes (e.g., othertables=c('tree', 'cond')).
uniqueid	String. Unique identifier of x. Only needed if othertables != NULL. The uniqueid must be the same for all tables except if PLT_CN and CN.
vardelete	String vector. Vector of variables you would like deleted from filter list. Mostly used for internal queries.
title.filter	String. Title of the filter query window. Mostuly used for internal queries.
savedata	Logical. If TRUE, writes output data to outfolder.
filternm	String. Optional. Name of filter, for feedback purposes.
stopifnull	Logical. If TRUE, stop if output is NULL.
returnDT	Logical. If TRUE, returns a data table. If FALSE, returns a data frame.
xnm	String. Name for filter attribute. Used for warning messages.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'datf'.
gui	Logical. If TRUE, pop-up windows will appear for user-interface.

Details

If no parameters, then user is prompted for input. If partial parameters, default parameter values are used.

Value

A list of the following items:

xf	A data frame of filtered x.
xfilter	The xfilter.

If othertables != NULL, the other tables, named with 'in' prefix

Note

If message returned is 'filter removed all records', either the filter removed all records in x or the filter is incorrect.

Author(s)

Tracey S. Frescino

Examples

# Set up data for example
tab <- data.frame(cbind(CONDCLASS=c(1, 1, 2, 1, 3, 3, 3, 1, 1, 1, 2, 1),
			                   FORTYPCD = c(182, 184, 201, 221, 221, 184, 221, 182,
			                                182, 201, 182, 221)))
			                    
	# Filter for value not equal to 182
	datFilter(x = tab, xfilter = "FORTYPCD != 182")

# Filter on two conditions, grab xf object from list
datFilter(x = WYcond, xfilter = "FORTYPCD == c(221) & STDSZCD == 3")$xf

---

Data - Get frequency table for specified variable(s).

Description

Generates a frequency table from a data frame, including number of records by a specified variable or variables in the data frame with optional totals and/or subtotals.

Usage

datFreq(
  x,
  xvar = NULL,
  total = FALSE,
  subtotal = FALSE,
  subtotalcol = NULL,
  savedata = FALSE,
  savedata_opts = NULL,
  gui = FALSE
)

Arguments

x	Data frame or comma-delimited file (*.csv). The table with the variable(s).
xvar	String (vector).* The name of the variable(s) to summarize.
total	Logical. If TRUE, a row is added to bottom of table with a total for the whole table.
subtotal	Logical. If TRUE, a row is added to bottom of each section for subtotals.
subtotalcol	Logical. If subtotal=TRUE, the column(s) to generate subtotals.
savedata	Logical. If TRUE, writes output data to outfolder.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'datfreq'.
gui	Logical. If TRUE, pop-up windows will appear for user-interface.

Details

If no parameters, then user is prompted for input. If partial parameters, default parameter values are used.

Value

freqtable

Data frame. The frequency table.

If savedata=TRUE, a comma-delimited file of the frequency table is written to the outfolder.

Author(s)

Tracey S. Frescino

Examples

# Set up data for example
tab <- data.frame(cbind(CONDCLASS = c(1, 1, 2, 1, 3, 3, 3, 1, 1, 1, 2, 1), 
		                     FORTYPCD = c(182, 184, 201, 221, 221, 184, 221, 182,
		                                  182, 201, 182, 221)))

# Frequency table with "FORTYPCD"       
datFreq(x = tab,
        xvar = "FORTYPCD")
		                                  
# Frequency table with "CONDCLASS" and "FORTYPCD" 		                                   
datFreq(x = tab,
        xvar = c("CONDCLASS", "FORTYPCD"))

# Frequency table with "CONDCLASS" and "FORTYPCD", adding total and subtotal
# rows 		                                   
datFreq(x = tab,
        xvar = c("CONDCLASS", "FORTYPCD"), 
        total = TRUE, 
        subtotal = TRUE)
        
# Frequency table for WYtree, multiple variables, subtotal options
datFreq(x = FIESTA::WYtree,
        xvar = c("SPGRPCD", "SPCD", "STATUSCD"), 
	       subtotal = TRUE, subtotalcol = "SPCD")

---

Data - Generates line graph.

Description

Generate a line plot of multiple estimates.

Usage

datLineplot(
  x,
  xvar,
  yvar,
  plotCI = FALSE,
  sevar = NULL,
  CIlst = c(68, 95),
  CIcolorlst = c("dark grey", "black"),
  addshade = FALSE,
  device.type = "dev.new",
  jpeg.res = 300,
  device.height = 5,
  device.width = 8,
  ylim = NULL,
  divideby = NULL,
  ylabel = NULL,
  xlabel = NULL,
  xticks = NULL,
  mar = NULL,
  addlegend = FALSE,
  main = NULL,
  cex.main = 1,
  cex.label = 1,
  cex.names = 0.9,
  las.xnames = 0,
  las.ynames = 1,
  savedata = FALSE,
  outfolder = NULL,
  outfn = NULL,
  outfn.pre = NULL,
  outfn.date = TRUE,
  overwrite = FALSE,
  ...
)

Arguments

x	Data frame or comma-delimited file (*.csv) - a frequency table.
xvar	String. Name of X variable.
yvar	String. Name of the y variable (e.g., FREQ).
plotCI	Logical. If TRUE, adds confidence intervals to plot as dotted lines.
sevar	String. Name of the variable with standard error values.
CIlst	String. Numeric vector. If plotCI=TRUE, identifies percent confidence interval to add to plot.
CIcolorlst	String. Character vector. If plotCI=TRUE, identifies colors to plot confidence interval lines. Must be same length as CIlst and from colors() list.
addshade	Logical. If TRUE, adds a light grey shading between the large confidence interval lines.
device.type	String. Type(s) of device for plotting ("dev.new", "jpg", "pdf").
jpeg.res	Integer. Resolution for jpeg image.
device.height	Integer. Height (in inches) of barplot, if writing to file.
device.width	Integer. Width (in inches) of barplot, if writing to file.
ylim	Number. A vector of min and max values, c(min,max) for the y axis (or x axis if horiz=TRUE). If NULL, defaults to maximum y value. If errbars=TRUE, the ylim defaults to the maximum y value plus the standard error.
divideby	String. Conversion number for output ('hundred', 'thousand', 'million').
ylabel	String. Label for the y axis (same as ylab).
xlabel	String. Label for the x axis (same as xlab).
xticks	Numeric vector. Vector of tick marks for x axis.
mar	See par.. A numerical vector representing number of lines for margins (c(bottom, left, top, right).
addlegend	Logical. If TRUE, adds legend to bar plot (only applicable if grouping).
main	String. Title for plot.
cex.main	Number. Expansion factor for title.
cex.label	Number. A number representing cex in barplot (size expansion of x and/or ylabels.
cex.names	Number. Expansion factor for axis names (bar labels) (e.g., 0.5 represents half the size.
las.xnames	Number. The direction of x variable names (0,1,3). 0:diagonal (Default), 1:horizontal; 3:vertical.
las.ynames	Number. The direction of y variable names (0,1,3). 0:diagonal (Default), 1:horizontal; 3:vertical.
savedata	Logical. If TRUE, writes output data to outfolder (jpg and pdf).
outfolder	String. The name of the output folder. If savedata=TRUE, all output saved to the outfolder. If savedata=FALSE, only a text file of input parameters is saved.
outfn	String. The name of the output file if savedata=TRUE (*.csv). Do not include extension. If NULL, the file will be named BARPLOT_'yvar_date'.csv
outfn.pre	String. Add a prefix to output name (e.g., "01").
outfn.date	Logical. If TRUE, add date to end of outfile (e.g., outfn_'date'.csv).
overwrite	Logical. If TRUE and exportshp=TRUE, overwrite files in outfolder.
...	additional arguments to pass to barplot(), including a list of arguments for legend() arguments (e.g., args.legend=list(x="topleft", "bty="n"), for moving legend to topleft and removing box around legend).

Details

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

Value

Outputs barplot to display window.

Note

If savedata = TRUE, writes a jpg and pdf of barplot to outfolder.

To add legend parameters, add a parameter named args.legend, defined as a list of specific legend parameters (see ?legend)... ex. .., args.legend=list(x="topright"). If specifying x and y, x defines the lower right corner of legend box and y defines the upper right corner of box.

Author(s)

Tracey S. Frescino

Examples

# Lineplot of cubic foot volume by above-ground biomass, Wyoming tree data
# datLineplot(x = WYtree, xvar = "VOLCFNET", yvar = "DRYBIO_AG") # needs work

---

Data - Create a variable with classified values.

Description

Merge a look-up table to define categories of continuous data in x (e.g., DIA). Adds a variable to x, defining as: xvar >= MIN (and xvar < MAX).

Usage

datLUTclass(
  x,
  xvar = NULL,
  LUT = NULL,
  minvar = NULL,
  maxvar = NULL,
  cutbreaks = NULL,
  cutlabels = NULL,
  LUTclassnm = NULL,
  label.dec = 1,
  NAto0 = FALSE,
  vars2keep = NULL,
  keepcutbreaks = FALSE,
  dsn = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  dbwrite = FALSE,
  dbreturn = TRUE,
  overwrite = TRUE,
  savedata = FALSE,
  savedata_opts = NULL,
  gui = FALSE
)

Arguments

x	Data frame or comma-delimited file (*.csv) or table in dsn. The data table with variable to classify.
xvar	String. Name of variable in the data table to join to.
LUT	Data frame or comma-delimited file (*.csv). Name of the look-up table with collapsed classes. Lookup table should include minimum values for classes, maximum values for classes, and a name of class (i.e., LUTclassnm). Maximum values and names are optional.
minvar	String. If LUT is not null, name of variable with minimimum class value (>= minvar).
maxvar	String. Optional. If LUT is not null, name of variable with maximum class value (<= maxvar).
cutbreaks	Numeric vector. Vector of numbers for minimum class values.
cutlabels	String vector. Optional. Vector of names for classes. If NULL, class names are generated from cutbreaks.
LUTclassnm	String. Optional. Name of classified variable in x. If LUT is not null and class names are included, this is the name of variable with class names. If NULL, a class names are generated from minvar or minvar and maxvar with default name equal to 'xvar'CL.
label.dec	Integer. Number of decimals to include in label.
NAto0	Logical. If TRUE, converts NA values to 0 before classification.
vars2keep	String vector. Variable names from LUT to keep (append) to x.
keepcutbreaks	Logical. If TRUE, the cutbreaks used for creating classes are appended to dataset.
dsn	String. Data source name of database with x.
dbconn	Open database connection.
dbconnopen	Logical. If TRUE, keep database connection open.
dbwrite	Logical. If TRUE, write class column to database table x.
dbreturn	Logical. If TRUE, return table with class column.
overwrite	Logical. If TRUE, and the class name already exists in x, overwrites class name.
savedata	Logical. If TRUE, saves data to outfolder.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'datlutcl'.
gui	Logical. If gui, user is prompted for parameters.

Details

Use datLUTclass() to prompt for input.

Value

xLUT	Input data table with look-up table variable(s).
LUTclassnm	Name of the classified variable.
LUT	Look-up table with categories.

tablst If savedata = TRUE, a comma-delimited file is output to the outfolder as outfn. If outfn = NULL, the name of the file will be datlut_'date'.csv.

Note

The look-up table format must be similar to the following table Set LUTclassnm = VARCLNM. MAX and VALCLNM columns are optional.

	MIN	MAX	VARCLNM
	1.0	4.9	1
	5.0	9.9	2
	10.0	15.0	3
	15.0	19.9	4
	20.0	24.9	5
	25.0	49.9	6

Author(s)

Tracey S. Frescino

Examples

head(FIESTA::ref_diacl2in)
WYtreelut <- datLUTclass(FIESTA::WYtree,
                         xvar = "DIA",
                         LUT = FIESTA::ref_diacl2in,
                         LUTclassnm = "DIACL2IN")
names(WYtreelut)
head(WYtreelut$xLUT)
table(WYtreelut$xLUT$DIACL2IN)

WYtreelut2 <- datLUTclass(FIESTA::WYtree,
                          xvar = "DIA",
                          cutbreaks = c(1, 5, 25, 50, 100),
                          LUTclassnm = "DIACL2IN")
names(WYtreelut2)
head(WYtreelut2$xLUT)
table(WYtreelut2$xLUT$DIACL2IN)

#' Create look-up table of stand age classes
MIN <- c(0, 20, 40, 60, 80, 101)
STDAGENM <- c("0-20", "21-40", "41-60", "61-80", "81-100", "101+")
stdagelut <- data.frame(MIN = MIN, STDAGENM = STDAGENM)
stdagelut

WYcondlut <- datLUTclass(FIESTA::WYcond,
                         xvar = "STDAGE",
                         LUT = stdagelut,
                         LUTclassnm = "STDAGENM")
names(WYcondlut)
head(WYcondlut$xLUT)
table(WYcondlut$xLUT$STDAGENM)

---

Data - Gets variable description or class.

Description

Merge a look-up table to append new variables, names, or categories to x.

Usage

datLUTnm(
  xvar,
  x = NULL,
  uniquex = NULL,
  LUT = NULL,
  LUTvar = NULL,
  LUTnewvar = NULL,
  LUTnewvarnm = NULL,
  FIAname = FALSE,
  group = FALSE,
  NAclass = "Other",
  add0 = FALSE,
  spcdname = "COMMON_SCIENTIFIC",
  stopifmiss = FALSE,
  xtxt = NULL,
  dsn = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  dbwrite = FALSE,
  dbreturn = TRUE,
  overwrite = TRUE,
  savedata = FALSE,
  savedata_opts = NULL,
  gui = FALSE
)

Arguments

xvar	String. Name of variable in the data table to join to.
x	Data frame or comma-delimited file (*.csv). The data table with variable to classify.
uniquex	String. Unique values to match, if x is NULL.
LUT	Data frame or comma-delimited file (*.csv). Name of the file with collapsed classes (If FIAname=FALSE).
LUTvar	String. Name of variable in LUT with values matching that xvar. If LUTvar=NULL, LUTvar=xvar.
LUTnewvar	String. Name(s) of other variable(s) in the look-up table to include in join. If NULL, all other variables in table will be included.
LUTnewvarnm	String. Different name(s) for LUTnewvar. If NULL, names will default to LUTnewvar. The length of LUTnewvarnm must equal the length for LUTnewvar.
FIAname	Logical. If TRUE, get FIA reference name based on (ref_codes) within FIESTA.
group	Logical. If TRUE and FIA=TRUE, the group variables in reference table (ref_codes) are merged to data table (GROUPCD, GROUPNM).
NAclass	String. NA values in xvar will be changed to NAclass.
add0	Logical. IF TRUE, keep all codes in look up table. If FALSE, only include codes that are in x.
spcdname	String. Name for species output type ('COMMON', 'SCIENTIFIC', 'SYMBOL', 'COMMON_SCIENTIFIC').
stopifmiss	Logical. IF TRUE, stops function if missing codes in LUTx.
xtxt	String.* Name of x table for more useful information in warnings.
dsn	String. Data source name of database with x.
dbconn	Open database connection.
dbconnopen	Logica. If TRUE, keep database connection open.
dbwrite	Logical. If TRUE, write class column to database table x.
dbreturn	Logical. If TRUE, return table with class column.
overwrite	Logical. If TRUE, and the class name already exists in x, overwrites class name.
savedata	Logical. If TRUE, saves data to outfolder.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'datlut'.
gui	Logical. If gui, user is prompted for parameters.

Value

xLUT	The input data table with look-up table variable(s).
xLUTnm	Name of the new variable(s).
LUT	Look up table with categories.

If savedata = TRUE, a comma-delimited file is output to the outfolder as outfn. If outfn = NULL, the name of the file will be datlut_'date'.csv.

Note

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

Author(s)

Tracey S. Frescino

Examples

# Append forest type names using the reference table above.
ref_fortypcd <- ref_codes[ref_codes$VARIABLE == "FORTYPCD",]
WYcondlut <- datLUTnm(WYcond,
                      xvar = "FORTYPCD",
                      LUT = ref_fortypcd,
                      LUTvar = "VALUE",
                      LUTnewvar = "MEANING",
                      LUTnewvarnm = "FORTYPNM")
names(WYcondlut)
WYcond2 <- WYcondlut$xLUT
head(WYcond2[WYcond2$FORTYPCD > 0, ])

# Append forest type names the FIAname parameter. If the xvar is in the stored
# reference table, the name and values will automatically be appended.
WYcondlut2 <- datLUTnm(WYcond,
                       xvar = "FORTYPCD",
                       FIAname = TRUE)
names(WYcondlut2)
WYcond3 <- WYcondlut2$xLUT
head(WYcond3[WYcond3$FORTYPCD > 0, ])

---

Data - Gets variable description or class for SPCD.

Description

Merge the ref_species table to append new variables, names, or categories to x.

Usage

datLUTspp(
  x = NULL,
  uniquex = NULL,
  NAclass = "Other",
  group = FALSE,
  states = NULL,
  spcdname = "COMMON",
  add0 = FALSE,
  stopifmiss = FALSE,
  xtxt = NULL,
  dsn = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  dbwrite = FALSE,
  dbreturn = TRUE,
  overwrite = TRUE,
  savedata = FALSE,
  savedata_opts = NULL,
  gui = FALSE
)

Arguments

x	Data frame or comma-delimited file (*.csv). The data table with variable to classify.
uniquex	String. Unique values of SPCD to match, if x is NULL.
NAclass	String. NA values in xvar will be changed to NAclass.
group	Logical. If TRUE, the group variable in ref_species are merged to data table (E_SPGRPCD, W_SPGRPCD), depending on state(s) specified. If states overlap both E and W regions, the region with majority is used or E if equal. The group name is merged from ref_codes, SPGRPCD Variable.
states	String. Name of state(s) the x table is from.
spcdname	String. Name for species output type ('COMMON', 'SCIENTIFIC', 'SYMBOL', 'COMMON_SCIENTIFIC').
add0	Logical. IF TRUE, keep all codes in look up table. If FALSE, only include codes that are in x.
stopifmiss	Logical. IF TRUE, stops function if missing codes in LUTx.
xtxt	String.* Name of x table for more useful information in warnings.
dsn	String. Data source name of database with x.
dbconn	Open database connection.
dbconnopen	Logica. If TRUE, keep database connection open.
dbwrite	Logical. If TRUE, write class column to database table x.
dbreturn	Logical. If TRUE, return table with class column.
overwrite	Logical. If TRUE, and the class name already exists in x, overwrites class name.
savedata	Logical. If TRUE, saves data to outfolder.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'datlut'.
gui	Logical. If gui, user is prompted for parameters.

Value

xLUT	The input data table with look-up table variable(s).
xLUTnm	Name of the new variable(s).
LUT	Look up table with categories.

If savedata = TRUE, a comma-delimited file is output to the outfolder as outfn. If outfn = NULL, the name of the file will be datlut_'date'.csv.

Note

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

Author(s)

Tracey S. Frescino

Examples

WYtreelut <- datLUTspp(WYtree)
names(WYtreelut)
WYtree2 <- WYtreelut$xLUT
head(WYtree2)

---

Data - Generates barplot of photo-based change estimates.

Description

Generate a bar plot of net change for photo-based estimates of land use / land cover change.

Usage

datPBplotchg(gainloss, CI = 95, figTitle = "")

Arguments

gainloss	Data frame or comma-delimited file (*.csv) - table with gain loss estimates.
CI	Number. Confidence Interval to include on plot.
figTitle	String. Title of figure.

Value

Outputs barplot to display window.

Note

If savedata = TRUE, writes a jpg and pdf of barplot to outfolder.

Author(s)

Tracey S. Frescino

---

Data - Transpose point data to plot-level percent by domain.

Description

Calculates percent point by plot and domain and transpose to plot level.

Usage

datPBpnt2pct(pnt, uniqueid, tvar, othervars = NULL)

Arguments

pnt	DF/DT or comma-delimited file (*.csv). Point-level table with one record per point. If NULL, aggregated point counts must be in pntcnt.
uniqueid	String. Name of unique identifier of plot in pnt.
tvar	String. Name of variable to transpose.
othervars	String vector. Name(s) of plot-level variables to merge with transposed data.

Value

pltdom.pct

Data frame with transposed data.

Author(s)

Tracey S. Frescino

Examples

# Load necessary data from FIESTA
## Point data
icepntfn <- system.file("extdata",
                        "PB_data/icepnt_utco1135.csv",
                         package = "FIESTA")
icepnt <- read.csv(icepntfn)

# Convert to percent
percent <- datPBpnt2pct(pnt = icepnt,
                        uniqueid = "plot_id",
                        tvar = "cover_1")
head(percent)

---

Data - Generates a pivot table.

Description

Generates a pivot table of values by x row and y column.

Usage

datPivot(
  x,
  pvar,
  xvar,
  yvar,
  pfun = sum,
  xfilter = NULL,
  NAto0 = TRUE,
  dropNAxvar = TRUE,
  dropNAyvar = TRUE,
  pvar.round = 6,
  returnDT = FALSE,
  savedata = FALSE,
  savedata_opts = NULL,
  gui = FALSE
)

Arguments

x	Dataframe. Table with pivot variables.
pvar	String. The name of the variable for pivot table values.
xvar	String. The name of the variable for rows.
yvar	String. The name of the variable for columns.
pfun	Function. The name of the function to use for pivot table values (ex. sum, mean, max).
xfilter	String. A filter to subset the datatable table x before pivoting (ex. "STATUSCD == 1").
NAto0	Logical. If TRUE, converts NA values to 0.
dropNAxvar	Logical. If TRUE, removes columns that are NA.
dropNAyvar	Logical. If TRUE, removes rows that have NA values.
pvar.round	Integer. Number to round pvar values to.
returnDT	Logical. If TRUE, returns a datatable.
savedata	Logical. If TRUE, writes output data to outfolder.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'datpivot'.
gui	Logical. If TRUE, pop-up windows will appear for user-interface.

Value

ptab	Matrix. The pivot table.

Author(s)

Tracey S. Frescino

Examples

# Pivot WYcond table
datPivot(x = FIESTA::WYcond,
         pvar = "CONDPROP_UNADJ",
         xvar = "FORTYPCD",
         yvar = "STDSZCD")

# Pivot WYtree table
datPivot(x = FIESTA::WYtree,
         pvar = "TPA_UNADJ",
         xvar = "SPCD",
         yvar = "STATUSCD",
         pfun = mean,
         NAto0 = TRUE)

---

Database - Get plot counts.

Description

Extract plot counts by inventory year and state.

Usage

datPlotcnt(
  plt,
  yrtype = "INVYR",
  states = NULL,
  designcd = FALSE,
  forsamp = TRUE,
  total = TRUE,
  subtotal = TRUE,
  savedata = FALSE,
  outfolder = NULL,
  outfn = NULL,
  gui = FALSE
)

Arguments

plt	Data frame. Table of plot-level variables to count plots. If using this table, it must include INVYR.
yrtype	String. Type of year to categorize data ("INVYR", "MEASYEAR").
states	String vector. The states in plt table.
designcd	Logical. If TRUE, includes FIA design codes in the table.
forsamp	Logical. If TRUE, includes forest/nonforest/nonsampled codes in the table.
total	Logical. If TRUE, a row is added to bottom of table with a total for the whole table.
subtotal	Logical. If TRUE, a row is added to bottom of each section for subtotals.
savedata	Logical. If TRUE, saves data to outfolder as comma-delimited file (*.csv). No objects are returned. If FALSE, the data are saved as R objects and returned to user. See details for caveats.
outfolder	String. The output folder path. If NULL and savedata=TRUE or parameters=TRUE, outfolder is the working directory.
outfn	String. The name of the output file. If NULL, defaults to pltcnt_'date'.csv
gui	Logical. If TRUE, gui windows pop up for parameter selection.

Value

pltcnt - a dataframe of counts (YEAR, STABBR, STCD, PLOTS, NONSAMPLED, FOREST, NONFOREST)

Author(s)

Tracey S. Frescino

---

Data - Aggregates numeric condition data to plot level.

Description

Aggregates CONDPROP_UNADJ variable or other continuous condition variables to plot level with option to apply condition filters. If condition variable is not CONDPROP_UNADJ the variable is multiplied by CONDPROP_UNADJ for weighted sum.

Usage

datSumCond(
  cond = NULL,
  datsource = "obj",
  data_dsn = NULL,
  plt = NULL,
  subp_cond = NULL,
  subplot = NULL,
  cuniqueid = "PLT_CN",
  puniqueid = "CN",
  condid = "CONDID",
  bycond = FALSE,
  bysubp = FALSE,
  subpid = "SUBP",
  csumvar = NULL,
  csumvarnm = NULL,
  cfilter = NULL,
  getadjplot = FALSE,
  adjcond = FALSE,
  NAto0 = FALSE,
  cround = 5,
  returnDT = TRUE,
  savedata = FALSE,
  savedata_opts = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  gui = FALSE
)

Arguments

cond	Data frame or comma-delimited file (*.csv). Condition-level table with aggregate variable and CONDPROP_UNADJ.
datsource	String. Source of data ('obj', 'csv', 'sqlite', 'gdb').
data_dsn	String. If datsource='sqlite', the name of SQLite database (*.sqlite).
plt	Data frame, comma-delimited file (*.csv), shapefile (*.shp), or database file. Plot-level table to join the aggregated tree data to (if bycond=FALSE). Nonsampled plots (PLOT_STATUS_CD = 3) are removed. Optional.
subp_cond	Dataframe, comma-delimited file (*.csv), or shapefile (*.shp). Subplot condition-level table to use to sum condition proportions, if bysubp=TRUE.
subplot	Dataframe, comma-delimited file (*.csv), or shapefile (*.shp). Subplot-level table to used to calculate adjustment factors, to remove nonsampled conditions (SUBP_STATUS_CD = 3). This table is optional.
cuniqueid	String. Unique identifier of cond (default = "PLT_CN").
puniqueid	String. Unique identifier of plt (default = "CN").
condid	String. Unique identifier for conditions.
bycond	Logical. If TRUE, the data are aggregated to the condition level (by: cuniqueid, condid). If FALSE, the data are aggregated to the plot level (by: puniqueid).
bysubp	Logical. If TRUE, data are aggregated to the subplot level.
subpid	String. Unique identifier of each subplot.
csumvar	String. One or more variable names to sum to plot level.
csumvarnm	String. Name of the resulting aggregated plot-level variable(s). Default = csumvar + '_PLT'.
cfilter	String. A filter to subset the cond data before aggregating (e.g., "COND_STATUS_CD == 1"). Must be R syntax.
getadjplot	Logical. If TRUE, adjustments are calculated for nonsampled conditions on plot.
adjcond	Logical. If TRUE, csumvar condition variables are adjusted for nonsampled conditions by plot.
NAto0	Logical. If TRUE, convert NA values to 0.
cround	Number. The number of digits to round to. If NULL, default=5.
returnDT	Logical. If TRUE, returns data.table object(s). If FALSE, returns data.frame object(s).
savedata	Logical. If TRUE, saves data to outfolder.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'condsum'.
dbconn	Open database connection.
dbconnopen	Logical. If TRUE, keep database connection open.
gui	Logical. If gui, user is prompted for parameters.

Details

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

Value

A list of the following items:

condsum	Data frame. Plot-level table with aggregated condition attribute.
cfilter	Condition filter.

If savedata=TRUE, condsum is saved to the outfolder.

Note

Nonsampled plots are removed from table.

Author(s)

Tracey S. Frescino

Examples

# Aggregate LIVE_CANOPY_CVR_PCT to plot, weighted by CONDPROP_UNADJ
condsum <- datSumCond(cond = FIESTA::WYcond,
                      csumvar = "LIVE_CANOPY_CVR_PCT")$condsum

# Check results
condsum[condsum$PLT_CN == 40404737010690,]
FIESTA::WYcond[FIESTA::WYcond$PLT_CN == 40404737010690,]

---

Data - Aggregates tree and/or seedling data to the plot, condition, or subplot level.

Description

Aggregates tree data (e.g., VOLCFNET) and/or seedling data (e.g., TPA_UNADJ) to plot, condition, or subplot. Includes options for filtering tree data, expanding to plot by multiplying by trees per acre (TPA_UNADJ), or adjusting for nonresponse at the plot level (getadjplot).

Usage

datSumTree(
  tree = NULL,
  seed = NULL,
  cond = NULL,
  plt = NULL,
  subp_cond = NULL,
  subplot = NULL,
  datsource = "obj",
  data_dsn = NULL,
  tuniqueid = "PLT_CN",
  cuniqueid = "PLT_CN",
  puniqueid = "CN",
  bycond = FALSE,
  condid = "CONDID",
  bysubp = FALSE,
  subpuniqueid = "PLT_CN",
  subpid = "SUBP",
  tsumvarlst = NULL,
  tsumvarnmlst = NULL,
  addseed = FALSE,
  seedonly = FALSE,
  woodland = "Y",
  TPA = TRUE,
  tfun = sum,
  ACI = FALSE,
  tfilter = NULL,
  lbs2tons = TRUE,
  metric = FALSE,
  getadjplot = FALSE,
  adjtree = FALSE,
  adjvar = "tadjfac",
  adjTPA = 1,
  NAto0 = FALSE,
  tround = 5,
  returnDT = TRUE,
  savedata = FALSE,
  savedata_opts = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  gui = FALSE
)

Arguments

tree	Dataframe or comma-delimited file (*.csv). The tree-level table.
seed	Dataframe or comma-delimited file (*.csv). The seedling table.
cond	Dataframe or comma-delimited file (*.csv). Condition-level table to join the aggregated Ftree data to, if bycond=TRUE. This table also may be used for condition proportion or strata variables used if adjcond or adjstrata = TRUE (See details below). This table is optional.
plt	Dataframe, comma-delimited file (*.csv), or shapefile (*.shp). Plot-level table to join the aggregated tree data to, if bycond=FALSE. This table is optional.
subp_cond	Dataframe, comma-delimited file (*.csv), or shapefile (*.shp). Subplot condition-level table to use to sum condition proportions, if bysubp=TRUE.
subplot	Dataframe, comma-delimited file (*.csv), or shapefile (*.shp). Subplot-level table to used to calculate adjustment factors, to remove nonsampled conditions (SUBP_STATUS_CD = 3). This table is optional. If included the aggregated tree data are joined to subplot before returning.
datsource	String. Source of data ('obj', 'csv', 'sqlite', 'gdb').
data_dsn	String. If datsource='sqlite', the name of SQLite database (*.sqlite).
tuniqueid	String. Unique identifier of plt in tree table.
cuniqueid	String. Unique identifier of plt in cond table if cond is NOT NULL.
puniqueid	String. Unique identifier of plt table if plt is NOT NULL.
bycond	Logical. If TRUE, the data are aggregated to the condition level (by: cuniqueid, condid). If FALSE, the data are aggregated to the plot level (by: puniqueid). If bysubp = TRUE and bycond = TRUE, data are aggregated by subpuniqueid, subpid, condid.
condid	String. Unique identifier for conditions.
bysubp	Logical. If TRUE, data are aggregated to the subplot level.
subpuniqueid	String. Unique identifier of plot in subplot and subp_cond table.
subpid	String. Unique identifier of each subplot.
tsumvarlst	String (vector). Tree-level variable(s) to aggregate (e.g., "TPA_UNADJ", "BA"). Use "TPA_UNADJ" (tfun=sum) for summed tree count.
tsumvarnmlst	String (vector). Name of the tree-level variable(s) to aggregate (e.g., "TPALIVE", "BALIVE"). This list must have the same number of variables as tsumvarlst and be in respective order. If NULL, the default names will be tsumvar'_tfun' (e.g., "TPA_UNADJ_SUM", "BA_SUM").
addseed	Logical. If TRUE, add seedling counts to tree counts. Note: tdomvar must be 'SPCD' or 'SPGRPCD'.
seedonly	Logical. If TRUE, seedling counts only. Note: tdomvar must be 'SPCD' or 'SPGRPCD'.
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.
TPA	Logical. If TRUE, tsumvarlst variable(s) are multiplied by the respective trees-per-acre variable (see details) to get per-acre measurements.
tfun	Function. The name of the function to use to aggregate the data (e.g., sum, mean, max).
ACI	Logical. If TRUE, if ACI (All Condition Inventory) plots exist, any trees on these plots will be included in summary. If FALSE, you must include condition table.
tfilter	String. Filter to subset the tree data before aggregating (e.g., "STATUSCD == 1"). This must be in R syntax. If tfilter=NULL, user is prompted. Use tfilter="NONE" if no filters.
lbs2tons	Logical. If TRUE, converts biomass or carbon variables from pounds to tons (1 pound = 0.0005 short tons).
metric	Logical. If TRUE, converts response to metric units based on FIESTA::ref_conversion, if any variable in tsumvarlst is in FIESTAutils::ref_units. Note: if TPA, TPA is converted to trees per hectare (TPH: 1/ tpavar * 0.4046860).
getadjplot	Logical. If TRUE, adjustments are calculated for nonsampled conditions on plot.
adjtree	Logical. If TRUE, trees are individually adjusted by adjustment factors. Adjustment factors must be included in tree table (see adjvar).
adjvar	String. If adjtree=TRUE, the name of the variable to use for multiplying by adjustment (e.g., tadjfac).
adjTPA	Numeric. A tree-per-acre adjustment. Use for DESIGNCD=1 (annual inventory), if using less than 4 subplots. If using only 1 sublot for estimate, adjTPA=4. The default is 1.
NAto0	Logical. If TRUE, convert NA values to 0.
tround	Number. The number of digits to round to. If NULL, default=5.
returnDT	Logical. If TRUE, returns data.table object(s). If FALSE, returns data.frame object(s).
savedata	Logical. If TRUE, saves data to outfolder.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'treesum'.
dbconn	Open database connection.
dbconnopen	Logical. If TRUE, keep database connection open.
gui	Logical. If gui, user is prompted for parameters.

Details

For adjcond (bycond=FALSE):
If you want to summarize trees-per-acre information aggregated to plot or condition level, you need to include a TPA variable in tree table.
For tsumvars = GROWCFGS, GROWBFSL, GROWCFAL, FGROWCFGS, FGROWBFSL, or FGROWCFAL, you must have TPAGROW_UNADJ
For tsumvars = MORTCFGS, MORTBFSL, MORTCFAL, FMORTCFGS, FMORTBFSL, or FMORTCFAL, you must have TPAMORT_UNADJ
For tsumvars = REMVCFGS, REMVBFSL, REMVCFAL, FREMVCFGS, FREMVBFSL, or FREMVCFAL, you must have TPAREMV_UNADJ

If you want to adjust plot-level or subplot-level information by condition proportions (adjplot), you need to include CONDID & CONDPROP_UNADJ in cond or tree table and COND_STATUS_CD.

Value

A list of the following items:

treedat	Data frame. Plot or condition-level table with aggregated tree attributes.
sumvars	String vector. Name(s) of the output aggregated tree attributes.
tunitlst	String list. Units of output, when available.
tfilter	String list. Filter used.
meta	Data frame. Associated metadata, when available.

If savedata=TRUE
- treedat will be saved to the outfolder.
- a text file of input parameters is saved to outfolder ('outfn'_parameters_'date'.txt).

Note

If a dat table is provided, the aggregated tree data will be merged to table and NULL values will be output as 0.

Author(s)

Tracey S. Frescino

Examples

# Aggregate LIVE_CANOPY_CVR_PCT to plot, weighted by CONDPROP_UNADJ
treesum <- datSumTree(tree = FIESTA::WYtree,
                      tsumvarlst = "TPA_UNADJ")$treedat

# Check results
treesum[treesum$PLT_CN == 40404737010690,]
FIESTA::WYtree[FIESTA::WYtree$PLT_CN == 40404737010690,]

---

Data - Aggregates numeric tree data by tree domain (i.e. species) to plot or condition-level.

Description

Aggregates numeric tree domain data (e.g., SPCD) to plot or condition, including options for filtering tree data or extrapolating to plot acre by multiplying by TPA. Includes options for generating barplots, proportion data, and cover data.

Usage

datSumTreeDom(
  tree = NULL,
  seed = NULL,
  cond = NULL,
  plt = NULL,
  subp_cond = NULL,
  subplot = NULL,
  datsource = "obj",
  data_dsn = NULL,
  tuniqueid = "PLT_CN",
  cuniqueid = "PLT_CN",
  puniqueid = "CN",
  bycond = FALSE,
  condid = "CONDID",
  bysubp = FALSE,
  subpid = "SUBP",
  tsumvar = NULL,
  addseed = FALSE,
  seedonly = FALSE,
  woodland = "Y",
  TPA = TRUE,
  tfun = sum,
  ACI = FALSE,
  tfilter = NULL,
  lbs2tons = TRUE,
  metric = FALSE,
  tdomvar = "SPCD",
  tdomvarlst = NULL,
  tdomvar2 = NULL,
  tdomvar2lst = NULL,
  tdomprefix = NULL,
  tdombarplot = FALSE,
  tdomtot = FALSE,
  tdomtotnm = NULL,
  FIAname = FALSE,
  spcd_name = "COMMON",
  pivot = TRUE,
  presence = FALSE,
  proportion = FALSE,
  cover = FALSE,
  getadjplot = FALSE,
  adjtree = FALSE,
  adjvar = "tadjfac",
  NAto0 = FALSE,
  adjTPA = 1,
  tround = 5,
  returnDT = TRUE,
  savedata = FALSE,
  savedata_opts = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  gui = FALSE
)

Arguments

tree	Data frame or comma-delimited file (*.csv). The tree-level table with tree domain data.
seed	Data frame or comma-delimited file (*.csv). The seedling table with tree seedling counts. Only applicable for counts (tsumvar="PLT_CN").
cond	Data frame or comma-delimited file (*.csv). Condition-level table to join the aggregated tree data to, if bycond=TRUE. This table also may be used for condition proportion or strata variables used if adjcond or adjstrata = TRUE (See details below). This table is optional. If included, CONDID must be present in table.
plt	Dataframe, comma-delimited file (*.csv), or shapefile (*.shp). Plot-level table to join the aggregated tree data to, if bycond=FALSE. This table is optional.
subp_cond	Dataframe, comma-delimited file (*.csv), or shapefile (*.shp). Subplot condition-level table to use to sum condition proportions, if bysubp=TRUE.
subplot	Dataframe, comma-delimited file (*.csv), or shapefile (*.shp). Subplot-level table to used to calculate adjustment factors, to remove nonsampled conditions (SUBP_STATUS_CD = 3). This table is optional.
datsource	String. Source of data ('obj', 'csv', 'sqlite', 'gdb').
data_dsn	String. If datsource='sqlite', the name of SQLite database (*.sqlite).
tuniqueid	String. Unique identifier of the tree table. If including seedling table, this should be the same for seed.
cuniqueid	String. Unique identifier of the cond table if cond is NOT NULL.
puniqueid	String. Unique identifier of the plt table if plt is NOT NULL.
bycond	Logical. If TRUE, data are aggregated to the condition level (by: uniqueid, CONDID). If FALSE, data are aggregated to the plot level (by: uniqueid).
condid	String. Unique identifier for conditions.
bysubp	Logical. If TRUE, data are aggregated to the subplot level.
subpid	String. Unique identifier of each subplot.
tsumvar	String. Name of the variable to aggregate (e.g., "BA"). For summing number of trees, use tsumvar="TPA_UNADJ" with tfun=sum.
addseed	Logical. If TRUE, add seedling counts to tree counts. Note: tdomvar must be 'SPCD' or 'SPGRPCD'.
seedonly	Logical. If TRUE, seedling counts only. Note: tdomvar must be 'SPCD' or 'SPGRPCD'.
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.
TPA	Logical. If TRUE, tsumvarlst variable(s) are multiplied by the respective trees-per-acre variable (see details) to get per-acre measurements.
tfun	Function. Name of the function to use to aggregate the data (e.g., sum, mean, max).
ACI	Logical. If TRUE, if ACI (All Condition Inventory) plots exist, any trees on these plots will be included in summary. If FALSE, you must include condition table.
tfilter	String. A filter to subset the tree data before aggregating (e.g., "STATUSCD == 1"). This must be in R syntax. If tfilter=NULL, user is prompted. Use tfilter="NONE" if no filters.
lbs2tons	Logical. If TRUE, converts biomass or carbon variables from pounds to tons (1 pound = 0.0005 short tons).
metric	Logical. If TRUE, converts response to metric units based on FIESTA::ref_conversion, if tsumvar is in FIESTAutils::ref_units. Note: if TPA, TPA is converted to trees per hectare (TPH: 1/ tpavar * 0.4046860).
tdomvar	String. The tree domain (tdom) variable used to aggregate by (e.g., "SPCD", "SPGRPCD").
tdomvarlst	String (vector). List of specific tree domains of tdomvar to aggregate (e.g., c(108, 202)). If NULL, all domains of tdomvar are used.
tdomvar2	String. A second tree domain variable to use to aggregate by (e.g. "DIACL"). The variables, tdomvar and tdomvar2 will be concatenated before summed.
tdomvar2lst	String (vector). List of specific tree domains of tdomvar2 to aggregate. If NULL, all domains of tdomvar2 are used.
tdomprefix	String. The prefix used for naming the aggregated tree data, before numeric codes (e.g., "SP" = SP102, SP746).
tdombarplot	Logical. If TRUE and pivot=TRUE, calls datBarplot() and outputs a barplot of tdom distributions. If savedata=TRUE, barplots are written to outfolder.
tdomtot	Logical. If TRUE and pivot=TRUE a total of all tree domains in tdomvarlst is calculated and added to output data frame.
tdomtotnm	String. If tdomtot=TRUE, the variable name for the total column in output data frame. If NULL, the default will be tdomvar + 'TOT'.
FIAname	Logical. If TRUE, changes names of columns for SPCD and SPGRPCD from code to FIA names.
spcd_name	String. Output name type if tdomvar or tdomvar2 = "SPCD" ('COMMON', 'SCIENTIFIC', 'SYMBOL').
pivot	Logical. If TRUE, tdomvar data are transposed (pivoted) to separate columns.
presence	Logical. If TRUE, an additional table is output with tree domain values as presence/absence (1/0).
proportion	Logical. If TRUE and pivot=TRUE, an additional table will be output with tree domain data as proportions of total tsumvar.
cover	Logical. If TRUE and pivot=TRUE, , an additional table will be output with tree domain data as percent cover, based on proportions of tsumvar (see proportion) and tree canopy cover variable in cond (LIVE_CANOPY_CVR_PCT) or in plt (CCLIVEPLT). Does not include seedlings.
getadjplot	Logical. If TRUE, adjustments are calculated for nonsampled conditions on plot.
adjtree	Logical. If TRUE, trees are individually adjusted by adjustment factors. Adjustment factors must be included in tree table (see adjvar).
adjvar	String. If adjtree=TRUE, the name of the variable to use for multiplying by adjustment (e.g., tadjfac).
NAto0	Logical. If TRUE, convert NA values to 0.
adjTPA	Numeric. A tree-per-acre adjustment. Use for DESIGNCD=1 (annual inventory), if using less than 4 subplots. If using only 1 sublot for estimate, adjTPA=4. The default is 1.
tround	Number. The number of digits to round to. If NULL, default=6.
returnDT	Logical. If TRUE, returns data.table object(s). If FALSE, returns data.frame object(s).
savedata	Logical. If TRUE, saves data to outfolder.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'tdomsum'.
dbconn	Open database connection.
dbconnopen	Logical. If TRUE, keep database connection open.
gui	Logical. If gui, user is prompted for parameters.

Details

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

If you want to get trees-per-acre information aggregated to plot or condition level, you need to include a TPA variable in tree table.
For tsumvars = GROWCFGS, GROWBFSL, GROWCFAL, FGROWCFGS, FGROWBFSL, or FGROWCFAL, you must have TPAGROW_UNADJ
For tsumvars = MORTCFGS, MORTBFSL, MORTCFAL, FMORTCFGS, FMORTBFSL, or FMORTCFAL, you must have TPAMORT_UNADJ
For tsumvars = REMVCFGS, REMVBFSL, REMVCFAL, FREMVCFGS, FREMVBFSL, or FREMVCFAL, you must have TPAREMV_UNADJ

If you want to adjust plot-level information by condition proportions, you need to include CONDID & CONDPROP_UNADJ in cond or tree table.

If you want to adjust the aggregated tree data by the area of the strata (estimation unit), you need to either have a variable in your tree data named adjfact or you need to included the following variables in your datasets:
Condition table: STATECD, CONDID, STRATA, ESTUNIT, SUBPPROP_UNADJ, MICRPROP_UNADJ (if microplot trees) MACRPROP_UNADJ (if macroplot trees).
Tree table: TPA_UNADJ

All trees where DIA=NA are removed from analysis. These are trees that were remeasured but are no longer in inventory (ex. a tree that is dead and not standing in the current inventory).

Value

tdomdata - a list of the following objects:

tdomdat	Data frame. Plot or condition-level table with aggregated tree domain (tdom) attributes (filtered).
tdomsum	Data frame. The tdom look-up table with data aggregated by species.
tdomvar	String. Name of the tdom variable used to aggregate by.
tsumvar	String. Name of the aggregated output variable.
tdomlst	Vector. List of the aggregated tree data in tdomdat.
tdomdat.pres	Data frame. Plot or condition-level table with aggregated tree domain attributes represented as presence/absence (1/0).
tdomdat.prop	Data frame. Plot or condition-level table with aggregated tree domain attributes represented as proportion of total by plot.
tdomdat.cov	Data frame. Plot or condition-level table with aggregated tree domain attributes represented as percent cover, multipying cover attribute by tdom proportion by plot.

If savedata=TRUE
- tdomdat will be saved to the outfolder ('tdomprefix'_DAT.csv).
- a text file of input parameters is saved to outfolder ('outfn'_parameters_'date'.txt).
- if presence=TRUE, tdomdat.prop is saved to outfolder ('tdomprefix'_PRESDAT.csv) - if proportion=TRUE, tdomdat.prop is saved to outfolder ('tdomprefix'_PROPDAT.csv) - if cover=TRUE, tdomdat.prop is saved to outfolder ('tdomprefix'_COVDAT.csv)

Note

This function can be used to get tree domain data. This data can be used for mapping tree domain distributions.

Author(s)

Tracey S. Frescino

Examples

# Sum of Live Basal Area Per Acre by Species
datSumTreeDom(tree = FIESTA::WYtree, 
              cond = FIESTA::WYcond, 
              plt = FIESTA::WYplt, 
              puniqueid = "CN", 
              bycond = FALSE, 
              tsumvar = "BA", 
              TPA = TRUE, 
              tdomtot = TRUE, 
              tdomtotnm = "BA_LIVE", 
              tdomprefix = "BA_LIVE", 
              tround = 2, 
              tfilter = "STATUSCD==1")
              
# Sum of Number of Live Trees by Species
datSumTreeDom(tree = FIESTA::WYtree, 
              cond = FIESTA::WYcond, 
              plt = FIESTA::WYplt, 
              puniqueid = "CN", 
              bycond = FALSE, 
              tsumvar = "PLT_CN", 
              TPA = TRUE, 
              tdomtot = TRUE, 
              tdomprefix = "CNT", 
              tround = 0, 
              tfilter = "STATUSCD==1")
              
# Sum of Number of Live Trees by Species, Including Seedlings
datSumTreeDom(cond = WYcond, 
              plt = WYplt, 
              seed = WYseed, 
              puniqueid = "CN", 
              bycond = FALSE, 
              tsumvar = "PLT_CN", 
              TPA = TRUE, 
              tdomtot = TRUE, 
              tdomprefix = "CNT", 
              tround = 0)

---

Database - Extracts data table(s) from FIA DataMart.

Description

Downloads and extracts compressed comma-delimited file(s) (*.zip) from FIA DataMart (https://apps.fs.usda.gov/fia/datamart/CSV/datamart_csv.html). Only 1 table can be specified, but multiple states may be included.

Usage

DBgetCSV(
  DBtable,
  states = NULL,
  returnDT = FALSE,
  stopifnull = TRUE,
  noIDate = TRUE
)

Arguments

DBtable	String. Name of table to download. Only 1 table allowed.
states	String or numeric vector. Name (e.g., "Arizona", "New Mexico") or code (e.g., 4, 35) of states to download data. If NULL, tables that are not state-level are downloaded.
returnDT	Logical. If TRUE, a data table is returned, else, a data frame.
stopifnull	Logical. If TRUE, stop if table is NULL.
noIDate	Logical. If TRUE, do not include columns with type IDate.

Details

The compressed data files are downloaded from FIA DataMart; saved to a temporary space; extracted and imported; and deleted from temporary space. Accessibility and download time depends on access and speed of internet connection.

Value

Returns a data table (returnDT=TRUE), or data.frame (returnDT=FALSE) of downloaded table(s). If more than one state, returned as one table.

Author(s)

Tracey S. Frescino

Examples

## Not run: 
# Get plot data for multiple states
FIAplots <- DBgetCSV("PLOT", c("Georgia", "Utah"))
table(FIAplots$STATECD)

## End(Not run)

---

Database - Gets or checks FIA EVALIDs and/or gets inventory years from FIA's online publicly-available DataMart (https://apps.fs.usda.gov/fia/datamart/CSV/datamart_csv.html).

Description

Extracts FIA EVALIDs for identifying an estimation group of plots. EVALIDs may be extracted by most current evaluation (evalCur=TRUE) or by the end year of an evaluation (evalEndyr) or all evaluations in the database for one or more states. See details for more information.

Usage

DBgetEvalid(
  states = NULL,
  RS = NULL,
  datsource = "datamart",
  data_dsn = NULL,
  invtype = "ANNUAL",
  evalCur = TRUE,
  evalEndyr = NULL,
  evalid = NULL,
  evalAll = FALSE,
  evalType = "VOL",
  invyrtab = NULL,
  dbTabs = dbTables(),
  dbconn = NULL,
  dbconnopen = FALSE,
  returnPOP = FALSE,
  gui = FALSE
)

Arguments

states	String or numeric vector. Name (e.g., 'Arizona','New Mexico') or code (e.g., 4, 35) of state(s) for evalid. If all states in one or more FIA Research Station is desired, set states=NULL and use RS argument to define RS.
RS	String vector. Name of research station(s) ('RMRS','SRS','NCRS','NERS','PNWRS'). Do not use if states is populated.
datsource	Source of data ('datamart', 'sqlite').
data_dsn	If datsource='sqlite', the file name (data source name) of the sqlite database (*.sqlite).
invtype	String. The type of FIA data to extract ('PERIODIC', 'ANNUAL'). Only 1 allowed at a time. See further details below.
evalCur	Logical. If TRUE, the most current FIA Evaluation is extracted for state(s).
evalEndyr	Number. The end year of the FIA Evaluation period of interest. Selects only sampled plots and conditions for the evaluation period. If more than one state, create a named list object with evalEndyr labeled for each state (e.g., list(Utah=2014, Colorado=2013).
evalid	Integer. One or more EVALID to check if exists.
evalAll	Logical. If TRUE, gets all EVALIDs for invtype.
evalType	String vector. The type(s) of evaluation of interest ('ALL', 'CURR', 'VOL', 'GRM', 'P2VEG', 'DWM", 'INV', 'REGEN', 'CRWN'). The evalType 'ALL' includes nonsampled plots; 'CURR' includes plots used for area estimates; 'VOL' includes plots used for area and/or tree estimates; The evalType 'GRM' includes plots used for growth, removals, mortality, and change estimates (eval_typ are accepted. See details below and FIA database manual for regional availability and/or differences.
invyrtab	Data frame. A data frame including inventory years by state. If NULL, it is generated from SURVEY table from FIA database based on states and invtype.
dbTabs	List of database tables the user would like returned. See help(dbTables) for a list of options.
dbconn	Open database connection.
dbconnopen	Logical. If TRUE, the dbconn connection is not closed.
returnPOP	Logical. If TRUE, returns pop tables (SURVEY, POP_PLOT_STRATUM_ASSGN) as R objects instead of table names, if in db.
gui	Logical. If TRUE, gui windows pop up for parameter selection.

Details

FIA Evaluation
An Evaluation defines a group of plots in the FIA Database used for state-level estimates, representing different spans of data and different stratification and area adjustments. An Evaluation Type (evalType) is used to identify a specific set of plots for a particular response to be able to ensure a sample-based estimate for a population. See FIA's Database documentation for current available Evaluation Types and descriptions (https://www.fia.fs.fed.us/library/database-documentation/index.php).

EVALID
An EVALID is a unique code defining an Evaluation, generally in the format of a 2-digit State code, a 2-digit year code, and a 2-digit Evaluation Type code.

EVAL_TYP

	EVALIDCD	EVAL_TYP	Description
	00	EXPALL	All area
	01	EXPVOL/EXPCURR	Area/Volume
	03	EXPCHNG/EXPGROW/EXPMORT/EXPREMV	Area Change/GRM
	07	EXPDWM	DWM
	08	EXPREGEN	Regeneration
	09	EXPINV	Invasive
	10	EXPP2VEG	Veg profile
	12	EXPCRWN	Crown

Value

A list of the following objects:

states	String vector. State names.
rslst	String vector. FIA research station names included in output.
evalidlist	Named list. evalid by state.
invtype	String. Inventory type for states(s) (ANNUAL/PERIODIC).
invyrtab	Data frame. Inventory years by state for evalidlist.
evalTypelist	Named list. Evaluation type(s) by state.
invyrs	Named list. Inventory years by state for evalidlist.
SURVEY	Data frame. If returnPOP=TRUE, the SURVEY table from FIADB.

Note

FIA database tables used:
1. SURVEY - To get latest inventory year, invyrtab = NULL
2. POP_EVAL - To get EVALID and EVALID years

Author(s)

Tracey S. Frescino

Examples

## Not run: 
# Get evalid and inventory years for Wyoming
WYeval <- DBgetEvalid(states="Wyoming")
names(WYeval)

WYeval$evalidlist
WYeval$invtype
WYeval$invyrtab
WYeval$evalType
WYeval$invyrs


# Get evalid for Utah and Wyoming
DBgetEvalid(states=c("Wyoming", "Utah"))

# Get evalid for an FIA Research Station
RSevalid <- DBgetEvalid(RS="NERS")
names(RSevalid)
RSevalid$evalidlist

## End(Not run)

---

Database - Extracts inventory plot data from FIA DataMart.

Description

Extracts data from FIA's online publicly-available DataMart (https://apps.fs.usda.gov/fia/datamart/CSV/datamart_csv.html).

Usage

DBgetPlots(
  states = NULL,
  RS = NULL,
  datsource = "datamart",
  data_dsn = NULL,
  dbTabs = dbTables(),
  eval = "FIA",
  eval_opts = NULL,
  puniqueid = "CN",
  invtype = "ANNUAL",
  intensity1 = FALSE,
  issubp = FALSE,
  istree = TRUE,
  isseed = FALSE,
  greenwt = FALSE,
  addplotgeom = FALSE,
  othertables = NULL,
  getxy = FALSE,
  xy_datsource = NULL,
  xy_dsn = NULL,
  xy = "PLOT",
  xy_opts = xy_options(),
  xymeasCur = FALSE,
  coordType = "PUBLIC",
  pjoinid = NULL,
  issp = FALSE,
  spcond = FALSE,
  spcondid1 = FALSE,
  defaultVars = TRUE,
  regionVars = FALSE,
  regionVarsRS = "RMRS",
  ACI = FALSE,
  subcycle99 = FALSE,
  stateFilter = NULL,
  allFilter = NULL,
  alltFilter = NULL,
  returndata = TRUE,
  savedata = FALSE,
  exportsp = FALSE,
  saveqry = FALSE,
  savePOP = FALSE,
  savedata_opts = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  evalInfo = NULL,
  ...
)

Arguments

states	String or numeric vector. Name (e.g., 'Arizona','New Mexico') or code (e.g., 4, 35) of state(s) for evalid. If all states in one or more FIA Research Station is desired, set states=NULL and use RS argument to define RS.
RS	String vector. Name of research station(s) to get public XY coordinates for ('RMRS','SRS','NCRS','NERS','PNWRS'). Do not use if states is populated. See FIESTA::ref_statecd for reference to RS and states.
datsource	String. Source of data ('datamart', 'sqlite').
data_dsn	String. If datsource='sqlite', the name of SQLite database (*.sqlite).
dbTabs	List. Source of tables needed for estimation based on what is defined in eval_opts(Type). The source can be a layer in data_dsn or a comma delimited file. For example, if Type='P2VEG', vsubpspp_layer and/or vsubpstr_layer must be defined. Defaults are 'P2VEG_SUBPLOT_SPP' and 'P2VEG_SUBP_STRUCTURE', respectively. See help(dbTables) for a list of options.
eval	String. Type of evaluation time frame for data extraction ('FIA', 'custom'). See eval_opts for more further options.
eval_opts	List of evaluation options for 'FIA' or 'custom' evaluations to determine the set of data returned. See help(eval_options) for a list of options.
puniqueid	String. Name of unique identifier in plot_layer in dbTabs.
invtype	String. Type of FIA inventory to extract ('PERIODIC', 'ANNUAL', 'BOTH').
intensity1	Logical. If TRUE, includes only plots where INTENSITY = 1.
issubp	Logical. If TRUE, subplot tables are extracted from FIA database (SUBPLOT, SUBP_COND).
istree	Logical. If TRUE, include tree data.
isseed	Logical. If TRUE, include seedling data.
greenwt	Logical. If TRUE, green weight biomass is calculated.
addplotgeom	Logical. If TRUE, variables from the PLOTGEOM table are appended to the plot table.
othertables	String Vector. Name of other table(s) in FIADB to include in output. The table must have PLT_CN as unique identifier of a plot.
getxy	Logical. If TRUE, gets separate XY table.
xy_datsource	Source of XY data ('obj', 'csv', 'datamart', 'sqlite').
xy_dsn	If datsource='sqlite', the file name (data source name) of the sqlite database (*.sqlite) where XY data are.
xy	sf R object or String. Table with xy coordinates. Can be a spatial polygon object, data frame, full pathname to a shapefile, or name of a layer within a database.
xy_opts	List of xy data options to specify if xy is NOT NULL. See xy_options (e.g., xy_opts = list(xvar='LON', yvar='LAT').
xymeasCur	Logical. If TRUE, include XY coordinates from the most current sampled measurement of each plot.
coordType	String. Type of xy coordinates using ('PUBLIC', 'ACTUAL')
pjoinid	String. Variable in plt to join to XY data. Not necessary to be unique. If using most current XY coordinates, use identifier for a plot (e.g., PLOT_ID).
issp	Logical. If TRUE, an sf spatial object is generated from the public X/Y coordinates in the plot table.
spcond	Logical. If TRUE, a set of condition-level attributes (e.g., FORTYPCD) represented at the plot-level are extracted from FIA DataMart COND table. (See Notes for more info on how condition attributes were added).
spcondid1	Logical. If TRUE and issp=TRUE and spcond=TRUE, condition variables are determined by condition 1 attributes. If FALSE, an algorithm is used to select the condition to use (See details for alorithm used).
defaultVars	Logical. If TRUE, a set of default variables are selected in query. See notes for variable descriptions.
regionVars	Logical. If TRUE, regional variables are included in query (e.g., SDI_RMRS, SDIPCT_RMRS, SDIMAX_RMRS, QMD_RMRS).
regionVarsRS	String. Region for regionVars ('RMRS','SRS','NCRS','NERS','PNWRS').
ACI	Logical. If TRUE, the data from All Condition Inventories (ACI) are included in dataset (NF_SAMPLING_STATUS_CD = 1). See below for more details.
subcycle99	Logical. If TRUE, includes plots with SUBCYCLE = 99. These plots are plots that are measured more than once and are not included in the estimation process.
stateFilter	Character string or Named list. Logical statement to use as plot and filter in sql query. Must include plot alias ('p.') and be sql syntax (e.g., 'p.COUNTYCD = 1'). If more than 1 state, stateFilter must be a named list with names as state(s) (e.g., list(Utah='p.COUNTYCD = 1').
allFilter	String. An overall filter for plot or condition data in all states in query. The expression must be R syntax (e.g., 'PLOT_STATUS_CD == 1').
alltFilter	String. If istree=TRUE, an overall filter for tree data in all states (e.g., only Whitebark pine trees - 'SPCD == 101'). Note: returns only plots with trees included in filter.
returndata	Logical. If TRUE, returns data objects.
savedata	Logical. If TRUE, saves data to outfolder as comma-delimited file (*.csv). No objects are returned. If FALSE, the data are saved as R objects and returned to user. See details for caveats.
exportsp	Logical. If TRUE, and issp=TRUE, exports spatial plots.
saveqry	Logical. If TRUE, saves queries to outfolder (by state).
savePOP	Logical. If TRUE, save and return the POP_PLOT_STRATUM_ASSGN table.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL,
dbconn	Open database connection.
dbconnopen	Logical. If TRUE, the dbconn connection is not closed.
evalInfo	List. List object output from DBgetEvalid or DBgetXY
...	For extendibility. FIESTA functions.

Details

FIA forest land definition

Current
Forested plots include plots with >= 10 percent cover (or equivalent stocking) by live trees of any size, including land that formerly had such tree cover and that will be naturally or artificially regenerated. To qualify, the area must be >= 1.0 acre in size and 120.0 feet wide (See Burrill et al. 2018).

*ACI (All Condition Inventory)*
RMRS National Forest plots. For nonforest conditions that have been visited in the field (NF_SAMPLING_STATUS_CD = if trees exist on the condition, the data exist in the tree table. If you do not want these trees included, ACI=FALSE. This will filter the data to only forested conditions (COND_STATUS_CD = 1)

*Nevada*
In 2016, the population area of Nevada changed to exclude the large restricted area owned by Department of Defense (Area 51) from the sample. Prior to 2016, the plots within this area were observed using aerial photos and if they were definitely nonforest the plots were entered in the database with nonforest information. If they were observed as forested or potentially forested, they were given a PLOT_STATUS_CD=3 because they were Denied Access. From 2016 on, all plots within this area are removed from the sample, and thus, removed from database.

FIA DataMart Data

FIA data available on FIA DataMart include the following information.

	- the PLOT variable is renumbered.
	- the LON/LAT coordinates are fuzzed & swapped.
	- the OWNERCD variable is based on fuzzed & swapped locations.
	- ECOSUBCD, CONGCD, ELEV, and EMAP_HEX are GIS-extracted values based on fuzzed & swapped locations.
	- For annual data, forested plots represent the current definition of >= 10 percent cover...
	- For periodic data, forested plots are defined by a definition of Other Wooded Land (OWL), including >= 5 percent cover...

FIA Evaluations

An evaluation is a group of plots within the FIA database that is used for generating population estimates, representing different inventory spans of data with different stratification or area adjustments. Each evaluation is determined by the type of estimation (Type) including: area and tree estimates; growth, removal, and mortality estimates; and area change estimates (EVAL_TYPE). These plots are identified by an evalid, which is a unique identifier in the format of a 2-digit State code, a 2-digit year code, and a 2-digit evaluation type code. For example, EVALID '491601' represents the Utah 2016 evaluation for current area estimates.

FIA Evaluation Types

Define one or more Evaluation Type for Cur=TRUE or Endyr=YYYY. An Evaluation type is used to identify a specific set of plots for a particular response that can be used to a make a statistically valid sample-based estimate. If Type='CURR', the evaluation includes all sampled and nonsampled plots or plots that were missed in an inventory year.

Regional differences may occur on how missed plots are represented in a FIA Evaluation. For example, RMRS Evaluations are static; missed plots are included in an Evaluation as nonsampled, and when measured, are included in a following Evaluation. Therefore, the number of nonsampled plots in previous Evaluations may change, depending on when missed plot are measured. In the PNW Research Station, plots are brought forward to replace missed plots in an evaluation, depending on the Type.

EVAL_TYP

	EVALIDCD	EVAL_TYP	Description
	00	EXPALL	All area
	01	EXPVOL/EXPCURR	Area/Volume
	03	EXPCHNG/EXPGROW/EXPMORT/EXPREMV	Area Change/GRM
	07	EXPDWM	DWM
	08	EXPREGEN	Regeneration
	09	EXPINV	Invasive
	10	EXPP2VEG	Veg profile
	12	EXPCRWN	Crown

Inventory span defining variables

Data can be extracted using FIA Evaluations or a custom-defined Evaluation for one or more states, one or more FIA Research Stations (RS), or all available states in database (states=NULL, RS=NULL).

*FIA Evaluation (eval=FIA)*

	eval_option	Description
	evalid	Specified FIA EVALID (e.g., 491801)
	Cur	Most current FIA Evaluation
	Endyr	End year of an FIA Evaluation (e.g., 2018)
	All	All evaluations in database
	Type	Type of FIA Evaluation (response)

*Custom evaluation (eval="custom")*

	eval_option	Description
	Cur	Most current measurement of plot in database
	Endyr	Most current measurement of plot in database in or before year
	All	All years for invtype (ANNUAL or PERIODIC or BOTH)
	Type	Type of custom Evaluation (response)
	invyrs	Specified inventory years (e.g., 2015:2018)

Spatial data

If issp=TRUE, an sf spatial object of plot-level attributes is generated from public coordinates, with NAD83 Geographic Coordinate Reference System.

*Exporting*
If savedata=TRUE and out_fmt="shp", the spatial object is exported to the outfolder using the ESRI Shapefile driver. The driver truncates variable names to 10 characters or less. Variable names are changed using an internal function. The name changes are written to a csv file and saved to the outfolder (shpfile_newnames.csv).

*spcond*
Only one condition per plot is used for spatial representation of condition attributes. IF CONDID1=TRUE, condition 1 is selected. If CONDID1=FALSE, the condition is selected based on the following criteria. A column named CONDMETHOD is added to the attribute table to show the method and steps used, identified by the abbreviation in parentheses.

	(1) minimum COND_STATUS_CD (_ST)
	(2) maximum condition proportion (_CP)
	(3) maximum live_canopy_cvr_pct (_CC)
	(4) minimum STDSZCD (_SZ)
	(5) minimum CONDID (_C1)

Derived Variables

If defaultVars=TRUE, the following derived variables are calculated after extracting data from the FIA database.

Plot-level variables:

	NBRCND - Number of conditions on plot, including nonsampled conditions (COND_STATUS_CD = 5)
	NBRCNDSAMP - Number of sampled conditions on plot.
	NBRCNDFOR - Number of sampled forested conditions on plot.
	NBRCNDFTYP - Number of sampled forested conditions with different forest types on plot.
	NBRCNDFGRP - Number of sampled forested conditions with different forest type groups on plot.
	CCLIVEPLT - Percent live canopy cover of condition aggregated to plot-level (LIVE_CANOPY_CVR_PCT * CONDPROP_UNADJ).
	PLOT_ID - Unique Identifier for a plot ('ID' + STATECD(2) + UNITCD(2) + COUNTYCD(3) + PLOT(5)). This variable can be used to identify multiple records for each measurement of plot.

Condition-level variables:

	FORTYPGRP - TYPGRPCD merged to FORTYPCD
	FLDTYPGRP - TYPGRPCD merged to FLDTYPCD
	FORNONSAMP - Combination of PLOT_STATUS_CD and PLOT_NONSAMPLE_REASN_CD
	QMD - Quadratic Mean Diameter

Tree-level variables:

	BA - the basal area of a tree (BA = DIA * DIA * 0.005454)

	TREE AGE Notes:
	- Available for live timber and woodland trees in the following states: AZ,CO,ID,MT,NV,UT,OR,WA.
	- BHAGE - Breast height age (4.5' above ground) of timber trees.
	- PNW - one tree is sampled for each species, within each crown class, and for each condition class present on plot. Age of saplings (<5.0" DIA) may be aged by counting branch whorls above 4.5ft. No timber hardwood species other than red alder are bored for age.
	- RMRS - one tree is sampled for each species and broad diameter class present on plot.

	DRYBIO Notes:
	DRYBIO_AG - Aboveground oven-dry biomass, in pounds (DRYBIO_AG = (DRYBIO_BOLE + DRYBIO_STUMP + DRYBIO_TOP + DRYBIO_SAPLING + DRYBIO_WDLD_SPP).
	- Available for both timber and woodland species, live trees >= 1.0" DIA and dead trees >= 5.0" DIA. Summed dry biomass of the top, bole, and stump of a tree, excluding foliage based on component ratio method (Heath and others, 2009).
	- DRYBIO_BOLE - dry biomass of sound wood in live and dead trees, including bark, from a 1-foot stump to a min 4-inch top DIA of central stem (Calculated for timber trees >= 5.0" DIA).
	- DRYBIO_STUMP - dry biomass in the tree stump, including the portion of the tree from the ground to the bottom of merchantable bole, 1-foot (Calculated for live and dead trees >= 5.0" DIA).
	- DRYBIO_TOP - dry biomass in the top of the tree, including the portion of the tree above merchantable bole, 4-inch top, and all branches, excludes foliage (Calculated for live and dead trees >= 5.0" DIA).
	- DRYBIO_SAPLING - dry biomass of saplings, including aboveground portion, excluding foliage, of live timber trees >=1.0" and <5.0" DIA.
	- DRYBIO_WDLD_SPP - dry biomass of woodland trees, live or dead, including the aboveground portion, excluding foliage, the top of the tree above 1.5" DIA, and a portion of the stump from ground to DRC (Calculated for woodland trees >= 1.0" DIA.

ABOVEGROUND CARBON ESTIMATES (IN POUNDS)
Available for both timber and woodland species, live trees >= 1.0" DIA and dead trees >= 5.0" DIA. Calculated as 1/2 of the aboveground estimates of biomass:
CARBON_AG = 0.5 * (DRYBIO_AG)

TREE AGE DATA ONLY IN FOR ("AZ", "CO", "ID", "MT", "NV", "UT")
FMORTCFAL includes trees >= 5.0" DIA and greater and is not populated for states("CA", "OR", "WA", "OK")
Mortality variables only available in: AZ, CO, ID, MT, NV, NM, UT, WY, ND, SD, NE, KS, OK.

TPA If TPA=TRUE and istree=TRUE or isseed=TRUE, the following tree/seedling variables are multiplied by trees-per-acre (TPA_UNADJ). TPA_UNADJ is set to a constant derived from the plot size and equals 6.018046 for trees sampled on subplots, 74.965282 for trees sampled on microplots, and 0.999188 for trees sampled on macroplots. Variable-radius plots were often used in earlier inventories, so the value in TPA_UNADJ decreases as the tree diameter increases (FIADB User Guide)

Variables: VOLCFNET, VOLCFGRS, GROWCFGS, GROWCFAL, FGROWCFGS, FGROWCFAL, MORTCFGS, MORTCFAL, FMORTCFGS, FMORTCFAL, REMVCFGS, REMVCFAL, FREMVCFGS, FREMVCFAL, DRYBIO_BOLE, DRYBIO_STUMP, DRYBIO_TOP, DRYBIO_SAPLING, DRYBIO_WDLD_SPP, DRYBIO_BG, CARBON_BG, CARBON_AG

MISC

For regions outside RMRS, there is no OWNCD attached to nonforest lands.

Value

if returndata=TRUE, a list of the following objects:

states	Vector. Input state(s) (full state names: Arizona).
tabs	List. A list of data frames from FIA database, including plt and cond; and tree (if Type='VOL'); seed (if isseed=TRUE), p2veg_subplot_spp, p2veg_subp_structure, and invasive_subplot_spp (if Type='P2VEG'). See below 'Output Tables - FIA Table Names' for reference to FIA database tables. See FIESTA:ref_* for variable descriptions (e.g., FIESTAutils::ref_tree). If istree and the number of states > 3, tree data are saved to outfolder and not returned to accommodate R memory issues.
xy*_PUBLIC	Data frame. XY data from FIA's public database. If measCur=TRUE, named xyCur_PUBLIC, else named xy_PUBLIC. The data frame has 10 columns ('PLT_CN', 'LON_PUBLIC', 'LAT_PUBLIC', 'STATECD', 'UNITCD', 'COUNTYCD', 'PLOT', 'INTENSITY', 'PLOT_ID' (ID+STATECD+UNTCD+COUNTYCD+PLOT), 'COUNTYFIPS'. If issp=TRUE, returns an sf object.
spconddat	If spcond=TRUE, the condition variables representing each plot for spatial display. For plots with multiple conditions, the selected condition is based on CONDID=1 (if spcondid1=TRUE) or a set if criteria defined in Details - spcond (if spcondid1=FALSE).
evalid	Number. If evalCur=TRUE or evalEndyr is not NULL, the Evalidation ID from the FIA database used to define the output data.
pltcnt	Data frame. Number of plots (NBRPLOTS) by state, cycle, inventory year, and plot status.
pop_plot_stratum_assgn	Data frame. If savePOP=TRUE, and FIA Evaluations are used to extract data from database, return the POP_PLOT_STRATUM_ASSGN table or, if more than one Type and savePOP=FALSE. If more than one Type, only the records for the evalTypes are returned, otherwise all Types for the state evaluation are returned.

*Output Tables - FIA Table Names*

	tab	FIA Table
	plt	plot
	cond	cond
	tree	tree
	p2veg_subplot_spp	P2VEG_SUBPLOT_SPP
	p2veg_subp_structure	P2VEG_SUBP_STRUCTURE
	invsubp	INVASIVE_SUBPLOT_SPP
	subplot	SUBPLOT
	subp_cond	SUBP_COND
	cond_dwm_calc	COND_DWM_CALC
	grm	TREE_GRM_COMPONENT
	issccm	SUBP_COND_CHNG_MTRX

#' Outputs to outfolder (if savedata=TRUE):

	- If saveqry=TRUE, text file(s) of SQL queries used to extract data from database (_.txt). Note: one query is used for extracting both plt and cond (pltcondqry*.txt).
	- CSV file of plot and condition counts (pltcnt*.txt).
	- Layers in a database or CSV files of output tables.
	- If issp=TRUE, a feature class or ESRI shapefile of plot-level level attributes. If shapefile (.shp), variable names are truncated to 10 characters or less. See notes for more info.
	- If issp=TRUE and out_fmt='sqlite', the SQLite data is SpatiaLite.

To deal with limitations of R object size and/or computer memory issues, if istree=TRUE and more than three states are desired, the tree data are saved to a CSV file, with no tree data object returned.

Note

If no parameters are included, the user is prompted for input. If partial parameters, the default parameter values are used for those not specified.

Data Access All data are downloaded from FIA's publicly-available online Datamart (https://apps.fs.usda.gov/fia/datamart/CSV/datamart_csv.html).

Because of FIA's confidentiality agreement to protect the privacy of landowners as well as protecting the scientific integrity of FIA's sample design, the exact coordinates of the sample plot locations are not included. The X/Y coordinates (LON_PUBLIC/LAT_PUBLIC) for download are perturbed up to a mile from the original location (https://www.fia.fs.fed.us/tools-data/spatial/Policy/index.php). If the exact location of the plots are necessary for your analysis, contact FIA's Spatial Data Services (https://www.fia.fs.fed.us/tools-data/spatial/index.php).

Author(s)

Tracey S. Frescino

References

DeBlander, Larry T.; Shaw, John D.; Witt, Chris; Menlove, Jim; Thompson, Michael T.; Morgan, Todd A.; DeRose, R. Justin; Amacher, Michael, C. 2010. Utah's forest resources, 2000-2005. Resour. Bull. RMRS-RB-10. Fort Collins, CO; U.S. Department of Agriculture, Forest Service, Rocky Mountain Research Station. 144 p.

Heath, L.S.; Hansen, M. H.; Smith, J.E. [and others]. 2009. Investigation into calculating tree biomass and carbon in the FIADB using a biomass expansion factor approach. In: Forest Inventory and Analysis (FIA) Symposium 2008. RMRS-P-56CD. Fort Collins, CO: U.S. Department of Agriculture, Forest Service, Rocky Mountain Research Station. 1 CD.

Burrill, E.A., Wilson, A.M., Turner, J.A., Pugh, S.A., Menlove, J., Christiansen, G., Conkling, B.L., Winnie, D., 2018. Forest Inventory and Analysis Database [WWW Document]. St Paul MN US Dep. Agric. For. Serv. North. Res. Stn. URL http://apps.fs.fed.us/fiadb-downloads/datamart.html (accessed 3.6.21).

Examples

## Not run: 
# Extract the most current evaluation of data for Utah
UTdat <- DBgetPlots(states = "Utah", 
                    eval = "FIA",
                    eval_opts = list(Cur = TRUE))
names(UTdat)
head(UTdat$plot)
UTdat$pltcnt

# Look at number of plots by inventory year
table(UTdat$plot$INVYR)

# Note: see FIESTAutils::ref_plot and FIESTAutils::ref_cond for variable descriptions
# Or consult FIA Database documentation
# \link{https://www.fia.fs.fed.us/library/database-documentation/index.php}

# Extract specified inventory years 2012:2014 and spatial information
UTdat2 <- DBgetPlots(states = "Utah",
                     eval = "custom",
                     eval_opts = list(invyrs = 2012:2014), 
                     issp = TRUE)
names(UTdat2)
UTdat2$pltcnt
UTdat2$xy_PUBLIC

# Extract and display plots with aspen forest type
UTdat3 <- DBgetPlots(states = "Utah",
                     eval = "custom",
                     eval_opts = eval_options(invyrs = 2012:2014),
                     issp = TRUE,
                     allFilter = "FORTYPCD == 901")
names(UTdat3)
UTdat3$pltcnt

plot(sf::st_geometry(FIESTA::stunitco[FIESTA::stunitco$STATENM == "Utah",]),
                     border = "light grey")
plot(sf::st_geometry(UTdat3$xy_PUBLIC), add=TRUE, pch=18, cex=.5)

## End(Not run)

---

Database - Queries a SQLite database table.

Description

Extracts and queries data from a SQLite (*.sqlite) database (Note: must use SQL syntax).

Usage

DBgetSQLite(states = NULL, outfolder = NULL)

Arguments

states	String. Vector of one or more state names.
outfolder	String. The output folder path. If NULL, outfolder is the working directory.

Value

Returns nothing.

Author(s)

Tracey S. Frescino

Examples

## Not run: 
# Extract data from Washington state
DBgetSQLite(states = "WA")

# Extract data from Utah and California, save to an outfolder
DBgetSQLite(states = c("UT", "CA"),
            outfolder = tempdir()) 

## End(Not run)

---

Database - Gets stratification information from FIA database.

Description

Gets strata information from FIA's Oracle database or FIA DataMart, including: (1) strata and estimation unit assignment per plot; (2) total area by estimation unit; (3) pixel counts and number plots by strata/estimation unit. Include a data frame of plots, states, or evaluation information.

Usage

DBgetStrata(
  dat = NULL,
  uniqueid = "CN",
  datsource = "datamart",
  data_dsn = NULL,
  states = NULL,
  eval_opts = eval_options(Cur = TRUE),
  savedata = FALSE,
  getassgn = TRUE,
  pop_plot_stratum_assgn = NULL,
  savedata_opts = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  evalInfo = NULL,
  ...
)

Arguments

dat	Data frame, comma-delimited file (*.csv), or shapefile (*.shp). The strata value is merged to this table and returned as a data frame. See details for necessary variables.
uniqueid	String. The unique plot identifier of dat (e.g., 'CN').
datsource	String. Source of data ('datamart', 'sqlite').
data_dsn	String. If datsource='sqlite', the name of SQLite database (*.sqlite).
states	String or numeric vector. Name(s) (e.g., 'Arizona','New Mexico') or code(s) (e.g., 4, 35) of states for strata if dat=NULL.
eval_opts	List of evaluation options for 'FIA' or 'custom' evaluations to determine the set of data returned. See help(eval_options) for a list of options.
savedata	Logical. If TRUE, writes output to outfolder.
getassgn	Logical. If TRUE, extracts plot assignments from pop_plot_stratum_assgn table in database.
pop_plot_stratum_assgn	Data frame. The pop_plot_stratum_assgn for state(s).
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE.
dbconn	Open database connection.
dbconnopen	Logical. If TRUE, the dbconn connection is not closed.
evalInfo	List. List object output from DBgetEvalid or DBgetXY
...	For extendibility. FIESTA functions.

Details

The following variables must be present in dat: STATECD, UNITCD, INVYR, a uniqueid (e.g. "PLT_CN"), and PLOT_STATUS_CD (if nonsampled plots in dataset).

FIADB TABLES USED:

	FS_FIADB.SURVEY	To get latest inventory year.
	FS_FIADB.POP_EVAL	To get EVALID and EVALID years.
	FS_FIADB.POP_ESTN_UNIT	To get total area by estimation unit (AREATOT_EU-includes water).
	FS_FIADB.POP_STRATUM	To get pixel counts by stratum and estimation unit.
	FS_FIADB.POP_PLOT_STRATUM_ASSGN	To get estimation unit & stratum assignment for each plot.

Area by estimation unit includes total area for all plots (Type="CURR").

Value

FIAstrata - a list of the following objects:

pltassgn	Data frame. Plot-level strata/estimation unit assignment. If dat is not NULL, strata/estimation unit variables are appended to dat.
pltassgnid	String. Name of unique identifier of plot in pltassgn.
unitarea	Data frame. Total acres by estimation unit.
unitvar	String. Name of the estimation unit variable (ESTN_UNIT).
areavar	String. Name of the acre variable (ACRES).
stratalut	Data frame. Strata look-up table with summarized pixel counts (P1POINTCNT) by strata/estimation unit.
strvar	String. Name of the strata variable (STRATA).
strwtvar	String. Name of the strata weight variable (P1POINTCNT).
evalid	List. evalid by state.

Outputs to outfolder (if savedata=TRUE):

	- CSV file of pltassgn (*'date'.csv).
	- CSV file of unitarea (*'date'.csv).
	- CSV file of stratalut (*'date'.csv).
	- If collapsed, a CSV file of original classes and new collapsed classes.

Note

Steps used in data extraction:

1. Get EVALID and EVALID years by state - DBgetEvalid().

2. unitarea: get total area by estimation unit for EVALID (POP_ESTN_UNIT).

3. stratalut: get pixel counts by estimation unit and stratum for EVALID (POP_STRATUM).

4. pltassgn: get estimation unit and stratum assignment for each plot for EVALID. (POP_PLOT_STRATUM_ASSGN).

5. If dat is not NULL, merge pltassgn assignment to dat.

6. Merge number of plots to stratalut

7. Check for only 1 MEASYEAR or 1 INVYR and number of plots by strata/estimation unit. If less than minimumnum plots per strata/estimation unit collapse using the following algorithm.

Strata collapsing:
If there are less than minplotnum (10) plots in the smallest strata of the estimation unit, these plots are grouped with the larger strata in the same estimation unit and defined as the highest strata value. If, after grouping, there are still less than minplotnum, all of these plots are combined with the corresponding strata of the estimation unit above. If there are no records above, then they are combined with the estimation unit below. The process repeats, grouping the strata to the highest strata value if necessary. All grouping is restrained within survey units (UNITCD).

More than one evaluation:
If attributing a table of plots and there are plots that have been visited more than once, all plots are assigned an estimation unit and strata value, but the area and strata proportions are from the most current evaluation for the dataset. The plots outside the most current evaluation are attributes with values from the next most current evaluation occurring in the database.

Author(s)

Tracey S. Frescino

Examples

## Not run: 
# Get strata for the most current evaluation of a state (ex. Wyoming)
WYstrat1 <- DBgetStrata(states = "Wyoming",
                        eval_opts = list(Cur = TRUE))
names(WYstrat1)

head(WYstrat1$pltassgn)
WYstrat1$unitarea
WYstrat1$unitvar
WYstrat1$areavar
WYstrat1$strvar
WYstrat1$evalid

# Get strata information for a specific set of plots
WYstrat4 <- DBgetStrata(dat = WYplt)
names(WYstrat4)

head(WYstrat4$pltassgn)
WYstrat4$unitarea
WYstrat4$evalid

## End(Not run)

---

Database - Extracts plot coordinates.

Description

Extracts public plot coordinates for an FIA evaluation or a custom evaluation. Plots are extracted from FIA's public Datamart (https://apps.fs.usda.gov/fia/datamart/datamart.html) or other defined datasource.

Usage

DBgetXY(
  states = NULL,
  RS = NULL,
  xy_datsource = NULL,
  xy_dsn = NULL,
  xy = "PLOT",
  xy_opts = xy_options(),
  datsource = NULL,
  data_dsn = NULL,
  dbTabs = dbTables(),
  pjoinid = "CN",
  eval = "FIA",
  eval_opts = eval_options(),
  invtype = "ANNUAL",
  coordType = "PUBLIC",
  intensity1 = FALSE,
  pvars2keep = NULL,
  issp = FALSE,
  returndata = TRUE,
  savedata = FALSE,
  exportsp = FALSE,
  savedata_opts = NULL,
  PLOT = NULL,
  POP_PLOT_STRATUM_ASSGN = NULL,
  SURVEY = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  evalInfo = NULL
)

Arguments

states	String or numeric vector. Name (e.g., 'Arizona','New Mexico') or code (e.g., 4, 35) of state(s) for evalid. If all states in one or more FIA Research Station is desired, set states=NULL and use RS argument to define RS.
RS	String vector. Name of research station(s) to get public XY coordinates for ('RMRS','SRS','NCRS','NERS','PNWRS'). Do not use if states is populated. See FIESTA::ref_statecd for reference to RS and states.
xy_datsource	Source of XY data ('datamart', 'sqlite', 'obj', 'csv').
xy_dsn	If datsource='sqlite', the file name (data source name) of the sqlite database (*.db) where XY data reside.
xy	sf R object or String. If xy_dsn = 'datamart', name of xy table in FIA DataMart. If xy_dsn = 'sqlite', name of xy layer in database. If datsource = 'csv', full pathname of xy CSV file(s). If datsource = 'obj', name of xy R object. If datsource = 'shp', full pathname of shapefile.
xy_opts	List of xy data options for xy (e.g., xy_opts = list(xvar='LON', yvar='LAT'). See xy_options() for more options and defaults.
datsource	String. Source of FIA data for defining FIA evaluations or appending variables ('datamart', 'sqlite', 'obj', 'csv'). If datsource = NULL, datsource = xy_datsource. If datsource = 'datamart', data are downloaded extracted from FIA DataMart (http://apps.fs.usda.gov/fia/datamart/datamart.html). If datsource='sqlite', specify database name(s) in data_dsn and table name(s) in dbTabs() argument. If datsource = ('obj','csv'), specify *.csv file name in dbTabs argument.
data_dsn	String. Name of database with plot_layer and/or ppsa_layer.
dbTabs	String or R Object. If data_dsn = 'datamart', name of table(s) in FIA DataMart. If data_dsn = 'sqlite', name of layer(s) in database. If datsource = 'csv', name of CSV file(s). If datsource = 'obj', name of R object.
pjoinid	String. Variable in plot table to join to XY data, if plot_layer is not NULL. Not necessary to be unique. If using most current XY coordinates, use identifier for a plot (e.g., PLOT_ID).
eval	String. Type of evaluation time frame for data extraction ('FIA', 'custom'). See eval_opts for more further options.
eval_opts	List of evaluation options for 'FIA' or 'custom' evaluations to determine the set of data returned. See help(eval_options) for a list of options.
invtype	String. Type of FIA inventory to extract ('PERIODIC', 'ANNUAL'). Only one inventory type (PERIODIC/ANNUAL) at a time.
coordType	String. c('PUBLIC', 'ACTUAL'). Defines type of coordinates and is used for the output name.
intensity1	Logical. If TRUE, includes only XY coordinates where INTENSITY = 1 (FIA base grid).
pvars2keep	String vector. One or more variables in plot_layer to append to output.
issp	Logical. If TRUE, returns spatial XY data as a list object with query.
returndata	Logical. If TRUE, returns XY data as a list object with query.
savedata	Logical. If TRUE, saves XY data. Specify outfolder and format using savedata_opts.
exportsp	Logical. If TRUE, exports data as spatial.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE or exportsp = TRUE.
PLOT	Data frame. The name of the PLOT data frame object if it is already downloaded and stored in environment.
POP_PLOT_STRATUM_ASSGN	Data frame. The name of the POP_PLOT_STRATUM_ASSGN data frame object if it is already downloaded and stored in environment.
SURVEY	Data frame. The name of the SURVEY data frame object if it has been already downloaded and stored in environment.
dbconn	Open database connection.
dbconnopen	Logical. If TRUE, the dbconn connection is not closed.
evalInfo	List. List object output from DBgetEvalid or DBgetXY FIESTA functions.

Value

if returndata=TRUE, a list of the following objects:

xy	Data frame. XY data from database. The output name is based on coordType parameter (e.g., xy_PUBLIC). the data frame include xy.uniqueid, xvar, yvar and appended plot variables in pvars2keep if plot_layer is not NULL. The default plot variables included are 'STATECD','UNITCD','COUNTYCD', 'PLOT','PLOT_ID' (ID+STATECD+UNTCD+COUNTYCD+PLOT), 'COUNTYFIPS'. If issp=TRUE, returns an sf object.
xyqry	String. Query to extract coordinates.
xvar	String. Name of X variable in xy*.
yvar	String. Name of Y variable in xy*.

If savedata=TRUE, outputs the xy* based on savedata_opts. If exportsp=TRUE, the output xy saved as spatial layer based on savedata_opts.

Note

If no parameters are included, the user is prompted for input. If partial parameters, the default parameter values are used for those not specified.

Author(s)

Tracey S. Frescino

Examples

## Not run: 
# Most current evaluation and shapefile with public coordinates
COxylst <- DBgetXY(states = "Colorado",
                   eval = "FIA",
                   eval_opts=eval_options(Endyr = 2019))
names(COxylst)

head(COxylst$xy_PUBLIC)
COxylst$xyqry

## End(Not run)

---

Database - Queries FIA Online Database.

Description

Downloads, extracts, and queries compressed comma-delimited file(s) (*.zip) from FIA DataMart (https://apps.fs.usda.gov/fia/datamart/CSV/datamart_csv.html). (Note: must use SQL syntax).

Usage

DBqryCSV(sql, states = NULL, sqltables = NULL)

Arguments

sql	String. A sql query. Must be appropriate sql syntax.
states	String vector. Name of state(s) in query. If not by state, set to NULL.
sqltables	String vector. Name of table(s) in sql statement to download. The sqltables must match tables in the sql statement (i.e., case-sensitive).

Details

The compressed data files are downloaded from FIA DataMart; saved to a temporary space; extracted and imported; and deleted from temporary space. Accessibility and download time depends on access and speed of internet connection.

Value

Returns a data frame from resulting query.

Author(s)

Tracey S. Frescino

Examples

## Not run: 
# Number of plots by inventory year for the state of Wyoming
sql <- "select INVYR, count(*) AS NBRPLOTS
        from plot
        where statecd=56 group by INVYR"
DBqryCSV(sql = sql,
         states = "Wyoming",
         sqltables = "plot")

## End(Not run)

---

List of population tables.

Description

Returns a list of user-supplied parameters and parameter values for data tables to be supplied to *DB functions.

Usage

dbTables(
  plot_layer = "PLOT",
  cond_layer = "COND",
  tree_layer = "TREE",
  seed_layer = "SEEDLING",
  plotgeom_layer = "PLOTGEOM",
  vsubpspp_layer = "P2VEG_SUBPLOT_SPP",
  vsubpstr_layer = "P2VEG_SUBP_STRUCTURE",
  invsubp_layer = "INVASIVE_SUBPLOT_SPP",
  subplot_layer = "SUBPLOT",
  subpcond_layer = "SUBP_COND",
  dwm_layer = "COND_DWM_CALC",
  sccm_layer = "SUBP_COND_CHNG_MTRX",
  grm_layer = "TREE_GRM_COMPONENT",
  grmb_layer = "TREE_GRM_BEGIN",
  grmm_layer = "TREE_GRM_MIDPT",
  survey_layer = "SURVEY",
  popeval_layer = "POP_EVAL",
  popevalgrp_layer = "POP_EVAL_GRP",
  popevaltyp_layer = "POP_EVAL_TYP",
  popstratum_layer = "POP_STRATUM",
  popestnunit_layer = "POP_ESTN_UNIT",
  ppsa_layer = "POP_PLOT_STRATUM_ASSGN",
  refspp_layer = "REF_SPECIES",
  other_layers = NULL,
  ...
)

Arguments

plot_layer	R object, comma-delimited file(*.csv), or name of layer in database. Plot-level data (PLOT).
cond_layer	R object, comma-delimited file(*.csv), or name of layer in database. Condition-level data (COND).
tree_layer	R object, comma-delimited file(*.csv), or name of layer in database. Tree-level data (TREE).
seed_layer	R object, comma-delimited file(*.csv), or name of layer in database. Seedling data (SEEDLING).
plotgeom_layer	R object, comma-delimited file(*.csv), or name of layer in database. Plot-level GIS extracted data (PLOTGEOM).
vsubpspp_layer	R object, comma-delimited file(*.csv), or name of layer in database. Understory vegetation species data (P2VEG_SUBPLOT_SPP).
vsubpstr_layer	R object, comma-delimited file(*.csv), or name of layer in database. Understory vegetation structure data (P2VEG_SUBP_STRUCTURE).
invsubp_layer	R object, comma-delimited file(*.csv), or name of layer in database. Understory vegetation invasives data (INVASIVE_SUBPLOT_SPP).
subplot_layer	R object, comma-delimited file(*.csv), or name of layer in database. Subplot-level data (SUBPLOT).
subpcond_layer	R object, comma-delimited file(*.csv), or name of layer in database. Subplot condition-level data (SUBP_COND).
dwm_layer	R object, comma-delimited file(*.csv), or name of layer in database. Down wood material data (COND_DWM_CALC)
sccm_layer	R object, comma-delimited file(*.csv), or name of layer in database. Subplot-level change matrix data (SUBP_COND_CHNG_MTRX).
grm_layer	R object, comma-delimited file(*.csv), or name of layer in database. Tree growth, removal, mortality data (TREE_GRM_COMPONENT).
grmb_layer	R object, comma-delimited file(*.csv), or name of layer in database. Tree growth, removal, mortality begin data (TREE_GRM_BEGIN).
grmm_layer	R object, comma-delimited file(*.csv), or name of layer in database. Tree growth, removal, mortality midpoint data (TREE_GRM_MIDPT).
survey_layer	R object, comma-delimited file(*.csv), or name of layer in database. Population survey (SURVEY) data.
popeval_layer	R object, comma-delimited file(*.csv), or name of layer in database. Population evaluation (POP_EVAL) data.
popevalgrp_layer	R object, comma-delimited file(*.csv), or name of layer in database. Population evaluation group data (POP_EVAL_GRP).
popevaltyp_layer	R object, comma-delimited file(*.csv), or name of layer in database. Population evaluation type data (POP_EVAL_TYP).
popstratum_layer	R object, comma-delimited file(*.csv), or name of layer in database. Population stratum data (POP_STRATUM).
popestnunit_layer	R object, comma-delimited file(*.csv), or name of layer in database. Population estimation unit data (POP_ESTN_UNIT).
ppsa_layer	R object, comma-delimited file(*.csv), or name of layer in database. Population plot stratum assignment data ( (POP_PLOT_STRATUM_ASSGN).
refspp_layer	R object, comma-delimited file(*.csv), or name of layer in database. Reference table for species (REF_SPECIES).
other_layers	String. Other layer(s) in database to clip and/or extract from database (Note: must include PLT_CN variable as unique identifier).
...	For extendibility.

Details

If no parameters, an empty list is returned.

Value

A list of user-supplied parameters and parameter values for strata.

Author(s)

Tracey S. Frescino

Examples

dbTables(plot_layer = FIESTA::WYplt)

---

Reference tables - gdal data types.

Description

Reference tables - gdal data types.

Usage

GDT_NAMES

Format

An object of class character of length 12.

Source

gdal values.

---

Reference table - List of RMRS plots that have fallen out of inventory because they were not found or they were in the wrong place.

Description

Reference table - List of RMRS plots that have fallen out of inventory because they were not found or they were in the wrong place.

Usage

kindcd3old

Format

An object of class data.frame with 38 rows and 8 columns.

Source

FIA query. SELECT bp.STATECD, bp.COUNTYCD, bp.PLOT_FIADB NEW_PLOT, bp.START_DATE NEW_START_DATE, bp_old.COUNTYCD OLD_COUNTYCD, bp_old.PLOT_FIADB OLD_PLOT, bp_old.END_DATE OLD_END_DATE, p.CN FROM fs_nims_rmrs.NIMS_BASE_PLOT bp JOIN fs_nims_rmrs.NIMS_BASE_PLOT bp_old on (bp.PREV_NBP_CN=bp_old.CN) JOIN fs_nims_rmrs.NIMS_PLOT_RMRS_VW p on(p.NBP_CN=bp_old.CN) WHERE p.KINDCD = 1 ORDER BY bp.STATECD, bp.COUNTYCD, bp_old.PLOT_FIADB"

---

Green-Book module - Generate area estimates.

Description

Generates area estimates by domain (and estimation unit). Calculations are based on Scott et al. 2005 ('the green-book') for mapped forest inventory plots. The non-ratio estimator for estimating area by stratum and domain is used. Plots that are totally nonsampled are excluded from estimation dataset. Next, an adjustment factor is calculated by strata to adjust for nonsampled (nonresponse) conditions that have proportion less than 1. The attribute is the proportion of the plot which is divided by the adjustment factor, and averaged by stratum. Strata means are combined using the strata weights and then expanded to area using the total land area in the population.

Usage

modGBarea(
  GBpopdat,
  landarea = "FOREST",
  pcfilter = 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().
landarea	String. The sample area filter for estimates ("ALL", "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.
rowvar	String. Name of row domain variable in cond. If only one domain, rowvar = domain variable. If more than one domain, include colvar. If no domain, rowvar = NULL.
colvar	String. Name of column domain variable in cond.
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 variables are NULL, then it will prompt user to input variables.

Necessary variables:

	Data	Variable	Description
	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.
	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. Area estimates, in area units (e.g., acres), by rowvar, colvar (and estimation unit). If sumunits=TRUE or one estimation unit and colvar=NULL, or allin1=TRUE, estimates and percent sampling error are in one data frame.
pse	Data frame. Percent sampling errors (Confidence level 68 for estimates by rowvar and colvar (and estimation unit).
titlelst	List. 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. Row and column tables are also included in list.
raw	List. 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 (e.g., 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.
domdat	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 (strata weight)
	CONDPROP_UNADJ_SUM	summed condition proportion by strata and estimation unit
	CONDPROP_ADJFAC	adjusted condition proportion by strata after nonresponse plots removed
	AREA	total area for estimation unit
	CONDPROP_ADJFAC	average area

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), colvar totals, if not NULL (unit.colvar); and a combination of rowvar and colvar, if colvar is not NULL (unit.grpvar). 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). The data frames include the following information: Variable Description nhat estimate proportion of land nhat.var variance estimate of estimated proportion of land NBRPLT.gt0 Number of non-zero plots used in estimates AREA total area for estimation unit est estimated area of land nhat*areavar est.var variance estimate of estimate acres of land nhat.var*areavar^2 est.se standard error of estimated area of land sqrt(est.var) est.cv coefficient of variation of estimated area of land 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

savedata
if savedata=TRUE...
tables with estimate and percent standard error will be written as *csv files to outfolder. if rawdata=TRUE, the rawdata will be output to the outfolder in a folder named rawdata (if raw_fmt="csv") or a database in the outfolder, if (raw_fmt != "csv").

if outfn.pre is not null...
a prefix is added to output files if raw_fmt = 'csv', prefix is added to file names in rawdata folder if raw_fmt != 'csv', prefix is added to dsn name

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 condition proportions (CONDPROP_UNADJ) and dividing by the number of plots in the strata/estimation unit.

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.

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

forest_area <- modGBarea(
GBpopdat = GBpopdat, 
landarea = "FOREST",  
sumunits = TRUE,      
)
str(forest_area, max.level = 1)

forest_area_by_forest_type <- modGBarea(
GBpopdat = GBpopdat,        
landarea = "FOREST",       
rowvar = "FORTYPCD",        
sumunits = TRUE            
)
str(forest_area_by_forest_type, max.level = 1)

---

Green-Book module - Generate area estimates.

Description

Generates area estimates by domain (and estimation unit). Calculations are based on Scott et al. 2005 ('the green-book') for mapped forest inventory plots. The non-ratio estimator for estimating area by stratum and domain is used. Plots that are totally nonsampled are excluded from estimation dataset. Next, an adjustment factor is calculated by strata to adjust for nonsampled (nonresponse) conditions that have proportion less than 1. The attribute is the proportion of the plot which is divided by the adjustment factor, and averaged by stratum. Strata means are combined using the strata weights and then expanded to area using the total land area in the population.

Usage

modGBchng(
  GBpopdat,
  chngtype = "total",
  landarea = "FOREST",
  pcfilter = NULL,
  rowvar = NULL,
  colvar = NULL,
  sumunits = TRUE,
  returntitle = FALSE,
  savedata = FALSE,
  table_opts = NULL,
  title_opts = NULL,
  savedata_opts = NULL,
  cdomdat = NULL,
  gui = FALSE,
  ...
)

Arguments

GBpopdat	List. Population data objects returned from modGBpop().
chngtype	String. The type of change estimates ('total', 'annual').
landarea	String. The sample area filter for estimates ("ALL", "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.
rowvar	String. Name of row domain variable in cond. If only one domain, rowvar = domain variable. If more than one domain, include colvar. If no domain, rowvar = NULL.
colvar	String. Name of column domain variable in cond.
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.
cdomdat	Data.frame of condition-domain data. Output from modGBchng().
gui	Logical. If gui, user is prompted for parameters.
...	Parameters for modGBpop() if GBpopdat is NULL.

Details

If variables are NULL, then it will prompt user to input variables.

Necessary variables:

	Data	Variable	Description
	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.
	pltassgn	puniqueid	Unique identifier for each plot, to link to cond (e.g., 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. Area estimates, in area units (e.g., acres), by rowvar, colvar (and estimation unit). If sumunits=TRUE or one estimation unit and colvar=NULL, or allin1=TRUE, estimates and percent sampling error are in one data frame.
pse	Data frame. Percent sampling errors (Confidence level 68 for estimates by rowvar and colvar (and estimation unit).
titlelst	List. 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. Row and column tables are also included in list.
raw	List. 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 (e.g., 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.
domdat	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 (strata weight)
	CONDPROP_UNADJ_SUM	summed condition proportion by strata and estimation unit
	CONDPROP_ADJFAC	adjusted condition proportion by strata after nonresponse plots removed
	AREA	total area for estimation unit
	CONDPROP_ADJFAC	average area

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), colvar totals, if not NULL (unit.colvar); and a combination of rowvar and colvar, if colvar is not NULL (unit.grpvar). 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). The data frames include the following information: Variable Description nhat estimate proportion of land nhat.var variance estimate of estimated proportion of land NBRPLT.gt0 Number of non-zero plots used in estimates AREA total area for estimation unit est estimated area of land nhat*areavar est.var variance estimate of estimate acres of land nhat.var*areavar^2 est.se standard error of estimated area of land sqrt(est.var) est.cv coefficient of variation of estimated area of land 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

savedata
if savedata=TRUE...
tables with estimate and percent standard error will be written as *csv files to outfolder. if rawdata=TRUE, the rawdata will be output to the outfolder in a folder named rawdata (if raw_fmt="csv") or a database in the outfolder, if (raw_fmt != "csv").

if outfn.pre is not null...
a prefix is added to output files if raw_fmt = 'csv', prefix is added to file names in rawdata folder if raw_fmt != 'csv', prefix is added to dsn name

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 condition proportions (CONDPROP_UNADJ) and dividing by the number of plots in the strata/estimation unit.

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.

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.

---

Green-Book module - Generate area estimates.

Description

Generates area estimates by domain (and estimation unit). Calculations are based on Scott et al. 2005 ('the green-book') for mapped forest inventory plots. The non-ratio estimator for estimating area by stratum and domain is used. Plots that are totally nonsampled are excluded from estimation dataset. Next, an adjustment factor is calculated by strata to adjust for nonsampled (nonresponse) conditions that have proportion less than 1. The attribute is the proportion of the plot which is divided by the adjustment factor, and averaged by stratum. Strata means are combined using the strata weights and then expanded to area using the total land area in the population.

Usage

modGBdwm(
  GBpopdat = NULL,
  dwmtype = "CWD",
  dwmvar = "VOLCF",
  peracre = FALSE,
  lbs2tons = FALSE,
  landarea = "FOREST",
  pcfilter = NULL,
  vfilter = 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().
dwmtype	String. Type of dwm estimate ('CWD', 'FWD_LG', "FWD_MD", "FWD_SM").
dwmvar	String. Type of dwm estimate ('VOLCF', 'BIOMASS', "CARBON").
peracre	Logical. If TRUE, generates per-acre estimates.
lbs2tons	Logical. If TRUE, converts biomass or carbon variables from pounds to tons. If metric=TRUE, converts to metric tons, else short tons.
landarea	String. The sample area filter for estimates ("ALL", "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.
vfilter	String. A filter for the P2 vegetation table used for estimate. Must be R logical syntax.
rowvar	String. Name of row domain variable in cond. If only one domain, rowvar = domain variable. If more than one domain, include colvar. If no domain, rowvar = NULL.
colvar	String. Name of column domain variable in cond.
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 variables are NULL, then it will prompt user to input variables.

Necessary variables:

	Data	Variable	Description
	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.
	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. Area estimates, in area units (e.g., acres), by rowvar, colvar (and estimation unit). If sumunits=TRUE or one estimation unit and colvar=NULL, or allin1=TRUE, estimates and percent sampling error are in one data frame.
pse	Data frame. Percent sampling errors (Confidence level 68 unit).
titlelst	List. 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. Row and column tables are also included in list.
raw	List. 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 (e.g., 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.
domdat	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 (strata weight)
	CONDPROP_UNADJ_SUM	summed condition proportion by strata and estimation unit
	CONDPROP_ADJFAC	adjusted condition proportion by strata after nonresponse plots removed
	AREA	total area for estimation unit
	CONDPROP_ADJFAC	average area

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), colvar totals, if not NULL (unit.colvar); and a combination of rowvar and colvar, if colvar is not NULL (unit.grpvar). 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). The data frames include the following information: Variable Description nhat estimate proportion of land nhat.var variance estimate of estimated proportion of land NBRPLT.gt0 Number of non-zero plots used in estimates AREA total area for estimation unit est estimated area of land nhat*areavar est.var variance estimate of estimate acres of land nhat.var*areavar^2 est.se standard error of estimated area of land sqrt(est.var) est.cv coefficient of variation of estimated area of land 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

savedata
if savedata=TRUE...
tables with estimate and percent standard error will be written as *csv files to outfolder. if rawdata=TRUE, the rawdata will be output to the outfolder in a folder named rawdata (if raw_fmt="csv") or a database in the outfolder, if (raw_fmt != "csv").

if outfn.pre is not null...
a prefix is added to output files if raw_fmt = 'csv', prefix is added to file names in rawdata folder if raw_fmt != 'csv', prefix is added to dsn name

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 condition proportions (CONDPROP_UNADJ) and dividing by the number of plots in the strata/estimation unit.

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.

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.

---

Green-Book module - Generate area estimates.

Description

Generates area estimates by domain (and estimation unit). Calculations are based on Scott et al. 2005 ('the green-book') for mapped forest inventory plots. The non-ratio estimator for estimating area by stratum and domain is used. Plots that are totally nonsampled are excluded from estimation dataset. Next, an adjustment factor is calculated by strata to adjust for nonsampled (nonresponse) conditions that have proportion less than 1. The attribute is the proportion of the plot which is divided by the adjustment factor, and averaged by stratum. Strata means are combined using the strata weights and then expanded to area using the total land area in the population.

Usage

modGBp2veg(
  GBpopdat = NULL,
  p2vegtype = "str",
  peracre = FALSE,
  landarea = "FOREST",
  pcfilter = NULL,
  vfilter = 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().
p2vegtype	String. Type of p2veg estimate ('str', 'spp').
peracre	Logical. If TRUE, generates per-acre estimates.
landarea	String. The sample area filter for estimates ("ALL", "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.
vfilter	String. A filter for the P2 vegetation table used for estimate. Must be R logical syntax.
rowvar	String. Name of row domain variable in cond (e.g., 'FORTYPCD') or P2VEG_SUBP_STRUCTURE (e.g., 'GROWTH_HABIT_CD', 'LAYER') or P2VEG_SUBPLOT_SPP (e.g., 'VEG_FLDSPCD', 'VEG_SPCD', 'GROWTH_HABIT_CD', 'LAYER'). If only one domain, rowvar = domain variable. If more than one domain, include colvar. If no domain, rowvar = NULL.
colvar	String. Name of column domain variable in cond.
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 variables are NULL, then it will prompt user to input variables.

Necessary variables:

	Data	Variable	Description
	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.
	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. Area estimates, in area units (e.g., acres), by rowvar, colvar (and estimation unit). If sumunits=TRUE or one estimation unit and colvar=NULL, or allin1=TRUE, estimates and percent sampling error are in one data frame.
pse	Data frame. Percent sampling errors (Confidence level 68 unit).
titlelst	List. 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. Row and column tables are also included in list.
raw	List. 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 (e.g., 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.
domdat	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 (strata weight)
	CONDPROP_UNADJ_SUM	summed condition proportion by strata and estimation unit
	CONDPROP_ADJFAC	adjusted condition proportion by strata after nonresponse plots removed
	AREA	total area for estimation unit
	CONDPROP_ADJFAC	average area

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), colvar totals, if not NULL (unit.colvar); and a combination of rowvar and colvar, if colvar is not NULL (unit.grpvar). 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). The data frames include the following information: Variable Description nhat estimate proportion of land nhat.var variance estimate of estimated proportion of land NBRPLT.gt0 Number of non-zero plots used in estimates AREA total area for estimation unit est estimated area of land nhat*areavar est.var variance estimate of estimate acres of land nhat.var*areavar^2 est.se standard error of estimated area of land sqrt(est.var) est.cv coefficient of variation of estimated area of land 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

savedata
if savedata=TRUE...
tables with estimate and percent standard error will be written as *csv files to outfolder. if rawdata=TRUE, the rawdata will be output to the outfolder in a folder named rawdata (if raw_fmt="csv") or a database in the outfolder, if (raw_fmt != "csv").

if outfn.pre is not null...
a prefix is added to output files if raw_fmt = 'csv', prefix is added to file names in rawdata folder if raw_fmt != 'csv', prefix is added to dsn name

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 condition proportions (CONDPROP_UNADJ) and dividing by the number of plots in the strata/estimation unit.

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.

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.

---