Repository files navigation

The R package,FIESTA (Forest Inventory ESTimation and Analysis) is aresearch estimation tool for analysts that work with sample-basedinventory data from the U.S. Department of Agriculture, Forest Service,Forest Inventory and Analysis (FIA) Program.FIESTA can generate FIA’straditional state-wide estimates while also accommodate: uniquepopulation boundaries, different evaluation time periods, customizedstratification schemes, non-standard variance equations, integration ofmulti-scale remotely-sensed data and other auxiliary information, andinteraction with other modeling and estimation tools from CRAN’s libraryof packages.FIESTA contains a collection of functions that can queryFIA databases, summarize and compile plot and spatial data, and generateestimates with associated sampling errors.

Functions are organized by type or objective and are named with acorresponding prefix (Fig. 1).FIESTA core functions (CORE) facilitatedata extraction and compilation of data input information and are usedindependently or within theFIESTA estimation modules.FIESTAestimation modules (MODULE) combine multiple functions fromFIESTA orother packages to generate population estimates using differentestimation strategies. Each module has an associatedmod*pop functionfor compiling the population data and calculations (e.g., adjustmentsfor nonresponse, standardizing auxiliary data) for a custom boundary andcan be used for generating multiple estimates.FIESTA analysisfunctions, found in theFIESTAnalysis package, streamline differentestimation routines by wrapping (i.e., combining) estimation modules andother functions for a specific purpose.

• Database tools (DB*) - functions for querying and extracting datafrom FIA’s national database.
• Data tools (dat*) - functions for summarizing and exploring FIAdata.
• Spatial tools (sp*) - functions for manipulating and summarizingspatial data.

• Green-Book (modGB*) - functions for FIA’s standard Green-Bookestimators.
• Photo-Based (modPB*) - functions for supplementary photo-basedestimators.
• Small Area (modSA*) - functions for integration with available smallarea estimators (SAE).
• Model-Assisted (modMA*) - functions for integration with availableModel-Assisted estimators.

• Analysis functions (an*) - wrapper functions for steam-liningestimation processes. These functions reside in theFIESTAnalysispackage.

You can install the current stable version ofFIESTA from CRAN:

install.packages("FIESTA")

Or, if you’d like to install the developmental version ofFIESTA, youcan do so through a few steps:

If you are using the Windows OS, in order to install source code fromGitHub, you must install Rtools fromCRAN. Install the most current Rtools forWindows 64-bit atthislink.

If you are using macOS, you’ll need to install xcode developer tools toinstall source code from GitHub. To do so, run the following code inyour terminal (not the R console):

xcode-select --install

First note that the developmental version ofFIESTA may rely on adevelopmental version ofFIESTAutils. For both of these installations,you’ll need to make sure to have theremotes package, and then you caninstall both packages from GitHub:

# Install developmental FIESTAutils firstremotes::install_github("USDAForestService/FIESTAutils",dependencies=TRUE)# Then install developmental FIESTAremotes::install_github("USDAForestService/FIESTA",dependencies=TRUE)

To report a bug withFIESTA, please open an issue on theFIESTAGitHub Repository issuespage. Pleaseprovide a description of the bug, and a reproducible example. For helpcreating a reproducible example, see thereprex R package.

This code was written and prepared by U.S. Government employees onofficial time, and therefore it is in the public domain and not subjectto copyright.

License is GPL-3.

The vignette tutorials fromFIESTA can be accessed fromthe packagewebsite. Thevignettes are split up into a few groups: general manuals (ModuleEstimatesandPopulationData),core functions (DatabaseTools,DataTools,andSpatialTools),and estimation modules (Green-bookEstimators,Model-AssistedEstimators,Small AreaEstimators,andPhoto-BasedModule).We suggest you read the general manuals first if you are new toFIESTA.

You can access documentation for external data included inFIESTA intheextdata-README.md file.

These examples make use of vignettes that come withFIESTA, and thesevignettes can be found by callingvignette(package = "FIESTA"). Thedata used in these examples come with theFIESTA package and are fromWyoming, inventory years 2011-2013 (Evaluation 561301). We first loadFIESTA to run these examples:

