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

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",
  dbconn = NULL,
  dsn = NULL,
  bycond = FALSE,
  bysubp = FALSE,
  tsumvar = NULL,
  seedlings = "N",
  woodland = "Y",
  tfilter = NULL,
  tdomvar = "SPCD",
  tdomvarlst = NULL,
  tdomvar2 = NULL,
  tdomvar2lst = NULL,
  tdomprefix = NULL,
  tdombarplot = FALSE,
  tdomtot = FALSE,
  tdomtotnm = NULL,
  bydomainlst = NULL,
  FIAname = FALSE,
  spcd_name = "COMMON",
  pivot = TRUE,
  presence = FALSE,
  proportion = FALSE,
  getadjplot = FALSE,
  domclassify = NULL,
  tderive = NULL,
  pltidsWITHqry = NULL,
  pcwhereqry = NULL,
  savedata = FALSE,
  tabIDs = tableIDs(),
  datSum_opts = datSum_options(),
  database_opts = NULL,
  savedata_opts = NULL
)

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').
dbconn: Open database connection.
dsn: String. If datsource='sqlite', the name of SQLite database (*.sqlite).
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).
bysubp: Logical. If TRUE, data are aggregated to the subplot level.
tsumvar: String. Name of the variable to aggregate (e.g., "BA"). For summing number of trees, use tsumvar="TPA_UNADJ" with tfun=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. 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.
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'.
bydomainlst: String (vector). Categorical domain variables not in tdomvar/tdomvar2. Variables must be in tree table or plt/cond table if tables are provided.
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.
getadjplot: Logical. If TRUE, adjustments are calculated for nonsampled conditions on plot.
domclassify: List. List for classifying domain variables in bydomainlst (e.g., DIA = c(10,20,30)).
tderive: List. List of derivative 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))'))
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)')
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 of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'tdomsum'.

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)

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

Note

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

Author

Tracey S. Frescino

Examples

# \donttest{
              
# Sum of Number of Live Trees by Species
datSumTreeDom(tree = FIESTA::WYtree,
              plt = FIESTA::WYplt, 
              bycond = FALSE, 
              tsumvar = "PLT_CN", 
              tdomtot = TRUE, 
              tdomprefix = "CNT", 
              tfilter = "STATUSCD==1",
              datSum_opts = list(tround = 0))
