add usage examples [WIP]

Author: ctoney

README.Rmd

@@ -31,6 +31,8 @@ The Forest Inventory and Analysis Program ([FIA](https://research.fs.usda.gov/pr
 * mapping erosion risk [[11]](#references)
 * assessment of tree canopy cover estimation methods [[12, 13]](#references)
 
+Note that analysis or computation based on tree spatial pattern within a plot require input data with coordinates of individual stems given as aziumuth and distance from the sample center point. FIA no longer provide `AZIMUTH` and `DIST` attributes in the publicly available FIADB `TREE` table. The FIADB User Guide states that these attributes are now available by request from [FIA Spatial Data Services](https://research.fs.usda.gov/programs/fia/sds) [[14]](#references). Tree data without stem locations can be used in **FIAstemmap** with reduced functionality which includes predicting individual tree crown width and computing several stand structure metrics.
+
 ## Installation
 
 You can install the development version of **FIAstemmap** with:
@@ -42,13 +44,66 @@ pak::pak("ctoney/FIAstemmap")
 
 ## Examples
 
-TODO...
+### Predict crown width
+
+The data frame `cw_coef` provides a curated set of linear regression coefficients for predicting crown width from stem diameter of tree species in the conterminous US. The crown width prediction method also addresses potential issues in cases of extrapolation beyond the range of the model fitting data. Details are given in the documentation for `calc_crwidth()`. Input is a data frame of tree records which must have columns `SPCD` (FIA integer species code), `STATUSCD` (FIA integer tree status code, `1` = live) and `DIA` (FIA tree diameter in inches), here using the `plantation` example tree list.
 
 ```{r example}
 library(FIAstemmap)
-## basic example code
+
+# structure of the cw_coef dataset
+str(cw_coef)
+
+# add a column of predicted crown width to the plantation tree list
+# `within()` is used to modify only a copy of the example dataset
+tree_list <- within(plantation, CRWIDTH <- calc_crwidth(plantation))
+str(tree_list)
+```
+
+### Exloratory analysis
+
+Plot-level visualization and other exploratory analyses require input data with stem locations provided in columns `AZIMUTH` (horizontal angle from subplot/microplot center to the stem location, in range `0:359`) and `DIST` (stem distance from subplot/microplot center).
+
+```{r example}
+# display modeled tree crowns projected vertically on boundaries of the FIA
+# four-subplot cluster design
+plot_crowns(tree_list, main = "plantation plot")
+
+# individual subplot
+plot_crowns(tree_list, subplot = 4, main = "plantation subplot 4")
+
+# or microplot
+plot_crowns(tree_list, subplot = 4, microplot = TRUE,
+            main = "plantation microplot 4")
 ```
 
+Helper functions are provided to facilitate analyzing 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 package **spatstat.explore** for additional plotting capabilty, computation of descriptive spatial statistics, and other exploratory data analysis.
+
+```{r example}
+# point pattern object for the plantation tree list
+X <- create_fia_ppp(plantation)
+summary(X)
+
+plot(X, pch = 16, main = "Loblolly pine plantation")
+
+# compute Ripley's K-function applying isotropic edge correction
+K <- spatstat.explore::Kest(X, rmax = 12, correction = "isotropic")
+
+# plot estimated values of K(r) along with theoretical values for a completely
+# random (Poisson) point process, suggestng spatial regularity in this case
+plot(K, main = "Ripley's K for the plantation trees")
+```
+
+### Compute stand structure metrics
+
+
+
+
+### Data processing
+
+
+
+
 ## 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.
@@ -77,3 +132,5 @@ _Ecological Indicators_, Volume 142, 109271, https://doi.org/10.1016/j.ecolind.2
 [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.