spGetXY: Spatial wrapper - Extracts XY coordinates within a given...

In FIESTA: Forest Inventory Estimation and Analysis

Spatial wrapper - Extracts XY coordinates within a given boundary.

Description

Wrapper to get FIA plots within the boundary population (area of interest) - Intersect with state boundary - Get FIA plots for intersected states, including tree, and spatial - Clip spatial coordinates and other tables to boundary (spClipPoint)

Usage

spGetXY(
  bnd,
  bnd_dsn = NULL,
  bnd.filter = NULL,
  states = NULL,
  RS = NULL,
  xy_datsource,
  xy_dsn = NULL,
  xy = "PLOT",
  xy_opts = xy_options(),
  datsource = NULL,
  data_dsn = NULL,
  dbTabs = dbTables(),
  eval = "FIA",
  eval_opts = NULL,
  pjoinid = "CN",
  invtype = "ANNUAL",
  intensity1 = FALSE,
  pvars2keep = NULL,
  bndvars2keep = NULL,
  clipxy = TRUE,
  showsteps = FALSE,
  returnxy = TRUE,
  savedata = FALSE,
  exportsp = FALSE,
  savedata_opts = NULL
)

Arguments

bnd	sf R object, Area of Interest (AOI) boundary. Can be a spatial sf object, full pathname to a shapefile, or name of a layer within a database.
bnd_dsn	String. Data source name (dsn; e.g., SQLite database or shapefile pathname) of bnd. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html). Optional if bnd is an R object.
bnd.filter	String. Filter to subset bnd spatial layer.
states	String. The name of state(s) for tables (e.g., "Vermont", "Utah").
RS	String. Name of FIA research station to restrict states to ('RMRS','SRS','NCRS','NERS','PNWRS'). If NULL, all research stations are included.
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.
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.
pjoinid	String. Variable in plt to join to XY data. Not necessary to be unique. If using most current XY coordinates, use identifier for a plot (e.g., PLOT_ID).
invtype	String. Type of FIA inventory to extract ('PERIODIC', 'ANNUAL'). Only one inventory type (PERIODIC/ANNUAL) at a time.
intensity1	Logical. If TRUE, includes only XY coordinates where INTENSITY = 1 (FIA base grid).
pvars2keep	String vector. One or more variables in plot table to append to output.
bndvars2keep	String vector. One or more variables in bnd to append to output.
clipxy	Logical. If TRUE, clips xy data to bnd.
showsteps	Logical. If TRUE, display data in device window.
returnxy	Logical. If TRUE, returns XY coordinates.
savedata	Logical. If TRUE, saves data to outfolder. Note: includes XY data if returnxy = TRUE.
exportsp	Logical. If savedata = TRUE and returnxy = TRUE, if TRUE, exports XY data as spatial data.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE.

Details

datsource

Plots are extracted from 3 different data sources:
1) CSV - data have previously been extracted from the FIA database and stored as CSV files.
2) datamart - data are extracted from FIA's publically-available datamart.
3) sqlite - data have previously been extracted from the FIA database and stored within a SQLite database.

Selection parameters

FIA plots are selected based on the following parameters:

	evalid - the FIA evaluation identifier
	evalCur - the most current FIA evaluation in database
	evalEndyr - the FIA evaluation ending in evalEndyr
	evalType - the FIA evaluation type ('ALL', 'AREAVOL', 'GRM', 'P2VEG', 'DWM', 'INV', 'REGEN', 'CRWN')
	measCur - the most current measurement of each plot in database
	measEndyr - the most current measuremtn of each plot in database in or prior to measEndyr
	Endyr.filter - a filter for bnd that specifies the boundary where measEndyr should be applied

Value

spxy	sf. If returnxy=TRUE, spatial xy point data.
pltids	data frame. A table of pltids that are within bnd.
spxy	sf data frame. If returnxy, a simple feature with pltids within bnd.
bndx	sf object. Input bnd.
xy.uniqueid	String. Unique identifier of plots in xy.
states	String. Vector of states that intersect bnd.
countyfips	String. Vector of countyfips values that intersect bnd.
stbnd.att	String. Name of state attribute used to select plots.

If savedata=TRUE and returnxy=TRUE, the plt data frame, including XY coordinates is saved to outfolder (xyplt).
If savedata=TRUE and returnxy=FALSE, the plt data frame, without XY coordinates is saved to outfolder (pltids).
If savedata=TRUE and returnxy=TRUE and exportsp=TRUE, the spxy sf object is exported as shapefile to outfolder.

Note

If savebnd=TRUE:
If out_fmt=c('csv','shp'), the st_write (sf) function is called. The ArcGIS driver truncates variable names to 10 characters or less. Variable names are changed before export using an internal function (trunc10shp). If Spatial object has more than 1 record, it will be returned but not exported.

If datsource="datmart", (default), data are imported from FIA DataMart. The plot coordinates have been altered for privacy (See https://www.fia.fs.fed.us/tools-data/spatial/Policy/index.php for details). The zip files are extracted on-the-fly from the online website. Web server connections will affect download speeds.

Author(s)

Tracey S. Frescino

Examples

## Not run: 
# Set up data from FIESTA
WYbhfn <- system.file("extdata",
                      "sp_data/WYbighorn_adminbnd.shp",
                      package = "FIESTA")
# Use spGetXY
WYbhxy <- spGetXY(bnd = WYbhfn,
                  xy_datsource = "datamart",
                  eval = "custom",
                  eval_opts = list(Cur = TRUE),
                  returnxy = TRUE)

## End(Not run)

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