spGetPlots: Spatial wrapper - Extracts plot data within a given boundary.

In FIESTA: Forest Inventory Estimation and Analysis

Spatial wrapper - Extracts plot data 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

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().

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

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.

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(s)

Tracey S. Frescino

Examples

## Not run: 
# 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)

## End(Not run) 

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