Generates tree and or seedling estimates by domain and/or tree domain (and estimation unit). Calculations are based on Scott et al. 2005 ('the green-book') for mapped forest inventory plots. The non-ratio estimator for estimating tree attributes by stratum and domain is used. 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.
modGBtree(
GBpopdat,
estvar,
estvar.filter = NULL,
estseed = "none",
woodland = "Y",
landarea = "FOREST",
pcfilter = NULL,
rowvar = NULL,
colvar = NULL,
sumunits = TRUE,
returntitle = FALSE,
savedata = FALSE,
table_opts = NULL,
title_opts = NULL,
savedata_opts = NULL,
gui = FALSE,
...
)List. Population data objects returned from FIESTA::modGBpop().
String. Name of the tree-level estimate variable (e.g., 'VOLCFNET').
String. A tree-level filter for estvar. Must be R syntax (e.g., 'STATUSCD == 1').
String. Use seedling data only or add to tree data. Seedling estimates are only for counts (estvar='TPA_UNADJ')-('none', 'only', 'add').
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.
String. The condition-level filter for defining land area ('ALL', 'FOREST', 'TIMBERLAND'). If landarea='FOREST', COND_STATUS_CD = 1; if landarea='TIMBERLAND', SITECLCD in(1:6) & RESERVCD = 0.
String. A filter for plot or cond attributes (including pltassgn). Must be R logical syntax.
String. Optional. Name of domain variable to group estvar by for rows in table output. Rowvar must be included in an input data frame (i.e., plt, cond, tree). If no rowvar is included, an estimate is returned for the total estimation unit. Include colvar for grouping by 2 variables.
String. Optional. If rowvar != NULL, name of domain variable to group estvar by for columns in table output. Colvar must be included in an input data frame (i.e., plt, cond, tree).
Logical. If TRUE, estimation units are summed and returned in one table.
Logical. If TRUE, returns title(s) of the estimation table(s).
Logical. If TRUE, saves table(s) to outfolder.
List. See help(table_options()) for a list of options.
List. See help(title_options()) for a list of options.
List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE.
Logical. If gui, user is prompted for parameters.
Parameters for modGBpop() if GBpopdat is NULL.
A list with estimates with percent sampling error for rowvar (and colvar). If sumunits=TRUE or unitvar=NULL and colvar=NULL, one data frame is returned. Otherwise, a list object is returned with the following information. If savedata=TRUE, all data frames are written to outfolder.
Data frame. Tree estimates by rowvar, colvar (and estimation unit). If sumunits=TRUE or one estimation unit and colvar=NULL, estimates and percent sampling error are in one data frame.
Data frame. Percent sampling errors (Confidence level 68 colvar (and estimation unit). Note: for 95 percent sampling error by 1.96.
List with 1 or 2 string vectors. If returntitle=TRUE a list with table title(s). The list contains one title if est and pse are in the same table and two titles if est and pse are in separate tables.
List of data frames. If rawdata=TRUE, a list including the processing data used for estimation including: number of plots and conditions; stratification information; and 1 to 8 tables with calculated values for table cells and totals (See processing data below).
Raw data
Table. Number of plots by plot status (ex. sampled forest on plot, sampled nonforest, nonsampled).
DF. Number of conditions by condition status (forest land, nonforest land, noncensus water, census water, nonsampled).
DF. Area by estimation unit.
DF. Condition-level area expansion factors.
DF. Final data table used for estimation.
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 condition proportion by strata and estimation unit | |
| CONDPROP_ADJFAC | adjusted condition proportion by strata after nonsampled plots removed |
Data frames. Separate data frames containing calculated variables used in estimation process. The number of processing tables depends on the input parameters. The tables include: total by estimation unit (unit.totest); rowvar totals (unit.rowest), and if colvar is not NULL, colvar totals, (unit.colvar); and a combination of rowvar and colvar (unit.grpvar). If sumunits=TRUE, the raw data for the summed estimation units are also included (totest, rowest, colest, grpest, respectively). These tables do not included estimate proportions (nhat and nhat.var).
The data frames include the following information:
| Variable | Description | |
| nhat | estimated proportion of trees | |
| nhat.var | variance estimate of estimated proportion of trees | |
| NBRPLT.gt0 | Number of non-zero plots used in estimates | |
| ACRES | total area for estimation unit | |
| est | estimated area of trees nhat*ACRES | |
| est.var | variance estimate of estimated area of trees nhat.var*areavar^2 | |
| est.se | standard error of estimated area of trees sqrt(est.var) | |
| est.cv | coefficient of variation of estimated area of trees est.se/est | |
| pse | percent sampling error of estimate est.cv*100 | |
| CI99left | left tail of 99 percent confidence interval for estimated area | |
| CI99right | right tail of 99 percent confidence interval for estimated area | |
| CI95left | left tail of 95 percent confidence interval for estimated area | |
| CI95right | right tail of 95 percent confidence interval for estimated area | |
| CI67left | left tail of 67 percent confidence interval for estimated area | |
| CI67right | right tail of 67 percent confidence interval for estimated area |
Table(s) are also written to outfolder.
If variables are NULL, then it will prompt user to input variables.
Necessary variables:
| Data | Variable | Description | |
| tree | tuniqueid | Unique identifier for each plot, to link to pltassgn (ex. PLT_CN). | |
| CONDID | Unique identifier of each condition on plot, to link to cond. Set CONDID=1, if only 1 condition per plot. | ||
| TPA_UNADJ | Number 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). | ||
| cond | cuniqueid | Unique identifier for each plot, to link to pltassgn (ex. PLT_CN). | |
| CONDID | Unique identfier 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 | puniqueid | Unique identifier for each plot, to link to cond (ex. CN). | |
| 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))
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.
sumunits:
An estimation unit is a population, or area of interest, with
known area and number of plots. Individual counties or combined
Super-counties are common estimation units for FIA. An estimation unit may
also be a subpopulation of a larger population (e.g., Counties within a
State). Subpopulations are mutually exclusive and independent within a
population, therefore estimated totals and variances are additive. For
example, State-level estimates are generated by summing estimates from all
subpopulations within the State (Bechtold and Patterson. 2005. Chapter 2).
Each plot must be assigned to only one estimation unit.
If sumunits=TRUE, estimates are generated by estimation unit, summed together, and returned as one estimate. If rawdata=TRUE, estimates by individual estimation unit are also returned.
If sumunits=FALSE, estimates are generated and returned by estimation unit as one data frame. If savedata=TRUE, a separate file is written for each estimation unit.
stratcombine:
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.
rowlut/collut:
There are several objectives for including rowlut/collut
look-up tables: 1) to include descriptive names that match row/column codes
in the input table; 2) to use number codes that match row/column names in
the input table for ordering rows; 3) to add rows and/or columns with 0
values for consistency. No duplicate names are allowed.
Include 2 columns in the table:
1-the merging variable with same name as
the variable in the input merge table;
2-the ordering or descriptive
variable.
If the ordering variable is the rowvar/colvar in the input
table and the descriptive variable is in rowlut/collut, set
row.orderby/col.orderby equal to rowvar/colvar. If the descriptive variable
is the rowvar/colvar in the input table, and the ordering code variable is
in rowlut/collut, set row.orderby/col.orderby equal to the variable name of
the code variable in rowlut/collut.
UNITS:
The following variables are converted from pounds (from FIA
database) to short tons by multiplying the variable by 0.0005. DRYBIO_AG,
DRYBIO_BG, DRYBIO_WDLD_SPP, DRYBIO_SAPLING, DRYBIO_STUMP, DRYBIO_TOP,
DRYBIO_BOLE, DRYBIOT, DRYBIOM, DRYBIOTB, JBIOTOT, CARBON_BG, CARBON_AG
MORTALITY:
For Interior-West FIA, mortality estimates are mainly based on
whether a tree has died within the last 5 years of when the plot was
measured. If a plot was remeasured, mortality includes trees that were alive
the previous visit but were dead in the next visit. If a tree was standing
the previous visit, but was not standing in the next visit, no diameter was
collected (DIA = NA) but the tree is defined as mortality.
Common tree filters:
| FILTER | DESCRIPTION | |
| "STATUSCD == 1" | Live trees | |
| "STATUSCD == 2" | Dead trees | |
| "TPAMORT_UNADJ > 0" | Mortality trees | |
| "STATUSCD == 2 & DIA >= 5.0" | Dead trees >= 5.0 inches diameter | |
| "STATUSCD == 2 & AGENTCD == 30" | Dead trees from fire |
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.
# \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)
)
#> For FIA estimation, adjustment factors are calculated to account for plots with partial nonresponse.
#> ...there are 14 nonsampled forest conditions in the dataset.
#> COND_STATUS_CD != 5
#> filter removed 14 records: COND_STATUS_CD != 5
#> calculating adjustment factors...
tree1.1 <- modGBtree(
GBpopdat = GBpopdat, # pop - population calculations
landarea = "FOREST", # est - forest land filter
sumunits = TRUE, # est - sum estimation units to population
estvar = "VOLCFNET", # est - net cubic-foot volume
estvar.filter = "STATUSCD == 1", # est - live trees only
returntitle = TRUE # out - return title information
)
#> COND_STATUS_CD == 1
#> filter removed 2620 records: COND_STATUS_CD == 1
#> COND_STATUS_CD == 1
#> multiplying VOLCFNET by TPA
#> STATUSCD == 1
#> getting output...
str(tree1.1, max.level = 1)
#> List of 5
#> $ est :'data.frame': 1 obs. of 3 variables:
#> $ titlelst:List of 10
#> $ raw :List of 11
#> $ statecd : int 56
#> $ invyr : int [1:3] 2011 2012 2013
tree1.2 <- modGBtree(
GBpopdat = GBpopdat, # pop - population calculations
landarea = "FOREST", # est - forest land filter
sumunits = TRUE, # est - sum estimation units to population
estvar = "VOLCFNET", # est - net cubic-foot volume
estvar.filter = "STATUSCD == 1", # est - live trees only
rowvar = "FORTYPCD", # est - row domain
returntitle = TRUE # out - return title information
)
#> COND_STATUS_CD == 1
#> filter removed 2620 records: COND_STATUS_CD == 1
#> COND_STATUS_CD == 1
#> multiplying VOLCFNET by TPA
#> STATUSCD == 1
#> getting output...
str(tree1.2, max.level = 1)
#> List of 5
#> $ est :'data.frame': 19 obs. of 3 variables:
#> $ titlelst:List of 11
#> $ raw :List of 13
#> $ statecd : int 56
#> $ invyr : int [1:3] 2011 2012 2013
# }