Green-Book module - Generate population data for GB module.

Generates population data for generating 'green-book' estimates (Scott et al. 2005). Plots that are totally nonsampled are excluded from estimation dataset. Next, an adjustment factor is calculated by strata to adjust for nonsampled (nonresponse) conditions that have proportion less than 1. Attributes adjusted to a per-acre value are summed by plot, divided by the adjustment factor, and averaged by stratum. Strata means are combined using the strata weights and then expanded to using the total land area in the population.

Usage

modGBpop(
  popType = "VOL",
  popTabs = popTables(),
  popTabIDs = popTableIDs(),
  popFilter = popFilters(),
  pltassgn = NULL,
  pltassgnid = "PLT_CN",
  datsource = "sqlite",
  dsn = NULL,
  dbconn = NULL,
  pjoinid = "CN",
  areawt = "CONDPROP_UNADJ",
  areawt2 = NULL,
  adj = "samp",
  defaultVars = TRUE,
  unitvar = NULL,
  unitarea = NULL,
  areavar = "ACRES",
  strata = TRUE,
  stratalut = NULL,
  strvar = "STRATUMCD",
  returndata = TRUE,
  savedata = FALSE,
  saveobj = FALSE,
  objnm = "GBpopdat",
  unit_opts = NULL,
  strata_opts = NULL,
  savedata_opts = NULL,
  database_opts = NULL,
  GBdata = NULL,
  pltdat = NULL,
  stratdat = NULL,
  auxdat = NULL,
  ...
)

Arguments

popType: String. Type of evaluation(s) to include in population data. Note: currently only c('CURR', 'VOL', 'LULC', 'DWM') are available. See details below for descriptions of each.
popTabs: List of population tables the user would like returned. See help(popTables) for a list of options.
popTabIDs: List of unique IDs corresponding to the population tables that the user has requested. See help(popTableIDs) for a list of options.
popFilter: List of population filters. See help(popFilters) for a list of options.
pltassgn: DF/DT, Optional. R object, sf R object, comma-delimited file(.csv), layer or spatial layer in dsn, or shapefile(.shp). Plot-level assignment of estimation unit and/or strata, with one record for each plot.
pltassgnid: String vector. One or more variables in pltassgn defining unique plot and will join to plt table.
datsource: String. Name of data source ('obj', 'sqlite', 'postgres').
dsn: String. Name of database where tree, cond, and plot-level tables reside. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html).
dbconn: Open database connection.
pjoinid: String vector. Join variable(s) in plot to match pltassgnid.
areawt: String. Name of variable in cond for summarizing area weights (e.g., CONDPROP_UNADJ).
areawt2: String. An equation to multiply to the adjusted areawt for estimation. All variables in equation must be in cond. (e.g., '1000 + SICOND * 3 + BALIVE * 4').
adj: String. How to calculate adjustment factors for nonsampled (nonresponse) conditions based on summed proportions for by plot ('samp', 'plot'). 'samp' - adjustments are calculated at strata/estimation unit level; 'plot' - adjustments are calculated at plot-level. Adjustments are only calculated for annual inventory plots (DESIGNCD=1).
defaultVars: Logical. If TRUE, a set of default variables are selected.
unitvar: String. Name of the estimation unit variable in unitarea and cond or pltassgn data frame with estimation unit assignment for each plot (e.g., 'ESTN_UNIT'). Optional if only one estimation unit.
unitarea: Numeric or DF. Total area by estimation unit. If only 1 estimation unit, include number of total acreage for the area of interest or a data frame with area and estimation unit. If more than one estimation unit, provide a data frame of total area by estimation unit, including unitvar and areavar.
areavar: String. Name of area variable in unitarea. Default="ACRES".
strata: Logical. If TRUE, include information for post-stratification.
stratalut: DF/DT. If strata=TRUE, look-up table with pixel counts or area by strata or proportion or area ('strwt') by strata (and estimation unit). If 'strwt' is not included, set getwt=TRUE and getwtvar as the name of variable to calculate weights from (e.g., pixel counts).
strvar: String. If strata=TRUE, name of the strata variable in stratalut and cond or pltassgn data frame with stratum assignment for each plot (Default = 'STRATUMCD').
returndata: Logical. If TRUE, returns data objects.
savedata: Logical. If TRUE, saves data table(s). See savedata_opts for saving options.
saveobj: Logical. If TRUE, saves returned list object. See savedata_opts for saving options.
objnm: String. Name of *.rds object.
unit_opts: List. See help(unit_options()) for a list of options.
strata_opts: List. See help(strata_options()) for a list of options. Only used when strata = TRUE.
savedata_opts: List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE.
database_opts: List. See help(database_options()) for a list of options. Only used when datsource = 'postgres'.
GBdata: R List object. Output data list components from FIESTA::anGBdata().
pltdat: R List object. Output data list components from FIESTA::spGetPlots().
stratdat: R List object. Output data list components from FIESTA::spGetStrata().
auxdat: R List object. Output data list components from FIESTA::spGetAuxiliary().
...: For extendibility.

