Generates population data for generating photo-based estimation. 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.

modPBpop(
  pntdat = NULL,
  pltpct = NULL,
  plotid = "plot_id",
  pntid = NULL,
  pltpctvars = NULL,
  plt = NULL,
  pltassgn = NULL,
  puniqueid = "CN",
  pltassgnid = "CN",
  nonsamp.pfilter = NULL,
  sumunits = FALSE,
  unitvar = NULL,
  unitarea = NULL,
  areavar = "ACRES",
  strata = FALSE,
  strtype = "POST",
  stratalut = NULL,
  strvar = "STRATUMCD",
  pvars2keep = NULL,
  saveobj = FALSE,
  objnm = "PBpopdat",
  savedata = FALSE,
  unit_opts = NULL,
  strata_opts = NULL,
  savedata_opts = NULL,
  PBstratdat = NULL,
  gui = FALSE
)

Arguments

pntdat

DF/DT or comma-delimited file (*.csv). Point-level table with one record per point. If NULL, aggregated point counts must be in pntcnt.

pltpct

DF/DT or comma-delimited file (*.csv). Plot-domain-level table with percent observed by domain per plot.

plotid

String. Unique identifier of plot in pnt. All values must match puniqueid values, if pltassgn is not NULL.

pntid

String. Unique identifier of points in pnt.

pltpctvars

String vector. Variables in pltpct for estimation. If NULL, all variables are used except plotid in pltpct.

plt

DF/DT, comma-separated values (CSV) file(*.csv), or layer in dsn, Can also be a shapefile(*.shp) with one record per plot, a spatial layer in dsn, or a sf R object. Plot-level variables. If nonsampled plots are included, PLOT_STATUS_CD variable must be in table. Optional.

pltassgn

DF/DT, comma-delimited file(*.csv), SpatialDataFrame, or shapefile(*.shp). The plot-level data with one record per plot, including estimation unit and/or strata information. Optional.

puniqueid

String. Unique identifier of plot.

pltassgnid

String. Name of unique identifier of plot in pltassgn with All values must match plotid values if pnt is not NULL.

nonsamp.pfilter

String. An expression for filtering nonsampled plots. Must be R syntax.

sumunits

Logical. If TRUE, estimation units are combined to one table for output. Note: only available if tabtype="AREA". Acres

unitvar

String. Name of the estimation unit variable in cond or pltassgn with estimation unit assignment for each plot (e.g., 'ESTN_UNIT'). If one estimation unit, set unitvar=NULL.

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 areavar. If more than one estimation unit, provide a data frame of total area by estimation unit, including unitvar and areavar.

areavar

String. Name of acre variable in unitarea. Default="ACRES".

strata

Logical. If TRUE, add data information for stratification.

strtype

String. If strata=TRUE, the type of strata ('POST', 'PRE'). Note: the variance equations are slightly different.

stratalut

DF/DT. If strata=TRUE, look-up table with strata proportions ('strwt') by strata (and estimation unit). To calculate 'strwt', set getwt=TRUE and getwtvar= name of variable with information 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').

pvars2keep

String vector. Additional plot variables to keep in dataset.

saveobj

Logical. If TRUE, saves SApopdat object to outfolder.

objnm

String. Name of *.rda object.

savedata

Logical. If TRUE, saves table(s) to outfolder.

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.

PBstratdat

R List object. Output data list components from FIESTA::DBgetStrata().

gui

Logical. If gui, user is prompted for parameters.

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) and adjusted condition proportion.

pltcondx

Data frame. Condition-level data, merged with plot data.

cuniqueid

String. Unique identifier of plot in condx and pltcondx.

condid

String. Unique identifier of condition in condx and pltcondx.

treex

Data frame. If esttype='TREE', tree-level data, including sample adjustment factor.

tuniqueid

String. If esttype='TREE', unique identifier of plot in treex.

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.

VariableDescription
unitvarestimation unit
strvarstratum value
strwtvarnumber of pixels by strata and estimation unit
n.stratanumber of plots in strata (after totally nonsampled plots removed)
n.totalnumber of plots for estimation unit
strwtproportion of area (or plots) by strata and estimation unit (i.e., strata weight)
CONDPROP_UNADJ_SUMsummed condition proportion by strata and estimation unit
CONDPROP_ADJFACadjusted condition proportion by strata after nonsampled plots removed
AREA_USEDtotal area of estimation unit
expfacstrata-level expansion factor after nonsampled plots and conditions removed (AREA_USED/n.strata)
EXPNSstrata-level area expansions (expfac * strwt)

Table(s) are also written to outfolder.