#> $tdomdat
#> Key: <PLT_CN>
#>               PLT_CN CNT NA CNT019 CNT065 CNT066 CNT093 CNT096 CNT101 CNT106
#>               <char>  <num>  <num>  <num>  <num>  <num>  <num>  <num>  <num>
#>    1: 40404728010690      0      0      0      0      0      0      0      0
#>    2: 40404729010690      0      0      0     12      0      0      0      0
#>    3: 40404730010690      0      0      0      0      0      0      0      0
#>    4: 40404731010690      0      0      0      0      0      0      0      0
#>    5: 40404733010690      0      0      0      0      0      0      0      0
#>   ---                                                                       
#> 3043: 40407866010690      0      0      0      0      0      0      0      0
#> 3044: 40407867010690      0      0      0      0      0      0      0      0
#> 3045: 40407868010690      0      0      0      0      0      0      0      0
#> 3046: 40407869010690      0      0      0      0      0      0      0      0
#> 3047: 46792188020004      0      0      0      0      0      0      0      0
#>       CNT108 CNT113 CNT122 CNT202 CNT313 CNT375 CNT475 CNT544 CNT745 CNT746
#>        <num>  <num>  <num>  <num>  <num>  <num>  <num>  <num>  <num>  <num>
#>    1:      0      0      0      0      0      0      0      0      0      0
#>    2:      0     18      0      0      0      0      0      0      0      0
#>    3:      6     36    135    138      0      0      0      0      0      0
#>    4:      0      0      0      0      0      0      0      0      0      0
#>    5:      0      0      0      0      0      0      0      0      0      0
#>   ---                                                                      
#> 3043:      0      0      0      0      0      0      0      0      0      0
#> 3044:      0      0      0      0      0      0      0      0      0      0
#> 3045:      0      0      0      0      0      0      0      0      0      0
#> 3046:      0      0      0      0      0      0      0      0      0      0
#> 3047:      0     18      0    282      0      0      0      0      0      0
#>       CNT749 CNT823 CNTTOT
#>        <num>  <num>  <num>
#>    1:      0      0      0
#>    2:      0      0     30
#>    3:      0      0    315
#>    4:      0      0      0
#>    5:      0      0      0
#>   ---                     
#> 3043:      0      0      0
#> 3044:      0      0      0
#> 3045:      0      0      0
#> 3046:      0      0      0
#> 3047:      0      0    300
#> 
#> $tsumuniqueid
#> [1] "PLT_CN"
#> 
#> $tsumvarnm
#> [1] "COUNT_TPA"
#> 
#> $tdomvarnm
#> [1] "SPCDNM"
#> 
#> $tdomvarlut
#>     SPCDNM COUNT_TPA NBRPLOTS
#>     <char>     <num>    <int>
#>  1: CNT NA         0     2506
#>  2: CNT066      5328       72
#>  3: CNT113      4770       78
#>  4: CNT108     69563      235
#>  5: CNT122     12995       91
#>  6: CNT202      9831       98
#>  7: CNT746     12339       64
#>  8: CNT019     55937      218
#>  9: CNT093     22564      186
#> 10: CNT065      2216       20
#> 11: CNT745        96        3
#> 12: CNT823      1213       12
#> 13: CNT375        75        1
#> 14: CNT101     11568       90
#> 15: CNT096       348        3
#> 16: CNT749       225        4
#> 17: CNT475        24        2
#> 18: CNT313        54        2
#> 19: CNT544        66        2
#> 20: CNT106         6        1
#>     SPCDNM COUNT_TPA NBRPLOTS
#> 
#> $tdomlst
#>  [1] "CNT NA" "CNT019" "CNT065" "CNT066" "CNT093" "CNT096" "CNT101" "CNT106"
#>  [9] "CNT108" "CNT113" "CNT122" "CNT202" "CNT313" "CNT375" "CNT475" "CNT544"
#> [17] "CNT745" "CNT746" "CNT749" "CNT823"
#> 
#> $tdomtotnm
#> [1] "CNTTOT"
#> 
#> $tdomainlst
#> [1] "SPCD"
#> 
#> $pcdomainlst
#> character(0)
#> 
#> $treeqry
#> [1] "WITH\npltids AS\n(SELECT CN AS PLT_CN\n FROM pltx), \n----- get tree data\ntdat AS\n(SELECT 'TREE' src, t.PLT_CN, t.CONDID, t.SUBP, t.TREE, t.SPCD, t.TPA_UNADJ\n FROM treex t\n JOIN pltids ON (t.PLT_CN = pltids.PLT_CN)\n WHERE STATUSCD=1)\n-------------------------------------------\nSELECT pltids.PLT_CN, SPCD,   \n  COALESCE(SUM(TPA_UNADJ),0) AS COUNT_TPA\nFROM pltids pltids\nLEFT JOIN tdat ON (tdat.PLT_CN = pltids.PLT_CN)\nGROUP BY pltids.PLT_CN, SPCD"
#> 
              
# Sum of Number of Live Trees by Species, Including Seedlings
datSumTreeDom(tree = WYtree,
              seed = WYseed, 
              bycond = FALSE, 
              tsumvar = "PLT_CN", 
              tdomtot = TRUE, 
              tdomprefix = "CNT", 
              datSum_opts = list(tround = 0))
