--- title: "Database Tools" output: rmarkdown::html_vignette description: > Explore the various database utility functions available within FIESTA. vignette: > %\VignetteIndexEntry{Database Tools} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- ```{r setup, include = F} library(knitr) knitr::opts_chunk$set(message = F, warning = F, eval = F) ``` ```{r, include=FALSE} # Sets up output folding hooks = knitr::knit_hooks$get() hook_foldable = function(type) { force(type) function(x, options) { res = hooks[[type]](x, options) if (isFALSE(options[[paste0("fold.", type)]])) return(res) paste0( "

", type, "

\n\n", res, "\n\n

" ) } } knitr::knit_hooks$set( output = hook_foldable("output"), plot = hook_foldable("plot") ) ``` ```{r, echo=-1} data.table::setDTthreads(2) ``` ### Overview of FIESTA Database (DB) tools FIESTA's DB tools extract data from FIA's online publicly-available, comma-delimited files (\*.csv or \*.zip). FIA's CSV files are available by state from the FIA DataMart at the following link: https://apps.fs.usda.gov/fia/datamart/datamart.html. Because of FIA's confidentiality agreement to protect the privacy of landowners, as well as protecting the scientific integrity of FIA's sample design, the exact coordinates of the sample plot locations are not included in the public data. If the exact coordinates are necessary for your analysis, contact FIA's Spatial Data Services (https://research.fs.usda.gov/programs/fia/sds). ### Objective of tutorial The objective of this tutorial is to demonstrate the use of FIESTA's DB tools for accessing FIA data. These tools extract data from FIA Datamart using FIA's standard evaluations as well as customized evaluations. An FIA Evaluation is a group of plots within the FIA database that is used for population estimates. An FIA Evaluation represents different inventory spans of data with different stratification and area adjustments for nonreponse. Each Evaluation is determined by the type of estimation (evalType) including: area and tree estimates, growth and mortality estimates, and area change estimates (evalType). These plots are identified by an evalid, which is a unique identifier in the format of a 2-digit State code, a 2-digit year code, and a 2-digit evaluation type code. For example, EVALID '491601' represents the Utah 2016 evaluation for current area estimates. FUNCTION | DESCRIPTION -------------- | --------------------------------------------------------------- [DBgetCSV()](#DBgetCSV) | Downloads comma-delimited file (.csv) or downloads and extracts a compressed csv file (.zip) from FIA's online DataMart. [DBqryCSV()](#DBqryCSV) | Extracts and queries data from FIA's online DataMart, either CSV or ZIP files. [DBgetEvalid()](#DBgetEvalid) | Gets evalid for identifying an estimation group of plots for state or checks evalid. [DBgetXY()](#DBgetXY) | Extracts XY data from FIA database. [DBgetPlots()](#DBgetPlots) | Extracts inventory plot data from FIA database. [DBgetStrata()](#DBgetStrata) | Extracts strata information and total acres by estimation unit from FIA database, including plot-level assignment and a data frame with strata weights by estimation unit. ### Set up First, you'll need to load the `FIESTA` library: ```{r, warning = F, message = F} library(FIESTA) ``` Next, you'll need to set up an "outfolder". This is just a file path to a folder where you'd like `FIESTA` to send your data output. For this vignette, we have saved our outfolder file path as the `outfolder` object in a temporary directory. We also set a few default options preferred for this vignette. ```{r} outfolder <- tempdir() ``` ## DB Examples The following examples show how to extract data from FIA's publicly-available, online DataMart. Data can be returned as R objects or exported to CSV (.csv) files or a SQLite (.sqlite) database. The zip files are extracted on-the-fly from the online website. Web server connections will affect download speeds. We show examples for the following functions: The following examples extract data from FIA's online DataMart (https://apps.fs.usda.gov/fia/datamart/datamart.html). Note that while `datsource = 'datamart'` is utilized for these examples, `datsource` can be set to 'sqlite' with `datsource_dsn` set to the local file path for the FIADB file to achieve the same results. ### `DBgetCSV()` The `DBgetCSV` function extracts data from FIA's publicly-available, online DataMart CSV/ZIP files. The zip files are extracted on-the-fly from the online website. Web server connections will affect download speeds. #### Example 1: Extract PLOT data for Wyoming and Utah