Details

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

Necessary variables:

DataVariableDescription
treetuniqueidUnique identifier for each plot, to link to pltassgn (ex. PLT_CN).
CONDIDUnique identifier of each condition on plot, to link to cond. Set CONDID=1, if only 1 condition per plot.
TPA_UNADJNumber of trees per acre each sample tree represents (ex. DESIGNCD=1: TPA_UNADJ=6.018046 for trees on subplot; 74.965282 for trees on microplot).
condcuniqueidUnique identifier for each plot, to link to pltassgn (ex. PLT_CN).
CONDIDUnique identifier of each condition on plot. Set CONDID=1, if only 1 condition per plot.
CONDPROP_UNADJUnadjusted proportion of condition on each plot. Set CONDPROP_UNADJ=1, if only 1 condition per plot.
COND_STATUS_CDStatus of each forested condition on plot (i.e. accessible forest, nonforest, water, etc.)
NF_COND_STATUS_CDIf ACI=TRUE. Status of each nonforest condition on plot (i.e. accessible nonforest, nonsampled nonforest)
SITECLCDIf landarea=TIMBERLAND. Measure of site productivity.
RESERVCDIf landarea=TIMBERLAND. Reserved status.
SUBPROP_UNADJUnadjusted proportion of subplot conditions on each plot. Set SUBPROP_UNADJ=1, if only 1 condition per subplot.
MICRPROP_UNADJIf microplot tree attributes. Unadjusted proportion of microplot conditions on each plot. Set MICRPROP_UNADJ=1, if only 1 condition per microplot.
MACRPROP_UNADJIf macroplot tree attributes. Unadjusted proportion of macroplot conditions on each plot. Set MACRPROP_UNADJ=1, if only 1 condition per macroplot.
pltassgnpuniqueidUnique identifier for each plot, to link to cond (ex. CN).
STATECDIdentifies state each plot is located in.
INVYRIdentifies inventory year of each plot.
PLOT_STATUS_CDStatus 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 SIZETPA_UNADJ
SUBPLOT6.018046
MICROPLOT74.965282
MACROPLOT0.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

# Load necessary data from FIESTA
## Point data
icepntfn <- system.file("extdata",
                        "PB_data/icepnt_utco1135.csv",
                         package = "FIESTA")
icepnt <- read.csv(icepntfn)

## Plot data
icepltfn <- system.file("extdata",
                        "PB_data/icepltassgn_utco1135.csv",
                         package = "FIESTA")
iceplt <- read.csv(icepltfn)

# Percent land cover at Time 1 (2011) for all land in Davis and Salt Lake
# Counties, UT
PBpopdat <- modPBpop(pnt = icepnt, 
                     pltassgn = iceplt,
                     pltassgnid = "plot_id",
                     pntid = "dot_cnt")
#> no strata

str(PBpopdat, max.level = 1)
#> List of 15
#>  $ PBx        :Classes ‘data.table’ and 'data.frame':	1305 obs. of  12 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr [1:2] "plot_id" "dot_cnt"
#>  $ pltassgnx  :Classes ‘data.table’ and 'data.frame':	133 obs. of  3 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr "plot_id"
#>  $ plotid     : chr "plot_id"
#>  $ pntid      : chr "dot_cnt"
#>  $ pltassgnid : chr "plot_id"
#>  $ sumunits   : logi FALSE
#>  $ unitvar    : chr "ONEUNIT"
#>  $ unitvars   : chr "ONEUNIT"
#>  $ strata     : logi FALSE
#>  $ strtype    : chr "POST"
#>  $ stratalut  :Classes ‘data.table’ and 'data.frame':	1 obs. of  5 variables:
#>   ..- attr(*, ".internal.selfref")=<externalptr> 
#>   ..- attr(*, "sorted")= chr [1:2] "ONEUNIT" "ONESTRAT"
#>  $ strvar     : chr "ONESTRAT"
#>  $ strwtvar   : chr "strwt"
#>  $ plotsampcnt: NULL
#>  $ getprop    : logi TRUE

# We can also create population data for estimates by estimation unit
## Read in data for multiple estimation units
unitareafn <- system.file("extdata", 
                          "PB_data/unitarea_utco1135.csv",
                           package = "FIESTA")
unitarea <- read.csv(unitareafn)

## Run modPBpop
PBpopunit <- modPBpop(pnt = icepnt, 
                      pltassgn = iceplt, 
                      pltassgnid = "plot_id", 
                      pntid = "dot_cnt",
                      unitarea = unitarea, 
                      unitvar = "ESTN_UNIT")
#> no strata