readFIA {rFIA} | R Documentation |
Load FIA database into R environment from local directory
Description
Loads FIA Datatables into R from .csv files stored in a local directory (common, easy), or from a database connection (uncommon, difficult). If you have not previously downloaded FIA Data from the FIA Datamart, use getFIA()
to download data for your region of interest and load it into R.
Usage
readFIA(dir = NULL, con = NULL, schema = NULL, common = TRUE, tables = NULL,
states = NULL, inMemory = TRUE, nCores = 1, ...)
Arguments
dir |
directory where .csv files of FIA tables are stored. |
con |
database connection (e.g., produced with |
schema |
SQL Schema that contains FIA tables. Only required when reading tables from a database connection, which most users should avoid. |
common |
logical; if TRUE, only import most commonly used tables, including all required for |
tables |
character vector; names of specific tables to be imported (e.g. 'PLOT', 'TREE', 'COND', 'TREE_GRM_COMPONENT'). |
states |
character; state/ US territory abbreviations (e.g. 'AL', 'MI', etc.) indicating which state subsets to read. Data for each state must be in |
inMemory |
logical; should data be stored in-memory? If FALSE, data will be read in state-by-state when an estimator function is called (e.g., |
nCores |
numeric; number of cores to use for parallel implementation. Check available cores using |
... |
other arguments to pass to |
Details
Download subsets of the FIA Database using getFIA()
(recommended), or manually from the FIA Datamart: https://apps.fs.usda.gov/fia/datamart/datamart.html. Once downloaded, unzip the directory (if downloaded manually), and read into R using readFIA()
.
If common = TRUE
, the following tables will be imported: COND, COND_DWM_CALC, INVASIVE_SUBPLOT_SPP, PLOT, POP_ESTN_UNIT, POP_EVAL, POP_EVAL_GRP, POP_EVAL_TYP, POP_PLOT_STRATUM_ASSGN, POP_STRATUM, SUBPLOT, TREE, TREE_GRM_COMPONENT, TREE_GRM_MIDPT, TREE_GRM_BEGIN, SUBP_COND_CHNG_MTRX, SEEDLING, SURVEY, SUBP_COND, P2VEG_SUBP_STRUCTURE. These tables currently support all functionality with rFIA
, and it is recommended that only these tables be imported to conserve RAM and reduce processing time.
If you wish to merge multiple state downloads of FIA data (e.g. North Carolina and Virginia state downloads), simply place both sets of datatables in the same directory (done for you when using getFIA()
) and import with readFIA
. Upon import, corresponding tables (e.g. NC_PLOT and VA_PLOT) will be merged, and analysis can be completed for the entire region or within spatial units which transcend state boundaries (e.g. Ecoregion subsections).
Easy, efficient parallelization is implemented with the parallel
package. Users must only specify the nCores
argument with a value greater than 1 in order to implement parallel processing on their machines. Parallel implementation is achieved using a snow type cluster on any Windows OS, and with multicore forking on any Unix OS (Linux, Mac). Implementing parallel processing may substantially decrease decrease free memory during processing, particularly on Windows OS. Thus, users should be cautious when running in parallel, and consider implementing serial processing for this task if computational resources are limited (nCores = 1
).
Value
List object containing FIA tables. List elements represent individual FIA tables stored as data.frame
objects. Names of list elements reflect names of files from which they were read into R environment (File names should not be changed after download from FIA Datamart).
If multiple subsets of the FIA database are held in the same directory (e.g. North Carolina and Virginia state downloads), corresponding tables will be merged (e.g. PLOT table returned contains plots in both North Carolina and Virginia).
Note
To download subsets of the FIA Database manually, go online to the FIA Datamart (https://apps.fs.usda.gov/fia/datamart/datamart.html) and choose to download .csv files. Here you can choose to download subsets of the full database for individual states, or select to download individual tables. For use with the rFIA
package, we recommend downloading of subsets of the full database representing individual states of interest. Files must be unzipped in order to be imported.
Alternatively, use getFIA()
to automate the download, reading, and saving process for you (recommended).
Author(s)
Hunter Stanke and Andrew Finley
References
FIA DataMart: https://apps.fs.usda.gov/fia/datamart/datamart.html
FIA Database User Guide: https://research.fs.usda.gov/understory/forest-inventory-and-analysis-database-user-guide-nfi
See Also
Examples
# The following examples shows how you
# can take an existing in-memory FIA.Database,
# save it, and read it back in!
# First download the common tables for Rhode Island,
# load into R, but don't save it anywhere yet
db <- getFIA(states = 'RI')
# Now we write it all out
# Replace tempdir() with the path to your
# directory (where data will be saved)
writeFIA(db, dir = tempdir())