DBgetXY: Database - Extracts plot coordinates.

In FIESTA: Forest Inventory Estimation and Analysis

Database - Extracts plot coordinates.

Description

Extracts public plot coordinates for an FIA evaluation or a custom evaluation. Plots are extracted from FIA's public Datamart (https://apps.fs.usda.gov/fia/datamart/datamart.html) or other defined datasource.

Usage

DBgetXY(
  states = NULL,
  RS = NULL,
  xy_datsource,
  xy_dsn = NULL,
  xy = "PLOT",
  xy_opts = xy_options(),
  datsource = NULL,
  data_dsn = NULL,
  dbTabs = dbTables(),
  pjoinid = "CN",
  eval = "FIA",
  eval_opts = eval_options(),
  invtype = "ANNUAL",
  coordType = "PUBLIC",
  intensity1 = FALSE,
  pvars2keep = NULL,
  issp = FALSE,
  returndata = TRUE,
  savedata = FALSE,
  exportsp = FALSE,
  savedata_opts = NULL,
  PLOT = NULL,
  POP_PLOT_STRATUM_ASSGN = NULL,
  SURVEY = NULL,
  dbconnopen = FALSE,
  evalInfo = NULL
)

Arguments

states	String or numeric vector. Name (e.g., 'Arizona','New Mexico') or code (e.g., 4, 35) of state(s) for evalid. If all states in one or more FIA Research Station is desired, set states=NULL and use RS argument to define RS.
RS	String vector. Name of research station(s) to get public XY coordinates for ('RMRS','SRS','NCRS','NERS','PNWRS'). Do not use if states is populated. See FIESTA::ref_statecd for reference to RS and states.
xy_datsource	Source of XY data ('datamart', 'sqlite', 'obj', 'csv').
xy_dsn	If datsource='sqlite', the file name (data source name) of the sqlite database (*.db) where XY data reside.
xy	sf R object or String. If xy_dsn = 'datamart', name of xy table in FIA DataMart. If xy_dsn = 'sqlite', name of xy layer in database. If datsource = 'csv', full pathname of xy CSV file(s). If datsource = 'obj', name of xy R object. If datsource = 'shp', full pathname of shapefile.
xy_opts	List of xy data options for xy (e.g., xy_opts = list(xvar='LON', yvar='LAT'). See xy_options() for more options and defaults.
datsource	String. Source of FIA data for defining FIA evaluations or appending variables ('datamart', 'sqlite', 'obj', 'csv'). If datsource = NULL, datsource = xy_datsource. If datsource = 'datamart', data are downloaded extracted from FIA DataMart (http://apps.fs.usda.gov/fia/datamart/datamart.html). If datsource='sqlite', specify database name(s) in data_dsn and table name(s) in dbTabs() argument. If datsource = ('obj','csv'), specify *.csv file name in dbTabs argument.
data_dsn	String. Name of database with plot_layer and/or ppsa_layer.
dbTabs	String or R Object. If data_dsn = 'datamart', name of table(s) in FIA DataMart. If data_dsn = 'sqlite', name of layer(s) in database. If datsource = 'csv', name of CSV file(s). If datsource = 'obj', name of R object.
pjoinid	String. Variable in plot table to join to XY data, if plot_layer is not NULL. Not necessary to be unique. If using most current XY coordinates, use identifier for a plot (e.g., PLOT_ID).
eval	String. Type of evaluation time frame for data extraction ('FIA', 'custom'). See eval_opts for more further options.
eval_opts	List of evaluation options for 'FIA' or 'custom' evaluations to determine the set of data returned. See help(eval_options) for a list of options.
invtype	String. Type of FIA inventory to extract ('PERIODIC', 'ANNUAL'). Only one inventory type (PERIODIC/ANNUAL) at a time.
coordType	String. c('PUBLIC', 'ACTUAL'). Defines type of coordinates and is used for the output name.
intensity1	Logical. If TRUE, includes only XY coordinates where INTENSITY = 1 (FIA base grid).
pvars2keep	String vector. One or more variables in plot_layer to append to output.
issp	Logical. If TRUE, returns spatial XY data as a list object with query.
returndata	Logical. If TRUE, returns XY data as a list object with query.
savedata	Logical. If TRUE, saves XY data. Specify outfolder and format using savedata_opts.
exportsp	Logical. If TRUE, exports data as spatial.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE or exportsp = TRUE.
PLOT	Data frame. The name of the PLOT data frame object if it is already downloaded and stored in environment.
POP_PLOT_STRATUM_ASSGN	Data frame. The name of the POP_PLOT_STRATUM_ASSGN data frame object if it is already downloaded and stored in environment.
SURVEY	Data frame. The name of the SURVEY data frame object if it has been already downloaded and stored in environment.
dbconnopen	Logical. If TRUE, the dbconn connection is not closed.
evalInfo	List. List object output from DBgetEvalid or DBgetXY FIESTA functions.

Value

if returndata=TRUE, a list of the following objects:

xy	Data frame. XY data from database. The output name is based on coordType parameter (e.g., xy_PUBLIC). the data frame include xy.uniqueid, xvar, yvar and appended plot variables in pvars2keep if plot_layer is not NULL. The default plot variables included are 'STATECD','UNITCD','COUNTYCD', 'PLOT','PLOT_ID' (ID+STATECD+UNTCD+COUNTYCD+PLOT), 'COUNTYFIPS'. If issp=TRUE, returns an sf object.
xyqry	String. Query to extract coordinates.
xvar	String. Name of X variable in xy*.
yvar	String. Name of Y variable in xy*.

If savedata=TRUE, outputs the xy* based on savedata_opts. If exportsp=TRUE, the output xy saved as spatial layer based on savedata_opts.

Note

If no parameters are included, the user is prompted for input. If partial parameters, the default parameter values are used for those not specified.

Author(s)

Tracey S. Frescino

Examples

## Not run: 
# Most current evaluation and shapefile with public coordinates
COxylst <- DBgetXY(states = "Colorado",
                   eval = "FIA",
                   eval_opts=eval_options(Endyr = 2019))
names(COxylst)

head(COxylst$xy_PUBLIC)
COxylst$xyqry

## End(Not run)

FIESTA documentation built on Nov. 22, 2023, 1:07 a.m.