Value

A list with population data for Green-Book estimates.

condx: Data frame. Condition-level data including plot-level assignment of estimation unit and stratum (if strata=TRUE), condition proportion adjustment factor (cadjfac), and adjusted condition proportions (CONDPROP_ADJ).
cuniqueid: String. Unique identifier of plot in condx and pltcondx.
condid: String. Unique identifier of condition in condx and pltcondx.
treex: Data frame. Tree data within population, used for estimation, including trees per acre adjustment factor (tadjfac), and adjusted trees per acre (TPA_ADJ) (if treef is included).
tuniqueid: String. Unique identifier of plot in treex (if treef is included).
ACI.filter: String. If ACI=FALSE, ACI.filter="COND_STATUS_CD == 1".
unitarea: String. Returned table of area by estimation unit.
unitvar: String. Variable name for estimation unit.
strlut: String. Strata-level table with pixel counts by strata (P1POINTCNT), strata weights (strwt), number of plots by strata (n.strata), total number of plots in estimation unit (n.total), sum of condition proportions (_UNADJ_SUM), area adjustments (*_ADJFAC), total area, and area expansion by strata (EXPNS).
strvar: String. Variable name for strata. If strata=FALSE, strvar="ONESTRAT".
expcondtab: String. If ACI=FALSE, ACI.filter="COND_STATUS_CD == 1".
plotsampcnt: Data frame. Number of plots by PLOT_STATUS_CD.
condsampcnt: Data frame. Number of conditions by COND_STATUS_CD.
states: String. State names in dataset.
invyrs: String. Range of inventory years in dataset.
stratdat: Data frame. Strata information by estimation unit.

	Variable	Description
	unitvar	estimation unit
	strvar	stratum value
	strwtvar	number of pixels by strata and estimation unit
	n.strata	number of plots in strata (after totally nonsampled plots removed)
	n.total	number of plots for estimation unit
	strwt	proportion of area (or plots) by strata and estimation unit (i.e., strata weight)
	CONDPROP_UNADJ_SUM	summed conditionproportion by strata and estimation unit
	CONDPROP_ADJFAC	adjusted condition proportion by strata after nonsampled plots removed
	AREA_USED	total area of estimation unit
	expfac	strata-level expansion factor after nonsampled plots and conditions removed (AREA_USED/n.strata)
	EXPNS	strata-level area expansions (expfac * strwt)

Table(s) are also written to outfolder.

Details

Population types

	popType Description
ALL	Population data, including nonsampled plots.
CURR	Population data for area estimates, excluding nonsampled plots.
VOL	Population data for area/tree estimates, excluding nonsampled plots.
LULC	Population data for land use/land cover transitional estimates, including only plots with previous measurements and excluding nonsampled plots.

If variables are NULL, then it will prompt user to input variables.

Necessary variables:

Data	Variable	Description
tree	tuniqueid	Unique identifier for each plot in tree table.
	CONDID	Unique identifier of each condition on plot. Set CONDID=1, if only 1 condition per plot.
	TPA_UNADJ	Number of trees per acre each sample tree represents (e.g., DESIGNCD=1: TPA_UNADJ=6.018046 for trees on subplot; 74.965282 for trees on microplot).
