spExtractRast: Spatial - Extracts point attribute values from raster...

In FIESTA: Forest Inventory Estimation and Analysis

Spatial - Extracts point attribute values from raster layer(s).

Description

Extracts values from one or more raster layers and appends to input SpatialPoints layer or data frame. Points are reprojected on-the-fly to projection of raster(s) using PROJ.4 transformation parameters and sf spTransform function. Includes options to use bilinear interpolation or summarize over a window of n pixels using a specified statistic.

Usage

spExtractRast(
  xyplt,
  xyplt_dsn = NULL,
  xy.uniqueid = "PLT_CN",
  rastlst,
  rastfolder = NULL,
  rast.crs = NULL,
  bandlst = NULL,
  var.name = NULL,
  interpolate = FALSE,
  windowsize = 1,
  windowstat = NULL,
  rast.NODATA = NULL,
  keepNA = TRUE,
  ncores = 1,
  showext = FALSE,
  savedata = FALSE,
  exportsp = FALSE,
  exportNA = FALSE,
  spMakeSpatial_opts = NULL,
  savedata_opts = NULL,
  gui = FALSE
)

Arguments

xyplt	Data frame object or String. Name of layer with xy coordinates and unique identifier. Can be layer with xy_dsn, full pathname, including extension, or file name (with extension) in xy_dsn folder.
xyplt_dsn	String. Name of database where xyplt is. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html).
xy.uniqueid	String. Unique identifier of xyplt rows.
rastlst	String vector or list or strings and/or rasters. File name(s) with extensions, or raster object(s). Note: raster objects must be written to file.
rastfolder	String. Name of the folder with raster layers. Optional. Useful if all raster layers are in same folder.
rast.crs	EPSG code or PROJ.4 String. Name of coordinate reference system for rasters with no projection defined. If more than one raster has no projection defined, the same crs will be used.
bandlst	Numeric named list. If rastfnlst includes a multi-layer raster and only 1 or some layers are desired, specify layer numbers in a named list format with names matching the base names in rastfnlst (e.g., list(rast1=5, rast3=1:3)). If NULL, all layers are extracted.
var.name	String vector. Extracted variable name(s). If NULL, uses the basename of raster layer, including band number for multi-band rasters.
interpolate	Logical vector. If TRUE, uses bilinear interpolation of pixel values, weighted average of 4 nearest pixels (i.e., continuous data).
windowsize	Number vector. The size of window for summarizing data.
windowstat	Character vector. If windowsize is greater than one, the statistic to use for summarizing data ("mean", "min", "max", "median", "sum", "range", "var", "sd", "rsd", "mode", "value"). If windowstat="value", all pixel values are returned, otherwise 1 value per row in xyplt is returned.
rast.NODATA	Numeric vector. NODATA value(s) of raster if not predefined (See notes below). This value will be converted to NA and removed if keepNA=FALSE. If rastfnlst includes more than one raster, the rast.NODATA value should coincide with number of rasters in rastfnlst. If only one rast.NODATA, the same NODATA value is used for all rasters.
keepNA	Logical. If TRUE, keeps NA values after data extraction.
ncores	Integer. Number of cores to use for extracting values.
showext	Logical. If TRUE, layer extents are displayed in plot window.
savedata	Logical. If TRUE, the input data with extracted values are saved to outfolder.
exportsp	Logical. If TRUE, the extracted raster point data are exported to outfolder.
exportNA	Logical. If TRUE, NA values are exported to outfolder.
spMakeSpatial_opts	List. See help(spMakeSpatial_options()) for a list of options. Use to convert X/Y values to simple feature (sf) coordinates.
savedata_opts	List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE. If out_layer = NULL, default = 'rastext'.
gui	Logical. If gui, user is prompted for parameters.

Details

*If variable = NULL, then it will prompt user for input.

Value

sppltext	sf object or data frame. Input xyplt data with extracted raster values appended.
outnames	String vector. Raster output names.
rastfnlst	String vector. Raster pathnames.
inputdf	Data frame. Raster information input to zonal summaries.
NAlst	sf List. If NA values exist after data extraction, the spatial NA points are returned.

If savedata=TRUE, pltassgn and unitarea are saved to outfolder.
If exportsp=TRUE, the spatial sf points object is exported to outfolder.
. If exportNA=TRUE and NA values exist after data extraction, the spatial NA points are exported to outfolder.

Note

rast.NODATA
NODATA values are raster pixel values that have no data of interest, including pixels within the extent of the layer, but outside the area of interest. Sometimes these pixels have been defined previously. The defined NODATA pixels are imported to R as NULL values. When not previously defined, the pixels outside the area of interest will be the minimum or maximum value depending on the data type (e.g., 16-bit signed: min=-32,768; max=32,768) or byte size (1 byte: min=0; max=255). These NODATA values will be added to the zonal statistic calculations if not specified in rast.NODATA.

The spTransform (sf) method is used for on-the-fly map projection conversion and datum transformation using PROJ.4 arguments. Datum transformation only occurs if the +datum tag is present in the both the from and to PROJ.4 strings. The +towgs84 tag is used when no datum transformation is needed. PROJ.4 transformations assume NAD83 and WGS84 are identical unless other transformation parameters are specified. Be aware, providing inaccurate or incomplete CRS information may lead to erroneous data shifts when reprojecting. See spTransform help documentation for more details.

Author(s)

Tracey S. Frescino

Examples

# Get point data from WYplt data in FIESTA
WYplt <- FIESTA::WYplt

# Get raster layers from FIESTA external data
fornffn <- system.file("extdata",
                       "sp_data/WYbighorn_forest_nonforest_250m.tif",
                       package = "FIESTA")
demfn <- system.file("extdata",
                     "sp_data/WYbighorn_dem_250m.img",
                     package = "FIESTA")

# Extract points from raster
xyext <- spExtractRast(xyplt = WYplt,
                       rastlst = c(fornffn, demfn),
                       var.name = c("fornf", "dem"),
                       xy.uniqueid = "CN",
                       spMakeSpatial_opts = list(xvar = "LON_PUBLIC",
                                                 yvar = "LAT_PUBLIC",
                                                 xy.crs = 4269))
names(xyext)
xyext$outnames
sppltext <- xyext$sppltext
head(sppltext)
xyext$inputdf

# Plot extracted values of forest/nonforest
plot(sppltext["fornf"])

# Plot extracted values of dem (i.e., elevation)
plot(sppltext["dem"])

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