library(FIESTA)

In order to produce estimates based on the Green-book, we first use theGBpopdat function to produce population data for our areas ofinterest. 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#> module         1     -none-     character#> popType        1     -none-     character#> pltidsadj      5     data.table list#> pltcondx      29     data.table list#> pltcondflds   28     -none-     character#> pjoinid        1     -none-     character#> cuniqueid      1     -none-     character#> condid         1     -none-     character#> ACI            1     -none-     logical#> areawt         1     -none-     character#> areawt2        0     -none-     NULL#> adjcase        1     -none-     character#> dbqueries      4     -none-     list#> dbqueriesWITH  4     -none-     list#> pltassgnx      4     data.table list#> pltassgnid     1     -none-     character#> unitarea       2     data.table list#> areavar        1     -none-     character#> areaunits      1     -none-     character#> unitvar        1     -none-     character#> unitvars       1     -none-     character#> unitltmin      1     -none-     numeric#> strata         1     -none-     logical#> stratalut      6     data.table list#> strvar         1     -none-     character#> strwtvar       1     -none-     character#> plotsampcnt    0     data.frame list#> condsampcnt    3     data.frame list#> states         1     -none-     character#> invyrs         0     -none-     NULL#> adj            1     -none-     character#> P2POINTCNT     3     data.frame list#> plotunitcnt    2     data.frame list#> treex         19     data.table list#> tuniqueid      1     -none-     character#> adjfactors     7     data.table list#> adjvarlst      4     -none-     character#> popdatindb     1     -none-     logical

Note that theGBpopdat list generated bymodGBpop contains manyitems. 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 ofplots and adjustment factors (stratalut), and the adjustment factorsadded to the condition-level, tree-level, and seedling data (condx,treex, andseedx, respectfully).

Now, with theGBpopdat object, we can quickly produce estimates ofbasal area (estvar = "BA") by county in Wyoming for the 2011-2013years.

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             : chr [1:23] "1" "11" "13" "15" ...#>   ..$ Estimate              : num [1:23] 34637492 34861880 70412559 308998 4687031 ...#>   ..$ Percent Sampling Error: num [1:23] 11.7 14.4 11.6 84.6 67.7 ...#>  $ raw    :List of 12#>   ..$ unit_totest  :'data.frame':    23 obs. of  18 variables:#>   ..$ domdat       :'data.frame':    590 obs. of  4 variables:#>   ..$ domdatqry    : chr "WITH\npltids AS\n(SELECT DISTINCT PLT_CN\n FROM condx), \n----- pltcondx\npltcondx AS\n(SELECT c.PLT_CN, c.COND"| __truncated__#>   ..$ 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#>  $ states : chr "Wyoming"

FIESTA makes it easy to do estimation through techniques such asmodel-assited estimation and small area estimation. In this example, weuse a similar process to the Green-Book estimation above to produceestimates 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 themodGBtree() function we can produce estimateswith themodMAtree() function

MAest<- modMAtree(MApopdat=MApopdat,MAmethod="greg",estvar="BA",estvar.filter="STATUSCD == 1")

and we can see the output ofmodMAtree():

str(MAest,max.level=2)#> List of 4#>  $ est    :'data.frame': 23 obs. of  3 variables:#>   ..$ ESTN_UNIT             : chr [1:23] "1" "11" "13" "15" ...#>   ..$ Estimate              : num [1:23] 75809929 117896280 312165085 -14313592 42191880 ...#>   ..$ Percent Sampling Error: num [1:23] 17 12.3 11 0 43.6 ...#>  $ raw    :List of 13#>   ..$ unit_totest  :'data.frame':    23 obs. of  18 variables:#>   ..$ domdat       :'data.frame':    590 obs. of  5 variables:#>   ..$ plotweights  :Classes 'data.table' and 'data.frame':   556 obs. of  5 variables:#>   .. ..- attr(*, ".internal.selfref")=<externalptr>#>   ..$ 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     : chr "square feet"#>  $ statecd: int 56#>  $ states : chr "Wyoming"