cond	cuniqueid	Unique identifier for each plot in cond table.
	CONDID	Unique identifier of each condition on plot. Set CONDID=1, if only 1 condition per plot.
	CONDPROP_UNADJ	Unadjusted proportion of condition on each plot. Set CONDPROP_UNADJ=1, if only 1 condition per plot.
	COND_STATUS_CD	Status of each forested condition on plot (i.e. accessible forest, nonforest, water, etc.)
	NF_COND_STATUS_CD	If ACI=TRUE. Status of each nonforest condition on plot (i.e. accessible nonforest, nonsampled nonforest)
	SITECLCD	If landarea=TIMBERLAND. Measure of site productivity.
	RESERVCD	If landarea=TIMBERLAND. Reserved status.
	SUBPROP_UNADJ	Unadjusted proportion of subplot conditions on each plot. Set SUBPROP_UNADJ=1, if only 1 condition per subplot.
	MICRPROP_UNADJ	If microplot tree attributes. Unadjusted proportion of microplot conditions on each plot. Set MICRPROP_UNADJ=1, if only 1 condition per microplot.
	MACRPROP_UNADJ	If macroplot tree attributes. Unadjusted proportion of macroplot conditions on each plot. Set MACRPROP_UNADJ=1, if only 1 condition per macroplot.
pltassgn	pltassgnid	Unique identifier for each plot in pltassgn.
	STATECD	Identifies state each plot is located in.
	INVYR	Identifies inventory year of each plot.
	PLOT_STATUS_CD	Status of each plot (i.e. sampled, nonsampled). If not included, all plots are assumed as sampled.

For available reference tables: sort(unique(FIESTAutils::ref_codes$VARIABLE))

Note

ADJUSTMENT FACTOR:
The adjustment factor is necessary to account for nonsampled conditions. It is calculated for each estimation unit by strata. by summing the unadjusted proportions of the subplot, microplot, and macroplot (i.e. *PROP_UNADJ) and dividing by the number of plots in the strata/estimation unit).

An adjustment factor is determined for each tree based on the size of the plot it was measured on. This is identified using TPA_UNADJ as follows:

	PLOT SIZE	TPA_UNADJ
	SUBPLOT	6.018046
	MICROPLOT	74.965282
	MACROPLOT	0.999188

If ACI=FALSE, only nonsampled forest conditions are accounted for in the adjustment factor.
If ACI=TRUE, the nonsampled nonforest conditions are removed as well and accounted for in adjustment factor. This is if you are interested in estimates for all lands or nonforest lands in the All-Condition-Inventory.

unitcombine:
If TRUE and less than 2 plots in any one estimation unit, all estimation units with 10 or less plots are combined. The current method for combining is to group the estimation unit with less than 10 plots with the estimation unit following in consecutive order (numeric or alphabetical), restrained by survey unit (UNITCD) if included in dataset, and continuing until the number of plots equals 10. If there are no estimation units following in order, it is combined with the estimation unit previous in order.

stratcombine:
If TRUE and less than 2 plots in any one strata class within an estimation unit, all strata classes with 2 or less plots are combined. The current method for combining is to group the strata with less than 2 plots with the strata class following in consecutive order (numeric or alphabetical), restrained by estimation unit (if unitcombine=FALSE), and continuing until the number of plots equals 10. If there are no strata classes following in order, it is combined with the estimation unit previous in order.

References

Scott, Charles T.; Bechtold, William A.; Reams, Gregory A.; Smith, William D.; Westfall, James A.; Hansen, Mark H.; Moisen, Gretchen G. 2005. Sample-based estimators used by the Forest Inventory and Analysis national information management system. Gen. Tech. Rep. SRS-80. Asheville, NC: U.S. Department of Agriculture, Forest Service, Southern Research Station, p.53-77.

Author

Tracey S. Frescino, Paul L. Patterson, Elizabeth A. Freeman

Examples

