/
README.Rmd
201 lines (137 loc) · 10.4 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{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 <a href='https://rfia.netlify.app'><img src='man/figures/logo.PNG' align="right" height="139" /></a>
```{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")
)
```
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).
<br>
## 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')
```
<br>
## 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 |
<br>
## 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)
```