R/datSumTree.R
datSumTree.RdAggregates 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).
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
)Dataframe or comma-delimited file (*.csv). The tree-level table.
Dataframe or comma-delimited file (*.csv). The seedling table.
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.
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.
Dataframe, comma-delimited file (*.csv), or shapefile (*.shp). Subplot condition-level table to use to sum condition proportions, if bysubp=TRUE.
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.
String. Source of data ('obj', 'csv', 'sqlite', 'gdb').
String. If datsource='sqlite', the name of SQLite database (*.sqlite).
String. Unique identifier of plt in tree table.
String. Unique identifier of plt in cond table if cond is NOT NULL.
String. Unique identifier of plt table if plt is NOT NULL.
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.
String. Unique identifier for conditions.
Logical. If TRUE, data are aggregated to the subplot level.
String. Unique identifier of plot in subplot and subp_cond table.
String. Unique identifier of each subplot.
String (vector). Tree-level variable(s) to aggregate (e.g., "TPA_UNADJ", "BA"). Use "TPA_UNADJ" (tfun=sum) for summed tree count.
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").
Logical. If TRUE, add seedling counts to tree counts. Note: tdomvar must be 'SPCD' or 'SPGRPCD'.
Logical. If TRUE, seedling counts only. Note: tdomvar must be 'SPCD' or 'SPGRPCD'.
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.
Logical. If TRUE, tsumvarlst variable(s) are multiplied by the respective trees-per-acre variable (see details) to get per-acre measurements.
Function. The name of the function to use to aggregate the data (e.g., sum, mean, max).
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.
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.
Logical. If TRUE, converts biomass or carbon variables from pounds to tons (1 pound = 0.0005 short tons).
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).
Logical. If TRUE, adjustments are calculated for nonsampled conditions on plot.
Logical. If TRUE, trees are individually adjusted by adjustment factors. Adjustment factors must be included in tree table (see adjvar).
String. If adjtree=TRUE, the name of the variable to use for multiplying by adjustment (e.g., tadjfac).
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.
Logical. If TRUE, convert NA values to 0.
Number. The number of digits to round to. If NULL, default=5.
Logical. If TRUE, returns data.table object(s). If FALSE, returns data.frame object(s).
Logical. If TRUE, saves data to outfolder.
List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'treesum'.
Open database connection.
Logical. If TRUE, keep database connection open.
Logical. If gui, user is prompted for parameters.
A list of the following items:
Data frame. Plot or condition-level table with aggregated tree attributes.
String vector. Name(s) of the output aggregated tree attributes.
String list. Units of output, when available.
String list. Filter used.
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).
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.
If a dat table is provided, the aggregated tree data will be merged to table and NULL values will be output as 0.
# \donttest{
# 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,]
#> Key: <PLT_CN>
#> PLT_CN COUNT_TPA
#> <char> <num>
#> 1: 40404737010690 12.03609
FIESTA::WYtree[FIESTA::WYtree$PLT_CN == 40404737010690,]
#> PLT_CN CONDID SUBP TREE STATUSCD SPCD SPGRPCD DIA HT TREECLCD
#> 8 40404737010690 2 3 1 2 746 44 NA NA NA
#> 9 40404737010690 2 3 2 2 746 44 NA NA NA
#> 10 40404737010690 2 3 3 1 746 44 5.9 24 2
#> 11 40404737010690 2 3 6 1 746 44 6.3 22 3
#> 12 40404737010690 2 3 7 2 746 44 NA NA NA
#> 13 40404737010690 2 3 8 2 746 44 NA NA NA
#> AGENTCD STANDING_DEAD_CD VOLCFNET VOLCFGRS VOLBFNET TPA_UNADJ DRYBIO_AG
#> 8 70 0 NA NA NA NA NA
#> 9 70 0 NA NA NA NA NA
#> 10 NA NA 1.270199 1.380651 NA 6.018046 76.89118
#> 11 NA NA 1.200818 1.501023 NA 6.018046 79.18261
#> 12 70 0 NA NA NA NA NA
#> 13 70 0 NA NA NA NA NA
#> CARBON_AG BA
#> 8 NA NA
#> 9 NA NA
#> 10 36.83087 0.1898537
#> 11 37.92847 0.2164693
#> 12 NA NA
#> 13 NA NA
# }