Authors: Frescino, Tracey S.; Moisen, Gretchen G.; Patterson, Paul L.; Toney, Chris; White, Grayson W.
The R package, FIESTA (Forest Inventory ESTimation and Analysis) is a
research estimation tool for analysts that work with sample-based
inventory data from the U.S. Department of Agriculture, Forest Service,
Forest Inventory and Analysis (FIA) Program. FIESTA can generate FIA’s
traditional state-wide estimates while also accommodate: unique
population boundaries, different evaluation time periods, customized
stratification schemes, non-standard variance equations, integration of
multi-scale remotely-sensed data and other auxiliary information, and
interaction with other modeling and estimation tools from CRAN’s library
of packages. FIESTA contains a collection of functions that can query
FIA databases, summarize and compile plot and spatial data, and generate
estimates with associated sampling errors.
Functions are organized by type or objective and are named with a
corresponding prefix (Fig. 1). FIESTA core functions (CORE) facilitate
data extraction and compilation of data input information and are used
independently or within the FIESTA estimation modules. FIESTA
estimation modules (MODULE) combine multiple functions from FIESTA or
other packages to generate population estimates using different
estimation strategies. Each module has an associated mod*pop function
for compiling the population data and calculations (e.g., adjustments
for nonresponse, standardizing auxiliary data) for a custom boundary and
can be used for generating multiple estimates. FIESTA analysis
functions, found in the FIESTAnalysis package, streamline different
estimation routines by wrapping (i.e., combining) estimation modules and
other functions for a specific purpose.
- Database tools (
DB*) - functions for querying and extracting data from FIA’s national database. - Data tools (
dat*) - functions for summarizing and exploring FIA data. - Spatial tools (
sp*) - functions for manipulating and summarizing spatial data.
- Green-Book (
modGB*) - functions for FIA’s standard Green-Book estimators. - Photo-Based (
modPB*) - functions for supplementary photo-based estimators. - Small Area (
modSA*) - functions for integration with available small area estimators (SAE). - Model-Assisted (
modMA*) - functions for integration with available Model-Assisted estimators.
- Analysis functions (
an*) - wrapper functions for steam-lining estimation processes. These functions reside in theFIESTAnalysispackage.
You can install the current stable version of FIESTA from CRAN:
install.packages("FIESTA")Or, if you’d like to install the developmental version of FIESTA, you
can do so through a few steps:
If you are using the Windows OS, in order to install source code from GitHub, you must install Rtools from CRAN. Install the most current Rtools for Windows 64-bit at this link.
If you are using macOS, you’ll need to install xcode developer tools to install source code from GitHub. To do so, run the following code in your terminal (not the R console):
xcode-select --install
First note that the developmental version of FIESTA may rely on a
developmental version of FIESTAutils. For both of these installations,
you’ll need to make sure to have the remotes package, and then you can
install both packages from GitHub:
# Install developmental FIESTAutils first
remotes::install_github("USDAForestService/FIESTAutils",
dependencies = TRUE)
# Then install developmental FIESTA
remotes::install_github("USDAForestService/FIESTA",
dependencies = TRUE)To report a bug with FIESTA, please open an issue on the FIESTA
GitHub Repository issues
page. Please
provide a description of the bug, and a reproducible example. For help
creating a reproducible example, see the
reprex R package.
This code was written and prepared by U.S. Government employees on official time, and therefore it is in the public domain and not subject to copyright.
License is GPL-3.
The vignette tutorials from FIESTA can be accessed from the package
website. The
vignettes are split up into a few groups: general manuals (Module
Estimates
and Population
Data),
core functions (Database
Tools,
Data
Tools,
and Spatial
Tools),
and estimation modules (Green-book
Estimators,
Model-Assisted
Estimators,
Small Area
Estimators,
and Photo-Based
Module).
We suggest you read the general manuals first if you are new to
FIESTA.
You can access documentation for external data included in FIESTA in
the extdata-README.md file.
These examples make use of vignettes that come with FIESTA, and these
vignettes can be found by calling vignette(package = "FIESTA"). The
data used in these examples come with the FIESTA package and are from
Wyoming, inventory years 2011-2013 (Evaluation 561301). We first load
FIESTA to run these examples:
library(FIESTA)In order to produce estimates based on the Green-book, we first use the
GBpopdat function to produce population data for our areas of
interest. We can look at a summary of the population data below.
GBpopdat <- modGBpop(popTabs = list(cond = FIESTA::WYcond,
tree = FIESTA::WYtree),
popTabIDs = list(cond = "PLT_CN"),
pltassgn = FIESTA::WYpltassgn,
pltassgnid = "CN",
pjoinid = "PLT_CN",
unitarea = FIESTA::WYunitarea,
unitvar = "ESTN_UNIT",
strata = TRUE,
stratalut = FIESTA::WYstratalut,
strata_opts = strata_options(getwt = TRUE))
summary(GBpopdat)
#> Length Class Mode
#> popType 1 -none- character
#> condx 12 data.table list
#> pltcondx 43 data.table list
#> cuniqueid 1 -none- character
#> condid 1 -none- character
#> ACI.filter 1 -none- character
#> unitarea 2 data.table list
#> areavar 1 -none- character
#> areaunits 1 -none- character
#> unitvar 1 -none- character
#> unitvars 1 -none- character
#> strata 1 -none- logical
#> stratalut 18 data.table list
#> strvar 1 -none- character
#> strwtvar 1 -none- character
#> expcondtab 12 data.table list
#> plotsampcnt 3 data.frame list
#> condsampcnt 3 data.frame list
#> states 1 -none- character
#> invyrs 1 -none- list
#> estvar.area 1 -none- character
#> adj 1 -none- character
#> areawt 1 -none- character
#> treex 21 data.table list
#> tuniqueid 1 -none- character
#> adjtree 1 -none- logicalNote that the GBpopdat list generated by modGBpop contains many
items. Some examples include the number of plots by plot status
(plotsampcnt), the number of conditions by condition status
(condsampcnt), the strata-level population data, including number of
plots and adjustment factors (stratalut), and the adjustment factors
added to the condition-level, tree-level, and seedling data (condx,
treex, and seedx, respectfully).
Now, with the GBpopdat object, we can quickly produce estimates of
basal area (estvar = "BA") by county in Wyoming for the 2011-2013
years.
GBest <- modGBtree(GBpopdat = GBpopdat,
estvar = "BA",
estvar.filter = "STATUSCD == 1",
sumunits = FALSE)We again output a list, now with estimates/standard errors, raw data, state code, and inventory year:
str(GBest, max.level = 2)
#> List of 4
#> $ est :'data.frame': 23 obs. of 3 variables:
#> ..$ ESTN_UNIT : int [1:23] 1 3 5 7 9 11 13 15 17 19 ...
#> ..$ Estimate : num [1:23] 35117889 24184274 8223787 73174024 16031144 ...
#> ..$ Percent Sampling Error: num [1:23] 11.71 26.91 32.24 8.56 31.4 ...
#> $ raw :List of 11
#> ..$ unit_totest :'data.frame': 23 obs. of 17 variables:
#> ..$ domdat :'data.frame': 590 obs. of 14 variables:
#> ..$ estvar : chr "BA"
#> ..$ estvar.filter: chr "STATUSCD == 1"
#> ..$ module : chr "GB"
#> ..$ esttype : chr "TREE"
#> ..$ GBmethod : chr "PS"
#> ..$ rowvar : chr "TOTAL"
#> ..$ colvar : chr "NONE"
#> ..$ areaunits : chr "acres"
#> ..$ estunits : chr "square feet"
#> $ statecd: int 56
#> $ invyr : int [1:3] 2011 2012 2013FIESTA makes it easy to do estimation through techniques such as
model-assited estimation and small area estimation. In this example, we
use a similar process to the Green-Book estimation above to produce
estimates for the same region, but through a generalized regression
(GREG) model-assisted estimator. First, we get our population data:
MApopdat <- modMApop(popTabs = list(tree = FIESTA::WYtree,
cond = FIESTA::WYcond),
pltassgn = FIESTA::WYpltassgn,
pltassgnid = "CN",
unitarea = FIESTA::WYunitarea,
unitvar = "ESTN_UNIT",
unitzonal = FIESTA::WYunitzonal,
prednames = c("dem", "tcc", "tpi", "tnt"),
predfac = "tnt")Now, analogous to the modGBtree() function we can produce estimates
with the modMAtree() function
MAest <- modMAtree(MApopdat = MApopdat,
MAmethod = "greg",
estvar = "BA",
estvar.filter = "STATUSCD == 1")and we can see the output of modMAtree():
str(MAest, max.level = 2)
#> List of 4
#> $ est :Classes 'data.table' and 'data.frame': 23 obs. of 3 variables:
#> ..$ ESTN_UNIT : int [1:23] 1 3 5 7 9 11 13 15 17 19 ...
#> ..$ Estimate : num [1:23] 34769303 28493559 8260491 69278394 23200460 ...
#> ..$ Percent Sampling Error: num [1:23] 8.7 19.8 25.69 9.23 20.17 ...
#> ..- attr(*, ".internal.selfref")=<externalptr>
#> ..- attr(*, "sorted")= chr "ESTN_UNIT"
#> $ raw :List of 13
#> ..$ unit_totest :'data.frame': 23 obs. of 18 variables:
#> ..$ domdat :'data.frame': 3210 obs. of 14 variables:
#> ..$ plotweights :List of 1
#> ..$ estvar : chr "BA"
#> ..$ estvar.filter: chr "STATUSCD == 1"
#> ..$ module : chr "MA"
#> ..$ esttype : chr "TREE"
#> ..$ MAmethod : chr "greg"
#> ..$ predselectlst:List of 1
#> ..$ rowvar : chr "TOTAL"
#> ..$ colvar : chr "NONE"
#> ..$ areaunits : chr "acres"
#> ..$ estunits : int [1:23] 1 3 5 7 9 11 13 15 17 19 ...
#> $ statecd: int 56
#> $ invyr : int [1:3] 2011 2012 2013