# \donttest{
GBpopdat <- modGBpop(
popTabs = list(cond = FIESTA::WYcond,  
               tree = FIESTA::WYtree,        
               seed = FIESTA::WYseed),      
popTabIDs = list(cond = "PLT_CN"),            
pltassgn = FIESTA::WYpltassgn,  
pltassgnid = "CN",        
pjoinid = "PLT_CN",         
unitarea = FIESTA::WYunitarea,
unitvar = "ESTN_UNIT",        
strata = TRUE,           
stratalut = WYstratalut,    
strata_opts = strata_options(getwt = TRUE)   
)
#> savedata=FALSE with savedata parameters... no data are saved
#> variables are missing from dataset: STATECD, UNITCD, COUNTYCD, PLOT, PLOT_STATUS_CD, PLOT_NONSAMPLE_REASN_CD, INTENSITY, SUBCYCLE, MACRO_BREAKPOINT_DIA
#> SURVEY table does not exist in database... assuming annual inventory plots
#> INVYR not in input data...  no invyrs returned...
#> SUBCYCLE not in data... assuming all SUBCYCLE <> 99
#> removing nonsampled forest plots...
#> returning data needed for estimation...
#> there are 14 nonsampled conditions

str(GBpopdat, max.level = 1)
#> List of 39
#>  $ module       : chr "GB"
#>  $ popType      : chr "VOL"
#>  $ pltidsadj    :Classes ‘data.table’ and 'data.frame':	3047 obs. of  5 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr "CN"
#>  $ pltcondx     :Classes ‘data.table’ and 'data.frame':	3224 obs. of  29 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr [1:2] "PLT_CN" "CONDID"
#>  $ pltcondflds  : chr [1:28] "PLT_CN" "CONDID" "COND_NONSAMPLE_REASN_CD" "CONDPROP_UNADJ" ...
#>  $ pjoinid      : chr "CN"
#>  $ cuniqueid    : chr "PLT_CN"
#>  $ condid       : chr "CONDID"
#>  $ ACI          : logi FALSE
#>  $ areawt       : chr "CONDPROP_UNADJ"
#>  $ areawt2      : NULL
#>  $ adjcase      : Named chr "ADJ_FACTOR_COND"
#>   ..- attr(*, "names")= chr "COND"
#>  $ dbqueries    :List of 5
#>  $ dbqueriesWITH:List of 4
#>  $ pltassgnx    :Classes ‘data.table’ and 'data.frame':	3047 obs. of  4 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr "CN"
#>  $ pltassgnid   : chr "CN"
#>  $ unitarea     :Classes ‘data.table’ and 'data.frame':	23 obs. of  2 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr "ESTN_UNIT"
#>  $ areavar      : chr "ACRES"
#>  $ areaunits    : chr "acres"
#>  $ unitvar      : chr "ESTN_UNIT"
#>  $ unitvars     : chr "ESTN_UNIT"
#>  $ unitltmin    : num 0
#>  $ strata       : logi TRUE
#>  $ stratalut    :Classes ‘data.table’ and 'data.frame':	35 obs. of  6 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr [1:2] "ESTN_UNIT" "STRATUMCD"
#>  $ strvar       : chr "STRATUMCD"
#>  $ strwtvar     : chr "strwt"
#>  $ plotsampcnt  :'data.frame':	0 obs. of  0 variables
#>  $ condsampcnt  :'data.frame':	5 obs. of  3 variables:
#>  $ states       : chr "Wyoming"
#>  $ invyrs       : NULL
#>  $ adj          : chr "samp"
#>  $ P2POINTCNT   :'data.frame':	35 obs. of  3 variables:
#>  $ plotunitcnt  :'data.frame':	23 obs. of  2 variables:
#>  $ treex        :Classes ‘data.table’ and 'data.frame':	18574 obs. of  19 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr [1:4] "PLT_CN" "CONDID" "SUBP" "TREE"
#>  $ tuniqueid    : chr "PLT_CN"
#>  $ seedx        :Classes ‘data.table’ and 'data.frame':	1607 obs. of  9 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr [1:3] "PLT_CN" "CONDID" "SUBP"
#>  $ adjfactors   :Classes ‘data.table’ and 'data.frame':	35 obs. of  7 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr [1:2] "ESTN_UNIT" "STRATUMCD"
#>  $ adjvarlst    : Named chr [1:4] "ADJ_FACTOR_COND" "ADJ_FACTOR_SUBP" "ADJ_FACTOR_MACR" "ADJ_FACTOR_MICR"
#>   ..- attr(*, "names")= chr [1:4] "COND" "SUBP" "MACR" "MICR"
#>  $ popdatindb   : logi FALSE
# }