R: Data - Aggregates numeric tree data by tree domain (i.e....

datSumTreeDom {FIESTA}

R Documentation

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)

[Package FIESTA version 3.6.4 Index]