#> $tdomdat
#> Key: <PLT_CN>
#>              PLT_CN CNT019 CNT065 CNT066 CNT093 CNT096 CNT101 CNT106 CNT108
#>              <char>  <num>  <num>  <num>  <num>  <num>  <num>  <num>  <num>
#>   1: 40404729010690      0      0     12      0      0      0      0      0
#>   2: 40404730010690      0      0      0      0      0      0      0      6
#>   3: 40404737010690      0      0      0      0      0      0      0      0
#>   4: 40404738010690      6      0      0      0      0      0      0      0
#>   5: 40404742010690      0      0      0      0      0      0      0      0
#>  ---                                                                       
#> 569: 40407821010690      0      0      6      0      0      0      0      0
#> 570: 40407831010690      0      0    309      0      0      0      0      0
#> 571: 40407845010690      0      0      0      0      0      0      0      0
#> 572: 40407861010690      0      0      0      0      0      0      0      0
#> 573: 46792188020004      0      0      0      0      0      0      0      0
#>      CNT113 CNT122 CNT202 CNT313 CNT375 CNT475 CNT544 CNT745 CNT746 CNT749
#>       <num>  <num>  <num>  <num>  <num>  <num>  <num>  <num>  <num>  <num>
#>   1:     30      0      0      0      0      0      0      0      0      0
#>   2:     48    141    138      0      0      0      0      0      0      0
#>   3:     12      0      0      0      0      0      0      0     12      0
#>   4:     72      6      0      0      0      0      0      0      0      0
#>   5:      0     42      0      0      0      0      0      0      0      0
#>  ---                                                                      
#> 569:      0      6      0      0      0      0      0      0      0      0
#> 570:      0     84      0      0      0      0      0      0      0      0
#> 571:      0      6      0      0      0      0      0      0      0      0
#> 572:      0    501      0      0      0      0      0      0      0      0
#> 573:     42      0    391      0      0      0      0      0      0      0
#>      CNT823 CNTTOT
#>       <num>  <num>
#>   1:      0     42
#>   2:      0    333
#>   3:      0     24
#>   4:      0     84
#>   5:      0     42
#>  ---              
#> 569:      0     12
#> 570:      0    393
#> 571:      0      6
#> 572:      0    501
#> 573:      0    433
#> 
#> $tsumuniqueid
#> [1] "PLT_CN"
#> 
#> $tsumvarnm
#> [1] "COUNT_TPA"
#> 
#> $tdomvarnm
#> [1] "SPCDNM"
#> 
#> $tdomvarlut
#>     SPCDNM COUNT_TPA NBRPLOTS
#>     <char>     <num>    <int>
#>  1: CNT066      5562       75
#>  2: CNT113      6270      102
#>  3: CNT108     81140      262
#>  4: CNT122     13670       98
#>  5: CNT202     11871      107
#>  6: CNT746     13608       72
#>  7: CNT019     60632      243
#>  8: CNT093     26341      209
#>  9: CNT065      2493       21
#> 10: CNT745       102        4
#> 11: CNT823      1237       12
#> 12: CNT375        81        2
#> 13: CNT101     15291      106
#> 14: CNT096       348        3
#> 15: CNT749       231        5
#> 16: CNT475        36        3
#> 17: CNT313        60        2
#> 18: CNT544        66        2
#> 19: CNT106         6        1
#> 
#> $tdomlst
#>  [1] "CNT019" "CNT065" "CNT066" "CNT093" "CNT096" "CNT101" "CNT106" "CNT108"
#>  [9] "CNT113" "CNT122" "CNT202" "CNT313" "CNT375" "CNT475" "CNT544" "CNT745"
#> [17] "CNT746" "CNT749" "CNT823"
#> 
#> $tdomtotnm
#> [1] "CNTTOT"
#> 
#> $tdomainlst
#> [1] "SPCD"
#> 
#> $pcdomainlst
#> character(0)
#> 
#> $treeqry
#> [1] "WITH tdat AS\n(SELECT 'TREE' src, t.PLT_CN, t.CONDID, t.SUBP, t.TREE, t.SPCD, t.TPA_UNADJ\n FROM treex t)\n-------------------------------------------\nSELECT tdat.PLT_CN, SPCD,   \n  COALESCE(SUM(TPA_UNADJ),0) AS COUNT_TPA\nFROM tdat\nGROUP BY tdat.PLT_CN, SPCD"
#> 
# }