Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/hunter-stanke/rFIA

rFIA
https://github.com/hunter-stanke/rFIA

compute-estimates fia fia-database fia-datamart forest-inventory forest-variables inventories r space-time spatial

Last synced: about 2 months ago
JSON representation

rFIA

Lists

README 

        
---

output: github_document

---



```{r, include=FALSE, echo=FALSE,message=FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  out.width = "100%")

```

# rFIA: Unlocking the FIA Database in R 



```{r, echo=FALSE, results='asis', message=FALSE}

#library(badger)

cat(

	badger::badge_cran_release("rFIA", "green"),

	badger::badge_custom("Cite rFIA", "in EMS", "yellow", "https://www.sciencedirect.com/science/article/abs/pii/S1364815219311089"),

	badger::badge_cran_download("rFIA", "grand-total", "blue"),

	#badge_cran_download("rFIA", "last-month", "blue"),

	badger::badge_travis("hunter-stanke/rFIA")

)

```



![US Biomass](man/figures/usBiomass.jpg)



The goal of `rFIA` is to increase the accessibility and use of the USFS Forest Inventory and Analysis (FIA) Database by providing a user-friendly, open source platform to easily query and analyze FIA Data. Designed to accommodate a wide range of potential user objectives, `rFIA` simplifies the estimation of forest variables from the FIA Database and allows all R users (experts and newcomers alike) to unlock the flexibility and potential inherent to the Enhanced FIA design.



Specifically, `rFIA` improves accessibility to the spatio-temporal estimation capacity of the FIA Database by producing space-time indexed summaries of forest variables within user-defined population boundaries. Direct integration with other popular R packages (e.g., dplyr, sp, and sf) facilitates efficient space-time query and data summary, and supports common data representations and API design. The package implements design-based estimation procedures outlined by Bechtold & Patterson (2005), and has been validated against estimates and sampling errors produced by EVALIDator. Current development is focused on the implementation of spatially-enabled model-assisted estimators to improve population, change, and ratio estimates.



