Spatial wrapper - Extracts plot data within a given boundary.

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

spGetPlots(
  bnd = NULL,
  bnd_dsn = NULL,
  bnd.filter = NULL,
  states = NULL,
  RS = NULL,
  pltids = NULL,
  xy_datsource = NULL,
  xy_dsn = NULL,
  xy = "PLOT",
  xy_opts = xy_options(),
  datsource = NULL,
  data_dsn = NULL,
  dbTabs = dbTables(),
  eval = "FIA",
  eval_opts = NULL,
  puniqueid = "CN",
  invtype = "ANNUAL",
  intensity1 = FALSE,
  clipxy = TRUE,
  pjoinid = NULL,
  showsteps = FALSE,
  returnxy = TRUE,
  returndata = TRUE,
  savedata = FALSE,
  savexy = FALSE,
  savebnd = FALSE,
  exportsp = FALSE,
  savedata_opts = NULL,
  spXYdat = NULL,
  gui = FALSE,
  ...
)

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.
pltids: Data frame. Non-spatial plot identifiers within bnd).
xy_datsource: String. Source of XY data ("obj", "csv", "datamart", "sqlite"). If datsource=NULL, checks extension of xy_dsn or xy to identify datsource.
xy_dsn: String. Data source name (dsn; i.e., pathname or database name) of xy. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html). Optional if bnd_layer is an R object.
xy: sf R object or String. Table with xy coordinates. Can be a spatial polygon object, data frame, full pathname to a shapefile, or name of a layer within a database.
xy_opts: List of xy data options to specify if xy is NOT NULL. See xy_options (e.g., xy_opts = list(xvar='LON', yvar='LAT').
datsource: String. Source of FIA data ("obj", "csv", "datamart", "sqlite"). If datsource="sqlite", specify database name in data_dsn and layers in *_layer arguments. If datsource="datamart", files are downloaded and extracted from FIA DataMart (http://apps.fs.usda.gov/fia/datamart/datamart.html). See details for more information about plot coordinates. If datsource="csv", specify *.csv file names in *_layer arguments.
data_dsn: String. Name of database where *_layers reside.
dbTabs: List of database tables the user would like returned. See help(dbTables) for a list of options.
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.
puniqueid: String. Name of unique identifier of plt.
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).
clipxy: Logical. If TRUE, clips xy data to bnd.
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).
showsteps: Logical. If TRUE, display data in device window.
returnxy: Logical. If TRUE, save xy coordinates to outfolder.
returndata: Logical. If TRUE, returns data objects.
savedata: Logical. If TRUE, saves data to outfolder.
savexy: Logical. If TRUE, saves XY data to outfolder.
savebnd: Logical. If TRUE, and savedata=TRUE, saves bnd. If out_fmt='sqlite', saves to a SpatiaLite database.
exportsp: Logical. If TRUE, and savexy=TRUE, saves xy data as spatial data. If FALSE, saves xy data as table.
savedata_opts: List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE.
spXYdat: R list object. Output from spGetXY().
gui: Logical. If TRUE, uses gui interface.
...: parameters passed to DBgetPlots().

Value

xypltx: sf object. Input xy data clipped to boundary.
bndx: sf object. Input bnd.
tabs: list object. List of input layers clipped to boundary (pltx,condx,etc.).
xy.uniqueid: String. Name of unique identifier of xy.
puniqueid: String. Name of unique identifier of plot in plt.
pjoinid: String. Name of unique identifier of plot in plt.

If savedata=TRUE, outdat data frame is saved to outfolder.

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

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", 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

Tracey S. Frescino

Examples

if (FALSE) { # \dontrun{
# Get polygon vector layer from FIESTA external data
WYbhfn <- system.file("extdata",
                      "sp_data/WYbighorn_adminbnd.shp",
                      package = "FIESTA")

# Extract data from FIA datamart for measurement years 2013 thru 2015
dat <- spGetPlots(bnd = WYbhfn,
                  datsource = "datamart",
                  eval = "custom",
                  eval_opts = list(measyrs = 2013:2015))
names(dat)
tabs <- dat$tabs
names(tabs)
head(tabs$plt)

table(tabs$plt$MEASYEAR)

# Extract data from FIA datamart for most current evaluation
datCur <- spGetPlots(bnd = WYbhfn,
                     datsource = "datamart",
                       eval = "FIA",
                     eval_opts = list(Cur = TRUE))
names(datCur)
tabsCur <- datCur$tabs
names(tabsCur)
head(tabsCur$plt)

table(tabsCur$plt$MEASYEAR)
} # }