datSumTree: Data - Aggregates numeric tree data to the plot or...

In FIESTA: Forest Inventory Estimation and Analysis

Data - Aggregates numeric tree data to the plot or condition-level.

Description

Aggregates numeric tree-level data (e.g., VOLCFNET) to plot or condition, including options for filtering tree data or extrapolating to plot aseedonlycre by multiplying by TPA.

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

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

Dependent external functions: datFilter Dependent internal functions: addcommas, fileexistsnm, getadjfactor

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,]

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