For more information and example usage of `rFIA`, check out our [website](https://rfia.netlify.app/). To report a bug or suggest additions to `rFIA`, please use our [active issues](https://github.com/hunter-stanke/rFIA/issues) page here on GitHub, or contact [Hunter Stanke](https://hunter-stanke.com/) (lead developer and maintainer). 



_**To cite**_ `rFIA`, please refer to our recent publication in [Environmental Modeling and Software](https://doi.org/10.1016/j.envsoft.2020.104664) (doi: https://doi.org/10.1016/j.envsoft.2020.104664).







## Installation



You can install the released version of `rFIA` from [CRAN](https://CRAN.R-project.org) with:



``` r

install.packages("rFIA")

```



Alternatively, you can install the development version from GitHub:

```r

devtools::install_github('hunter-stanke/rFIA')

```







## Functionality



|`rFIA` Function  | Description                                                          |

|---------------- |----------------------------------------------------------------------|

|`area`           | Estimate land area in various classes                                |

|`biomass`        | Estimate volume, biomass, & carbon stocks of standing trees          |

|`clipFIA`        | Spatial & temporal queries for FIA data                              |

|`diversity`      | Estimate diversity indices (e.g. species diversity)                  |

|`dwm`            | Estimate volume, biomass, and carbon stocks of down woody material   |

|`getFIA`         | Download FIA data, load into R, and optionally save to disk          |

|`growMort`       | Estimate recruitment, mortality, and harvest rates                   |

|`invasive`       | Estimate areal coverage of invasive species                          |

|`plotFIA`        | Produce static & animated plots of FIA summaries                     |

|`readFIA`        | Load FIA database into R environment from disk                       |

|`seedling`       | Estimate seedling abundance (TPA)                                    |

|`standStruct`    | Estimate forest structural stage distributions                       |

|`tpa`            | Estimate abundance of standing trees (TPA & BAA)                     |

|`vitalRates`     | Estimate live tree growth rates                                      |

|`writeFIA`       | Write in-memory FIA Database to disk                                 |







## Example Usage



### _Download FIA Data and Load into R_

The first step to using `rFIA` is to download subsets of the FIA Database. The easiest way to accomplish this is using `getFIA`. Using one line of code, you can download state subsets of the FIA Database, load data into your R environment, and optionally save those data to a local directory for future use!



```{r eval = FALSE}

## Download the state subset or Connecticut (requires an internet connection)

# All data acquired from FIA Datamart: https://apps.fs.usda.gov/fia/datamart/datamart.html

ct <- getFIA(states = 'CT', dir = '/path/to/save/data')

```



By default, `getFIA` only loads the portions of the database required to produce summaries with other `rFIA` functions (`common = TRUE`). This conserves memory on your machine and speeds download time. If you would like to download all available tables for a state, simple specify `common = FALSE` in the call to `getFIA`.



**But what if I want to load multiple states worth of FIA data into R?** No problem! Simply specify mutiple state abbreviations in the `states` argument of `getFIA` (e.g. `states = c('MI', 'IN', 'WI', 'IL'`)), and all state subsets will be downloaded and merged into a single `FIA.Database` object. This will allow you to use other `rFIA` functions to produce estimates within polygons which straddle state boundaries!



Note: given the massive size of the full FIA Database, users are cautioned to only download the subsets containing their region of interest.



**If you have previously downloaded FIA data would simply like to load into R from a local directory, use `readFIA`:**

```{r eval = FALSE}

## Load FIA Data from a local directory

db <- readFIA('/path/to/your/directory/')

```



----



### _Compute Estimates of Forest Variables_

Now that you have loaded your FIA data into R, it's time to put it to work. Let's explore the basic functionality of `rFIA` with `tpa`, a function to compute tree abundance estimates (TPA, BAA, & relative abundance) from FIA data, and `fiaRI`, a subset of the FIA Database for Rhode Island including inventories from 2013-2018. 



**Estimate the abundance of live trees in Rhode Island:**

```{r warning= FALSE, message=FALSE, fig.width = .5, fig.height=.5}

library(rFIA)

## Load the Rhode Island subset of the FIADB (included w/ rFIA)

## NOTE: This object can be produced using getFIA and/or readFIA

data("fiaRI")



## Only estimates for the most recent inventory year

fiaRI_MR <- clipFIA(fiaRI, mostRecent = TRUE) ## subset the most recent data

tpaRI_MR <- tpa(fiaRI_MR)

head(tpaRI_MR)



## All Inventory Years Available (i.e., returns a time series)

tpaRI <- tpa(fiaRI)

head(tpaRI)



```



**What if I want to group estimates by species? How about by size class?**

```{r warning= FALSE, message=FALSE, height=4.5}

## Group estimates by species

tpaRI_species <- tpa(fiaRI_MR, bySpecies = TRUE)

head(tpaRI_species, n = 3)



## Group estimates by size class

## NOTE: Default 2-inch size classes, but you can make your own using makeClasses()

tpaRI_sizeClass <- tpa(fiaRI_MR, bySizeClass = TRUE)

head(tpaRI_sizeClass, n = 3)



## Group by species and size class, and plot the distribution 

##  for the most recent inventory year

tpaRI_spsc <- tpa(fiaRI_MR, bySpecies = TRUE, bySizeClass = TRUE)

plotFIA(tpaRI_spsc, BAA, grp = COMMON_NAME, x = sizeClass,

        plot.title = 'Size-class distributions of BAA by species', 

        x.lab = 'Size Class (inches)', text.size = .75,

        n.max = 5) # Only want the top 5 species, try n.max = -5 for bottom 5



```



**What if I want estimates for a specific type of tree (ex. greater than 12-inches DBH and in a canopy dominant or subdominant position) in specific area (ex. growing on mesic sites), and I want to group by estimates by some variable other than species or size class (ex. ownsership group)?** Easy! Each of these specifications are described in the FIA Database, and all `rFIA` functions can leverage these data to easily implement complex queries!



``` {r warning = FALSE, message = FALSE}

## grpBy specifies what to group estimates by (just like species and size class above)

## treeDomain describes the trees of interest, in terms of FIA variables 

## areaDomain, just like above,describes the land area of interest

tpaRI_own <- tpa(fiaRI_MR, 

                     grpBy = OWNGRPCD, 

                     treeDomain = DIA > 12 & CCLCD %in% c(1,2),

                     areaDomain = PHYSCLCD %in% c(20:29))

head(tpaRI_own)

```



**What if I want to produce estimates within my own population boundaries (within user-defined spatial zones/polygons)?** This is where things get really exciting. 

``` {r warning = FALSE, message = FALSE}

## Load the county boundaries for Rhode Island

data('countiesRI') ## Load your own spatial data from shapefiles using readOGR() (rgdal)



## polys specifies the polygons (zones) where you are interested in producing estimates

## returnSpatial = TRUE indicates that the resulting estimates will be joined with the 

##    polygons we specified, thus allowing us to visualize the estimates across space

tpaRI_counties <- tpa(fiaRI_MR, polys = countiesRI, returnSpatial = TRUE)



## NOTE: Any grey polygons below simply means no FIA data was available for that region

plotFIA(tpaRI_counties, BAA) # Plotting method for spatial FIA summaries, also try 'TPA' or 'TPA_PERC'

```



**We produced a really cool time series earlier, how would I marry the spatial and temporal capacity of `rFIA` to produce estimates across user-defined polygons and through time?** Easy! Just hand `tpa` the full FIA.Database object you produced with `readFIA` (not the most recent subset produced with `clipFIA`). For stunning space-time visualizations, hand the output of `tpa` to `plotFIA`. To save the animation as a .gif file, simpy specify `fileName` (name of output file) and `savePath` (directory to save file, combined with `fileName`). 

```{r warning = FALSE, message=FALSE}

## Using the full FIA dataset, all available inventories

tpaRI_st <- tpa(fiaRI, polys = countiesRI, returnSpatial = TRUE)



## Animate the output

library(gganimate)

plotFIA(tpaRI_st, TPA, animate = TRUE, legend.title = 'Abundance (TPA)', legend.height = .8)



```