fast {fasterRaster} | R Documentation |
Create a GRaster or GVector
Description
fast()
creates a GRaster
or GVector
from 1) a file; 2) from a SpatRaster
, SpatVector
, or sf
vector; or 3) from a numeric vector, matrix
, data.frame
, or data.table
. Behind the scenes, this function will also create a connection to GRASS if none has yet been made yet.
GRASS supports loading from disk a variety of raster formats (see the GRASS manual page for r.in.gdal
(see grassHelp("r.in.gdal")
) and vector formats v.in.ogr
(see grassHelp("v.in.ogr")'), though not all of them will work with this function.
Note that GVectors
may fail to be created if they contain issues that do not coincide with the topological data model used by GRASS. The most common of these is overlapping polygons. See Details on how to fix these kinds of issues.
Note also that GRASS (and thus, fasterRaster) is not very fast when loading vectors. So, if the vector is large and you only want a portion of it, consider using the extent
argument to load the spatial subset you need.
Usage
## S4 method for signature 'character'
fast(
x,
rastOrVect = NULL,
levels = TRUE,
extent = NULL,
correct = TRUE,
snap = NULL,
area = NULL,
steps = 10,
dropTable = FALSE,
resolve = NA,
verbose = TRUE,
...
)
## S4 method for signature 'SpatRaster'
fast(x, ...)
## S4 method for signature 'SpatVector'
fast(
x,
extent = NULL,
correct = TRUE,
snap = NULL,
area = NULL,
steps = 10,
dropTable = FALSE,
resolve = NA,
verbose = TRUE
)
## S4 method for signature 'sf'
fast(
x,
extent = NULL,
correct = TRUE,
snap = NULL,
area = NULL,
steps = 10,
resolve = NA,
dropTable = FALSE,
verbose = TRUE
)
## S4 method for signature 'missing'
fast(x, rastOrVect, crs = "")
## S4 method for signature 'numeric'
fast(x, crs = "", keepgeom = FALSE)
## S4 method for signature 'data.frame'
fast(x, geom = 1:2, crs = "", keepgeom = FALSE)
## S4 method for signature 'data.table'
fast(x, geom = 1:2, crs = "", keepgeom = FALSE)
## S4 method for signature 'matrix'
fast(x, geom = 1:2, crs = "", keepgeom = FALSE)
Arguments
x |
Any one of:
|
rastOrVect |
Either |
levels |
(
|
extent |
( |
correct |
Logical ( |
snap |
|
area |
Polygon |
steps |
|
dropTable |
|
resolve |
|
verbose |
|
... |
Other arguments::
|
crs |
String: Coordinate reference system (CRS) WKT2 string. This argument is used for creating a |
keepgeom |
Logical: If |
geom |
Character or integer vector: If |
Details
GRASS uses a "topological" model for vectors. Topological issues generally arise only with polygon vectors, not point or line vectors. Sometimes, polygons created in other software are topologically incorrect–the borders of adjacent polygons may cross one another, or there may be small gaps between them. These errors can be corrected by slightly shifting vertices and/or removing small polygons that result from intersections of larger ones that border one another. A topological system also recognizes that boundaries to adjacent polygons are shared by the areas, so should not be ascribed attributes that belong to both areas (e.g., the shared border between two countries "belongs" to both countries).
By default, fast()
will try to correct topological errors in vectors. There are three levels of correction, and they are not necessarily mutually exclusive:
-
Automatic correction: By default,
fast()
will apply automatic topology correction. You can turn this off using thecorrect = FALSE
argument, though in most cases this is not recommended. -
Manual snapping and/or area removal: In addition to correction from step 1, you can cause vertices of polygons close to one another to be "snapped" to same place and/or polygons that are smaller than some threshold to be removed. Problems with mis-aligned vertices arise when adjacent polygons are meant to share borders, but slight differences in the locations of the vertices cause them to mis-align. This mis-alignment can also produce small "slivers" of polygons that are the areas where they overlap. You can snap vertices within a given distance of one another using the
snap
argument followed by a numeric value, likesnap = 0.000001
. Units ofsnap
are in map units (usually meters) for projected coordinate reference systems and degrees for unprojected systems (e.g., WGS84, NAD83, NAD27). You can also remove polygons that are smaller than a particular area using thearea
argument followed by a numeric value (e.g.,area = 1
). The units ofarea
are in meters-squared, regardless of the coordinate reference system. Note that usingsnap
andarea
entails some risk, as it is possible for nearby vertices to actually be distinct and for small areas to be legitimate. -
Automatic snapping and/or area removal: In addition to the correction from step 1, you can use automatic
snap
and/orarea
correction on polygons vectors by settingsnap
and/orarea
toNULL
(i.e., their default values). If justsnap
isNULL
, only automatic snapping will be performed, and if justarea
isNULL
, then only automatic area removal will be performed. Regardless, you will also need to set an integer value forsteps
, which is the number of steps to take between the smallest value ofsnap
and/orarea
and the maximum value attempted. The function will then proceed by first attemptingsnap = 0
and/orarea = 0
(i.e., no snapping or area removal). If this does not produce a topologically correct vector, GRASS will (internally) suggest a range forsnap
. Thefast()
function then createssteps
values from the lowest to the highest values of this range evenly-spaced along the log values of this range, then proceed to repeat the importing process until either the vector is imported correctly or the maximum value ofsnap
is reached and results in a failed topology. Smaller values ofstep
will result in more fine-grained attempts so are less likely to yield overcorrection, but can also take more time. The value ofarea
in automatic correction is set tosnap^2
. NB: Automated snapping and area removal are only performed on polygons vectors, even ifsnap
orarea
isNULL
. To snap lines or points, you must setsnap
equal to a numeric value. Thearea
correction is ignored for points and lines.
Issues can also arise due to:
-
Data table-vector mismatching: If your vector has a data table ("attribute table") associated with it, errors can occur if there are more/fewer geometries (or multi-geometries) per row in the table. If you do not really need the data table to do your analysis, you can remove it (and thus obviate this error) using
dropTable = TRUE
. -
Dissolving or aggregating "invalid" geometries: Using the
resolve
argument, you can create a topologically valid vector by either coercing all overlapping portions of polygons into their own geometries (resolve = "disaggregate"
), or by coercing them into a single, combined geometry (resolve = "aggregate"
). Aggregation/disaggregation will be implemented after loading the vector into GRASS using the settings given bysnap
andarea
. Aggregation/disaggregation will cause any associated data table to be dropped (it forcesdropTable
to beTRUE
). The default action is to do neither aggregation nor disaggregation (resolve = NA
).
If none of these fixes work, you can try:
-
Correction outside of fasterRaster: Before you convert the vector into fasterRaster's
GVector
format, you can also try using theterra::makeValid()
orsf::st_make_valid()
tools to fix issues, then usefast()
. -
Post-conversion to a
GVector
: If you do get a vector loaded intoGVector
format, you can also use a set of fasterRaster vector-manipulation tools orfillHoles()
to fix issues.
Value
A GRaster
or GVector
.
See Also
rgrass::read_RAST()
and rgrass::read_VECT()
, vector cleaning, fillHoles()
, plus GRASS modules v.in.ogr
(see grassHelp("v.in.ogr")
) and r.import
(see grassHelp("r.import")
)
Examples
if (grassStarted()) {
# Setup
library(sf)
library(terra)
# Example data
madElev <- fastData("madElev") # integer raster
madCover <- fastData("madCover") # categorical raster
madCoast4 <- fastData("madCoast4") # polygons vector
madRivers <- fastData("madRivers") # lines vector
madDypsis <- fastData("madDypsis") # points vector
### Create GRasters from SpatRasters
# Create an integer raster:
elev <- fast(madElev)
elev
# Create a categorical raster:
cover <- fast(madCover)
madCover
levels(madCover) # category levels
# Create a GRaster from a file on disk:
rastFile <- system.file("extdata", "madForest2000.tif", package = "fasterRaster")
forest2000 <- fast(rastFile)
forest2000
# Create a 1's raster that spans the world:
ones <- fast(rastOrVect = "raster", crs = "epsg:4326")
ones
### Create GVectors
# Create a GVector from an sf vector:
coast4 <- fast(madCoast4)
coast4
# Create a GVector from a SpatVector:
madRivers <- vect(madRivers)
class(madRivers)
rivers <- fast(madRivers)
rivers
# Create a GVector from a vector on disk:
vectFile <- system.file("extdata/shapes", "madCoast.shp",
package = "fasterRaster")
coast0 <- fast(vectFile)
coast0
# Import only Dypsis occurrences in a restricted area:
ant <- coast4[coast4$NAME_4 == "Antanambe"]
dypsisRestrict <- fast(madDypsis, extent = ant)
dypsis <- fast(madDypsis)
plot(coast4)
plot(ant, col = "gray80", add = TRUE)
plot(dypsis, add = TRUE)
plot(dypsisRestrict, col = "red", add = TRUE)
# Create a generic GVector that spans the world:
wallToWall <- fast(rastOrVect = "vector", crs = "epsg:4326") # WGS84
wallToWall
# Create a GVector from a numeric vector
pts <- c(-90.2, 38.6, -122.3, 37.9)
pts <- fast(pts, crs = "epsg:4326") # WGS84
# Create a GVector from a matrix (can also use data.frame or data.table):
mat <- matrix(c(-90.2, 38.6, -122.3, 37.9), ncol = 2, byrow = TRUE)
mat <- fast(mat, crs = "epsg:4326", keepgeom = TRUE) # WGS84
}