Repository navigation
Expand file tree
/
Copy pathREADME.Rmd
More file actions
210 lines (140 loc) · 13.8 KB
/
Copy pathREADME.Rmd
File metadata and controls
210 lines (140 loc) · 13.8 KB
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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
fig.width = 7, fig.height = 7,
out.width = "70%"
)
```
# FIAstemmap <a href="https://firelab.github.io/FIAstemmap/"><img src="man/figures/logo.png" align="right" height="138" alt="FIAstemmap website" /></a>
<!-- badges: start -->
[](https://github.com/firelab/FIAstemmap/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=FIAstemmap)
[](https://firelab.r-universe.dev/FIAstemmap)
<!-- badges: end -->
The Forest Inventory and Analysis Program ([FIA](https://research.fs.usda.gov/programs/nfi)) of USDA Forest Service provide tree-level measurements from a systematic grid of field plots across all forest ownerships and land uses in the US.
**FIAstemmap** is an R package for mapping tree stem locations on FIA plots, modeling individual crown dimensions, and generating plot-level estimates of fractional tree canopy cover. Several stand height metrics can also be calculated. Spatial analysis of tree point pattern is facilitated for the standard FIA four-point cluster plot design. Efficient data processing is intended to support national applications. The package provides an updated implementation of the software originally described by Toney et al. 2009 [[1]](#references). The original implementation for predicting canopy cover from individual tree measurements has supported several applications of FIA data, including:
* LANDFIRE vegetation classification and tree canopy cover mapping [[2, 3, 4, 5]](#references)
* National Land Cover Database (NLCD) Tree Canopy Cover science and development [[6, 7]](#references)
* wildlife habitat analysis [[8, 9, 10]](#references)
* mapping erosion risk [[11]](#references)
* assessment of tree canopy cover estimation methods [[12, 13]](#references)
Computations based on tree spatial pattern within a plot require input data with coordinates of the individual stems given as azimuth and distance from the sample center point. Note that FIA no longer provide the `AZIMUTH` and `DIST` attributes in the publicly available `TREE` table. The FIADB User Guide [[14]](#references) states that these attributes are now available by request from [FIA Spatial Data Services](https://research.fs.usda.gov/programs/fia/sds).
Tree data lacking stem locations can still be used with **FIAstemmap** for certain functionality, which includes predicting individual tree crown width and computing several stand structure metrics. The latter includes the option to estimate plot-level tree canopy cover using the aspatial "FVS" method [[15]](#references) which assumes a random arrangement of the crowns.
## Installation
You can install the released version from CRAN:
``` r
install.packages("FIAstemmap")
```
Or install the development version from GitHub:
``` r
# install.packages("remotes")
remotes::install_github("firelab/FIAstemmap")
```
## Examples
### Predict tree crown width
The data frame `cw_coef` contains a curated set of linear regression coefficients for predicting crown width from stem diameter of tree species in the conterminous US (see `?cw_coef`). The method for crown width prediction attempts to avoid extrapolation beyond the range of the model fitting data by providing reasonable fall backs for the obvious cases. Details are given in the documentation for `calc_crwidth()`.
The input is a data frame of tree records which must have columns `SPCD` (FIA species code), `STATUSCD` (FIA tree status code, `1` = live) and `DIA` (FIA tree diameter). FIA distribute data in [United States customary units](https://en.wikipedia.org/wiki/United_States_customary_units) with tree diameter given in inches, height in feet, and area in acres. Convenience functions are provided for converting to and from SI units[^1^](#footnotes) (`in_to_cm()`, `cm_to_in()`, `ft_to_m()`, `m_to_ft()`, `ac_to_ha()`, `ha_to_ac()`).
The `plantation` dataset used here is an example tree list included in the package.
```{r predict-crwidth}
library(FIAstemmap)
# Regression coefficients for estimating crown width from diameter are included.
# See `?cw_coef`.
head(cw_coef)
# Add a column of predicted crown widths to the `plantation` tree list.
# The base R function `within()` modifies a copy of the example dataset.
tree_list <- within(plantation, CRWIDTH <- calc_crwidth(plantation))
str(tree_list)
```
### Exploratory analysis
Plot-level visualization and other exploratory analyses require input data with individual stem locations given in columns named `AZIMUTH` (horizontal angle from subplot/microplot center, `0:359`) and `DIST` (distance from subplot/microplot center).
```{r plot-crowns}
# Display modeled tree crowns projected vertically on the FIA plot boundary.
plot_crowns(tree_list, main = "Loblolly pine plantation")
# Individual subplot
plot_crowns(tree_list, subplot = 4,
main = "Loblolly pine plantation subplot 4")
# Or microplot
plot_crowns(tree_list, subplot = 4, microplot = TRUE,
main = "Loblolly pine plantation microplot 4")
```
Helper functions facilitate the analysis of FIA tree lists as spatial point patterns using the **spatstat** library. `create_fia_ppp()` returns an object of class `"ppp"` representing the point pattern of an FIA tree list in the 2-D plane. This object can be used with functions of [**spatstat.explore**](https://cran.r-project.org/package=spatstat.explore) which provide additional plotting capabilities, descriptive spatial statistics, and other exploratory data analysis.
```{r spatstat-explore}
## Create a spatstat point pattern object for the pine plantation tree list.
X <- create_fia_ppp(plantation)
summary(X)
plot(X, pch = 16, background = "#fdf6e3",
main = "Pine plantation point pattern")
# Compute Ripley's K-function applying isotropic edge correction.
K <- spatstat.explore::Kest(X, rmax = 12, correction = "isotropic")
# Plot estimated K(r) along with theoretical values for a random point process,
# suggesting spatial regularity in this case.
plot(K, main = "Ripley's K for the plantation FIA plot")
```
The `western_redcedar` dataset is another example tree list included in the package. The following code uses meter for the distance unit.
```{r spatstat-explore-cont}
## Spatial point pattern for the western redcedar tree list.
# Give stem distances in meters.
trees <- within(western_redcedar, DIST <- ft_to_m(DIST))
X <- create_fia_ppp(trees, linear_unit = "m")
summary(X)
plot(X, pch = 16, background = "#fdf6e3",
main = "Western redcedar point pattern")
K <- spatstat.explore::Kest(X, rmax = ft_to_m(12), correction = "isotropic")
plot(K, main = "Ripley's K for the western redcedar FIA plot")
```
### Compute stand structure metrics
```{r stand-structure}
## Compute fractional tree canopy cover of a specific sampled area by overlaying
## modeled crowns.
# Subplot 1 of the plantation plot (subplot radius 24 ft).
# Omit saplings which are only sampled in the microplot.
# Visualized with: `plot_crowns(tree_list, subplot = 1)`
tree_list[tree_list$SUBP == 1 & tree_list$DIA >= 5, ] |>
calc_crown_overlay(sample_radius = 24)
## Calculate stand height metrics, which are also included by default in the
## output of `calc_tcc_metrics()` (see below).
# Compute stand height metrics only.
# calc_ht_metrics(plantation)
## Predict plot-level canopy cover from individual tree measurements.
# By default, TCC is predicted using the "stem-map" model, full output returned.
calc_tcc_metrics(plantation)
# Return only the predicted TCC value (`$model_tcc`).
calc_tcc_metrics(plantation, full_output = FALSE)
# Alternatively, use the "FVS method" which assumes a random arrangement of
# tree crowns. This method does not require individual stem coordinates.
calc_tcc_metrics(plantation, stem_map = FALSE, full_output = FALSE)
```
### Data processing
```{r data-proc}
# Load tree data from a file or database connection.
# Lolo NF, single-condition forested plots, INVYR = 2022, from public FIADB
f <- system.file("extdata/mt_lnf_2022_1cond_tree.csv", package="FIAstemmap")
tree_table <- load_tree_data(f)
head(tree_table)
process_tree_data(tree_table, stem_map = FALSE, full_output = TRUE)
```
## References
[1] Toney, Chris; Shaw, John D.; Nelson, Mark D. 2009. A stem-map model for predicting tree canopy cover of Forest Inventory and Analysis (FIA) plots. In: McWilliams, Will; Moisen, Gretchen; Czaplewski, Ray, comps. _Forest Inventory and Analysis (FIA) Symposium 2008_; October 21-23, 2008; Park City, UT. Proc. RMRS-P-56CD. Fort Collins, CO: U.S. Department of Agriculture, Forest Service, Rocky Mountain Research Station. 19 p. Available: https://research.fs.usda.gov/treesearch/33381.
[2] LANDFIRE: LANDFIRE Existing Vegetation Cover layer. (LF2024 version released 2025 - last update). U.S. Department of Interior, Geological Survey, and U.S. Department of Agriculture. [Online]. Available: https://landfire.gov/vegetation/evc [accessed 2026, Feb 24].
[3] Moore, Annabelle; La Puma, Inga; Dillon, Greg; Smail, Tobin; Schleeweis, Karen; Toney, Chris; Menakis, Jim; Bastian, Henry; Picotte, Josh; Dockter, Daryn; Tolk, Brian. 2024. Twenty years of science and management with LANDFIRE. Connected Science, October 2024. Fort Collins, CO: U.S. Department of Agriculture, Forest Service, Rocky Mountain Research Station. 2 p. Available: https://research.fs.usda.gov/treesearch/68397.
[4] Vogelmann, Jim & Kost, Jay & Tolk, Brian & Howard, Stephen & Short, Karen & Chen, Xuexia & Huang, Chengquan & Pabst, Kari & Rollins, Matthew. (2011). Monitoring Landscape Change for LANDFIRE Using Multi-Temporal Satellite Imagery and Ancillary Data. _Selected Topics in Applied Earth Observations and Remote Sensing, IEEE Journal of_. 4. 252-264. 10. https://doi.org/10.1109/JSTARS.2010.2044478.
[5] Nelson, K.J., Connot, J., Peterson, B. et al. 2013. The LANDFIRE Refresh Strategy: Updating the National Dataset. _Fire Ecology_, 9, 80-101, https://doi.org/10.4996/fireecology.0902080.
[6] Toney, Chris; Liknes, Greg; Lister, Andy; Meneguzzo, Dacia. 2012. Assessing alternative measures of tree canopy cover: Photo-interpreted NAIP and ground-based estimates. In: McWilliams, Will; Roesch, Francis A. eds. 2012. _Monitoring Across Borders: 2010 Joint Meeting of the Forest Inventory and Analysis (FIA) Symposium and the Southern Mensurationists_. e-Gen. Tech. Rep. SRS-157. Asheville, NC: U.S. Department of Agriculture, Forest Service, Southern Research Station. 209-215. Available: https://research.fs.usda.gov/treesearch/41009.
[7] Derwin, J.M., Thomas, V.A., Wynne, R.H., Coulston, J.W., Liknes, G.C., Bender, S., Blinn, C.E., Brooks, E.B., Ruefenacht, B., Benton, R. and Finco, M.V., 2020. Estimating tree canopy cover using harmonic regression coefficients derived from multitemporal Landsat data. _International Journal of Applied Earth Observation and Geoinformation_, 86, 101985, https://doi.org/10.1016/j.jag.2019.101985.
[8] Tavernia, B., Nelson, M., Goerndt, M., Walters, B., & Toney, C. (2013). Changes in forest habitat classes under alternative climate and land-use change scenarios in the northeast and midwest, USA. _Mathematical and Computational Forestry & Natural-Resource Sciences_ (MCFNS), 5:2, 135-150. Retrieved from https://www.mcfns.com/index.php/Journal/article/view/MCFNS_165.
[9] Rowland, M.M.; Vojta, C.D.; tech. eds. 2013. A technical guide for monitoring wildlife habitat. Gen. Tech. Rep. WO-89. Washington, DC: U.S. Department of Agriculture, Forest Service: 400 p. Available: https://doi.org/10.2737/WO-GTR-89.
[10] Michael C. McGrann, Bradley Wagner, Matthew Klauer, Kasia Kaphan, Erik Meyer, Brett J. Furnas. 2022. Using an acoustic complexity index to help monitor climate change effects on avian diversity.
_Ecological Indicators_, Volume 142, 109271, https://doi.org/10.1016/j.ecolind.2022.109271.
[11] McGwire KC, Weltz MA, Nouwakpo S, Spaeth K, Founds M, Cadaret E. 2020. Mapping erosion risk for saline rangelands of the Mancos Shale using the rangeland hydrology erosion model. _Land Degradation & Development_. 31: 2552-2564, https://doi.org/10.1002/ldr.3620.
[12] Riemann, R., Liknes, G., O'Neil-Dunne, J., Toney, C., Lister, T. (2016). Comparative assessment of methods for estimating tree canopy cover across a rural-to-urban gradient in the mid-Atlantic region of the USA. _Environmental Monitoring and Assessment_, 188, 297, https://doi.org/10.1007/s10661-016-5281-8.
[13] Andrew N. Gray, Anne C.S. McIntosh, Steven L. Garman, Michael A. Shettles. 2021. Predicting canopy cover of diverse forest types from individual tree measurements. _Forest Ecology and Management_, Volume 501, 119682, ISSN 0378-1127, https://doi.org/10.1016/j.foreco.2021.119682.
[14] Burrill, Elizabeth A.; DiTommaso, Andrea M.; Turner, Jeffery A.; Pugh, Scott A.; Christensen, Glenn; Kralicek, Karin M.; Perry, Carol J.; Lepine, Lucie C.; Walker, David M.; Conkling, Barbara L. 2024. The Forest Inventory and Analysis Database, FIADB user guides, volume: database description (version 9.4), nationwide forest inventory (NFI). U.S. Department of Agriculture, Forest Service. 1016 p. [Online]. Available at: https://research.fs.usda.gov/understory/forest-inventory-and-analysis-database-user-guide-nfi.
[15] Crookston, N.L. and A.R. Stage. (1999). Percent canopy cover and stand structure statistics from the Forest Vegetation Simulator. Gen. Tech. Rep. RMRS-GTR-24. Ogden, UT: U. S. Department of Agriculture, Forest Service, Rocky Mountain Research Station. 11 p. Available: https://research.fs.usda.gov/treesearch/6261.
## Footnotes
^1^ The hectare (ha) is technically a non-SI unit of area that is [accepted for use with SI](https://en.wikipedia.org/wiki/International_System_of_Units#Non-SI_units_accepted_for_use_with_SI).