Data - Aggregates numeric tree data to the plot or condition-level.
Source:R/datSumTree.R
datSumTree.RdAggregates 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",
dbconn = NULL,
dsn = NULL,
bycond = FALSE,
bysubp = FALSE,
bydomainlst = NULL,
tsumvarlst = NULL,
tsumvarnmlst = NULL,
seedlings = "N",
woodland = "Y",
tfilter = NULL,
domclassify = NULL,
tderive = NULL,
getadjplot = FALSE,
pltidsWITHqry = NULL,
pltidsid = NULL,
pcwhereqry = NULL,
savedata = FALSE,
tabIDs = tableIDs(),
datSum_opts = datSum_options(),
database_opts = NULL,
savedata_opts = NULL
)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 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.
- 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').
- dbconn
Open database connection.
- dsn
String. If datsource='sqlite', the name of SQLite database (*.sqlite).
- 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 subplotid, subpid, condid.
- bysubp
Logical. If TRUE, data are aggregated to the subplot level.
- bydomainlst
String (vector). Categorical domain variables for summing tree data by (e.g., SPCD). Variables must be in tree table or plt/cond table if tables are provided.
- tsumvarlst
String (vector). Tree-level variable(s) to aggregate (e.g., "TPA_UNADJ", "BA"). Use "TPA_UNADJ" 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_SUM (e.g., "TPA_UNADJ_SUM", "BA_SUM").
- seedlings
String. ('Y', 'N', 'only') If seedlings = 'Y', add seedlings to summary ('TPA_UNADJ' do not add seedlings. If seedlings = 'only', only include seedlings.
- woodland
String. ('Y', 'N', 'only') 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. If NULL, use whatever is in 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.
- domclassify
List. List for classifying domain variables in bydomainlst (e.g., DIA = c(10,20,30)).
- tderive
List. List of derivative from tree table to add to output data (e.g., list(MEAN_DIA = 'AVG(DIA)', SDI = 'POWER(DIA / 10, 1.605)', QMD = 'SQRT(SUM(POWER(DIA,2) * 0.005454 * TPA_UNADJ) / (SUM(TPA_UNADJ)*0.005454))'))
- getadjplot
Logical. If TRUE, and adj='plot', adjfactors are calculated for nonsampled conditions at plot-level.
- pltidsWITHqry
SQL query. A query identifying plots to sum (e.g., 'WITH pltids AS (SELECT cn AS PLT_CN FROM plot WHERE statecd=49 and INVYR=2018)')
- pltidsid
Sting. Name of unique identifier in pltidsWITHqry.
- pcwhereqry
String. Plot/Condition filter if plot and/or cond table is included.
- savedata
Logical. If TRUE, saves data to outfolder.
- tabIDs
List of unique IDs corresponding to the tables. See See help(tableIDs) for a list of options.
- datSum_opts
List. Options for summarizing tree data, such as TPA, rounding, and adjusting TPA. See help(datSum_options()) for a list of options.
- database_opts
List. Options for database, such as schema and password. See help(database_options()) for a list of options.
- savedata_opts
List. See help(savedata_options()) for a list
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.
If savedata=TRUE
- treedat will be saved to the outfolder.
- a text
file of input parameters is saved to outfolder
('outfn'_parameters_'date'.txt).
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.
Note
If a dat table is provided, the aggregated tree data will be merged to table and NULL values will be output as 0.
Examples
# Aggregate LIVE_CANOPY_CVR_PCT to plot
treesum <- datSumTree(tree = FIESTA::WYtree,
tsumvarlst = "TPA_UNADJ")$treedat
#> Warning: no DISPLAY variable so Tk is not available
# Check results
treesum[treesum$PLT_CN == 40404737010690,]
#> Key: <PLT_CN>
#> PLT_CN COUNT_TPA
#> <char> <num>
#> 1: 40404737010690 24.07218
FIESTA::WYtree[FIESTA::WYtree$PLT_CN == 40404737010690,]
#> PLT_CN CONDID SUBP TREE STATUSCD SPCD SPGRPCD DIA HT TREECLCD
#> 8 40404737010690 1 1 1 1 113 24 7.7 17 2
#> 9 40404737010690 1 1 3 2 113 24 NA NA NA
#> 10 40404737010690 1 1 4 2 113 24 NA NA NA
#> 11 40404737010690 2 3 1 2 746 44 NA NA NA
#> 12 40404737010690 2 3 2 2 746 44 NA NA NA
#> 13 40404737010690 2 3 3 1 746 44 5.9 24 2
#> 14 40404737010690 2 3 6 1 746 44 6.3 22 3
#> 15 40404737010690 2 3 7 2 746 44 NA NA NA
#> 16 40404737010690 2 3 8 2 746 44 NA NA NA
#> 17 40404737010690 1 4 1 2 113 24 11.7 22 3
#> AGENTCD STANDING_DEAD_CD VOLCFNET VOLCFGRS VOLBFNET TPA_UNADJ DRYBIO_AG
#> 8 NA NA 1.698099 1.698099 NA 6.018046 92.57234
#> 9 50 0 NA NA NA NA NA
#> 10 50 0 NA NA NA NA NA
#> 11 70 0 NA NA NA NA NA
#> 12 70 0 NA NA NA NA NA
#> 13 NA NA 1.270199 1.380651 NA 6.018046 76.89118
#> 14 NA NA 1.200818 1.501023 NA 6.018046 79.18261
#> 15 70 0 NA NA NA NA NA
#> 16 70 0 NA NA NA NA NA
#> 17 NA 1 3.892168 5.560240 NA 6.018046 191.39679
#> CARBON_AG BA
#> 8 44.43472 0.3233677
#> 9 NA NA
#> 10 NA NA
#> 11 NA NA
#> 12 NA NA
#> 13 36.83087 0.1898537
#> 14 37.92847 0.2164693
#> 15 NA NA
#> 16 NA NA
#> 17 96.46398 0.7465981