spGetAuxiliary {FIESTA} | R Documentation |
Spatial wrapper - Extracts and compiles auxiliary data within a specified boundary.
Description
Wrapper to extract and compile auxiliary data by domain unit (i.e, estimation
unit or small area domain). The following information is compiled:
-
Attribute defining domain (i.e., estimation unit) from domain layer
-
Area by domain (i.e., estimation unit)
- Zonal statistics by domain
(i.e., estimation unit) - spZonalRast()
Usage
spGetAuxiliary(
xyplt = NULL,
xyplt_dsn = NULL,
uniqueid = "PLT_CN",
unittype = "POLY",
unit_layer = NULL,
unit_dsn = NULL,
unitvar = NULL,
unitvar2 = NULL,
rastlst.cont = NULL,
rastlst.cont.name = NULL,
rastlst.cont.stat = "mean",
rastlst.cont.NODATA = NULL,
rastlst.cat = NULL,
rastlst.cat.name = NULL,
rastlst.cat.NODATA = NULL,
rastfolder = NULL,
asptransform = FALSE,
rast.asp = NULL,
rast.lut = NULL,
rastlut = NULL,
extract = TRUE,
areacalc = TRUE,
areaunits = "ACRES",
keepNA = TRUE,
ncores = 1,
NAto0 = TRUE,
npixels = TRUE,
addN = FALSE,
showext = FALSE,
returnxy = FALSE,
savedata = FALSE,
exportsp = FALSE,
exportNA = FALSE,
spMakeSpatial_opts = NULL,
savedata_opts = NULL,
vars2keep = 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). |
uniqueid |
String.* Unique identifier of xyplt records. |
unittype |
String. Type of spatial layer unit_layer is ("POLY", "RASTER"). |
unit_layer |
sf R object or String. Name of the domain spatial layer. Can be a spatial polygon object, full pathname to a shapefile, name of a polygon layer within a database, or a full pathname to raster file. |
unit_dsn |
String. The data source name (dsn; i.e., folder or database name) of unit_layer. The dsn varies by driver. See gdal OGR vector formats (https://www.gdal.org/ogr_formats.html). Optional. |
unitvar |
String. Name of domain variable in domlayer. If NULL, assuming one domain. An attribute names ONEUNIT is added to layer with value=1. |
unitvar2 |
String. If unittype="POLY", name of attribute in unit_layer defining a second, hierarchical larger, estimation unit (e.g., Statecd). |
rastlst.cont |
String vector or list. A list of raster(s) with continuous data values (e.g., DEM). The list may include file name of raster(s) or raster objects that are not InMemory. |
rastlst.cont.name |
String vector. Output names for continuous rasters. Optional. If NULL, name of raster is used as default or name+'_'+layer number for multi-band layers. |
rastlst.cont.stat |
String. Zonal statistic for continuous rasters. |
rastlst.cont.NODATA |
Numeric vector. NODATA value for continuous rasters (See notes). These values will be converted to NA and removed from output if keepNA=FALSE. If 1 number, the same value will be used for all categorical rasters. If more than 1 number, the number of values must be equal to the number of rasters in rastlst.cont. |
rastlst.cat |
String vector or list. A list of raster(s) with thematic (i.e., categorical) data values. The list may include file name of raster(s) or raster objects that are not InMemory. |
rastlst.cat.name |
String vector. Output names for categorical rasters. If NULL, name of raster is used as default or name+'_'+layer number for multi-band layers. |
rastlst.cat.NODATA |
Numeric vector. NODATA value for categorical rasters (See notes). These values will be converted to NA and removed from output if keepNA=FALSE. If 1 number, the same value will be used for all categorical rasters. If more than 1 number, the number of values must be equal to the number of rasters in rastlst.cat. |
rastfolder |
String. Name of the folder with raster layers. Optional. Useful if all raster layers are in same folder. |
asptransform |
Logical. If TRUE, transforms aspect to Northness and Eastness indices using sin and cosine functions. |
rast.asp |
String or raster object. The raster in rastlst.cont that is the aspect raster (Note: aspect must have units in degrees). |
rast.lut |
String. A raster in rastlst.cat to group class values. Only one raster is allowed. |
rastlut |
String or raster object. The raster look up table used for collapsing rast.lut values. |
extract |
Logical. If TRUE, extracts values from rastlst.cont and rastlst.cat along with values from unit_layer. If FALSE, extracts only values from unit_layer. |
areacalc |
Logical. If TRUE, returns area by domvar. |
areaunits |
String. Output area units ("ACRES", "HECTARES", "SQMETERS"). |
keepNA |
Logical. If TRUE, returns data frame of NA values. |
ncores |
Integer. Number of cores to use for extracting values. |
NAto0 |
Logical. If TRUE, converts extracted NA values to 0. |
npixels |
Logical. If TRUE, include number of pixels. |
addN |
Logical. If TRUE, adds N to unitzonal output with number of plots by unit. |
showext |
Logical. If TRUE, layer extents are displayed in plot window. |
returnxy |
Logical. If TRUE, returns xy data as sf object (spxyplt). |
savedata |
Logical. If TRUE, the input data with extracted values are saved to outfolder. |
exportsp |
Logical. If savedata=TRUE and returnxy=TRUE, If TRUE, the extracted strata 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. |
vars2keep |
String vector. Attributes in SAdoms, other than domvar to include in unitzonal output and extract to pltassgn points. |
gui |
Logical. If gui, user is prompted for parameters. |
Details
*If variable = NULL, then it will prompt user for input.
If there is a raster and SpatialPolygon layer, and the projection of the SpatialPolygons is different than the projection of the raster, the SpatialPolygons object is reprojected to the projection of raster (See note about on-the-fly projection conversion).
Value
pltassgn |
sf object. xyplt data with extracted values from rastlst*. |
unitzonal |
Data frame. Number of pixels and zonal statistics from continuous rasters or zonal proportions from categorical raster for each domain (i.e., estimation unit). |
unitvar |
Data frame. Domain (i.e., estimation unit) name. |
inputdf |
Data frame. Raster information input to zonal summaries. |
prednames |
String vector. Name(s) of predictor variable(s). |
zonalnames |
String vector. Name(s) of zonal variable(s). |
predfac |
String vector. Name(s) of categorical (i.e. factor) variable(s). |
npixelvar |
String. Name of variable describing number of pixels. |
unitarea |
Data frame. Area by domain (i.e., estimation unit). |
areavar |
String. Name of variable describing acres in domarea. |
pltassgnid |
String. Unique identifier of plot. |
spxy |
Simple feature. If returnxy=TRUE, Spatial coordinates. |
xy.uniqueid |
String. If returnxy=TRUE, unique identifier of spxy. |
If savedata=TRUE, datstrat and unitarea are saved to outfolder. If exportsp=TRUE, the sf object is 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.
If exportsp=TRUE:
If out_fmt="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.
On-the-fly projection conversion
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 layers from FIESTA external data
## dem (continuous)
demfn <- system.file("extdata",
"sp_data/WYbighorn_dem_250m.img",
package = "FIESTA")
## tnt (categorical)
tntfn <- system.file("extdata",
"sp_data/WYbighorn_forest_nonforest_250m.tif",
package = "FIESTA")
## unit layer
WYbhdistfn <- system.file("extdata",
"sp_data/WYbighorn_districtbnd.shp",
package = "FIESTA")
# Get Auxiliary data
spGetAuxiliary(xyplt = FIESTA::WYplt,
uniqueid = "CN",
unit_layer = WYbhdistfn,
unitvar = "DISTRICTNA",
rastlst.cont = demfn,
rastlst.cat = tntfn,
spMakeSpatial_opts = list(xvar = "LON_PUBLIC",
yvar = "LAT_PUBLIC"))