Title: | Spatial Data Analysis |
---|---|
Description: | Methods for spatial data analysis with vector (points, lines, polygons) and raster (grid) data. Methods for vector data include geometric operations such as intersect and buffer. Raster methods include local, focal, global, zonal and geometric operations. The predict and interpolate methods facilitate the use of regression type (interpolation, machine learning) models for spatial prediction, including with satellite remote sensing data. Processing of very large files is supported. See the manual and tutorials on <https://rspatial.org/> to get started. 'terra' replaces the 'raster' package ('terra' can do more, and it is faster and easier to use). |
Authors: | Robert J. Hijmans [cre, aut] |
Maintainer: | Robert J. Hijmans <[email protected]> |
License: | GPL (>=3) |
Version: | 1.7-81 |
Built: | 2024-09-07 05:37:28 UTC |
Source: | https://github.com/rspatial/terra |
terra
provides methods to manipulate geographic (spatial) data in "raster" and "vector" form. Raster data divide space into rectangular grid cells and they are commonly used to represent spatially continuous phenomena, such as elevation or the weather. Satellite images also have this data structure, and in that context grid cells are often referred to as pixels. In contrast, "vector" spatial data (points, lines, polygons) are typically used to represent discrete spatial entities, such as a road, country, or bus stop.
The package implements two main classes (data types): SpatRaster
and SpatVector
. SpatRaster
supports handling large raster files that cannot be loaded into memory; local, focal, zonal, and global raster operations; polygon, line and point to raster conversion; integration with modeling methods to make spatial predictions; and more. SpatVector
supports all types of geometric operations such as intersections.
Additional classes include SpatExtent
, which is used to define a spatial extent (bounding box); SpatRasterDataset
, which represents a collection of sub-datasets for the same area. Each sub-dataset is a SpatRaster with possibly many layers, and may, for example, represent different weather variables; and SpatRasterCollection
and SpatVectorCollection
that are equivalent to lists of SpatRaster
or SpatVector
objects. There is also a SpatGraticule
class to assist in adding a longitude/latitude lines and labels to a map with another coordinate reference system.
These classes hold a C++ pointer to the data "reference class" and that creates some limitations. They cannot be recovered from a saved R session either or directly passed to nodes on a computer cluster. Generally, you should use writeRaster
to save SpatRaster
objects to disk (and pass a filename or cell values to cluster nodes). Also see wrap
. Also, package developers should not directly access this pointer, as its user-interface is not stable.
The terra
package is conceived as a replacement of the raster
package. terra
has a very similar, but simpler, interface, and it is faster than raster
. At the bottom of this page there is a table that shows differences in the methods between the two packages.
Below is a list of some of the most important methods grouped by theme.
———————————————————————————————————————
———————————————————————————————————————
rast
|
Create a SpatRaster from scratch, file, or another object |
c |
Combine SpatRasters (multiple layers) |
add<- |
Add a SpatRaster to another one |
subset or [[ , or $ |
Select layers of a SpatRaster |
selectRange |
Select cell values from different layers using an index layer |
--------------------------- | ------------------------------------------------------------------------------------------ |
Also see the methods in section VIII
merge |
Combine SpatRasters with different extents (but same origin and resolution) |
mosaic |
Combine SpatRasters with different extents using a function for overlapping cells |
crop |
Select a geographic subset of a SpatRaster |
extend |
Add rows and/or columns to a SpatRaster |
trim |
Trim a SpatRaster by removing exterior rows and/or columns that only have NAs |
aggregate |
Combine cells of a SpatRaster to create larger cells |
disagg |
Subdivide cells |
resample |
Resample (warp) values to a SpatRaster with a different origin and/or resolution |
project |
Project (warp) values to a SpatRaster with a different coordinate reference system |
shift |
Adjust the location of SpatRaster |
flip |
Flip values horizontally or vertically |
rotate |
Rotate values around the date-line (for lon/lat data) |
t |
Transpose a SpatRaster |
--------------------------- | ------------------------------------------------------------------------------------------ |
app |
Apply a function to all cells, across layers, typically to summarize (as in base::apply ) |
tapp |
Apply a function to groups of layers (as in base::tapply and stats::aggregate ) |
lapp |
Apply a function to using the layers of a SpatRaster as variables |
sapp |
Apply a function to each layer |
rapp |
Apply a function to a spatially variable range of layers |
--------------------------- | ------------------------------------------------------------------------------------------ |
Arith-methods |
Standard arithmetic methods (+, -, *, ^, %%, %/%, / ) |
Compare-methods |
Comparison methods for SpatRaster (==, !=, >, <, <=, >=m is.na, is.finite ) |
not.na |
a one-step equivalent to !is.na |
Summary-methods |
mean, max, min, median, sum, range, prod, |
any, all, stdev, which.min, which.max, anyNA, noNA, allNA
|
|
Logic-methods |
Boolean methods (!, &, | ) |
Math-methods |
abs, sign, sqrt, ceiling, floor, trunc, cummax, cummin, cumprod, |
cumsum, log, log10, log2, log1p, acos, acosh, asin, asinh, atan, atanh, |
|
exp, expm1, cos, cosh, sin, sinh, tan, tanh, round, signif
|
|
as.bool
|
create a Boolean (logical) SpatRaster |
as.int
|
create an integer (whole numbers) SpatRaster |
--------------------------- | ------------------------------------------------------------------------------------------ |
approximate |
Compute missing values for cells by interpolation across layers |
roll |
Rolling functions such as the rolling mean |
cellSize |
Compute the area of cells |
classify |
(Re-)classify values |
subst |
Substitute (replace) cell values |
cover |
First layer covers second layer except where the first layer is NA |
init |
Initialize cells with new values |
mask |
Replace values in a SpatRaster based on values in another SpatRaster |
which.lyr |
which is the first layer that is TRUE ? |
segregate |
Make a 0/1 layer for each unique value |
rangeFill |
Make a 0/1 SpatRaster for a time series |
regress |
Cell-based regression models |
--------------------------- | ------------------------------------------------------------------------------------------ |
expanse |
Compute the summed area of cells |
crosstab |
Cross-tabulate two SpatRasters |
freq |
Frequency table of SpatRaster cell values |
global |
Summarize SpatRaster cell values with a function |
quantile |
Quantiles |
layerCor |
Correlation between layers |
stretch |
Stretch values |
scale |
Scale values |
summary |
Summary of the values of a SpatRaster (quartiles and mean) |
unique |
Get the unique values in a SpatRaster |
zonal |
Summarize a SpatRaster by zones in another SpatRaster |
--------------------------- | ------------------------------------------------------------------------------------------ |
adjacent |
Identify cells that are adjacent to a set of cells of a SpatRaster |
boundaries |
Detection of boundaries (edges) |
distance |
Shortest distance to a cell that is not NA or to or from a vector object |
gridDist |
Shortest distance through adjacent grid cells |
costDist |
Shortest distance considering cell-varying friction |
direction |
Direction (azimuth) to or from cells that are not NA
|
focal |
Focal (neighborhood; moving window) functions |
focal3D |
Three dimensional (row, col, lyr) focal functions |
focalCpp |
Faster focal by using custom C++ functions |
focalReg |
Regression between layers for focal areas |
focalPairs |
Apply a function (e.g. a correlation coefficient) to focal values for pairs of layers |
patches |
Find patches (clumps) |
sieve |
Sieve filter to remove small patches |
terrain |
Compute slope, aspect and other terrain characteristics from elevation data |
viewshed |
Compute viewshed (showing areas that are visible from a particular location |
shade |
Compute hill shade from slope and aspect layers |
autocor |
Compute global or local spatial autocorrelation |
--------------------------- | ------------------------------------------------------------------------------------------ |
predict |
Predict a non-spatial (regression or classification) model to a SpatRaster |
interpolate |
Predict a spatial model to a SpatRaster |
interpIDW |
Inverse-distance-weighted interpolation |
interpNear |
Nearest neighbor interpolation |
k_means |
k-means clustering of SpatRaster data |
princomp and prcomp |
Principal Component Analysis (PCA) with raster data |
--------------------------- | ------------------------------------------------------------------------------------------ |
Apart from the function listed below, you can also use indexing with [
with cell numbers, and row and/or column numbers
values |
cell values (fails with very large rasters) |
values<- |
Set new values to the cells of a SpatRaster |
setValues |
Set new values to the cells of a SpatRaster |
as.matrix |
Get cell values as a matrix |
as.array |
Get cell values as an array |
extract |
Extract cell values from a SpatRaster (with cell numbers, coordinates, points, lines, or polygons) |
extractAlong |
Extract cell values along a line such that the values are in the right order |
spatSample |
Regular or random sample |
minmax |
Get the minimum and maximum value of the cells of a SpatRaster (if known) |
setMinMax |
Compute the minimum and maximum value of a SpatRaster if these are not known |
extract |
spatial queries of a SpatRaster with a SpatVector |
--------------------------- | ------------------------------------------------------------------------------------------ |
Get or set basic parameters of SpatRasters. If there are values associated with a SpatRaster (either in memory or via a link to a file) these are lost when you change the number of columns or rows or the resolution. This is not the case when the extent is changed (as the number of columns and rows will not be affected). Similarly, with crs you can set the coordinate reference system, but this does not transform the data (see project for that).
ncol
|
The number of columns |
nrow |
The number of rows |
ncell |
The number of cells (can not be set directly, only via ncol or nrow) |
res |
The resolution (x and y) |
nlyr |
Get or set the number of layers |
names |
Get or set the layer names |
xres |
The x resolution (can be set with res) |
yres |
The y resolution (can be set with res) |
xmin |
The minimum x coordinate (or longitude) |
xmax |
The maximum x coordinate (or longitude) |
ymin |
The minimum y coordinate (or latitude) |
ymax |
The maximum y coordinate (or latitude) |
ext |
Get or set the extent (minimum and maximum x and y coordinates ("bounding box") |
origin |
The origin of a SpatRaster |
crs |
The coordinate reference system (map projection) |
is.lonlat |
Test if an object has (or may have) a longitude/latitude coordinate reference system |
sources |
Get the filename(s) to which a SpatRaster is linked |
inMemory |
Are the data sources in memory (or on disk)? |
compareGeom |
Compare the geometry of SpatRasters |
NAflag |
Set the NA value (for reading from a file with insufficient metadata) |
--------------------------- | ------------------------------------------------------------------------------------------ |
Cell numbers start at 1 in the upper-left corner. They increase within rows, from left to right, and then row by row from top to bottom. Likewise, row numbers start at 1 at the top of the raster, and column numbers start at 1 at the left side of the raster.
xFromCol |
x-coordinates from column numbers |
yFromRow |
y-coordinates from row numbers |
xFromCell |
x-coordinates from row numbers |
yFromCell |
y-coordinates from cell numbers |
xyFromCell |
x and y coordinates from cell numbers |
colFromX |
Column numbers from x-coordinates (or longitude) |
rowFromY |
Row numbers from y-coordinates (or latitude) |
rowColFromCell |
Row and column numbers from cell numbers |
cellFromXY |
Cell numbers from x and y coordinates |
cellFromRowCol |
Cell numbers from row and column numbers |
cellFromRowColCombine |
Cell numbers from all combinations of row and column numbers |
cells
|
Cell numbers from an SpatVector or SpatExtent |
--------------------------- | ------------------------------------------------------------------------------------------ |
time |
Get or set time |
fillTime |
can add empty layers in between existing layers to assure that the time step between layers is constant |
mergeTime |
combine multiple rasters, perhaps partly overlapping in time, into a single time series |
--------------------------- | ------------------------------------------------------------------------------------------ |
is.factor |
Are there categorical layers? |
levels |
Get active categories, or set categories |
activeCat |
Get or set the active category |
cats |
Get categories (active and inactive) |
set.cats |
Set categories in place |
concats |
Combine SpatRasters with different categories |
catalyze |
Create a layer for each category |
as.numeric |
use the active category to create a non-categorical SpatRaster |
as.factor |
Make the layers of a SpatRaster categorical |
--------------------------- | ------------------------------------------------------------------------------------------ |
writeRaster |
Write all values of SpatRaster to disk. You can set the filetype, datatype, compression. |
writeCDF |
Write SpatRaster data to a netCDF file |
--------------------------- | ------------------------------------------------------------------------------------------ |
readStart |
Open file connections for efficient multi-chunk reading |
readStop |
Close file connections |
writeStart |
Open a file for writing |
writeValues |
Write some values |
writeStop |
Close the file after writing |
blocks |
Get blocksize for reading files (when not writing) |
--------------------------- | ------------------------------------------------------------------------------------------ |
terraOptions |
Show, set, or get session options, mostly to control memory use and to set write options |
sources |
Show the data sources of a SpatRaster |
tmpFiles |
Show or remove temporary files |
mem_info |
memory needs and availability |
inMemory |
Are the cell values in memory? |
--------------------------- | ------------------------------------------------------------------------------------------ |
A SpatRasterDataset contains SpatRasters that represent sub-datasets for the same area. They all have the same extent and resolution.
sds |
Create a SpatRasterDataset from a file with subdatasets (ncdf or hdf) or from SpatRasters |
[ or $ |
Extract a SpatRaster |
names |
Get the names of the sub-datasets |
--------------------------- | ------------------------------------------------------------------------------------------ |
A SpatRasterCollection is a vector of SpatRaster objects. Unlike for a SpatRasterDataset, there the extent and resolution of the SpatRasters do not need to match each other.
sprc |
create a SpatRasterCollection from (a list of) SpatRasters |
length |
how many SpatRasters does the SpatRasterCollection have? |
crop |
crop a SpatRasterCollection |
impose |
force the members of SpatRasterCollection to the same geometry |
merge |
merge the members of a SpatRasterCollection |
mosaic |
mosaic (merge with a function for overlapping areas) the members of a SpatRasterCollection |
[ |
extract a SpatRaster |
--------------------------- | ------------------------------------------------------------------------------------------ |
———————————————————————————————————————
vect |
Create a SpatVector from a file (for example a "shapefile") or from another object |
vector_layers |
list or delete layers in a vector database such as GPGK |
rbind |
append SpatVectors of the same geometry type |
unique |
remove duplicates |
na.omit |
remove empty geometries and/or fields that are NA |
project |
Project a SpatVector to a different coordinate reference system |
writeVector |
Write SpatVector data to disk |
centroids |
Get the centroids of a SpatVector |
voronoi |
Voronoi diagram |
delaunay |
Delaunay triangles |
convHull |
Compute the convex hull of a SpatVector |
minRect |
Compute the minimum minimal bounding rotated rectangle of a SpatVector |
minCircle |
Compute the minimal bounding circle of a SpatVector |
fillHoles
|
Remove or extract holes from polygons |
--------------------------- | ------------------------------------------------------------------------------------------ |
geom |
returns the geometries as matrix or WKT |
crds |
returns the coordinates as a matrix |
linearUnits |
returns the linear units of the crs (in meter) |
ncol
|
The number of columns (of the attributes) |
nrow |
The number of rows (of the geometries and attributes) |
names |
Get or set the layer names |
ext |
Get the extent (minimum and maximum x and y coordinates ("bounding box") |
crs |
The coordinate reference system (map projection) |
is.lonlat |
Test if an object has (or may have) a longitude/latitude coordinate reference system |
--------------------------- | ------------------------------------------------------------------------------------------ |
adjacent |
find adjacent polygons |
expanse |
computes the area covered by polygons |
nearby |
find nearby geometries |
nearest |
find the nearest geometries |
relate |
geometric relationships such as "intersects", "overlaps", and "touches" |
perim |
computes the length of the perimeter of polygons, and the length of lines |
--------------------------- | ------------------------------------------------------------------------------------------ |
erase or "-" |
erase (parts of) geometries |
intersect or "*" |
intersect geometries |
union or "+" |
Merge geometries |
cover |
update polygons |
symdif |
symmetrical difference of two polygons |
aggregate |
dissolve smaller polygons into larger ones |
buffer |
buffer geometries |
disagg |
split multi-geometries into separate geometries |
crop |
clip geometries using a rectangle (SpatExtent) or SpatVector |
--------------------------- | ------------------------------------------------------------------------------------------ |
We use the term "attributes" for the tabular data (data.frame) associated with vector geometries.
extract |
spatial queries between SpatVector and SpatVector (e.g. point in polygons) |
sel |
select - interactively select geometries |
click |
identify attributes by clicking on a map |
merge |
Join a table with a SpatVector |
as.data.frame |
get attributes as a data.frame |
as.list |
get attributes as a list |
values |
Get the attributes of a SpatVector |
values<- |
Set new attributes to the geometries of a SpatRaster |
sort |
sort SpatVector by the values in a field |
--------------------------- | ------------------------------------------------------------------------------------------ |
shift |
change the position geometries by shifting their coordinates in horizontal and/or vertical direction |
spin
|
rotate geometries around an origin |
rescale |
shrink (or expand) geometries, for example to make an inset map |
flip |
flip geometries vertically or horizontally |
t |
transpose geometries (switch x and y) |
--------------------------- | ------------------------------------------------------------------------------------------ |
width |
the minimum diameter of the geometries |
clearance |
the minimum clearance of the geometries |
sharedPaths |
shared paths (arcs) between line or polygon geometries |
simplifyGeom |
simplify geometries |
gaps |
find gaps between polygon geometries |
fillHoles |
get or remove the polygon holes |
makeNodes |
create nodes on lines |
mergeLines |
connect lines to form polygons |
removeDupNodes |
remove duplicate nodes in geometries and optionally rounds the coordinates |
is.valid |
check if geometries are valid |
makeValid |
attempt to repair invalid geometries |
snap |
make boundaries of geometries identical if they are very close to each other |
erase (single argument) |
remove parts of geometries that overlap |
union (single argument) |
create new polygons such that there are no overlapping polygons |
rotate |
rotate to (dis-) connect them across the date-line |
normalize.longitude |
move geometries that are outside of the -180 to 180 degrees range. |
elongate |
make lines longer by extending both sides |
combineGeoms |
combine geometries that overlap, share a border, or are within a minimum distance of each other |
forceCCW |
force counter-clockwise polygon winding |
--------------------------- | ------------------------------------------------------------------------------------------ |
A SpatVectorCollection is a vector of SpatVector objects.
svc |
create a SpatVectorCollection from (a list of) SpatVector objects |
length |
how many SpatRasters does the SpatRasterCollection have? |
[ |
extract a SpatVector |
--------------------------- | ------------------------------------------------------------------------------------------ |
———————————————————————————————————————
ext |
Create a SpatExtent object. For example to crop a Spatial dataset |
intersect |
Intersect two SpatExtent objects, same as - |
union |
Combine two SpatExtent objects, same as + |
Math-methods |
round/floor/ceiling of a SpatExtent |
align |
Align a SpatExtent with a SpatRaster |
draw |
Create a SpatExtent by drawing it on top of a map (plot) |
--------------------------- | ------------------------------------------------------------------------------------------ |
graticule |
Create a graticule |
crop |
crop a graticule |
plot<SpatGraticule> |
plot a graticule |
--------------------------- | ------------------------------------------------------------------------------------------ |
———————————————————————————————————————
You can coerce SpatRasters to Raster* objects, after loading the raster
package, with as(object, "Raster")
, or raster(object)
or brick(object)
or stack(object)
rast |
SpatRaster from matrix and other objects |
vect |
SpatVector from sf or Spatial* vector data |
sf::st_as_sf |
sf object from SpatVector |
rasterize |
Rasterizing points, lines or polygons |
rasterizeWin |
Rasterize points with a moving window |
rasterizeGeom |
Rasterize attributes of geometries such as "count", "area", or "length" |
as.points |
Create points from a SpatRaster or SpatVector |
as.lines |
Create lines from a SpatRaster or SpatVector |
as.polygons |
Create polygons from a SpatRaster |
as.contour |
Contour lines from a SpatRaster |
--------------------------- | ------------------------------------------------------------------------------------------ |
plot |
Plot a SpatRaster or SpatVector. The main method to create a map |
panel |
Combine multiple plots |
points |
Add points to a map |
lines |
Add lines to a map |
polys |
Add polygons to a map |
text |
Add text (such as the values of a SpatRaster or SpatVector) to a map |
halo |
Add text with a halo to a map |
map.pal |
Color palettes for mapping |
image |
Alternative to plot to make a map with a SpatRaster |
plotRGB |
Combine three layers (red, green, blue channels) into a single "real color" plot |
plot<SpatGraticule> |
plot a graticule |
sbar |
Add a scale bar to a map |
north |
Add a north arrow to a map |
inset |
Add a small inset (overview) map |
add_legend |
Add a legend to a map |
add_box |
Add a bounding box to a map |
map_extent |
Get the coordinates of a map's axes positions |
dots |
Make a dot-density map |
cartogram |
Make a cartogram |
persp |
Perspective plot of a SpatRaster |
contour |
Contour plot or filled-contour plot of a SpatRaster |
colorize |
Combine three layers (red, green, blue channels) into a single layer with a color-table |
--------------------------- | ------------------------------------------------------------------------------------------ |
zoom |
Zoom in to a part of a map by drawing a bounding box on it |
click |
Query values of SpatRaster or SpatVector by clicking on a map |
sel |
Select a spatial subset of a SpatRaster or SpatVector by drawing on a map |
draw |
Create a SpatExtent or SpatVector by drawing on a map |
--------------------------- | ------------------------------------------------------------------------------------------ |
plot |
x-y scatter plot of the values of (a sample of) the layers of two SpatRaster objects |
hist |
Histogram of SpatRaster values |
barplot |
Bar plot of a SpatRaster |
density |
Density plot of SpatRaster values |
pairs |
Pairs plot for layers in a SpatRaster |
boxplot |
Box plot of the values of a SpatRaster |
--------------------------- | ------------------------------------------------------------------------------------------ |
———————————————————————————————————————
terra
has a single class SpatRaster
for which raster
has three (RasterLayer, RasterStack, RasterBrick
). Likewise there is a single class for vector data SpatVector
that replaces six Spatial*
classes. Most method names are the same, but note the following important differences in methods names with the raster
package
raster package | terra package |
raster, brick, stack
|
rast |
rasterFromXYZ
|
rast( , type="xyz") |
stack, addLayer
|
c |
addLayer |
add<- |
area |
cellSize or expanse
|
approxNA |
approximate |
calc
|
app |
cellFromLine, cellFromPolygon,
|
cells
|
cellsFromExtent
|
cells |
cellStats
|
global |
clump
|
patches |
compareRaster
|
compareGeom |
corLocal
|
focalPairs |
coordinates
|
crds |
couldBeLonLat
|
is.lonlat |
disaggregate |
disagg |
distanceFromPoints |
distance
|
drawExtent, drawPoly, drawLine |
draw
|
dropLayer
|
subset |
extent
|
ext |
getValues
|
values |
isLonLat, isGlobalLonLat
|
is.lonlat |
layerize
|
segregate |
layerStats
|
layerCor |
movingFun
|
roll |
NAvalue
|
NAflag |
nlayers
|
nlyr |
overlay
|
lapp |
unstack
|
as.list |
projectRaster
|
project |
rasterToPoints
|
as.points |
rasterToPolygons
|
as.polygons |
reclassify, subs, cut
|
classify |
sampleRandom, sampleRegular
|
spatSample |
shapefile
|
vect |
stackApply
|
tapp |
stackSelect
|
selectRange |
Also note that even if function names are the same in terra
and raster
, their output can be different. In most cases this was done to get more consistency in the returned values (and thus fewer errors in the downstream code that uses them). In other cases it simply seemed better. Here are some examples:
as.polygons
|
By default, terra returns dissolved polygons |
quantile
|
computes by cell, across layers instead of the other way around |
extract
|
By default, terra returns a matrix, with the first column the sequential ID of the vectors. |
raster returns a list (for lines or polygons) or a matrix (for points, but without the ID |
|
column. You can use list=TRUE to get the results as a list |
|
values
|
terra always returns a matrix. raster returns a vector for a RasterLayer
|
Summary-methods
|
With raster , mean(x, y) and mean(stack(x, y) return the same result, a single |
layer with the mean of all cell values. This is also what terra returns with |
|
mean(c(x, y)) , but with mean(x, y) the parallel mean is returned -- that is, the |
|
computation is done layer-wise, and the number of layers in the output is the same as | |
that of x and y (or the larger of the two if they are not the same). This affects |
|
all summary functions (sum , mean , median , which.min , which.max , min , max , |
|
prod , any , all , stdev ), except range , which is not implemented for this case |
|
(you can use min and max instead) |
|
--------------------------- | ------------------------------------------------------------------------------------------ |
Except where indicated otherwise, the methods and functions in this package were written by Robert Hijmans. The configuration scripts were written by Roger Bivand. Some of code using the GEOS library was adapted from code by Edzer Pebesma for sf
. Michael Sumner contributed various bits and pieces.
This package is an attempt to climb on the shoulders of giants (GDAL, PROJ, GEOS, NCDF, GeographicLib, Rcpp, R). Many people have contributed by asking questions or raising issues. Feedback and suggestions by Márcia Barbosa, Kendon Bell, Andrew Gene Brown, Jean-Luc Dupouey, Krzysztof Dyba, Sarah Endicott, Derek Friend, Alex Ilich, Gerald Nelson, Jakub Nowosad, and Monika Tomaszewska have been especially helpful.
Get or set the active category of a multi-categorical SpatRaster layer
## S4 method for signature 'SpatRaster' activeCat(x, layer=1) ## S4 replacement method for signature 'SpatRaster' activeCat(x, layer=1)<-value
## S4 method for signature 'SpatRaster' activeCat(x, layer=1) ## S4 replacement method for signature 'SpatRaster' activeCat(x, layer=1)<-value
x |
SpatRaster |
layer |
positive integer, the layer number or name |
value |
positive integer or character, indicating which column in the categories to use. Note that when a number is used this index is zero based, and "1" refers to the second column. This is because the first column of the categories has the cell values, not categorical labels |
integer
set.seed(0) r <- rast(nrows=10, ncols=10) values(r) <- sample(3, ncell(r), replace=TRUE) + 10 d <- data.frame(id=11:13, cover=c("forest", "water", "urban"), letters=letters[1:3], value=10:12) levels(r) <- d activeCat(r) activeCat(r) <- 3 activeCat(r)
set.seed(0) r <- rast(nrows=10, ncols=10) values(r) <- sample(3, ncell(r), replace=TRUE) + 10 d <- data.frame(id=11:13, cover=c("forest", "water", "urban"), letters=letters[1:3], value=10:12) levels(r) <- d activeCat(r) activeCat(r) <- 3 activeCat(r)
Add (in place) a SpatRaster to another SpatRaster. Comparable with c
, but without copying the object.
## S4 replacement method for signature 'SpatRaster,SpatRaster' add(x)<-value ## S4 replacement method for signature 'SpatRasterDataset,SpatRaster' add(x)<-value ## S4 replacement method for signature 'SpatRasterCollection,SpatRaster' add(x)<-value
## S4 replacement method for signature 'SpatRaster,SpatRaster' add(x)<-value ## S4 replacement method for signature 'SpatRasterDataset,SpatRaster' add(x)<-value ## S4 replacement method for signature 'SpatRasterCollection,SpatRaster' add(x)<-value
x |
SpatRaster, SpatRasterDataset or SpatRasterCollection |
value |
SpatRaster |
SpatRaster
r <- rast(nrows=5, ncols=9, vals=1:45) x <- c(r, r*2) add(x) <- r*3 x
r <- rast(nrows=5, ncols=9, vals=1:45) x <- c(r, r*2) add(x) <- r*3 x
Similar to box
allowing adding a box around a map. This function will place the box around the mapped area.
add_box(...)
add_box(...)
... |
arguments passed to |
add_legend
, add_grid
, add_mtext
v <- vect(system.file("ex/lux.shp", package="terra")) plot(v) add_box(col="red", lwd=3, xpd=TRUE)
v <- vect(system.file("ex/lux.shp", package="terra")) plot(v) add_box(col="red", lwd=3, xpd=TRUE)
Adaptation of grid
that allows adding a grid to a map. This function will place the legend in the locations within the mapped area as delineated by the axes.
Also see graticule
add_grid(nx=NULL, ny=nx, col="lightgray", lty="dotted", lwd=1)
add_grid(nx=NULL, ny=nx, col="lightgray", lty="dotted", lwd=1)
nx , ny
|
number of cells of the grid in x and y direction. When NULL, as per default, the grid aligns with the tick marks on the corresponding default axis (i.e., tickmarks as computed by axTicks). When NA, no grid lines are drawn in the corresponding direction |
col |
character or (integer) numeric; color of the grid lines |
lty |
character or (integer) numeric; line type of the grid lines |
lwd |
non-negative numeric giving line width of the grid lines |
graticule
, add_legend
, add_box
, add_grid
, add_mtext
v <- vect(system.file("ex/lux.shp", package="terra")) plot(v) add_grid()
v <- vect(system.file("ex/lux.shp", package="terra")) plot(v) add_grid()
Wrapper around legend
that allows adding a custom legend to a map using a keyword such as "topleft" or "bottomright". This function will place the legend in the locations within the mapped area as delineated by the axes.
add_legend(x, y, ...)
add_legend(x, y, ...)
x |
The keyword to be used to position the legend (or the x coordinate) |
y |
The y coordinate to be used to position the legend (is x is also a coordinate) |
... |
arguments passed to |
v <- vect(system.file("ex/lux.shp", package="terra")) plot(v) points(centroids(v), col="red") legend("topleft", legend = "centroids", pch = 20, xpd=NA, bg="white", col="red") add_legend("topright", legend = "centroids", pch = 20, col="red")
v <- vect(system.file("ex/lux.shp", package="terra")) plot(v) points(centroids(v), col="red") legend("topleft", legend = "centroids", pch = 20, xpd=NA, bg="white", col="red") add_legend("topright", legend = "centroids", pch = 20, col="red")
Similar to mtext
allowing adding a text to the margins of a map. This function useds the margins around the mapped area; not the margins that R would use.
add_mtext(text, side=3, line=0, ...)
add_mtext(text, side=3, line=0, ...)
text |
character or expression vector specifying the text to be written |
side |
integer indicating the margin to use (1=bottom, 2=left, 3=top, 4=right) |
line |
numeric to move the text in or outwards. |
... |
arguments passed to |
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) plot(r, axes=FALSE, legend=FALSE) add_box() for (i in 1:4) add_mtext("margin text", i, cex=i, col=i, line=2-i)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) plot(r, axes=FALSE, legend=FALSE) add_box() for (i in 1:4) add_mtext("margin text", i, cex=i, col=i, line=2-i)
Identify cells that are adjacent to a set of raster cells. Or identify adjacent polygons
## S4 method for signature 'SpatRaster' adjacent(x, cells, directions="rook", pairs=FALSE, include=FALSE, symmetrical=FALSE) ## S4 method for signature 'SpatVector' adjacent(x, type="rook", pairs=TRUE, symmetrical=FALSE)
## S4 method for signature 'SpatRaster' adjacent(x, cells, directions="rook", pairs=FALSE, include=FALSE, symmetrical=FALSE) ## S4 method for signature 'SpatVector' adjacent(x, type="rook", pairs=TRUE, symmetrical=FALSE)
x |
SpatRaster |
cells |
vector of cell numbers for which adjacent cells should be found. Cell numbers start with 1 in the upper-left corner and increase from left to right and from top to bottom |
directions |
character or matrix to indicated the directions in which cells are considered connected. The following character values are allowed: "rook" or "4" for the horizontal and vertical neighbors; "bishop" to get the diagonal neighbors; "queen" or "8" to get the vertical, horizontal and diagonal neighbors; or "16" for knight and one-cell queen move neighbors. If |
pairs |
logical. If |
include |
logical. Should the focal cells be included in the result? |
type |
character. One of "rook", "queen", "touches", or "intersects". "queen" and "touches" are synonyms. "rook" exclude polygons that touch at a single node only. "intersects" includes polygons that touch or overlap |
symmetrical |
logical. If |
matrix
When using global lon/lat rasters, adjacent cells at the other side of the date-line are included.
r <- rast(nrows=10, ncols=10) adjacent(r, cells=c(1, 5, 55), directions="queen") r <- rast(nrows=10, ncols=10, crs="+proj=utm +zone=1 +datum=WGS84") adjacent(r, cells=11, directions="rook") #same as rk <- matrix(c(0,1,0,1,0,1,0,1,0), 3, 3) adjacent(r, cells=11, directions=rk) ## note that with global lat/lon data the E and W connect r <- rast(nrows=10, ncols=10, crs="+proj=longlat +datum=WGS84") adjacent(r, cells=11, directions="rook") f <- system.file("ex/lux.shp", package="terra") v <- vect(f) a <- adjacent(v, symmetrical=TRUE) head(a)
r <- rast(nrows=10, ncols=10) adjacent(r, cells=c(1, 5, 55), directions="queen") r <- rast(nrows=10, ncols=10, crs="+proj=utm +zone=1 +datum=WGS84") adjacent(r, cells=11, directions="rook") #same as rk <- matrix(c(0,1,0,1,0,1,0,1,0), 3, 3) adjacent(r, cells=11, directions=rk) ## note that with global lat/lon data the E and W connect r <- rast(nrows=10, ncols=10, crs="+proj=longlat +datum=WGS84") adjacent(r, cells=11, directions="rook") f <- system.file("ex/lux.shp", package="terra") v <- vect(f) a <- adjacent(v, symmetrical=TRUE) head(a)
Aggregate a SpatRaster to create a new SpatRaster with a lower resolution (larger cells). Aggregation groups rectangular areas to create larger cells. The value for the resulting cells is computed with a user-specified function.
You can also aggregate ("dissolve") a SpatVector. This either combines all geometries into one geometry, or it combines the geometries that have the same value for the variable(s) specified with argument by
.
## S4 method for signature 'SpatRaster' aggregate(x, fact=2, fun="mean", ..., cores=1, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatVector' aggregate(x, by=NULL, dissolve=TRUE, fun="mean", count=TRUE, ...)
## S4 method for signature 'SpatRaster' aggregate(x, fact=2, fun="mean", ..., cores=1, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatVector' aggregate(x, by=NULL, dissolve=TRUE, fun="mean", count=TRUE, ...)
x |
SpatRaster |
fact |
positive integer. Aggregation factor expressed as number of cells in each direction (horizontally and vertically). Or two integers (horizontal and vertical aggregation factor) or three integers (when also aggregating over layers) |
fun |
function used to aggregate values. Either an actual function, or for the following, their name: "mean", "max", "min", "median", "sum", "modal", "any", "all", "prod", "which.min", "which.max", "sd" (sample standard deviation) and "std" (population standard deviation) |
... |
additional arguments passed to |
cores |
positive integer. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
by |
character. The variable(s) used to group the geometries |
dissolve |
logical. Should borders between aggregated geometries be dissolved? |
count |
logical. If |
Aggregation starts at the upper-left end of a SpatRaster. If a division of the number of columns or rows with factor
does not return an integer, the extent of the resulting SpatRaster will be somewhat larger then that of the original SpatRaster. For example, if an input SpatRaster has 100 columns, and fact=12
, the output SpatRaster will have 9 columns and the maximum x coordinate of the output SpatRaster is also adjusted.
The function fun
should take multiple numbers, and return a single number. For example mean
, modal
, min
or max
.
It should also accept a na.rm
argument (or ignore it as one of the 'dots' arguments).
SpatRaster
disagg
to disaggregate
r <- rast() # aggregated SpatRaster, no values ra <- aggregate(r, fact=10) values(r) <- runif(ncell(r)) # aggregated raster, max of the values ra <- aggregate(r, fact=10, fun=max) # multiple layers s <- c(r, r*2) x <- aggregate(s, 20) ## SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) va <- aggregate(v, "ID_1") plot(va, "NAME_1", lwd=5, plg=list(x="topright"), mar=rep(2,4)) lines(v, lwd=3, col="light gray") lines(va) text(v, "ID_1", halo=TRUE)
r <- rast() # aggregated SpatRaster, no values ra <- aggregate(r, fact=10) values(r) <- runif(ncell(r)) # aggregated raster, max of the values ra <- aggregate(r, fact=10, fun=max) # multiple layers s <- c(r, r*2) x <- aggregate(s, 20) ## SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) va <- aggregate(v, "ID_1") plot(va, "NAME_1", lwd=5, plg=list(x="topright"), mar=rep(2,4)) lines(v, lwd=3, col="light gray") lines(va) text(v, "ID_1", halo=TRUE)
Align an SpatExtent with a SpatRaster This can be useful to create a new SpatRaster with the same origin and resolution as an existing SpatRaster. Do not use this to force data to match that really does not match (use e.g. resample
or (dis)aggregate for this).
It is also possible to align a SpatExtent to a clean divisor.
## S4 method for signature 'SpatExtent,SpatRaster' align(x, y, snap="near") ## S4 method for signature 'SpatExtent,numeric' align(x, y)
## S4 method for signature 'SpatExtent,SpatRaster' align(x, y, snap="near") ## S4 method for signature 'SpatExtent,numeric' align(x, y)
x |
SpatExtent |
y |
SpatRaster or numeric |
snap |
Character. One of "near", "in", or "out", to determine in which direction the extent should be aligned. To the nearest border, inwards or outwards |
SpatExtent
r <- rast() e <- ext(-10.1, 9.9, -20.1, 19.9) ea <- align(e, r) e ext(r) ea align(e, 0.5)
r <- rast() e <- ext(-10.1, 9.9, -20.1, 19.9) ea <- align(e, r) e ext(r) ea align(e, 0.5)
Compare two SpatRasters for (near) equality.
First the attributes of the objects are compared. If these are the same, a (perhaps small) sample of the raster cells is compared as well.
The sample size used can be increased with the maxcell
argument. You can set it to Inf
, but for large rasters your computer may not have sufficient memory. See the examples for a safe way to compare all values.
## S4 method for signature 'SpatRaster,SpatRaster' all.equal(target, current, maxcell=100000, ...)
## S4 method for signature 'SpatRaster,SpatRaster' all.equal(target, current, maxcell=100000, ...)
target |
SpatRaster |
current |
SpatRaster |
maxcell |
positive integer. The size of the regular sample used to compare cell values |
... |
additional arguments passed to |
Either TRUE
or a character vector describing the differences between target and current.
x <- sqrt(1:100) mat <- matrix(x, 10, 10) r1 <- rast(nrows=10, ncols=10, xmin=0, vals = x) r2 <- rast(nrows=10, ncols=10, xmin=0, vals = mat) all.equal(r1, r2) all.equal(r1, r1*1) all.equal(rast(r1), rast(r2)) # compare geometries compareGeom(r1, r2) # Compare all cell values for near equality # as floating point number imprecision can be a problem m <- minmax(r1 - r2) all(abs(m) < 1e-7) # comparison of cell values to create new SpatRaster e <- r1 == r2
x <- sqrt(1:100) mat <- matrix(x, 10, 10) r1 <- rast(nrows=10, ncols=10, xmin=0, vals = x) r2 <- rast(nrows=10, ncols=10, xmin=0, vals = mat) all.equal(r1, r2) all.equal(r1, r1*1) all.equal(rast(r1), rast(r2)) # compare geometries compareGeom(r1, r2) # Compare all cell values for near equality # as floating point number imprecision can be a problem m <- minmax(r1 - r2) all(abs(m) < 1e-7) # comparison of cell values to create new SpatRaster e <- r1 == r2
Animate (sequentially plot) the layers of a SpatRaster to create a movie.
This does not work with R-Studio.
## S4 method for signature 'SpatRaster' animate(x, pause=0.25, main, range, maxcell=50000, n=1, ...)
## S4 method for signature 'SpatRaster' animate(x, pause=0.25, main, range, maxcell=50000, n=1, ...)
x |
SpatRaster |
pause |
numeric. How long should be the pause be between layers? |
main |
title for each layer. If not supplied the z-value is used if available. Otherwise the names are used. |
range |
numeric vector of length 2. Range of values to plot |
maxcell |
positive integer. Maximum number of cells to use for the plot. If |
n |
integer > 0. Number of loops |
... |
Additional arguments passed to |
None
s <- rast(system.file("ex/logo.tif", package="terra")) animate(s, n=1)
s <- rast(system.file("ex/logo.tif", package="terra")) animate(s, n=1)
Apply a function to the values of each cell of a SpatRaster. Similar to apply
– think of each layer in a SpatRaster as a column (or row) in a matrix.
This is generally used to summarize the values of multiple layers into one layer; but this is not required.
app
calls function fun
with the raster data as first argument. Depending on the function supplied, the raster data is represented as either a matrix in which each layer is a column, or a vector representing a cell. The function should return a vector or matrix that is divisible by ncell(x). Thus, both "sum" and "rowSums" can be used, but "colSums" cannot be used.
You can also apply a function fun
across datasets by layer of a SpatRasterDataset
. In that case, summarization is by layer across SpatRasters.
## S4 method for signature 'SpatRaster' app(x, fun, ..., cores=1, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterDataset' app(x, fun, ..., cores=1, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' app(x, fun, ..., cores=1, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterDataset' app(x, fun, ..., cores=1, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster or SpatRasterDataset |
fun |
a function that operates on a vector or matrix. This can be a function that is defined in base-R or in a package, or a function you write yourself (see examples). Functions that return complex output (e.g. a list) may need to be wrapped in your own function to simplify the output to a vector or matrix. The following functions have been re-implemented in C++ for speed: "sum", "mean", "median", "modal", "which", "which.min", "which.max", "min", "max", "prod", "any", "all", "sd", "std", "first". To use the base-R function for say, "min", you could use something like |
... |
additional arguments for |
cores |
positive integer. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
To speed things up, parallelization is supported, but this is often not helpful, and it may actually be slower. There is only a speed gain if you have many cores (> 8) and/or a very complex (slow) function fun
. If you write fun
yourself, consider supplying a cppFunction
made with the Rcpp package instead (or go have a cup of tea while the computer works for you).
SpatRaster
lapp
, tapp
, Math-methods
, roll
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) x <- c(r, sqrt(r), r+50) s <- app(x, fun=sum) s # for a few generic functions like # "sum", "mean", and "max" you can also do sum(x) ## SpatRasterDataset sd <- sds(x, x*2, x/3) a <- app(sd, max) a # same as max(x, x*2, x/3) # and as (but slower) b <- app(sd, function(i) max(i)) ## also works for a single layer f <- function(i) (i+1) * 2 * i + sqrt(i) s <- app(r, f) # same as above, but that is not memory-safe # and has no filename argument s <- f(r) ## Not run: #### multiple cores test0 <- app(x, sqrt) test1 <- app(x, sqrt, cores=2) testfun <- function(i) { 2 * sqrt(i) } test2 <- app(x, fun=testfun, cores =2) ## this fails because testfun is not exported to the nodes # test3 <- app(x, fun=function(i) testfun(i), cores=2) ## to export it, add it as argument to fun test3 <- app(x, fun=function(i, ff) ff(i), cores =3, ff=testfun) ## End(Not run)
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) x <- c(r, sqrt(r), r+50) s <- app(x, fun=sum) s # for a few generic functions like # "sum", "mean", and "max" you can also do sum(x) ## SpatRasterDataset sd <- sds(x, x*2, x/3) a <- app(sd, max) a # same as max(x, x*2, x/3) # and as (but slower) b <- app(sd, function(i) max(i)) ## also works for a single layer f <- function(i) (i+1) * 2 * i + sqrt(i) s <- app(r, f) # same as above, but that is not memory-safe # and has no filename argument s <- f(r) ## Not run: #### multiple cores test0 <- app(x, sqrt) test1 <- app(x, sqrt, cores=2) testfun <- function(i) { 2 * sqrt(i) } test2 <- app(x, fun=testfun, cores =2) ## this fails because testfun is not exported to the nodes # test3 <- app(x, fun=function(i) testfun(i), cores=2) ## to export it, add it as argument to fun test3 <- app(x, fun=function(i, ff) ff(i), cores =3, ff=testfun) ## End(Not run)
NA
by interpolating between layersapproximate uses the stats
function approx
to estimate values for cells that are NA
by interpolation across layers. Layers are considered equidistant, unless argument z
is used, or time(x)
returns values that are not NA
, in which case these values are used to determine distance between layers.
For estimation based on neighboring cells see focal
## S4 method for signature 'SpatRaster' approximate(x, method="linear", yleft, yright, rule=1, f=0, ties=mean, z=NULL, NArule=1,filename="", ...)
## S4 method for signature 'SpatRaster' approximate(x, method="linear", yleft, yright, rule=1, f=0, ties=mean, z=NULL, NArule=1,filename="", ...)
x |
SpatRaster |
method |
specifies the interpolation method to be used. Choices are "linear" or "constant" (step function; see the example in |
yleft |
the value to be returned before a non- |
yright |
the value to be returned after the last non- |
rule |
an integer (of length 1 or 2) describing how interpolation is to take place at for the first and last cells (before or after any non- |
f |
for method = "constant" a number between 0 and 1 inclusive, indicating a compromise between left- and right-continuous step functions. If y0 and y1 are the values to the left and right of the point then the value is |
ties |
Handling of tied 'z' values. Either a function with a single vector argument returning a single number result or the string "ordered" |
z |
numeric vector to indicate the distance between layers (e.g., depth). The default is |
NArule |
single integer used to determine what to do when only a single layer with a non- |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(ncols=5, nrows=5) r1 <- setValues(r, runif(ncell(r))) r2 <- setValues(r, runif(ncell(r))) r3 <- setValues(r, runif(ncell(r))) r4 <- setValues(r, runif(ncell(r))) r5 <- setValues(r, NA) r6 <- setValues(r, runif(ncell(r))) r1[6:10] <- NA r2[5:15] <- NA r3[8:25] <- NA s <- c(r1,r2,r3,r4,r5,r6) s[1:5] <- NA x1 <- approximate(s) x2 <- approximate(s, rule=2) x3 <- approximate(s, rule=2, z=c(1,2,3,5,14,15))
r <- rast(ncols=5, nrows=5) r1 <- setValues(r, runif(ncell(r))) r2 <- setValues(r, runif(ncell(r))) r3 <- setValues(r, runif(ncell(r))) r4 <- setValues(r, runif(ncell(r))) r5 <- setValues(r, NA) r6 <- setValues(r, runif(ncell(r))) r1[6:10] <- NA r2[5:15] <- NA r3[8:25] <- NA s <- c(r1,r2,r3,r4,r5,r6) s[1:5] <- NA x1 <- approximate(s) x2 <- approximate(s, rule=2) x3 <- approximate(s, rule=2, z=c(1,2,3,5,14,15))
Standard arithmetic operators for computations with SpatRasters. Computations are local (applied on a cell by cell basis). If multiple SpatRasters are used, these must have the same geometry (extent and resolution). These operators have been implemented:
+, -, *, /, ^, %%, %/%
You can also use a SpatRaster and a vector or a matrix. If you use a SpatRaster with a vector of multiple numbers, each element in the vector is considered a layer (with a constant value). If you use a SpatRaster with a matrix, the number of columns of the matrix must match the number of layers of the SpatRaster. The rows are used to match the cells. That is, if there are two rows, these match cells 1 and 2, and they are recycled to 3 and 4, etc.
The following methods have been implemented for (SpatExtent, SpatExtent)
: +, -
, and the following for (SpatExtent, numeric)
: +, -, *, /, %%
SpatRaster or SpatExtent
ifel
to conveniently combine operations and Math-methods
or app
to use mathematical functions not implemented by the package.
r1 <- rast(ncols=10, nrows=10) v <- runif(ncell(r1)) v[10:20] <- NA values(r1) <- v r2 <- rast(r1) values(r2) <- 1:ncell(r2) / ncell(r2) r3 <- r1 + r2 r2 <- r1 / 10 r3 <- r1 * (r2 - 1 / r2) b <- c(r1, r2, r3) b2 <- b * 10 ### SpatExtent methods x <- ext(0.1, 2.2, 0, 3) y <- ext(-2, 1, -2,2) # union x + y # intersection x * y e <- x e e * 2 e / 2 e + 1 e - 1
r1 <- rast(ncols=10, nrows=10) v <- runif(ncell(r1)) v[10:20] <- NA values(r1) <- v r2 <- rast(r1) values(r2) <- 1:ncell(r2) / ncell(r2) r3 <- r1 + r2 r2 <- r1 / 10 r3 <- r1 * (r2 - 1 / r2) b <- c(r1, r2, r3) b2 <- b * 10 ### SpatExtent methods x <- ext(0.1, 2.2, 0, 3) y <- ext(-2, 1, -2,2) # union x + y # intersection x * y e <- x e e * 2 e / 2 e + 1 e - 1
Create a text representation of (the skeleton of) an object
## S4 method for signature 'SpatExtent' as.character(x) ## S4 method for signature 'SpatRaster' as.character(x)
## S4 method for signature 'SpatExtent' as.character(x) ## S4 method for signature 'SpatRaster' as.character(x)
x |
SpatRaster |
character
r <- rast() ext(r) ext(c(0, 20, 0, 20))
r <- rast() ext(r) ext(c(0, 20, 0, 20))
Coerce a SpatRaster or SpatVector to a data.frame
## S4 method for signature 'SpatVector' as.data.frame(x, row.names=NULL, optional=FALSE, geom=NULL, ...) ## S4 method for signature 'SpatRaster' as.data.frame(x, row.names=NULL, optional=FALSE, xy=FALSE, cells=FALSE, time=FALSE, na.rm=NA, wide=TRUE, ...)
## S4 method for signature 'SpatVector' as.data.frame(x, row.names=NULL, optional=FALSE, geom=NULL, ...) ## S4 method for signature 'SpatRaster' as.data.frame(x, row.names=NULL, optional=FALSE, xy=FALSE, cells=FALSE, time=FALSE, na.rm=NA, wide=TRUE, ...)
x |
SpatRaster or SpatVector |
geom |
character or NULL. If not NULL, either "WKT" or "HEX", to get the geometry included in Well-Known-Text or hexadecimal notation. If |
xy |
logical. If |
time |
logical. If |
na.rm |
logical. If |
cells |
logical. If |
wide |
logical. If |
... |
Additional arguments passed to the |
row.names |
This argument is ignored |
optional |
This argument is ignored |
data.frame
as.list, as.matrix
. See geom
to only extract the geometry of a SpatVector
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) as.data.frame(v)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) as.data.frame(v)
Conversion of a SpatRaster, SpatVector or SpatExtent to a SpatVector of lines.
## S4 method for signature 'SpatRaster' as.lines(x) ## S4 method for signature 'SpatVector' as.lines(x) ## S4 method for signature 'SpatExtent' as.lines(x, crs="")
## S4 method for signature 'SpatRaster' as.lines(x) ## S4 method for signature 'SpatVector' as.lines(x) ## S4 method for signature 'SpatExtent' as.lines(x, crs="")
x |
SpatRaster, SpatVector or SpatExtent |
crs |
character. The coordinate reference system (see |
SpatVector
r <- rast(ncols=2, nrows=2) values(r) <- 1:ncell(r) as.lines(r) as.lines(ext(r), crs=crs(r)) if (gdal() >= "3.0.0") { p <- as.polygons(r) as.lines(p) }
r <- rast(ncols=2, nrows=2) values(r) <- 1:ncell(r) as.lines(r) as.lines(ext(r), crs=crs(r)) if (gdal() >= "3.0.0") { p <- as.polygons(r) as.lines(p) }
Coerce a SpatRaster, SpatRasterCollection, SpatRasterDataset, SpatVector or SpatVectorCollection to a list. With a SpatRaster, each layer becomes a list element. With a SpatRasterCollection or SpatRasterDataset, each SpatRaster becomes a list element. With a SpatVector, each variable (attribute) becomes a list element. With a SpatVectorCollection, each SpatVector becomes a list element.
## S4 method for signature 'SpatRaster' as.list(x, geom=NULL, ...) ## S4 method for signature 'SpatRasterCollection' as.list(x, ...) ## S4 method for signature 'SpatVector' as.list(x, geom=NULL, ...) ## S4 method for signature 'SpatVectorCollection' as.list(x, ...)
## S4 method for signature 'SpatRaster' as.list(x, geom=NULL, ...) ## S4 method for signature 'SpatRasterCollection' as.list(x, ...) ## S4 method for signature 'SpatVector' as.list(x, geom=NULL, ...) ## S4 method for signature 'SpatVectorCollection' as.list(x, ...)
x |
SpatRaster, SpatRasterDataset, SpatRasterCollection, or SpatVector |
geom |
character or NULL. If not NULL, and |
... |
additional arguments. These are ignored |
list
see coerce
for as.data.frame
with a SpatRaster; and geom
to only extract the geometry of a SpatVector
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) as.list(v) s <- rast(system.file("ex/logo.tif", package="terra")) + 1 as.list(s)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) as.list(v) s <- rast(system.file("ex/logo.tif", package="terra")) + 1 as.list(s)
Conversion of a SpatRaster, SpatVector or SpatExtent to a SpatVector of points.
## S4 method for signature 'SpatRaster' as.points(x, values=TRUE, na.rm=TRUE, na.all=FALSE) ## S4 method for signature 'SpatVector' as.points(x, multi=FALSE, skiplast=TRUE) ## S4 method for signature 'SpatExtent' as.points(x, crs="")
## S4 method for signature 'SpatRaster' as.points(x, values=TRUE, na.rm=TRUE, na.all=FALSE) ## S4 method for signature 'SpatVector' as.points(x, multi=FALSE, skiplast=TRUE) ## S4 method for signature 'SpatExtent' as.points(x, crs="")
x |
SpatRaster, SpatVector or SpatExtent |
values |
logical; include cell values as attributes? |
multi |
logical. If |
skiplast |
logical. If |
na.rm |
logical. If |
na.all |
logical. If |
crs |
character. The coordinate reference system (see |
SpatVector
r <- rast(ncols=2, nrows=2) values(r) <- 1:ncell(r) as.points(r) if (gdal() >= "3.0.0") { p <- as.polygons(r) as.points(p) }
r <- rast(ncols=2, nrows=2) values(r) <- 1:ncell(r) as.points(r) if (gdal() >= "3.0.0") { p <- as.polygons(r) as.points(p) }
Conversion of a SpatRaster, SpatVector or SpatExtent to a SpatVector of polygons.
## S4 method for signature 'SpatRaster' as.polygons(x, round=TRUE, aggregate=TRUE, values=TRUE, na.rm=TRUE, na.all=FALSE, extent=FALSE, digits=0, ...) ## S4 method for signature 'SpatVector' as.polygons(x, extent=FALSE) ## S4 method for signature 'SpatExtent' as.polygons(x, crs="")
## S4 method for signature 'SpatRaster' as.polygons(x, round=TRUE, aggregate=TRUE, values=TRUE, na.rm=TRUE, na.all=FALSE, extent=FALSE, digits=0, ...) ## S4 method for signature 'SpatVector' as.polygons(x, extent=FALSE) ## S4 method for signature 'SpatExtent' as.polygons(x, crs="")
x |
SpatRaster, SpatVector or SpatExtent |
round |
logical; If |
aggregate |
logical; combine cells with the same values? If |
values |
logical; include cell values as attributes? |
extent |
logical. if |
na.rm |
logical. If |
na.all |
logical. If |
digits |
integer. The number of digits for rounding (if |
crs |
character. The coordinate reference system (see |
... |
additional arguments. For backward compatibility. Will be removed in the future |
SpatVector
r <- rast(ncols=2, nrows=2) values(r) <- 1:ncell(r) if (gdal() >= "3.0.0") { p <- as.polygons(r) p }
r <- rast(ncols=2, nrows=2) values(r) <- 1:ncell(r) if (gdal() >= "3.0.0") { p <- as.polygons(r) p }
Implementation of the generic as.raster
function to create a "raster" (small r) object. Such objects can be used for plotting with the rasterImage
function. NOT TO BE CONFUSED with the Raster* (big R) objects defined by the 'raster' package!
## S4 method for signature 'SpatRaster' as.raster(x, maxcell=500000, col)
## S4 method for signature 'SpatRaster' as.raster(x, maxcell=500000, col)
x |
SpatRaster |
maxcell |
positive integer. Maximum number of cells to use for the plot |
col |
vector of colors. The default is |
'raster' object
r <- rast(ncols=3, nrows=3) values(r) <- 1:ncell(r) as.raster(r)
r <- rast(ncols=3, nrows=3) values(r) <- 1:ncell(r) as.raster(r)
For SpatRasters x and y, atan2(y, x) returns the angle in radians for the tangent y/x, handling the case when x is zero. See Trig
See Math-methods
for other trigonometric and mathematical functions that can be used with SpatRasters.
## S4 method for signature 'SpatRaster,SpatRaster' atan2(y, x) ## S4 method for signature 'SpatRaster,SpatRaster' atan_2(y, x, filename, ...)
## S4 method for signature 'SpatRaster,SpatRaster' atan2(y, x) ## S4 method for signature 'SpatRaster,SpatRaster' atan_2(y, x, filename, ...)
y |
SpatRaster |
x |
SpatRaster |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
r1 <- rast(nrows=10, ncols=10) r2 <- rast(nrows=10, ncols=10) values(r1) <- (runif(ncell(r1))-0.5) * 10 values(r2) <- (runif(ncell(r1))-0.5) * 10 atan2(r1, r2)
r1 <- rast(nrows=10, ncols=10) r2 <- rast(nrows=10, ncols=10) values(r1) <- (runif(ncell(r1))-0.5) * 10 values(r2) <- (runif(ncell(r1))-0.5) * 10 atan2(r1, r2)
Compute spatial autocorrelation for a numeric vector or a SpatRaster. You can compute standard (global) Moran's I or Geary's C, or local indicators of spatial autocorrelation (Anselin, 1995).
## S4 method for signature 'numeric' autocor(x, w, method="moran") ## S4 method for signature 'SpatRaster' autocor(x, w=matrix(c(1,1,1,1,0,1,1,1,1),3), method="moran", global=TRUE)
## S4 method for signature 'numeric' autocor(x, w, method="moran") ## S4 method for signature 'SpatRaster' autocor(x, w=matrix(c(1,1,1,1,0,1,1,1,1),3), method="moran", global=TRUE)
x |
numeric or SpatRaster |
w |
Spatial weights defined by or a rectangular matrix. For a SpatRaster this matrix must the sides must have an odd length (3, 5, ...) |
global |
logical. If |
method |
character. If |
The default setting uses a 3x3 neighborhood to compute "Queen's case" indices. You can use a filter (weights matrix) to do other things, such as "Rook's case", or different lags.
numeric or SpatRaster
Moran, P.A.P., 1950. Notes on continuous stochastic phenomena. Biometrika 37:17-23
Geary, R.C., 1954. The contiguity ratio and statistical mapping. The Incorporated Statistician 5: 115-145
Anselin, L., 1995. Local indicators of spatial association-LISA. Geographical Analysis 27:93-115
https://en.wikipedia.org/wiki/Indicators_of_spatial_association
The spdep
package for additional and more general approaches for computing spatial autocorrelation
### raster r <- rast(nrows=10, ncols=10, xmin=0) values(r) <- 1:ncell(r) autocor(r) # rook's case neighbors f <- matrix(c(0,1,0,1,0,1,0,1,0), nrow=3) autocor(r, f) # local rc <- autocor(r, w=f, global=FALSE) ### numeric (for vector data) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) w <- relate(v, relation="touches") # global autocor(v$AREA, w) # local v$Gi <- autocor(v$AREA, w, "Gi") plot(v, "Gi")
### raster r <- rast(nrows=10, ncols=10, xmin=0) values(r) <- 1:ncell(r) autocor(r) # rook's case neighbors f <- matrix(c(0,1,0,1,0,1,0,1,0), nrow=3) autocor(r, f) # local rc <- autocor(r, w=f, global=FALSE) ### numeric (for vector data) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) w <- relate(v, relation="touches") # global autocor(v$AREA, w) # local v$Gi <- autocor(v$AREA, w, "Gi") plot(v, "Gi")
Create a barplot of the values of the first layer of a SpatRaster. For large datasets a regular sample with a size of approximately maxcells
is used.
## S4 method for signature 'SpatRaster' barplot(height, maxcell=1000000, digits=0, breaks=NULL, col, ...)
## S4 method for signature 'SpatRaster' barplot(height, maxcell=1000000, digits=0, breaks=NULL, col, ...)
height |
SpatRaster |
maxcell |
integer. To regularly subsample very large datasets |
digits |
integer used to determine how to |
breaks |
breaks used to group the data as in |
col |
a color generating function such as |
... |
additional arguments for plotting as in |
A numeric vector (or matrix, when beside = TRUE
) of the coordinates of the bar midpoints, useful for adding to the graph. See barplot
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) barplot(r, digits=-1, las=2, ylab="Frequency") op <- par(no.readonly = TRUE) par(mai = c(1, 2, .5, .5)) barplot(r, breaks=10, col=c("red", "blue"), horiz=TRUE, digits=NULL, las=1) par(op)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) barplot(r, digits=-1, las=2, ylab="Frequency") op <- par(no.readonly = TRUE) par(mai = c(1, 2, .5, .5)) barplot(r, breaks=10, col=c("red", "blue"), horiz=TRUE, digits=NULL, las=1) par(op)
Determine for each grid cell which reference it is most similar to. A reference consists of a SpatVector with reference locations, or a data.frame in which each column matches a layer name in the SpatRaster.
Similarity is computed with the sum of squared differences between the cell and the reference. It may be important to first scale the input.
## S4 method for signature 'SpatRaster,SpatVector' bestMatch(x, y, labels="", filename="", ...) ## S4 method for signature 'SpatRaster,data.frame' bestMatch(x, y, labels="", filename="", ...)
## S4 method for signature 'SpatRaster,SpatVector' bestMatch(x, y, labels="", filename="", ...) ## S4 method for signature 'SpatRaster,data.frame' bestMatch(x, y, labels="", filename="", ...)
x |
SpatRaster |
y |
SpatVector or data.frame |
labels |
character. labels that correspond to each class (row in |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
f <- system.file("ex/logo.tif", package = "terra") r <- rast(f) # locations of interest pts <- vect(cbind(c(25.25, 34.324, 43.003), c(54.577, 46.489, 30.905))) pts$code <- LETTERS[1:3] plot(r) points(pts, pch=20, cex=2, col="red") text(pts, "code", pos=4, halo=TRUE) x <- scale(r) s1 <- bestMatch(x, pts, labels=pts$code) plot(s1) # same result e <- extract(x, pts, ID=FALSE) s2 <- bestMatch(x, e, labels=c("Ap", "Nt", "Ms"))
f <- system.file("ex/logo.tif", package = "terra") r <- rast(f) # locations of interest pts <- vect(cbind(c(25.25, 34.324, 43.003), c(54.577, 46.489, 30.905))) pts$code <- LETTERS[1:3] plot(r) points(pts, pch=20, cex=2, col="red") text(pts, "code", pos=4, halo=TRUE) x <- scale(r) s1 <- bestMatch(x, pts, labels=pts$code) plot(s1) # same result e <- extract(x, pts, ID=FALSE) s2 <- bestMatch(x, e, labels=c("Ap", "Nt", "Ms"))
Detect boundaries (edges). Boundaries are cells that have more than one class in the 4 or 8 cells surrounding it, or, if classes=FALSE
, cells with values and cells with NA
.
## S4 method for signature 'SpatRaster' boundaries(x, classes=FALSE, inner=TRUE, directions=8, falseval=0, filename="", ...)
## S4 method for signature 'SpatRaster' boundaries(x, classes=FALSE, inner=TRUE, directions=8, falseval=0, filename="", ...)
x |
SpatRaster |
inner |
logical. If |
classes |
character. Logical. If |
directions |
integer. Which cells are considered adjacent? Should be 8 (Queen's case) or 4 (Rook's case) |
falseval |
numeric. The value to use for cells that are not a boundary and not |
filename |
character. Output filename |
... |
options for writing files as in |
SpatRaster. Cell values are either 1 (a border) or 0 (not a border), or NA
r <- rast(nrows=18, ncols=36, xmin=0) r[150:250] <- 1 r[251:450] <- 2 bi <- boundaries(r) bo <- boundaries(r, inner=FALSE) bc <- boundaries(r, classes=TRUE) #plot(bc)
r <- rast(nrows=18, ncols=36, xmin=0) r[150:250] <- 1 r[251:450] <- 2 bi <- boundaries(r) bo <- boundaries(r, inner=FALSE) bc <- boundaries(r, classes=TRUE) #plot(bc)
Box plot of layers in a SpatRaster
## S4 method for signature 'SpatRaster' boxplot(x, y=NULL, maxcell=100000, ...)
## S4 method for signature 'SpatRaster' boxplot(x, y=NULL, maxcell=100000, ...)
x |
SpatRaster |
y |
NULL or a SpatRaster. If |
maxcell |
Integer. Number of cells to sample from datasets |
... |
additional arguments passed to |
boxplot returns a list (invisibly) that can be used with bxp
r1 <- r2 <- r3 <- rast(ncols=10, nrows=10) set.seed(409) values(r1) <- rnorm(ncell(r1), 100, 40) values(r2) <- rnorm(ncell(r1), 80, 10) values(r3) <- rnorm(ncell(r1), 120, 30) s <- c(r1, r2, r3) names(s) <- c("Apple", "Pear", "Cherry") boxplot(s, notch=TRUE, col=c("red", "blue", "orange"), main="Box plot", ylab="random", las=1) op <- par(no.readonly = TRUE) par(mar=c(4,6,2,2)) boxplot(s, horizontal=TRUE, col="lightskyblue", axes=FALSE) axis(1) axis(2, at=0:3, labels=c("", names(s)), las=1, cex.axis=.9, lty=0) par(op) ## boxplot with 2 layers v <- vect(system.file("ex/lux.shp", package="terra")) r <- rast(system.file("ex/elev.tif", package="terra")) y <- rasterize(v, r, "NAME_2") b <- boxplot(r, y) bxp(b)
r1 <- r2 <- r3 <- rast(ncols=10, nrows=10) set.seed(409) values(r1) <- rnorm(ncell(r1), 100, 40) values(r2) <- rnorm(ncell(r1), 80, 10) values(r3) <- rnorm(ncell(r1), 120, 30) s <- c(r1, r2, r3) names(s) <- c("Apple", "Pear", "Cherry") boxplot(s, notch=TRUE, col=c("red", "blue", "orange"), main="Box plot", ylab="random", las=1) op <- par(no.readonly = TRUE) par(mar=c(4,6,2,2)) boxplot(s, horizontal=TRUE, col="lightskyblue", axes=FALSE) axis(1) axis(2, at=0:3, labels=c("", names(s)), las=1, cex.axis=.9, lty=0) par(op) ## boxplot with 2 layers v <- vect(system.file("ex/lux.shp", package="terra")) r <- rast(system.file("ex/elev.tif", package="terra")) y <- rasterize(v, r, "NAME_2") b <- boxplot(r, y) bxp(b)
Calculate a buffer around all cells that are not NA
in a SpatRaster, or around the geometries of a SpatVector.
SpatRaster cells inside the buffer distance get a value of 1.
Note that the distance unit of the buffer width
parameter is meters if the CRS is (+proj=longlat
), and in map units (typically also meters) if not.
## S4 method for signature 'SpatRaster' buffer(x, width, background=0, filename="", ...) ## S4 method for signature 'SpatVector' buffer(x, width, quadsegs=10, capstyle="round", joinstyle="round", mitrelimit=NA, singlesided=FALSE)
## S4 method for signature 'SpatRaster' buffer(x, width, background=0, filename="", ...) ## S4 method for signature 'SpatVector' buffer(x, width, quadsegs=10, capstyle="round", joinstyle="round", mitrelimit=NA, singlesided=FALSE)
x |
SpatRaster or SpatVector |
width |
numeric. Unit is meter if |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
background |
numeric. value to assign to cells outside the buffer. If this value is zero or FALSE, a boolean SpatRaster is returned |
quadsegs |
positive integer. Number of line segments to use to draw a quart circle |
capstyle |
character. One of "round", "square" or "flat". Ignored if |
joinstyle |
character. One of "round", "mitre" or "bevel". Ignored if |
mitrelimit |
numeric. Place an upper bound on a mitre join to avoid it from extending very far from acute angles in the input geometry. Ignored if |
singlesided |
logical. If |
Same as x
r <- rast(ncols=36, nrows=18) r[500] <- 1 b <- buffer(r, width=5000000) plot(b) v <- vect(rbind(c(10,10), c(0,60)), crs="+proj=merc") b <- buffer(v, 20) plot(b) points(v) crs(v) <- "+proj=longlat" b <- buffer(v, 1500000) plot(b) points(v)
r <- rast(ncols=36, nrows=18) r[500] <- 1 b <- buffer(r, width=5000000) plot(b) v <- vect(rbind(c(10,10), c(0,60)), crs="+proj=merc") b <- buffer(v, 20) plot(b) points(v) crs(v) <- "+proj=longlat" b <- buffer(v, 1500000) plot(b) points(v)
With c
you can:
– Combine SpatRaster
objects. They must have the same extent and resolution. However, if x
is empty (has no cell values), its geometry is ignored with a warning. Two empty SpatRasters with the same geometry can also be combined (to get a summed number of layers). Also see add<-
– Add a SpatRaster
to a SpatRasterDataset
or SpatRasterCollection
– Add SpatVector
objects to a new or existing SpatVectorCollection
To append SpatVectors, use rbind
.
## S4 method for signature 'SpatRaster' c(x, ..., warn=TRUE) ## S4 method for signature 'SpatRasterDataset' c(x, ...) ## S4 method for signature 'SpatRasterCollection' c(x, ...) ## S4 method for signature 'SpatVector' c(x, ...) ## S4 method for signature 'SpatVectorCollection' c(x, ...)
## S4 method for signature 'SpatRaster' c(x, ..., warn=TRUE) ## S4 method for signature 'SpatRasterDataset' c(x, ...) ## S4 method for signature 'SpatRasterCollection' c(x, ...) ## S4 method for signature 'SpatVector' c(x, ...) ## S4 method for signature 'SpatVectorCollection' c(x, ...)
x |
SpatRaster, SpatVector, SpatRasterDataset or SpatVectorCollection |
warn |
logical. If |
... |
as for |
Same class as x
r <- rast(nrows=5, ncols=9) values(r) <- 1:ncell(r) x <- c(r, r*2, r*3)
r <- rast(nrows=5, ncols=9) values(r) <- 1:ncell(r) x <- c(r, r*2, r*3)
Make a cartogram, that is, a map where the area of polygons is made proportional to another variable. This can be a good way to map raw count data (e.g. votes).
## S4 method for signature 'SpatVector' cartogram(x, var, type)
## S4 method for signature 'SpatVector' cartogram(x, var, type)
x |
SpatVector |
var |
character. A variable name in |
type |
character. Cartogram type, only "nc" (non-contiguous) is currently supported |
SpatVector
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v$value <- 1:12 p <- cartogram(v, "value", "nc") plot(v, col="light gray", border="gray") lines(p, col="red", lwd=2)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v$value <- 1:12 p <- cartogram(v, "value", "nc") plot(v, col="light gray", border="gray") lines(p, col="red", lwd=2)
Change a categorical layer into one or more numerical layers. With as.numeric
you can transfer the active category values to cell values in a non-categorical SpatRaster. catalyze
creates new layers for each category.
## S4 method for signature 'SpatRaster' as.numeric(x, index=NULL, filename="", ...) ## S4 method for signature 'SpatRaster' catalyze(x, filename="", ...)
## S4 method for signature 'SpatRaster' as.numeric(x, index=NULL, filename="", ...) ## S4 method for signature 'SpatRaster' catalyze(x, filename="", ...)
x |
SpatRaster |
index |
positive integer or category indicating the category to use. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
set.seed(0) r <- rast(nrows=10, ncols=10) values(r) <- sample(3, ncell(r), replace=TRUE) + 10 d <- data.frame(id=11:13, cover=c("forest", "water", "urban"), letters=letters[1:3], value=10:12) levels(r) <- d catalyze(r) activeCat(r) <- 3 as.numeric(r)
set.seed(0) r <- rast(nrows=10, ncols=10) values(r) <- sample(3, ncell(r), replace=TRUE) + 10 d <- data.frame(id=11:13, cover=c("forest", "water", "urban"), letters=letters[1:3], value=10:12) levels(r) <- d catalyze(r) activeCat(r) <- 3 as.numeric(r)
Get the cell numbers covered by a SpatVector or SpatExtent. Or that match values in a vector; or all non NA
values.
## S4 method for signature 'SpatRaster,missing' cells(x, y) ## S4 method for signature 'SpatRaster,numeric' cells(x, y, pairs=FALSE) ## S4 method for signature 'SpatRaster,SpatVector' cells(x, y, method="simple", weights=FALSE, exact=FALSE, touches=is.lines(y), small=TRUE) ## S4 method for signature 'SpatRaster,SpatExtent' cells(x, y)
## S4 method for signature 'SpatRaster,missing' cells(x, y) ## S4 method for signature 'SpatRaster,numeric' cells(x, y, pairs=FALSE) ## S4 method for signature 'SpatRaster,SpatVector' cells(x, y, method="simple", weights=FALSE, exact=FALSE, touches=is.lines(y), small=TRUE) ## S4 method for signature 'SpatRaster,SpatExtent' cells(x, y)
x |
SpatRaster |
y |
SpatVector, SpatExtent, 2-column matrix representing points, numeric representing values to match, or missing |
method |
character. Method for getting cell numbers for points. The default is "simple", the alternative is "bilinear". If it is "bilinear", the four nearest cells and their weights are returned |
weights |
logical. If |
pairs |
logical. If |
exact |
logical. If |
touches |
logical. If |
small |
logical. If |
numeric vector or matrix
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) r[c(1:25, 31:100)] <- NA r <- ifel(r > 28, r + 10, r) # all cell numbers of cells that are not NA cells(r) # cell numbers that match values x <- cells(r, c(28,38)) x$lyr.1 # cells for points m <- cbind(x=c(0,10,-30), y=c(40,-10,20)) cellFromXY(r, m) v <- vect(m) cells(r, v) cells(r, v, method="bilinear") # cells for polygons f <- system.file("ex/lux.shp", package="terra") v <- vect(f) r <- rast(v) cv <- cells(r, v)
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) r[c(1:25, 31:100)] <- NA r <- ifel(r > 28, r + 10, r) # all cell numbers of cells that are not NA cells(r) # cell numbers that match values x <- cells(r, c(28,38)) x$lyr.1 # cells for points m <- cbind(x=c(0,10,-30), y=c(40,-10,20)) cellFromXY(r, m) v <- vect(m) cells(r, v) cells(r, v, method="bilinear") # cells for polygons f <- system.file("ex/lux.shp", package="terra") v <- vect(f) r <- rast(v) cv <- cells(r, v)
Compute the area covered by individual raster cells.
Computing the surface area of raster cells is especially relevant for longitude/latitude rasters.
But note that for both angular (longitude/latitude) and for planar (projected) coordinate reference systems raster cells sizes are generally not constant, unless you are using an equal-area coordinate reference system.
For planar CRSs, the area is therefore not computed based on the linear units of the coordinate reference system, but on the *actual* area by transforming cells to longitude/latitude. If you do not want that correction, you can use transform=FALSE
or init(x, prod(res(x)))
## S4 method for signature 'SpatRaster' cellSize(x, mask=FALSE, lyrs=FALSE, unit="m", transform=TRUE, rcx=100, filename="", ...)
## S4 method for signature 'SpatRaster' cellSize(x, mask=FALSE, lyrs=FALSE, unit="m", transform=TRUE, rcx=100, filename="", ...)
x |
SpatRaster |
mask |
logical. If |
lyrs |
logical. If |
unit |
character. One of "m", "km", or "ha" |
transform |
logical. If |
rcx |
positive integer. The maximum number of rows and columns to be used to compute area of planar data if |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
# SpatRaster r <- rast(nrows=18, ncols=36) v <- 1:ncell(r) v[200:400] <- NA values(r) <- v # size of each raster cell a <- cellSize(r) # illustration of distortion r <- rast(ncols=90, nrows=45, ymin=-80, ymax=80) m <- project(r, "+proj=merc") bad <- init(m, prod(res(m)) / 1000000, names="naive") good <- cellSize(m, unit="km", names="corrected") plot(c(good, bad), nc=1, mar=c(2,2,1,6))
# SpatRaster r <- rast(nrows=18, ncols=36) v <- 1:ncell(r) v[200:400] <- NA values(r) <- v # size of each raster cell a <- cellSize(r) # illustration of distortion r <- rast(ncols=90, nrows=45, ymin=-80, ymax=80) m <- project(r, "+proj=merc") bad <- init(m, prod(res(m)) / 1000000, names="naive") good <- cellSize(m, unit="km", names="corrected") plot(c(good, bad), nc=1, mar=c(2,2,1,6))
Get the centroids of polygons or lines, or centroid-like points that are guaranteed to be inside the polygons or on the lines.
## S4 method for signature 'SpatVector' centroids(x, inside=FALSE)
## S4 method for signature 'SpatVector' centroids(x, inside=FALSE)
x |
SpatVector |
inside |
logical. If |
SpatVector of points
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) x <- centroids(v) y <- centroids(v, TRUE)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) x <- centroids(v) y <- centroids(v, TRUE)
Clamp values to a minimum and maximum value. That is, all values below a lower threshold value and above the upper threshold value become either NA
, or, if values=TRUE
, become the threshold value
## S4 method for signature 'SpatRaster' clamp(x, lower=-Inf, upper=Inf, values=TRUE, filename="", ...) ## S4 method for signature 'numeric' clamp(x, lower=-Inf, upper=Inf, values=TRUE, ...)
## S4 method for signature 'SpatRaster' clamp(x, lower=-Inf, upper=Inf, values=TRUE, filename="", ...) ## S4 method for signature 'numeric' clamp(x, lower=-Inf, upper=Inf, values=TRUE, ...)
x |
SpatRaster |
lower |
numeric with the lowest acceptable value (you can specify a different value for each layer). Or a SpatRaster that has a single layer or the same number of layers as |
upper |
numeric with the highest acceptable value (you can specify a different value for each layer). Or a SpatRaster that has a single layer or the same number of layers as |
values |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) rc <- clamp(r, 25, 75) rc
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) rc <- clamp(r, 25, 75) rc
clamp time-series datat that are S shaped. The value in layers before the minimum value in a cell can be set to that minimum value, and the value in layers after the maximum value for a cell can be set to that maximum value.
## S4 method for signature 'SpatRaster' clamp_ts(x, min=FALSE, max=TRUE, filename="", ...)
## S4 method for signature 'SpatRaster' clamp_ts(x, min=FALSE, max=TRUE, filename="", ...)
x |
SpatRaster |
min |
logical. If |
max |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
sigm <- function(x) { .8 / (1 + exp(-(x-10))) + runif(length(x))/4 } r <- rast(ncols=10, nrows=10, nlyr=50) s <- seq(5.2, 15,.2) set.seed(1) values(r) <- t(replicate(100, sigm(s))) x <- clamp_ts(r, TRUE, TRUE) plot(unlist(r[4])) lines(unlist(x[4]))
sigm <- function(x) { .8 / (1 + exp(-(x-10))) + runif(length(x))/4 } r <- rast(ncols=10, nrows=10, nlyr=50) s <- seq(5.2, 15,.2) set.seed(1) values(r) <- t(replicate(100, sigm(s))) x <- clamp_ts(r, TRUE, TRUE) plot(unlist(r[4])) lines(unlist(x[4]))
Classify values of a SpatRaster. The function (re-)classifies groups of values to other values.
The classification is done based on the argument rcl
. You can classify ranges by specifying a three-column matrix "from-to-becomes" or change specific values by using a two-column matrix "is-becomes". You can also supply a vector with "cuts" or the "number of cuts".
With "from-to-becomes" or "is-becomes" classification is done in the row order of the matrix. Thus, if there are overlapping ranges or values, the first time a number is within a range determines the reclassification value.
With "cuts" the values are sorted, so that the order in which they are provided does not matter.
## S4 method for signature 'SpatRaster' classify(x, rcl, include.lowest=FALSE, right=TRUE, others=NULL, brackets=TRUE, filename="", ...)
## S4 method for signature 'SpatRaster' classify(x, rcl, include.lowest=FALSE, right=TRUE, others=NULL, brackets=TRUE, filename="", ...)
x |
SpatRaster |
rcl |
matrix for classification. This matrix must have 1, 2 or 3 columns. If there are three columns, the first two columns are "from" "to" of the input values, and the third column "becomes" has the new value for that range. The two column matrix ("is", "becomes") can be useful for classifying integer values. In that case, the arguments A single column matrix (or a vector) is interpreted as a set of cuts if there is more than one value. In that case the values are classified based on their location in-between the cut-values. If a single number is provided, that is used to make that number of cuts, at equal intervals between the lowest and highest values of the SpatRaster. |
include.lowest |
logical, indicating if a value equal to the lowest value in |
right |
logical. If |
others |
numeric. If not |
brackets |
logical. If |
filename |
character. Output filename |
... |
Additional arguments for writing files as in |
SpatRaster
classify works with the "raw" values of categorical rasters, ignoring the levels (labels, categories). To change the labels of categorical rasters, use subst
instead.
For model-based classification see predict
subst
for simpler from-to replacement
r <- rast(ncols=10, nrows=10) values(r) <- (0:99)/99 ## from-to-becomes # classify the values into three groups # all values >= 0 and <= 0.25 become 1, etc. m <- c(0, 0.25, 1, 0.25, 0.5, 2, 0.5, 1, 3) rclmat <- matrix(m, ncol=3, byrow=TRUE) rc1 <- classify(r, rclmat, include.lowest=TRUE) ## cuts # equivalent to the above, but now a categorical SpatRaster is returned rc2 <- classify(r, c(0, 0.25, 0.5, 1), include.lowest=TRUE, brackets=TRUE) freq(rc2) ## is-becomes x <- round(r*3) unique(x) # replace 0 with NA y <- classify(x, cbind(0, NA)) unique(y) # multiple replacements m <- rbind(c(2, 200), c(3, 300)) m rcx1 <- classify(x, m) unique(rcx1) rcx2 <- classify(x, m, others=NA) unique(rcx2)
r <- rast(ncols=10, nrows=10) values(r) <- (0:99)/99 ## from-to-becomes # classify the values into three groups # all values >= 0 and <= 0.25 become 1, etc. m <- c(0, 0.25, 1, 0.25, 0.5, 2, 0.5, 1, 3) rclmat <- matrix(m, ncol=3, byrow=TRUE) rc1 <- classify(r, rclmat, include.lowest=TRUE) ## cuts # equivalent to the above, but now a categorical SpatRaster is returned rc2 <- classify(r, c(0, 0.25, 0.5, 1), include.lowest=TRUE, brackets=TRUE) freq(rc2) ## is-becomes x <- round(r*3) unique(x) # replace 0 with NA y <- classify(x, cbind(0, NA)) unique(y) # multiple replacements m <- rbind(c(2, 200), c(3, 300)) m rcx1 <- classify(x, m) unique(rcx1) rcx2 <- classify(x, m, others=NA) unique(rcx2)
Click on a map (plot) to get the coordinates or the values of a SpatRaster or SpatVector at that location. For a SpatRaster you can also get the coordinates and cell number of the location.
This does to work well on the default RStudio plotting device. To work around that, you can first run dev.new(noRStudioGD = TRUE)
which will create a separate window for plotting, then use plot()
followed by click()
and click on the map.
## S4 method for signature 'SpatRaster' click(x, n=10, id=FALSE, xy=FALSE, cell=FALSE, type="p", show=TRUE, ...) ## S4 method for signature 'SpatVector' click(x, n=10, id=FALSE, xy=FALSE, type="p", show=TRUE, ...) ## S4 method for signature 'missing' click(x, n=10, id=FALSE, type="p", show=TRUE, ...)
## S4 method for signature 'SpatRaster' click(x, n=10, id=FALSE, xy=FALSE, cell=FALSE, type="p", show=TRUE, ...) ## S4 method for signature 'SpatVector' click(x, n=10, id=FALSE, xy=FALSE, type="p", show=TRUE, ...) ## S4 method for signature 'missing' click(x, n=10, id=FALSE, type="p", show=TRUE, ...)
x |
SpatRaster or SpatVector, or missing |
n |
number of clicks on the plot (map) |
id |
logical. If |
xy |
logical. If |
cell |
logical. If |
type |
one of "n", "p", "l" or "o". If "p" or "o" the points are plotted; if "l" or "o" they are joined by lines. See |
show |
logical. Print the values after each click? |
... |
additional graphics parameters used if type != "n" for plotting the locations. See |
The value(s) of x
at the point(s) clicked on (or touched by the box drawn).
A data.frame
with the value(s) of all layers of SpatRaster x
for the cell(s) clicked on; or with the attributes of the geometries of SpatVector x
that intersect with the box drawn).
The plot only provides the coordinates for a spatial query, the values are read from the SpatRaster or SpatVector that is passed as an argument. Thus, you can extract values from an object that has not been plotted, as long as it spatially overlaps with the extent of the plot.
Unless the process is terminated prematurely values at most n
positions are determined. The identification process can be terminated, depending on how you interact with R, by hitting Esc, or by clicking the right mouse button and selecting "Stop" from the menu, or from the "Stop" menu on the graphics window.
## Not run: r <-rast(system.file("ex/elev.tif", package="terra")) plot(r) click(r, n=1) ## now click on the plot (map) ## End(Not run)
## Not run: r <-rast(system.file("ex/elev.tif", package="terra")) plot(r) click(r, n=1) ## now click on the plot (map) ## End(Not run)
Coercion of a SpatRaster to a vector, matrix or array. Or coerce a SpatExtent to a vector or matrix
## S4 method for signature 'SpatRaster' as.vector(x, mode='any') ## S4 method for signature 'SpatRaster' as.matrix(x, wide=FALSE, ...) ## S4 method for signature 'SpatRaster' as.array(x) ## S4 method for signature 'SpatExtent' as.vector(x, mode='any') ## S4 method for signature 'SpatExtent' as.matrix(x, ...)
## S4 method for signature 'SpatRaster' as.vector(x, mode='any') ## S4 method for signature 'SpatRaster' as.matrix(x, wide=FALSE, ...) ## S4 method for signature 'SpatRaster' as.array(x) ## S4 method for signature 'SpatExtent' as.vector(x, mode='any') ## S4 method for signature 'SpatExtent' as.matrix(x, ...)
x |
SpatRaster or SpatVector |
wide |
logical. If |
mode |
this argument is ignored |
... |
additional arguments (none implemented) |
vector, matrix, or array
r <- rast(ncols=2, nrows=2) values(r) <- 1:ncell(r) as.vector(r) as.matrix(r) as.matrix(r, wide=TRUE) as.data.frame(r, xy=TRUE) as.array(r) as.vector(ext(r)) as.matrix(ext(r))
r <- rast(ncols=2, nrows=2) values(r) <- 1:ncell(r) as.vector(r) as.matrix(r) as.matrix(r, wide=TRUE) as.data.frame(r, xy=TRUE) as.array(r) as.vector(ext(r)) as.matrix(ext(r))
Get or set color table(s) associated with a SpatRaster. Color tables are used for associating colors with values, for use in mapping (plot).
## S4 method for signature 'SpatRaster' coltab(x) ## S4 replacement method for signature 'SpatRaster' coltab(x, ..., layer=1)<-value ## S4 method for signature 'SpatRaster' has.colors(x)
## S4 method for signature 'SpatRaster' coltab(x) ## S4 replacement method for signature 'SpatRaster' coltab(x, ..., layer=1)<-value ## S4 method for signature 'SpatRaster' has.colors(x)
x |
SpatRaster |
layer |
positive integer, the layer number or name |
value |
a two-column data.frame (first column the cell value, the second column the color); a vector of colors (the first one is the color for value 0 and so on); or a four (value,red,green,blue) or five (including alpha) column data.frame also from 0 to n; or NULL to remove the color table. You can also supply a list of such data.frames to set a color table to all layers |
... |
additional arguments (none implemented) |
data.frame
r <- rast(ncols=3, nrows=2, vals=1:6) coltb <- data.frame(value=1:6, col=rainbow(6, end=.9)) coltb plot(r) has.colors(r) coltab(r) <- coltb plot(r) has.colors(r) tb <- coltab(r) class(tb) dim(tb[[1]])
r <- rast(ncols=3, nrows=2, vals=1:6) coltb <- data.frame(value=1:6, col=rainbow(6, end=.9)) coltb plot(r) has.colors(r) coltab(r) <- coltb plot(r) has.colors(r) tb <- coltab(r) class(tb) dim(tb[[1]])
Combine the geometries of one SpatVector with those of another. Geometries can be combined based on overlap, shared boundaries and distance (in that order of operation).
The typical use-case of this method is when you are editing geometries and you have a number of small polygons in one SpatVector that should be part of the geometries of the another SpatVector; perhaps because they were small holes inbetween the borders of two SpatVectors.
To append SpatVectors use 'rbind' and see methods like intersect
and union
for "normal" polygons combinations.
## S4 method for signature 'SpatVector,SpatVector' combineGeoms(x, y, overlap=TRUE, boundary=TRUE, distance=TRUE, append=TRUE, minover=0.1, maxdist=Inf, dissolve=TRUE, erase=TRUE)
## S4 method for signature 'SpatVector,SpatVector' combineGeoms(x, y, overlap=TRUE, boundary=TRUE, distance=TRUE, append=TRUE, minover=0.1, maxdist=Inf, dissolve=TRUE, erase=TRUE)
x |
SpatVector of polygons |
y |
SpatVector of polygons geometries that are to be combined with |
overlap |
logical. If |
boundary |
logical. If |
distance |
logical. If |
append |
logical. Should remaining geometries be appended to the output? Not relevant if |
minover |
numeric. The fraction of the geometry in |
maxdist |
numeric. Geometries further away from each other than this distance (in meters) will not be combined |
dissolve |
logical. Should internal boundaries be dissolved? |
erase |
logical. If |
SpatVector
x1 <- vect("POLYGON ((0 0, 8 0, 8 9, 0 9, 0 0))") x2 <- vect("POLYGON ((10 4, 12 4, 12 7, 11 7, 11 6, 10 6, 10 4))") y1 <- vect("POLYGON ((5 6, 15 6, 15 15, 5 15, 5 6))") y2 <- vect("POLYGON ((8 2, 9 2, 9 3, 8 3, 8 2))") y3 <- vect("POLYGON ((2 6, 3 6, 3 8, 2 8, 2 6))") y4 <- vect("POLYGON ((2 12, 3 12, 3 13, 2 13, 2 12))") x <- rbind(x1, x2) values(x) <- data.frame(xid=1:2) crs(x) <- "+proj=utm +zone=1" y <- rbind(y1, y2, y3, y4) values(y) <- data.frame(yid=letters[1:4]) crs(y) <- "+proj=utm +zone=1" plot(rbind(x, y), border=c(rep("red",2), rep("blue", 4)), lwd=2) text(x, "xid") text(y, "yid") v <- combineGeoms(x, y) plot(v, col=c("red", "blue")) v <- combineGeoms(x, y, boundary=FALSE, maxdist=1, minover=.05) plot(v, col=rainbow(4))
x1 <- vect("POLYGON ((0 0, 8 0, 8 9, 0 9, 0 0))") x2 <- vect("POLYGON ((10 4, 12 4, 12 7, 11 7, 11 6, 10 6, 10 4))") y1 <- vect("POLYGON ((5 6, 15 6, 15 15, 5 15, 5 6))") y2 <- vect("POLYGON ((8 2, 9 2, 9 3, 8 3, 8 2))") y3 <- vect("POLYGON ((2 6, 3 6, 3 8, 2 8, 2 6))") y4 <- vect("POLYGON ((2 12, 3 12, 3 13, 2 13, 2 12))") x <- rbind(x1, x2) values(x) <- data.frame(xid=1:2) crs(x) <- "+proj=utm +zone=1" y <- rbind(y1, y2, y3, y4) values(y) <- data.frame(yid=letters[1:4]) crs(y) <- "+proj=utm +zone=1" plot(rbind(x, y), border=c(rep("red",2), rep("blue", 4)), lwd=2) text(x, "xid") text(y, "yid") v <- combineGeoms(x, y) plot(v, col=c("red", "blue")) v <- combineGeoms(x, y, boundary=FALSE, maxdist=1, minover=.05) plot(v, col=rainbow(4))
Standard comparison and logical operators for computations with SpatRasters. Computations are local (applied on a cell by cell basis). If multiple SpatRasters are used, these must have the same geometry (extent and resolution). These operators have been implemented:
Logical: !, &, |, isTRUE, isFALSE
Compare: ==, !=, >, <, <=, >=, is.na, is.nan, is.finite, is.infinite
See not.na
for the inverse of is.na
, and noNA
to detect cells with missing value across layers.
The compare
and logic
methods implement these operators in a method that can return NA
istead of FALSE
and allows for setting an output filename.
The terra package does not distinguish between NA
(not available) and NaN
(not a number). In most cases this state is represented by NaN
.
If you use a SpatRaster with a vector of multiple numbers, each element in the vector is considered a layer (with a constant value). If you use a SpatRaster with a matrix, the number of columns of the matrix must match the number of layers of the SpatRaster. The rows are used to match the cells. That is, if there are two rows, these match cells 1 and 2, and they are recycled to 3 and 4, etc.
The following method has been implemented for (SpatExtent, SpatExtent): ==
## S4 method for signature 'SpatRaster' compare(x, y, oper, falseNA=FALSE, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatRaster' logic(x, oper, falseNA=FALSE, filename="", overwrite=FALSE, ...)
## S4 method for signature 'SpatRaster' compare(x, y, oper, falseNA=FALSE, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatRaster' logic(x, oper, falseNA=FALSE, filename="", overwrite=FALSE, ...)
x |
SpatRaster |
y |
SpatRaster or numeric |
oper |
character. Operator name. For |
falseNA |
logical. Should the result be |
filename |
character. Output filename |
overwrite |
logical. If |
... |
additional arguments for writing files as in |
SpatRaster or SpatExtent
all.equal
, Arith-methods. See ifel
to conveniently combine operations and Math-methods
or app
to apply any R function to a SpatRaster.
r1 <- rast(ncols=10, nrows=10) values(r1) <- runif(ncell(r1)) r1[10:20] <- NA r2 <- rast(r1) values(r2) <- 1:ncell(r2) / ncell(r2) x <- is.na(r1) !x r1 == r2 compare(r1, r2, "==") compare(r1, r2, "==", TRUE)
r1 <- rast(ncols=10, nrows=10) values(r1) <- runif(ncell(r1)) r1[10:20] <- NA r2 <- rast(r1) values(r2) <- 1:ncell(r2) / ncell(r2) x <- is.na(r1) !x r1 == r2 compare(r1, r2, "==") compare(r1, r2, "==", TRUE)
Evaluate whether two SpatRasters have the same extent, number of rows and columns, projection, resolution, and origin (or a subset of these comparisons).
Or evaluate whether two SpatVectors have the same geometries, or whether a SpatVector has duplicated geometries.
## S4 method for signature 'SpatRaster,SpatRaster' compareGeom(x, y, ..., lyrs=FALSE, crs=TRUE, warncrs=FALSE, ext=TRUE, rowcol=TRUE, res=FALSE, stopOnError=TRUE, messages=FALSE) ## S4 method for signature 'SpatVector,SpatVector' compareGeom(x, y, tolerance=0) ## S4 method for signature 'SpatVector,missing' compareGeom(x, y, tolerance=0)
## S4 method for signature 'SpatRaster,SpatRaster' compareGeom(x, y, ..., lyrs=FALSE, crs=TRUE, warncrs=FALSE, ext=TRUE, rowcol=TRUE, res=FALSE, stopOnError=TRUE, messages=FALSE) ## S4 method for signature 'SpatVector,SpatVector' compareGeom(x, y, tolerance=0) ## S4 method for signature 'SpatVector,missing' compareGeom(x, y, tolerance=0)
x |
SpatRaster or SpatVector |
y |
Same as |
... |
Additional SpatRasters |
lyrs |
logical. If |
crs |
logical. If |
warncrs |
logical. If |
ext |
logical. If |
rowcol |
logical. If |
res |
logical. If |
stopOnError |
logical. If |
messages |
logical. If |
tolerance |
numeric |
logical (SpatRaster) or matrix of logical (SpatVector)
r1 <- rast() r2 <- rast() r3 <- rast() compareGeom(r1, r2, r3) nrow(r3) <- 10 ## Not run: compareGeom(r1, r3) ## End(Not run)
r1 <- rast() r2 <- rast() r3 <- rast() compareGeom(r1, r2, r3) nrow(r3) <- 10 ## Not run: compareGeom(r1, r3) ## End(Not run)
Combine two categorical rasters by concatenating their levels.
## S4 method for signature 'SpatRaster' concats(x, y, filename="", ...)
## S4 method for signature 'SpatRaster' concats(x, y, filename="", ...)
x |
SpatRaster (with a single, categorical, layer) |
y |
SpatRaster (with a single, categorical, layer) |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
set.seed(0) r <- rast(nrows=10, ncols=10) values(r) <- sample(3, ncell(r), replace=TRUE) levels(r) <- data.frame(id=1:3, cover=c("forest", "water", "urban")) rr <- rast(r) values(rr) <- sample(1:3, ncell(rr), replace=TRUE) levels(rr) <- data.frame(id=c(1:3), color=c("red", "green", "blue")) x <- concats(r, rr) x levels(x)[[1]]
set.seed(0) r <- rast(nrows=10, ncols=10) values(r) <- sample(3, ncell(r), replace=TRUE) levels(r) <- data.frame(id=1:3, cover=c("forest", "water", "urban")) rr <- rast(r) values(rr) <- sample(1:3, ncell(rr), replace=TRUE) levels(rr) <- data.frame(id=c(1:3), color=c("red", "green", "blue")) x <- concats(r, rr) x levels(x)[[1]]
Contour lines (isolines) of a SpatRaster. Use add=TRUE
to add the lines to the current plot. See graphics::contour
for details.
if filled=TRUE
, a new filled contour plot is made. See graphics::filled.contour
for details.
as.contour
returns the contour lines as a SpatVector.
## S4 method for signature 'SpatRaster' contour(x, maxcells=100000, filled=FALSE, ...) ## S4 method for signature 'SpatRaster' as.contour(x, maxcells=100000, ...)
## S4 method for signature 'SpatRaster' contour(x, maxcells=100000, filled=FALSE, ...) ## S4 method for signature 'SpatRaster' as.contour(x, maxcells=100000, ...)
x |
SpatRaster. Only the first layer is used |
maxcells |
maximum number of pixels used to create the contours |
filled |
logical. If |
... |
any argument that can be passed to |
r <- rast(system.file("ex/elev.tif", package="terra")) plot(r) contour(r, add=TRUE) v <- as.contour(r) plot(r) lines(v) contour(r, filled=TRUE, nlevels=5) ## if you want a SpatVector with contour lines template <- disagg(rast(r), 10) rr <- resample(r, template) rr <- floor(rr/100) * 100 v <- as.polygons(rr) plot(v, 1, col=terrain.colors(7))
r <- rast(system.file("ex/elev.tif", package="terra")) plot(r) contour(r, add=TRUE) v <- as.contour(r) plot(r) lines(v) contour(r, filled=TRUE, nlevels=5) ## if you want a SpatVector with contour lines template <- disagg(rast(r), 10) rr <- resample(r, template) rr <- floor(rr/100) * 100 v <- as.polygons(rr) plot(v, 1, col=terrain.colors(7))
Get the convex hull, the minimal bounding rotated rectangle, or minimal bounding circle of a SpatVector
## S4 method for signature 'SpatVector' convHull(x, by="") ## S4 method for signature 'SpatVector' minRect(x, by="") ## S4 method for signature 'SpatVector' minCircle(x, by="")
## S4 method for signature 'SpatVector' convHull(x, by="") ## S4 method for signature 'SpatVector' minRect(x, by="") ## S4 method for signature 'SpatVector' minCircle(x, by="")
x |
SpatVector |
by |
character (variable name), to get a new geometry for groups of input geometries |
SpatVector
p <- vect(system.file("ex/lux.shp", package="terra")) h <- convHull(p) hh <- convHull(p, "NAME_1") rr <- minRect(p, "NAME_1") plot(rr, lwd=5, border="gray") plot(hh, "NAME_1", col=rainbow(10, alpha=.5), lwd=3, add=TRUE, plg=list(x="topright")) lines(aggregate(p, "NAME_1"), col="blue", lty=2, lwd=2)
p <- vect(system.file("ex/lux.shp", package="terra")) h <- convHull(p) hh <- convHull(p, "NAME_1") rr <- minRect(p, "NAME_1") plot(rr, lwd=5, border="gray") plot(hh, "NAME_1", col=rainbow(10, alpha=.5), lwd=3, add=TRUE, plg=list(x="topright")) lines(aggregate(p, "NAME_1"), col="blue", lty=2, lwd=2)
Use a friction (cost) surface to compute the cost-distance from any cell to the border of one or more target cells.
Distances are computed by summing local distances between cells, which are connected with their neighbors in 8 directions, and assuming that the path has to go through the centers of one of the neighboring raster cells.
Distances are multiplied with the friction, thus to get the cost-distance, the friction surface must express the cost per unit distance (speed) of travel.
## S4 method for signature 'SpatRaster' costDist(x, target=0, scale=1, maxiter=50, filename="", ...)
## S4 method for signature 'SpatRaster' costDist(x, target=0, scale=1, maxiter=50, filename="", ...)
x |
SpatRaster |
target |
numeric. value of the target cells (where to compute cost-distance to) |
scale |
numeric. Scale factor. The cost distance is divided by this number |
maxiter |
numeric. The maximum number of iterations. Increase this number if you get the warning that |
filename |
character. output filename (optional) |
... |
additional arguments as for |
SpatRaster
r <- rast(ncols=5, nrows=5, crs="+proj=utm +zone=1 +datum=WGS84", xmin=0, xmax=5, ymin=0, ymax=5, vals=1) r[13] <- 0 d <- costDist(r) plot(d) text(d, digits=1) r <- rast(ncols=10, nrows=10, xmin=0, xmax=10, ymin=0, ymax=10, vals=10, crs="+proj=utm +zone=1 +datum=WGS84") r[5, 1] <- -10 r[2:3, 1] <- r[1, 2:4] <- r[2, 5] <- 0 r[3, 6] <- r[2, 7] <- r[1, 8:9] <- 0 r[6, 6:10] <- NA r[6:9, 6] <- NA d <- costDist(r, -10) plot(d) text(d, digits=1, cex=.8)
r <- rast(ncols=5, nrows=5, crs="+proj=utm +zone=1 +datum=WGS84", xmin=0, xmax=5, ymin=0, ymax=5, vals=1) r[13] <- 0 d <- costDist(r) plot(d) text(d, digits=1) r <- rast(ncols=10, nrows=10, xmin=0, xmax=10, ymin=0, ymax=10, vals=10, crs="+proj=utm +zone=1 +datum=WGS84") r[5, 1] <- -10 r[2:3, 1] <- r[1, 2:4] <- r[2, 5] <- 0 r[3, 6] <- r[2, 7] <- r[1, 8:9] <- 0 r[6, 6:10] <- NA r[6:9, 6] <- NA d <- costDist(r, -10) plot(d) text(d, digits=1, cex=.8)
Replace NA
or other values in SpatRaster x
with the values of SpatRaster y
For polygons: areas of x
that overlap with y
are replaced by y
or, if identity=TRUE
intersected with y
.
## S4 method for signature 'SpatRaster,SpatRaster' cover(x, y, values=NA, filename="", ...) ## S4 method for signature 'SpatVector,SpatVector' cover(x, y, identity=FALSE, expand=TRUE)
## S4 method for signature 'SpatRaster,SpatRaster' cover(x, y, values=NA, filename="", ...) ## S4 method for signature 'SpatVector,SpatVector' cover(x, y, identity=FALSE, expand=TRUE)
x |
SpatRaster or SpatVector |
y |
Same as |
values |
numeric. The cell values in |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
identity |
logical. If |
expand |
logical. Should parts of |
SpatRaster
r1 <- r2 <- rast(ncols=36, nrows=18) values(r1) <- 1:ncell(r1) values(r2) <- runif(ncell(r2)) r2 <- classify(r2, cbind(-Inf, 0.5, NA)) r3 <- cover(r2, r1) p <- vect(system.file("ex/lux.shp", package="terra")) e <- as.polygons(ext(6, 6.4, 49.75, 50)) values(e) <- data.frame(y=10) cv <- cover(p, e) plot(cv, col=rainbow(12)) ci <- cover(p, e, identity=TRUE) lines(e, lwd=3) plot(ci, col=rainbow(12)) lines(e, lwd=3)
r1 <- r2 <- rast(ncols=36, nrows=18) values(r1) <- 1:ncell(r1) values(r2) <- runif(ncell(r2)) r2 <- classify(r2, cbind(-Inf, 0.5, NA)) r3 <- cover(r2, r1) p <- vect(system.file("ex/lux.shp", package="terra")) e <- as.polygons(ext(6, 6.4, 49.75, 50)) values(e) <- data.frame(y=10) cv <- cover(p, e) plot(cv, col=rainbow(12)) ci <- cover(p, e, identity=TRUE) lines(e, lwd=3) plot(ci, col=rainbow(12)) lines(e, lwd=3)
Get the coordinates of a SpatVector or SpatRaster cells. A matrix or data.frame of the x (longitude) and y (latitude) coordinates is returned.
## S4 method for signature 'SpatVector' crds(x, df=FALSE, list=FALSE) ## S4 method for signature 'SpatRaster' crds(x, df=FALSE, na.rm=TRUE, na.all=FALSE)
## S4 method for signature 'SpatVector' crds(x, df=FALSE, list=FALSE) ## S4 method for signature 'SpatRaster' crds(x, df=FALSE, na.rm=TRUE, na.all=FALSE)
x |
SpatRaster or SpatVector |
df |
logical. If |
list |
logical. If |
na.rm |
logical. If |
na.all |
logical. If |
matrix or data.frame
geom
returns the complete structure of SpatVector geometries. For SpatRaster see xyFromCell
x1 <- rbind(c(-175,-20), c(-140,55), c(10, 0), c(-140,-60)) x2 <- rbind(c(-125,0), c(0,60), c(40,5), c(15,-45)) x3 <- rbind(c(-10,0), c(140,60), c(160,0), c(140,-55)) x4 <- rbind(c(80,0), c(105,13), c(120,2), c(105,-13)) z <- rbind(cbind(object=1, part=1, x1), cbind(object=2, part=1, x2), cbind(object=3, part=1, x3), cbind(object=3, part=2, x4)) colnames(z)[3:4] <- c('x', 'y') z <- cbind(z, hole=0) z[(z[, "object"]==3 & z[,"part"]==2), "hole"] <- 1 p <- vect(z, "polygons") crds(p) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) g <- crds(v) head(g)
x1 <- rbind(c(-175,-20), c(-140,55), c(10, 0), c(-140,-60)) x2 <- rbind(c(-125,0), c(0,60), c(40,5), c(15,-45)) x3 <- rbind(c(-10,0), c(140,60), c(160,0), c(140,-55)) x4 <- rbind(c(80,0), c(105,13), c(120,2), c(105,-13)) z <- rbind(cbind(object=1, part=1, x1), cbind(object=2, part=1, x2), cbind(object=3, part=1, x3), cbind(object=3, part=2, x4)) colnames(z)[3:4] <- c('x', 'y') z <- cbind(z, hole=0) z[(z[, "object"]==3 & z[,"part"]==2), "hole"] <- 1 p <- vect(z, "polygons") crds(p) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) g <- crds(v) head(g)
Cut out a part of a SpatRaster or SpatVector.
You can crop a SpatRaster with a SpatExtent, or with another object from which an extent can be obtained. Note that the SpatRaster returned may not have the exactly the same extent as the SpatExtent supplied because you can only select entire cells (rows and columns), and you cannot add new areas. See methods like resample
and disagg
to force SpatRasters to align and extend
to add rows and/or columns.
You can only crop rectangular areas of a SpatRaster, but see argument mask=TRUE
for setting cell values within SpatRaster to NA
; or use the mask
method after crop for additional masking options.
You can crop a SpatVector with another SpatVector. If these are not polygons, the minimum convex hull is used. Unlike with intersect
the geometries and attributes of y
are not transferred to the output. You can also crop a SpatVector with a rectangle (SpatRaster, SpatExtent).
## S4 method for signature 'SpatRaster' crop(x, y, snap="near", mask=FALSE, touches=TRUE, extend=FALSE, filename="", ...) ## S4 method for signature 'SpatRasterDataset' crop(x, y, snap="near", extend=FALSE) ## S4 method for signature 'SpatRasterCollection' crop(x, y, snap="near", extend=FALSE) ## S4 method for signature 'SpatVector' crop(x, y, ext=FALSE) ## S4 method for signature 'SpatGraticule' crop(x, y)
## S4 method for signature 'SpatRaster' crop(x, y, snap="near", mask=FALSE, touches=TRUE, extend=FALSE, filename="", ...) ## S4 method for signature 'SpatRasterDataset' crop(x, y, snap="near", extend=FALSE) ## S4 method for signature 'SpatRasterCollection' crop(x, y, snap="near", extend=FALSE) ## S4 method for signature 'SpatVector' crop(x, y, ext=FALSE) ## S4 method for signature 'SpatGraticule' crop(x, y)
x |
SpatRaster or SpatVector |
y |
SpatRaster, SpatVector, SpatExtent, or any other object that has a SpatExtent ( |
snap |
character. One of "near", "in", or "out". Used to align |
mask |
logical. Should |
touches |
logical. If |
extend |
logical. Should rows and/or columns be added if |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
ext |
logical. Use the extent of |
SpatRaster
See window
for a virtual and sometimes more efficient way to crop a dataset.
r <- rast(xmin=0, xmax=10, ymin=0, ymax=10, nrows=25, ncols=25) values(r) <- 1:ncell(r) e <- ext(-5, 5, -5, 5) rc <- crop(r, e) # crop and mask f <- system.file("ex/elev.tif", package="terra") r <- rast(f) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) cm <- crop(r, v[9:12,], mask=TRUE) plot(cm) lines(v) # crop vector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) e <- ext(6.15, 6.3, 49.7, 49.8) x <- crop(v, e) plot(x, "NAME_1")
r <- rast(xmin=0, xmax=10, ymin=0, ymax=10, nrows=25, ncols=25) values(r) <- 1:ncell(r) e <- ext(-5, 5, -5, 5) rc <- crop(r, e) # crop and mask f <- system.file("ex/elev.tif", package="terra") r <- rast(f) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) cm <- crop(r, v[9:12,], mask=TRUE) plot(cm) lines(v) # crop vector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) e <- ext(6.15, 6.3, 49.7, 49.8) x <- crop(v, e) plot(x, "NAME_1")
Cross-tabulate the layers of a SpatRaster to create a contingency table.
## S4 method for signature 'SpatRaster,missing' crosstab(x, digits=0, long=FALSE, useNA=FALSE)
## S4 method for signature 'SpatRaster,missing' crosstab(x, digits=0, long=FALSE, useNA=FALSE)
x |
SpatRaster |
digits |
integer. The number of digits for rounding the values before cross-tabulation |
long |
logical. If |
useNA |
logical, indicting if the table should includes counts of |
A table or data.frame
r <- s <- rast(nc=5, nr=5) set.seed(1) values(r) <- runif(ncell(r)) * 2 values(s) <- runif(ncell(r)) * 3 x <- c(r, s) crosstab(x) rs <- r/s r[1:5] <- NA s[20:25] <- NA x <- c(r, s, rs) crosstab(x, useNA=TRUE, long=TRUE)
r <- s <- rast(nc=5, nr=5) set.seed(1) values(r) <- runif(ncell(r)) * 2 values(s) <- runif(ncell(r)) * 3 x <- c(r, s) crosstab(x) rs <- r/s r[1:5] <- NA s[20:25] <- NA x <- c(r, s, rs) crosstab(x, useNA=TRUE, long=TRUE)
Get or set the coordinate reference system (CRS), also referred to as a "projection", of a SpatRaster or SpatVector.
Setting a new CRS does not change the data itself, it just changes the label. So you should only set the CRS of a dataset (if it does not come with one) to what it *is*, not to what you would *like it to be*. See project
to *transform* an object from one CRS to another.
## S4 method for signature 'SpatRaster' crs(x, proj=FALSE, describe=FALSE, parse=FALSE) ## S4 method for signature 'SpatVector' crs(x, proj=FALSE, describe=FALSE, parse=FALSE) ## S4 method for signature 'character' crs(x, proj=FALSE, describe=FALSE, parse=FALSE) ## S4 replacement method for signature 'SpatRaster' crs(x, warn=FALSE)<-value ## S4 replacement method for signature 'SpatVector' crs(x, warn=FALSE)<-value
## S4 method for signature 'SpatRaster' crs(x, proj=FALSE, describe=FALSE, parse=FALSE) ## S4 method for signature 'SpatVector' crs(x, proj=FALSE, describe=FALSE, parse=FALSE) ## S4 method for signature 'character' crs(x, proj=FALSE, describe=FALSE, parse=FALSE) ## S4 replacement method for signature 'SpatRaster' crs(x, warn=FALSE)<-value ## S4 replacement method for signature 'SpatVector' crs(x, warn=FALSE)<-value
x |
SpatRaster or SpatVector |
proj |
logical. If |
describe |
logical. If |
warn |
logical. If |
value |
character string describing a coordinate reference system. This can be in a WKT format, as a <authority:number> code such as "EPSG:4326", or a PROJ-string format such as "+proj=utm +zone=12" (see Note) |
parse |
logical. If |
character or modified SpatRaster/Vector
Projections are handled by the PROJ/GDAL libraries. The PROJ developers suggest to define a CRS with the WKT2 or <authority>:<code> notation. It is not practical to define one's own custom CRS with WKT2, and the the <authority>:<code> system only covers a handful of (commonly used) CRSs. To work around this problem it is still possible to use the deprecated PROJ-string notation (+proj=...
) with one major caveat: the datum should be WGS84 (or the equivalent NAD83) – if you want to transform your data to a coordinate reference system with a different datum. Thus as long as you use WGS84, or an ellipsoid instead of a datum, you can safely use PROJ-strings to represent your CRS; including to define your own custom CRS.
You can also set the crs to "local" to get an informal coordinate system on an arbitrary Euclidean (Cartesian) plane with units in meter.
r <- rast() crs(r) crs(r, describe=TRUE, proj=TRUE) crs(r) <- "+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +ellps=WGS84" crs(r) # You can use epsg codes crs(r) <- "epsg:25831" crs(r, describe=TRUE)$area crs("epsg:25831", describe=TRUE)
r <- rast() crs(r) crs(r, describe=TRUE, proj=TRUE) crs(r) <- "+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +ellps=WGS84" crs(r) # You can use epsg codes crs(r) <- "epsg:25831" crs(r, describe=TRUE)$area crs("epsg:25831", describe=TRUE)
Get the data types of the fields (attributes, variables) of a SpatVector or of the file(s) associated with a SpatRaster. A (layer of a) SpatRaster has no datatype if it has no values, or if the values are in memory.
## S4 method for signature 'SpatRaster' datatype(x, bylyr=TRUE) ## S4 method for signature 'SpatVector' datatype(x)
## S4 method for signature 'SpatRaster' datatype(x, bylyr=TRUE) ## S4 method for signature 'SpatVector' datatype(x)
x |
SpatRaster or SpatVector |
bylyr |
logical. If |
character
Raster data types
to check / set the type of SpatRaster values.
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) datatype(v) f <- system.file("ex/elev.tif", package="terra") r <- rast(f) datatype(r) # no data type datatype(rast())
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) datatype(v) f <- system.file("ex/elev.tif", package="terra") r <- rast(f) datatype(r) # no data type datatype(rast())
Make a deep copy of a SpatRaster or SpatVector. This is occasionally useful when wanting to use a replacement function in a shallow copy. That is a copy that was created like this: x <- y
. If you use a replacement function to change an object, its shallow copies also change.
## S4 method for signature 'SpatRaster' deepcopy(x) ## S4 method for signature 'SpatVector' deepcopy(x)
## S4 method for signature 'SpatRaster' deepcopy(x) ## S4 method for signature 'SpatVector' deepcopy(x)
x |
SpatRaster or SpatVector |
Same as x
r <- rast(ncols=10, nrows=10, nl=3) tm <- as.Date("2001-05-03") + 1:3 time(r) <- tm time(r) x <- r time(x) <- tm + 365 time(x) time(r) y <- deepcopy(r) time(y) <- tm - 365 time(y) time(r) # or make a new object like this z <- rast(r) time(z) <- tm time(z) time(r)
r <- rast(ncols=10, nrows=10, nl=3) tm <- as.Date("2001-05-03") + 1:3 time(r) <- tm time(r) x <- r time(x) <- tm + 365 time(x) time(r) y <- deepcopy(r) time(y) <- tm - 365 time(y) time(r) # or make a new object like this z <- rast(r) time(z) <- tm time(z) time(r)
Add additional nodes to lines or polygons. This can be useful to do prior to using project
such that the path does not change too much.
## S4 method for signature 'SpatVector' densify(x, interval, equalize=TRUE, flat=FALSE)
## S4 method for signature 'SpatVector' densify(x, interval, equalize=TRUE, flat=FALSE)
x |
SpatVector |
interval |
positive number, specifying the desired minimum distance between nodes. The unit is meter for lonlat data, and in the linear unit of the crs for planar data |
equalize |
logical. If |
flat |
logical. If |
SpatVector
v <- vect(rbind(c(-120,-20), c(-80,5), c(-40,-60), c(-120,-20)), type="polygons", crs="+proj=longlat") vd <- densify(v, 200000) p <- project(v, "+proj=robin") pd <- project(vd, "+proj=robin") # good plot(pd, col="gray", border="red", lwd=10) points(pd, col="gray") # bad lines(p, col="blue", lwd=3) points(p, col="blue", cex=2) plot(p, col="blue", alpha=.1, add=TRUE) legend("topright", c("good", "bad"), col=c("red", "blue"), lty=1, lwd=3) ## the other way around does not work ## unless the original data was truly planar (e.g. derived from a map) x <- densify(p, 250000) y <- project(x, "+proj=longlat") # bad plot(y) # good lines(vd, col="red")
v <- vect(rbind(c(-120,-20), c(-80,5), c(-40,-60), c(-120,-20)), type="polygons", crs="+proj=longlat") vd <- densify(v, 200000) p <- project(v, "+proj=robin") pd <- project(vd, "+proj=robin") # good plot(pd, col="gray", border="red", lwd=10) points(pd, col="gray") # bad lines(p, col="blue", lwd=3) points(p, col="blue", cex=2) plot(p, col="blue", alpha=.1, add=TRUE) legend("topright", c("good", "bad"), col=c("red", "blue"), lty=1, lwd=3) ## the other way around does not work ## unless the original data was truly planar (e.g. derived from a map) x <- densify(p, 250000) y <- project(x, "+proj=longlat") # bad plot(y) # good lines(vd, col="red")
Create density plots of the cell values of a SpatRaster
## S4 method for signature 'SpatRaster' density(x, maxcells=100000, plot=TRUE, main, ...)
## S4 method for signature 'SpatRaster' density(x, maxcells=100000, plot=TRUE, main, ...)
x |
SpatRaster |
maxcells |
the maximum number of (randomly sampled) cells to be used for creating the plot |
plot |
if |
main |
character. Caption of plot(s) |
... |
additional arguments passed to |
density plot (and a density object, returned invisibly if plot=TRUE)
logo <- rast(system.file("ex/logo.tif", package="terra")) density(logo)
logo <- rast(system.file("ex/logo.tif", package="terra")) density(logo)
These methods are deprecated and will be removed in future versions
## S4 method for signature 'SpatRaster' setCats(x, ...) ## S4 method for signature 'SpatRaster' area(x, ...)
## S4 method for signature 'SpatRaster' setCats(x, ...) ## S4 method for signature 'SpatRaster' area(x, ...)
x |
object |
... |
additional arguments |
Get or set the depth of the layers of a SpatRaster. Experimental.
## S4 method for signature 'SpatRaster' depth(x) ## S4 replacement method for signature 'SpatRaster' depth(x)<-value
## S4 method for signature 'SpatRaster' depth(x) ## S4 replacement method for signature 'SpatRaster' depth(x)<-value
x |
SpatRaster |
value |
numeric vector |
numeric
s <- rast(system.file("ex/logo.tif", package="terra")) depth(s) <- 1:3 depth(s)
s <- rast(system.file("ex/logo.tif", package="terra")) depth(s) <- 1:3 depth(s)
Describe the properties of spatial data in a file as generated with the "GDALinfo" tool.
## S4 method for signature 'character' describe(x, sds=FALSE, meta=FALSE, parse=FALSE, options="", print=FALSE, open_opt="")
## S4 method for signature 'character' describe(x, sds=FALSE, meta=FALSE, parse=FALSE, options="", print=FALSE, open_opt="")
x |
character. The name of a file with spatial data. Or a fully specified subdataset within a file such as |
sds |
logical. If |
meta |
logical. Get the file level metadata instead |
parse |
logical. If |
options |
character. A vector of valid options (if |
print |
logical. If |
open_opt |
character. Driver specific open options |
character (invisibly, if print=FALSE
)
f <- system.file("ex/elev.tif", package="terra") describe(f) describe(f, meta=TRUE) #g <- describe(f, options=c("json", "nomd", "proj4")) #head(g)
f <- system.file("ex/elev.tif", package="terra") describe(f) describe(f, meta=TRUE) #g <- describe(f, options=c("json", "nomd", "proj4")) #head(g)
Compute the difference between consecutive layers in a SpatRaster.
## S4 method for signature 'SpatRaster' diff(x, lag=1, filename="", ...)
## S4 method for signature 'SpatRaster' diff(x, lag=1, filename="", ...)
x |
SpatRaster |
lag |
positive integer indicating which lag to use |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
s <- rast(system.file("ex/logo.tif", package="terra")) d <- diff(s)
s <- rast(system.file("ex/logo.tif", package="terra")) d <- diff(s)
Get the number of rows (nrow
), columns (ncol
), cells (ncell
), layers (nlyr
), sources (nsrc
), the size size
(nlyr(x)*ncell(x)
), or spatial resolution of a SpatRaster.
length
returns the number of sub-datasets in a SpatRasterDataset or SpatVectorCollection.
For a SpatVector length(x)
is the same as nrow(x)
.
You can also set the number of rows or columns or layers. When setting dimensions, all cell values are dropped.
## S4 method for signature 'SpatRaster' ncol(x) ## S4 method for signature 'SpatRaster' nrow(x) ## S4 method for signature 'SpatRaster' nlyr(x) ## S4 method for signature 'SpatRaster' ncell(x) ## S4 method for signature 'SpatRaster' nsrc(x) ## S4 replacement method for signature 'SpatRaster,numeric' ncol(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' nrow(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' nlyr(x)<-value ## S4 method for signature 'SpatRaster' res(x) ## S4 replacement method for signature 'SpatRaster,numeric' res(x)<-value ## S4 method for signature 'SpatRaster' xres(x) ## S4 method for signature 'SpatRaster' yres(x) ## S4 method for signature 'SpatVector' ncol(x) ## S4 method for signature 'SpatVector' nrow(x) ## S4 method for signature 'SpatVector' length(x)
## S4 method for signature 'SpatRaster' ncol(x) ## S4 method for signature 'SpatRaster' nrow(x) ## S4 method for signature 'SpatRaster' nlyr(x) ## S4 method for signature 'SpatRaster' ncell(x) ## S4 method for signature 'SpatRaster' nsrc(x) ## S4 replacement method for signature 'SpatRaster,numeric' ncol(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' nrow(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' nlyr(x)<-value ## S4 method for signature 'SpatRaster' res(x) ## S4 replacement method for signature 'SpatRaster,numeric' res(x)<-value ## S4 method for signature 'SpatRaster' xres(x) ## S4 method for signature 'SpatRaster' yres(x) ## S4 method for signature 'SpatVector' ncol(x) ## S4 method for signature 'SpatVector' nrow(x) ## S4 method for signature 'SpatVector' length(x)
x |
SpatRaster or SpatVector or related objects |
value |
For ncol and nrow: positive integer. For res: one or two positive numbers |
integer
r <- rast() ncol(r) nrow(r) nlyr(r) dim(r) nsrc(r) ncell(r) rr <- c(r,r) nlyr(rr) nsrc(rr) ncell(rr) nrow(r) <- 18 ncol(r) <- 36 # equivalent to dim(r) <- c(18, 36) dim(r) dim(r) <- c(10, 10, 5) dim(r) xres(r) yres(r) res(r) res(r) <- 1/120 # different xres and yres res(r) <- c(1/120, 1/60)
r <- rast() ncol(r) nrow(r) nlyr(r) dim(r) nsrc(r) ncell(r) rr <- c(r,r) nlyr(rr) nsrc(rr) ncell(rr) nrow(r) <- 18 ncol(r) <- 36 # equivalent to dim(r) <- c(18, 36) dim(r) dim(r) <- c(10, 10, 5) dim(r) xres(r) yres(r) res(r) res(r) <- 1/120 # different xres and yres res(r) <- c(1/120, 1/60)
The direction (azimuth) to or from the nearest cell that is not NA
. The direction is expressed in radians, unless you use argument degrees=TRUE
.
## S4 method for signature 'SpatRaster' direction(x, from=FALSE, degrees=FALSE, filename="", ...)
## S4 method for signature 'SpatRaster' direction(x, from=FALSE, degrees=FALSE, filename="", ...)
x |
SpatRaster |
filename |
Character. Output filename (optional) |
degrees |
Logical. If |
from |
Logical. Default is |
... |
Additional arguments as for |
SpatRaster
r <- rast(ncol=36,nrow=18, crs="+proj=merc") values(r) <- NA r[306] <- 1 b <- direction(r, degrees=TRUE) plot(b) crs(r) <- "+proj=longlat" b <- direction(r) plot(b)
r <- rast(ncol=36,nrow=18, crs="+proj=merc") values(r) <- NA r[306] <- 1 b <- direction(r, degrees=TRUE) plot(b) crs(r) <- "+proj=longlat" b <- direction(r) plot(b)
SpatRaster
: Create a SpatRaster with a higher resolution (smaller cells). The values in the new SpatRaster are the same as in the larger original cells.
SpatVector
: Separate multi-objects (points, lines, polygons) into single objects; or further into segments (for lines or polygons).
## S4 method for signature 'SpatRaster' disagg(x, fact, method="near", filename="", ...) ## S4 method for signature 'SpatVector' disagg(x, segments=FALSE)
## S4 method for signature 'SpatRaster' disagg(x, fact, method="near", filename="", ...) ## S4 method for signature 'SpatVector' disagg(x, segments=FALSE)
x |
SpatRaster or SpatVector |
fact |
positive integer. Aggregation factor expressed as number of cells in each direction (horizontally and vertically). Or two integers (horizontal and vertical aggregation factor) or three integers (when also aggregating over layers) |
method |
character. Either "near" for nearest or "bilinear" for bilinear interpolation |
segments |
logical. Should (poly-)lines or polygons be disaggregated into their line-segments? |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(ncols=10, nrows=10) rd <- disagg(r, fact=c(10, 2)) ncol(rd) nrow(rd) values(r) <- 1:ncell(r) rd <- disagg(r, fact=c(4, 2))
r <- rast(ncols=10, nrows=10) rd <- disagg(r, fact=c(10, 2)) ncol(rd) nrow(rd) values(r) <- 1:ncell(r) rd <- disagg(r, fact=c(4, 2))
If x
is a SpatRaster:
If y
is missing
this method computes the distance, for all cells that are NA
in SpatRaster x
to the nearest cell that is not NA
(or other values, see arguments "target" and "exclude").
If y
is a numeric value, the cells with that value are ignored. That is, distance to or from these cells is not computed (only if grid=FALSE
).
If y
is a SpatVector, the distance to that SpatVector is computed for all cells. For lines and polygons this is done after rasterization; and only the overlapping areas of the vector and raster are considered (for now).
The distance is always expressed in meter if the coordinate reference system is longitude/latitude, and in map units otherwise. Map units are typically meter, but inspect crs(x)
if in doubt.
Results are more precise, sometimes much more precise, when using longitude/latitude rather than a planar coordinate reference system, as these distort distance.
If x
is a SpatVector:
If y
is missing
, a distance matrix between all objects in x
is computed. A distance matrix object of class "dist" is returned.
If y
is a SpatVector the geographic distance between all objects is computed (and a matrix is returned). If both sets have the same number of points, and pairwise=TRUE
, the distance between each pair of objects is computed, and a vector is returned.
The distance is always expressed in meter, except when the coordinate reference system is longitude/latitude AND one of the SpatVector(s) consists of lines or polygons. In that case the distance is in degrees, and thus not very useful (this will be fixed soon). Otherwise, results are more precise, sometimes much more precise, when using longitude/latitude rather than a planar coordinate reference system, as these distort distance.
If x
is a matrix:
x
should consist of two columns, the first with "x" (or longitude) and the second with "y" coordinates (or latitude). If y
is a also a matrix, the distance between each points in x
and all points in y
is computed, unless pairwise=TRUE
If y
is missing, the distance between each points in x
with all other points in x
is computed, unless sequential=TRUE
## S4 method for signature 'SpatRaster,missing' distance(x, y, target=NA, exclude=NULL, unit="m", haversine=TRUE, filename="", ...) ## S4 method for signature 'SpatRaster,SpatVector' distance(x, y, unit="m", rasterize=FALSE, haversine=TRUE, filename="", ...) ## S4 method for signature 'SpatVector,ANY' distance(x, y, sequential=FALSE, pairs=FALSE, symmetrical=TRUE, unit="m") ## S4 method for signature 'SpatVector,SpatVector' distance(x, y, pairwise=FALSE, unit="m") ## S4 method for signature 'matrix,matrix' distance(x, y, lonlat, pairwise=FALSE, unit="m") ## S4 method for signature 'matrix,missing' distance(x, y, lonlat, sequential=FALSE, pairs=FALSE, symmetrical=TRUE, unit="m")
## S4 method for signature 'SpatRaster,missing' distance(x, y, target=NA, exclude=NULL, unit="m", haversine=TRUE, filename="", ...) ## S4 method for signature 'SpatRaster,SpatVector' distance(x, y, unit="m", rasterize=FALSE, haversine=TRUE, filename="", ...) ## S4 method for signature 'SpatVector,ANY' distance(x, y, sequential=FALSE, pairs=FALSE, symmetrical=TRUE, unit="m") ## S4 method for signature 'SpatVector,SpatVector' distance(x, y, pairwise=FALSE, unit="m") ## S4 method for signature 'matrix,matrix' distance(x, y, lonlat, pairwise=FALSE, unit="m") ## S4 method for signature 'matrix,missing' distance(x, y, lonlat, sequential=FALSE, pairs=FALSE, symmetrical=TRUE, unit="m")
x |
SpatRaster, SpatVector, or two-column matrix with coordinates (x,y) or (lon,lat) |
y |
missing, numeric, SpatVector, or two-column matrix |
target |
numeric. The value of the cells for which distances to cells that are not |
exclude |
numeric. The value of the cells that should not be considered for computing distances |
unit |
character. Can be either "m" or "km" |
haversine |
logical. Use the haversine formula for lon/lat data use the haversine formula? If |
rasterize |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
sequential |
logical. If |
pairwise |
logical. If |
lonlat |
logical. If |
pairs |
logical. If |
symmetrical |
logical. If |
SpatRaster or numeric or matrix or distance matrix (object of class "dist")
A distance matrix can be coerced into a regular matrix with as.matrix
Karney, C.F.F., 2013. Algorithms for geodesics, J. Geodesy 87: 43-55. doi:10.1007/s00190-012-0578-z.
#lonlat r <- rast(ncols=36, nrows=18, crs="+proj=longlat +datum=WGS84") r[500] <- 1 d <- distance(r) plot(d / 100000) #planar rr <- rast(ncols=36, nrows=18, crs="+proj=utm +zone=1 +datum=WGS84") rr[500] <- 1 d <- distance(rr) rr[3:10, 3:10] <- 99 e <- distance(rr, exclude=99) p1 <- vect(rbind(c(0,0), c(90,30), c(-90,-30)), crs="+proj=longlat +datum=WGS84") dp <- distance(r, p1) d <- distance(p1) d as.matrix(d) p2 <- vect(rbind(c(30,-30), c(25,40), c(-9,-3)), crs="+proj=longlat +datum=WGS84") dd <- distance(p1, p2) dd pd <- distance(p1, p2, pairwise=TRUE) pd pd == diag(dd) # polygons, lines crs <- "+proj=utm +zone=1" p1 <- vect("POLYGON ((0 0, 8 0, 8 9, 0 9, 0 0))", crs=crs) p2 <- vect("POLYGON ((5 6, 15 6, 15 15, 5 15, 5 6))", crs=crs) p3 <- vect("POLYGON ((2 12, 3 12, 3 13, 2 13, 2 12))", crs=crs) p <- rbind(p1, p2, p3) L1 <- vect("LINESTRING(1 11, 4 6, 10 6)", crs=crs) L2 <- vect("LINESTRING(8 14, 12 10)", crs=crs) L3 <- vect("LINESTRING(1 8, 12 14)", crs=crs) lns <- rbind(L1, L2, L3) pts <- vect(cbind(c(7,10,10), c(3,5,6)), crs=crs) distance(p1,p3) distance(p) distance(p,pts) distance(p,lns) distance(pts,lns)
#lonlat r <- rast(ncols=36, nrows=18, crs="+proj=longlat +datum=WGS84") r[500] <- 1 d <- distance(r) plot(d / 100000) #planar rr <- rast(ncols=36, nrows=18, crs="+proj=utm +zone=1 +datum=WGS84") rr[500] <- 1 d <- distance(rr) rr[3:10, 3:10] <- 99 e <- distance(rr, exclude=99) p1 <- vect(rbind(c(0,0), c(90,30), c(-90,-30)), crs="+proj=longlat +datum=WGS84") dp <- distance(r, p1) d <- distance(p1) d as.matrix(d) p2 <- vect(rbind(c(30,-30), c(25,40), c(-9,-3)), crs="+proj=longlat +datum=WGS84") dd <- distance(p1, p2) dd pd <- distance(p1, p2, pairwise=TRUE) pd pd == diag(dd) # polygons, lines crs <- "+proj=utm +zone=1" p1 <- vect("POLYGON ((0 0, 8 0, 8 9, 0 9, 0 0))", crs=crs) p2 <- vect("POLYGON ((5 6, 15 6, 15 15, 5 15, 5 6))", crs=crs) p3 <- vect("POLYGON ((2 12, 3 12, 3 13, 2 13, 2 12))", crs=crs) p <- rbind(p1, p2, p3) L1 <- vect("LINESTRING(1 11, 4 6, 10 6)", crs=crs) L2 <- vect("LINESTRING(8 14, 12 10)", crs=crs) L3 <- vect("LINESTRING(1 8, 12 14)", crs=crs) lns <- rbind(L1, L2, L3) pts <- vect(cbind(c(7,10,10), c(3,5,6)), crs=crs) distance(p1,p3) distance(p) distance(p,pts) distance(p,lns) distance(pts,lns)
Create the dots for a dot-density map and add these to the current map. Dot-density maps are made to display count data. For example of population counts, where each dot represents n persons. The dots are returned as a SpatVector
. It there is an active graphics device, the dots are added to it with points
.
## S4 method for signature 'SpatVector' dots(x, field, size, ...)
## S4 method for signature 'SpatVector' dots(x, field, size, ...)
x |
SpatVector |
field |
character of numeric indicating field name. Or numeric vector of the same length as |
size |
positive number indicating the number of cases associated with each dot |
... |
graphical arguments passed to |
SpatVector (invisibly)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v$population <- 1000*(1:12)^2 plot(v, lwd=3, col="light gray", border="white") d <- dots(v, "population", 1000, col="red", cex=.75) lines(v) d
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v$population <- 1000*(1:12)^2 plot(v, lwd=3, col="light gray", border="white") d <- dots(v, "population", 1000, col="red", cex=.75) lines(v) d
Draw on a plot (map) to get a SpatVector or SpatExtent object for later use. After calling the function, start clicking on the map. When you are done, press ESC
. You can also preset the maximum number of clicks.
This does to work well on the default RStudio plotting device. To work around that, you can first run dev.new(noRStudioGD = TRUE)
which will create a separate window for plotting, then use plot()
followed by click()
and click on the map.
## S4 method for signature 'character' draw(x="extent", col="red", lwd=2, id=FALSE, n=1000, xpd=TRUE, ...)
## S4 method for signature 'character' draw(x="extent", col="red", lwd=2, id=FALSE, n=1000, xpd=TRUE, ...)
x |
character. The type of object to draw. One of "extent", "polygon", "line", or "points" |
col |
the color to be used |
lwd |
the width of the lines to be drawn |
id |
logical. If |
n |
the maximum number of clicks (does not apply when |
xpd |
logical. If |
... |
additional graphics arguments for drawing |
SpatVector or SpatExtent
Elongate SpatVector lines
## S4 method for signature 'SpatVector' elongate(x, length=1, flat=FALSE)
## S4 method for signature 'SpatVector' elongate(x, length=1, flat=FALSE)
x |
SpatVector |
length |
positive number indicating how much the lines should be elongated at each end. The unit is meter is the crs is lonlat and it is the same as the linear unit of the crs on other cases (also meter in most cases) |
flat |
logical. If |
SpatVector
v <- vect(cbind(c(0,1,2), c(0,0,2)), "lines", crs="lonlat") e <- elongate(v, 100000) plot(e) points(e) geom(e)
v <- vect(cbind(c(0,1,2), c(0,0,2)), "lines", crs="lonlat") e <- elongate(v, 100000) plot(e) points(e) geom(e)
Erase parts of a SpatVector with another SpatVector or with a SpatExtent. You can also erase (parts of) polygons with the other polygons of the same SpatVector.
## S4 method for signature 'SpatVector,SpatVector' erase(x, y) ## S4 method for signature 'SpatVector,missing' erase(x, sequential=TRUE) ## S4 method for signature 'SpatVector,SpatExtent' erase(x, y)
## S4 method for signature 'SpatVector,SpatVector' erase(x, y) ## S4 method for signature 'SpatVector,missing' erase(x, sequential=TRUE) ## S4 method for signature 'SpatVector,SpatExtent' erase(x, y)
x |
SpatVector |
y |
SpatVector or SpatExtent |
sequential |
logical. Should areas be erased sequentially? See Details |
If polygons are erased sequentially, everything that is covered by the first polygon is removed from all other polygons, then everything that is covered by (what is remaining of) the second polygon is removed, etc.
If polygons are not erased sequentially, all overlapping areas are erased and only the areas covered by a single geometry are returned.
SpatVector or SpatExtent
crop
and intersect
for the inverse.
The equivalent for SpatRaster is mask
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) # polygons with polygons or extent e <- ext(5.6, 6, 49.55, 49.7) x <- erase(v, e) p <- vect("POLYGON ((5.8 49.8, 6 49.9, 6.15 49.8, 6 49.6, 5.8 49.8))") y <- erase(v, p) # lines with polygons lns <- as.lines(rast(v, ncol=10, nrow=10))[12:22] eln <- erase(lns, v) plot(v) lines(lns, col='blue', lwd=4, lty=3) lines(eln, col='red', lwd=2) ## self-erase h <- convHull(v[-12], "NAME_1") he <- erase(h) plot(h, lwd=2, border="red", lty=2) lines(he, col="gray", lwd=3)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) # polygons with polygons or extent e <- ext(5.6, 6, 49.55, 49.7) x <- erase(v, e) p <- vect("POLYGON ((5.8 49.8, 6 49.9, 6.15 49.8, 6 49.6, 5.8 49.8))") y <- erase(v, p) # lines with polygons lns <- as.lines(rast(v, ncol=10, nrow=10))[12:22] eln <- erase(lns, v) plot(v) lines(lns, col='blue', lwd=4, lty=3) lines(eln, col='red', lwd=2) ## self-erase h <- convHull(v[-12], "NAME_1") he <- erase(h) plot(h, lwd=2, border="red", lty=2) lines(he, col="gray", lwd=3)
Compute the area covered by polygons or for all raster cells that are not NA
.
This method computes areas for longitude/latitude rasters, as the size of the cells is constant in degrees, but not in square meters. But it can also be important if the coordinate reference system is planar, but not equal-area.
For vector data, the best way to compute area is to use the longitude/latitude CRS. This is contrary to (erroneous) popular belief that suggest that you should use a planar coordinate reference system. This is done automatically, if transform=TRUE
.
## S4 method for signature 'SpatRaster' expanse(x, unit="m", transform=TRUE, byValue=FALSE, zones=NULL, wide=FALSE, usenames=FALSE) ## S4 method for signature 'SpatVector' expanse(x, unit="m", transform=TRUE)
## S4 method for signature 'SpatRaster' expanse(x, unit="m", transform=TRUE, byValue=FALSE, zones=NULL, wide=FALSE, usenames=FALSE) ## S4 method for signature 'SpatVector' expanse(x, unit="m", transform=TRUE)
x |
SpatRaster or SpatVector |
unit |
character. Output unit of area. One of "m", "km", or "ha" |
transform |
logical. If |
byValue |
logical. If |
zones |
NULL or SpatRaster with the same geometry identifying zones in |
wide |
logical. Should the results be in "wide" rather than "long" format? |
usenames |
logical. If |
SpatRaster: data.frame
with at least two columns ("layer" and "area") and possibly also "value" (if byValue
is TRUE
), and "zone" (if zones
is TRUE
). If x
has no values, the total area of all cells is returned. Otherwise, the area of all cells that are not NA
is returned.
SpatVector: numeric (one value for each (multi-) polygon geometry.
cellSize
for a the size of individual cells of a raster, that can be summed with global
or with zonal
to get the area for different zones.
### SpatRaster r <- rast(nrows=18, ncols=36) v <- 1:ncell(r) v[200:400] <- NA values(r) <- v # summed area in km2 expanse(r, unit="km") # all cells expanse(rast(r), unit="km") r <- rast(ncols=90, nrows=45, ymin=-80, ymax=80) m <- project(r, "+proj=merc") expanse(m, unit="km") expanse(m, unit="km", transform=FALSE) m2 <- c(m, m) values(m2) <- cbind(c(1,2,NA,NA), c(11:14)) expanse(m2, unit="km", byValue=TRUE, wide=TRUE) v <- vect(system.file("ex/lux.shp", package="terra")) r <- rast(system.file("ex/elev.tif", package="terra")) r <- round((r-50)/100) levels(r) <- data.frame(id=1:5, name=c("forest", "water", "urban", "crops", "grass")) expanse(r, byValue=TRUE) g <- rasterize(v, r, "NAME_1") expanse(r, byValue=TRUE, zones=g, wide=TRUE) ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) a <- expanse(v) a sum(a)
### SpatRaster r <- rast(nrows=18, ncols=36) v <- 1:ncell(r) v[200:400] <- NA values(r) <- v # summed area in km2 expanse(r, unit="km") # all cells expanse(rast(r), unit="km") r <- rast(ncols=90, nrows=45, ymin=-80, ymax=80) m <- project(r, "+proj=merc") expanse(m, unit="km") expanse(m, unit="km", transform=FALSE) m2 <- c(m, m) values(m2) <- cbind(c(1,2,NA,NA), c(11:14)) expanse(m2, unit="km", byValue=TRUE, wide=TRUE) v <- vect(system.file("ex/lux.shp", package="terra")) r <- rast(system.file("ex/elev.tif", package="terra")) r <- round((r-50)/100) levels(r) <- data.frame(id=1:5, name=c("forest", "water", "urban", "crops", "grass")) expanse(r, byValue=TRUE) g <- rasterize(v, r, "NAME_1") expanse(r, byValue=TRUE, zones=g, wide=TRUE) ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) a <- expanse(v) a sum(a)
Get a SpatExtent of a SpatRaster, SpatVector, or other spatial objects. Or create a SpatExtent from a vector (length=4; order=xmin, xmax, ymin, ymax)
You can set the extent of a SpatRaster, but you cannot set the extent of a SpatVector (see rescale
for that). See set.ext
to set the extent in place.
## S4 method for signature 'SpatRaster' ext(x, cells=NULL) ## S4 method for signature 'SpatVector' ext(x) ## S4 method for signature 'numeric' ext(x, ..., xy=FALSE) ## S4 replacement method for signature 'SpatRaster,SpatExtent' ext(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' ext(x)<-value
## S4 method for signature 'SpatRaster' ext(x, cells=NULL) ## S4 method for signature 'SpatVector' ext(x) ## S4 method for signature 'numeric' ext(x, ..., xy=FALSE) ## S4 replacement method for signature 'SpatRaster,SpatExtent' ext(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' ext(x)<-value
x |
SpatRaster |
cells |
positive integer (cell) numbers to subset the extent to area covered by these cells |
value |
SpatExtent, or numeric vector of length four (xmin, xmax, ymin, ymax) |
... |
if |
xy |
logical. Set this to |
A SpatExtent
object.
r <- rast() e <- ext(r) as.vector(e) as.character(e) ext(r) <- c(0, 2.5, 0, 1.5) r er <- ext(r) round(er) # go "in" floor(er) # go "out" ceiling(er) ext(r) <- e
r <- rast() e <- ext(r) as.vector(e) as.character(e) ext(r) <- c(0, 2.5, 0, 1.5) r er <- ext(r) round(er) # go "in" floor(er) # go "out" ceiling(er) ext(r) <- e
Enlarge the spatial extent of a SpatRaster. See crop
if you (also) want to remove rows or columns.
Note that you can only enlarge SpatRasters with entire rows and columns. Therefore, the extent of the output SpatRaster may not be exactly the same as the requested. Depending on argument snap
it may be a bit smaller or larger.
You can also enlarge a SpatExtent with this method, or with an algebraic notation (see examples)
## S4 method for signature 'SpatRaster' extend(x, y, snap="near", fill=NA, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatExtent' extend(x, y)
## S4 method for signature 'SpatRaster' extend(x, y, snap="near", fill=NA, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatExtent' extend(x, y)
x |
SpatRaster or SpatExtent |
y |
If |
snap |
character. One of "near", "in", or "out". Used to align |
fill |
numeric. The value used to for the new raster cells |
filename |
character. Output filename |
overwrite |
logical. If |
... |
additional arguments for writing files as in |
SpatRaster or SpatExtent
r <- rast(xmin=-150, xmax=-120, ymin=30, ymax=60, ncols=36, nrows=18) values(r) <- 1:ncell(r) e <- ext(-180, -100, 40, 70) re <- extend(r, e) # extend with a number of rows and columns (at each side) re2 <- extend(r, c(2,10)) # SpatExtent e <- ext(r) e extend(e, 10) extend(e, c(10, -10, 0, 20)) # add 10 columns / rows on all sides e + 10 # double extent e * 2 # increase extent by 25% e * 1.25
r <- rast(xmin=-150, xmax=-120, ymin=30, ymax=60, ncols=36, nrows=18) values(r) <- 1:ncell(r) e <- ext(-180, -100, 40, 70) re <- extend(r, e) # extend with a number of rows and columns (at each side) re2 <- extend(r, c(2,10)) # SpatExtent e <- ext(r) e extend(e, 10) extend(e, c(10, -10, 0, 20)) # add 10 columns / rows on all sides e + 10 # double extent e * 2 # increase extent by 25% e * 1.25
Extract values from a SpatRaster for a set of locations. The locations can be a SpatVector (points, lines, polygons), a data.frame or matrix with (x, y) or (longitude, latitude – in that order!) coordinates, or a vector with cell numbers.
When argument y
is a SpatVector
the first column has the ID (record number) of the SpatVector
used (unless you set ID=FALSE
).
Alternatively, you can use zonal
after using rasterize
with a SpatVector
(this may be more efficient in some cases).
## S4 method for signature 'SpatRaster,SpatVector' extract(x, y, fun=NULL, method="simple", cells=FALSE, xy=FALSE, ID=TRUE, weights=FALSE, exact=FALSE, touches=is.lines(y), small=TRUE, layer=NULL, bind=FALSE, raw=FALSE, ...) ## S4 method for signature 'SpatRaster,SpatExtent' extract(x, y, cells=FALSE, xy=FALSE) ## S4 method for signature 'SpatRaster,matrix' extract(x, y, cells=FALSE, method="simple") ## S4 method for signature 'SpatRaster,numeric' extract(x, y, xy=FALSE, raw=FALSE) ## S4 method for signature 'SpatVector,SpatVector' extract(x, y)
## S4 method for signature 'SpatRaster,SpatVector' extract(x, y, fun=NULL, method="simple", cells=FALSE, xy=FALSE, ID=TRUE, weights=FALSE, exact=FALSE, touches=is.lines(y), small=TRUE, layer=NULL, bind=FALSE, raw=FALSE, ...) ## S4 method for signature 'SpatRaster,SpatExtent' extract(x, y, cells=FALSE, xy=FALSE) ## S4 method for signature 'SpatRaster,matrix' extract(x, y, cells=FALSE, method="simple") ## S4 method for signature 'SpatRaster,numeric' extract(x, y, xy=FALSE, raw=FALSE) ## S4 method for signature 'SpatVector,SpatVector' extract(x, y)
x |
SpatRaster or SpatVector of polygons |
y |
SpatVector (points, lines, or polygons). Alternatively, for points, a 2-column matrix or data.frame (x, y) or (lon, lat). Or a vector with cell numbers |
fun |
function to summarize the extracted data by line or polygon geometry. You can use |
method |
character. method for extracting values with points ("simple" or "bilinear"). With "simple" values for the cell a point falls in are returned. With "bilinear" the returned values are interpolated from the values of the four nearest raster cells |
cells |
logical. If |
xy |
logical. If |
ID |
logical. Should an ID column be added? If so, the first column returned has the IDs (record numbers) of |
weights |
logical. If |
exact |
logical. If |
touches |
logical. If |
small |
logical. If |
layer |
character or numeric to select the layer to extract from for each geometry. If |
bind |
logical. If |
raw |
logical. If |
... |
additional arguments to |
data.frame, matrix or SpatVector
values, zonal, extractAlong, extractRange, rapp
r <- rast(ncols=5, nrows=5, xmin=0, xmax=5, ymin=0, ymax=5) values(r) <- 1:25 xy <- rbind(c(0.5,0.5), c(2.5,2.5)) p <- vect(xy, crs="+proj=longlat +datum=WGS84") extract(r, xy) extract(r, p) r[1,] r[5] r[,5] r[c(0:2, 99:101)] f <- system.file("ex/meuse.tif", package="terra") r <- rast(f) xy <- cbind(179000, 330000) xy <- rbind(xy-100, xy, xy+1000) extract(r, xy) p <- vect(xy) g <- geom(p) g extract(r, p) x <- r + 10 extract(x, p) i <- cellFromXY(r, xy) x[i] r[i] y <- c(x,x*2,x*3) y[i] ## extract with a polygon f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v <- v[1:2,] rf <- system.file("ex/elev.tif", package="terra") x <- rast(rf) extract(x, v, mean, na.rm=TRUE) z <- rast(v, resolution=.1, names="test") values(z) <- 1:ncell(z) e <- extract(z, v, ID=TRUE) e tapply(e[,2], e[,1], mean, na.rm=TRUE) x <- c(z, z*2, z/3) names(x) <- letters[1:3] e <- extract(x, v, ID=TRUE) de <- data.frame(e) aggregate(de[,2:4], de[,1,drop=FALSE], mean)
r <- rast(ncols=5, nrows=5, xmin=0, xmax=5, ymin=0, ymax=5) values(r) <- 1:25 xy <- rbind(c(0.5,0.5), c(2.5,2.5)) p <- vect(xy, crs="+proj=longlat +datum=WGS84") extract(r, xy) extract(r, p) r[1,] r[5] r[,5] r[c(0:2, 99:101)] f <- system.file("ex/meuse.tif", package="terra") r <- rast(f) xy <- cbind(179000, 330000) xy <- rbind(xy-100, xy, xy+1000) extract(r, xy) p <- vect(xy) g <- geom(p) g extract(r, p) x <- r + 10 extract(x, p) i <- cellFromXY(r, xy) x[i] r[i] y <- c(x,x*2,x*3) y[i] ## extract with a polygon f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v <- v[1:2,] rf <- system.file("ex/elev.tif", package="terra") x <- rast(rf) extract(x, v, mean, na.rm=TRUE) z <- rast(v, resolution=.1, names="test") values(z) <- 1:ncell(z) e <- extract(z, v, ID=TRUE) e tapply(e[,2], e[,1], mean, na.rm=TRUE) x <- c(z, z*2, z/3) names(x) <- letters[1:3] e <- extract(x, v, ID=TRUE) de <- data.frame(e) aggregate(de[,2:4], de[,1,drop=FALSE], mean)
Extract raster values along a line. That is, the returned values are ordered along the line. That is not the case with extract
extractAlong(x, y, ID=TRUE, cells=FALSE, xy=FALSE, online=FALSE, bilinear=TRUE)
extractAlong(x, y, ID=TRUE, cells=FALSE, xy=FALSE, online=FALSE, bilinear=TRUE)
x |
SpatRaster |
y |
SpatVector with lines geometry |
ID |
logical. Should an ID column be added? If so, the first column returned has the IDs (record numbers) of input SpatVector |
cells |
logical. If |
xy |
logical. If |
online |
logical. If |
bilinear |
logical. If |
data.frame
r <- rast(ncols=36, nrows=18, vals=1:(18*36)) cds1 <- rbind(c(-50,0), c(0,60), c(40,5), c(15,-45), c(-10,-25)) cds2 <- rbind(c(80,20), c(140,60), c(160,0), c(140,-55)) lines <- vect(list(cds1, cds2), "lines") extractAlong(r, lines)
r <- rast(ncols=36, nrows=18, vals=1:(18*36)) cds1 <- rbind(c(-50,0), c(0,60), c(40,5), c(15,-45), c(-10,-25)) cds2 <- rbind(c(80,20), c(140,60), c(160,0), c(140,-55)) lines <- vect(list(cds1, cds2), "lines") extractAlong(r, lines)
Extract values from a SpatRaster for a set of locations and a range of layers. To extract values for a single or all layers, use extract
## S4 method for signature 'SpatRaster' extractRange(x, y, first, last, lyr_fun=NULL, geom_fun=NULL, ID=FALSE, na.rm=TRUE, ...)
## S4 method for signature 'SpatRaster' extractRange(x, y, first, last, lyr_fun=NULL, geom_fun=NULL, ID=FALSE, na.rm=TRUE, ...)
x |
SpatRaster |
y |
SpatVector (points, lines, or polygons). Alternatively, for points, a 2-column matrix or data.frame (x, y) or (lon, lat). Or a vector with cell numbers |
first |
layer name of number, indicating the first layer in the range of layers to be considered |
last |
layer name or number, indicating the last layer in the range to be considered |
lyr_fun |
function to summarize the extracted data across layers |
geom_fun |
function to summarize the extracted data for each line or polygon geometry. Ignored if |
ID |
logical. Should an ID column be added? If so, the first column returned has the IDs (record numbers) of |
na.rm |
logical. Should missing values be ignored? |
... |
additional arguments passed to |
numeric or data.frame
r <- rast(system.file("ex/logo.tif", package="terra")) xy <- data.frame(c(50,80), c(30, 60)) extract(r, xy) extract(r, xy, layer=c("red", "green")) extractRange(r, xy, first=1:2, last=3:2, lyr_fun=sum)
r <- rast(system.file("ex/logo.tif", package="terra")) xy <- data.frame(c(50,80), c(30, 60)) extract(r, xy) extract(r, xy, layer=c("red", "green")) extractRange(r, xy, first=1:2, last=3:2, lyr_fun=sum)
The minimum and maximum value of a SpatRaster are returned or computed (from a file on disk if necessary) and stored in the object.
## S4 method for signature 'SpatRaster' minmax(x, compute=FALSE) ## S4 method for signature 'SpatRaster' hasMinMax(x) ## S4 method for signature 'SpatRaster' setMinMax(x, force=FALSE)
## S4 method for signature 'SpatRaster' minmax(x, compute=FALSE) ## S4 method for signature 'SpatRaster' hasMinMax(x) ## S4 method for signature 'SpatRaster' setMinMax(x, force=FALSE)
x |
SpatRaster |
compute |
logical. If |
force |
logical. If |
minmax: numeric matrix of minimum and maximum cell values by layer
hasMinMax: logical indicating whether the min and max values are available.
setMinMax: nothing. Used for the side-effect of computing the minimum and maximum values of a SpatRaster
r <- rast(system.file("ex/elev.tif", package="terra")) minmax(r)
r <- rast(system.file("ex/elev.tif", package="terra")) minmax(r)
A SpatRaster layer can represent a categorical variable (factor). Like factor
s, SpatRaster categories are stored as integers that have an associated label.
The categories can be inspected with levels
and cats
. They are represented by a data.frame
that must have two or more columns, the first one identifying the (integer) cell values and the other column(s) providing the category labels.
If there are multiple columns with categories, you can set the "active" category to choose the one you want to use.
cats
returns the entire data.frame, whereas levels
only return two columns: the index and the active category.
To set categories for the first layer of a SpatRaster, you can provide levels<-
with a data.frame or a list with a data.frame. To set categories for multiple layers you can provide levels<-
with a list with one element (that either has a data.frame
or is NULL
) for each layer. Use categories
to set the categories for a specific layer or specific layers.
droplevels
removes categories that are not used (declared but not present as values in the raster) if levels=NULL
.
addCats
adds additional categories to a layer that already is categorical. It adds new variables, not new levels of an existing categorical variable.
## S4 method for signature 'SpatRaster' levels(x) ## S4 replacement method for signature 'SpatRaster' levels(x)<-value ## S4 method for signature 'SpatRaster' cats(x, layer) ## S4 method for signature 'SpatRaster' categories(x, layer=1, value, active=1, ...) ## S4 method for signature 'SpatRaster' droplevels(x, level=NULL, layer=1) ## S4 method for signature 'SpatRaster' addCats(x, value, merge=FALSE, layer=1)
## S4 method for signature 'SpatRaster' levels(x) ## S4 replacement method for signature 'SpatRaster' levels(x)<-value ## S4 method for signature 'SpatRaster' cats(x, layer) ## S4 method for signature 'SpatRaster' categories(x, layer=1, value, active=1, ...) ## S4 method for signature 'SpatRaster' droplevels(x, level=NULL, layer=1) ## S4 method for signature 'SpatRaster' addCats(x, value, merge=FALSE, layer=1)
x |
SpatRaster |
layer |
the layer name or number (positive integer); or 0 for all layers |
value |
a data.frame (ID, category) that define the categories. Or |
active |
positive integer, indicating the column in |
level |
the categories to remove for the layer specified with |
merge |
logical. If |
... |
additional arguments (none) |
list of data.frames (levels, cats) or logical (is.factor)
activeCat
, catalyze
, set.cats
, as.factor
, is.factor
set.seed(0) r <- rast(nrows=10, ncols=10) values(r) <- sample(3, ncell(r), replace=TRUE) is.factor(r) cls <- data.frame(id=1:3, cover=c("forest", "water", "urban")) levels(r) <- cls is.factor(r) r plot(r, col=c("green", "blue", "light gray")) text(r, digits=3, cex=.75, halo=TRUE) # raster starts at 3 x <- r + 2 is.factor(x) # Multiple categories d <- data.frame(id=3:5, cover=cls[,2], letters=letters[1:3], value=10:12) levels(x) <- d x # get current index activeCat(x) # set index activeCat(x) <- 3 activeCat(x) activeCat(x) <- "letters" plot(x, col=c("green", "blue", "light gray")) text(x, digits=3, cex=.75, halo=TRUE) r <- as.numeric(x) r p <- as.polygons(x) plot(p, "letters", col=c("green", "blue", "light gray"))
set.seed(0) r <- rast(nrows=10, ncols=10) values(r) <- sample(3, ncell(r), replace=TRUE) is.factor(r) cls <- data.frame(id=1:3, cover=c("forest", "water", "urban")) levels(r) <- cls is.factor(r) r plot(r, col=c("green", "blue", "light gray")) text(r, digits=3, cex=.75, halo=TRUE) # raster starts at 3 x <- r + 2 is.factor(x) # Multiple categories d <- data.frame(id=3:5, cover=cls[,2], letters=letters[1:3], value=10:12) levels(x) <- d x # get current index activeCat(x) # set index activeCat(x) <- 3 activeCat(x) activeCat(x) <- "letters" plot(x, col=c("green", "blue", "light gray")) text(x, digits=3, cex=.75, halo=TRUE) r <- as.numeric(x) r p <- as.polygons(x) plot(p, "letters", col=c("green", "blue", "light gray"))
Remove the holes in SpatVector polygons. If inverse=TRUE
the holes are returned (as polygons).
## S4 method for signature 'SpatVector' fillHoles(x, inverse=FALSE)
## S4 method for signature 'SpatVector' fillHoles(x, inverse=FALSE)
x |
SpatVector |
inverse |
logical. If |
SpatVector
x <- rbind(c(-10,0), c(140,60), c(160,0), c(140,-55)) hole <- rbind(c(80,0), c(105,13), c(120,2), c(105,-13)) z <- rbind(cbind(object=1, part=1, x, hole=0), cbind(object=1, part=1, hole, hole=1)) colnames(z)[3:4] <- c('x', 'y') p <- vect(z, "polygons", atts=data.frame(id=1)) p f <- fillHoles(p) g <- fillHoles(p, inverse=TRUE) plot(p, lwd=16, border="gray", col="light yellow") polys(f, border="blue", lwd=3, density=4, col="orange") polys(g, col="white", lwd=3)
x <- rbind(c(-10,0), c(140,60), c(160,0), c(140,-55)) hole <- rbind(c(80,0), c(105,13), c(120,2), c(105,-13)) z <- rbind(cbind(object=1, part=1, x, hole=0), cbind(object=1, part=1, hole, hole=1)) colnames(z)[3:4] <- c('x', 'y') p <- vect(z, "polygons", atts=data.frame(id=1)) p f <- fillHoles(p) g <- fillHoles(p, inverse=TRUE) plot(p, lwd=16, border="gray", col="light yellow") polys(f, border="blue", lwd=3, density=4, col="orange") polys(g, col="white", lwd=3)
Add empty layers in between existing layers such that the time step between each layer is the same.
See approximate
to estimate values for these layer (and other missing values)
## S4 method for signature 'SpatRaster' fillTime(x, filename="", ...)
## S4 method for signature 'SpatRaster' fillTime(x, filename="", ...)
x |
SpatRaster |
filename |
character. Output filename |
... |
list with named options for writing files as in |
SpatRaster
r <- rast(system.file("ex/logo.tif", package="terra")) s <- c(r, r) time(s) <- as.Date("2001-01-01") + c(0:2, 5:7) time(s) ss <- fillTime(s) time(ss) a <- approximate(ss)
r <- rast(system.file("ex/logo.tif", package="terra")) s <- c(r, r) time(s) <- as.Date("2001-01-01") + c(0:2, 5:7) time(s) ss <- fillTime(s) time(ss) a <- approximate(ss)
Flip the values of a SpatRaster by inverting the order of the rows (vertical=TRUE
) or the columns (vertical=FALSE
).
rev
is the same as a horizontal *and* a vertical flip.
## S4 method for signature 'SpatRaster' flip(x, direction="vertical", filename="", ...) ## S4 method for signature 'SpatVector' flip(x, direction="vertical") ## S4 method for signature 'SpatRaster' rev(x)
## S4 method for signature 'SpatRaster' flip(x, direction="vertical", filename="", ...) ## S4 method for signature 'SpatVector' flip(x, direction="vertical") ## S4 method for signature 'SpatRaster' rev(x)
x |
SpatRaster or SpatVector |
direction |
character. Should (partially) match "vertical" to flip by rows, or "horizontal" to flip by columns |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(nrow=18, ncol=36) m <- matrix(1:ncell(r), nrow=18) values(r) <- as.vector(t(m)) rx <- flip(r, direction="h") values(r) <- as.vector(m) ry <- flip(r, direction="v") v <- rev(r)
r <- rast(nrow=18, ncol=36) m <- matrix(1:ncell(r), nrow=18) values(r) <- as.vector(t(m)) rx <- flip(r, direction="h") values(r) <- as.vector(m) ry <- flip(r, direction="v") v <- rev(r)
Computes flow accumulation or the total contributing area in terms of numbers of cells upstream of each cell.
## S4 method for signature 'SpatRaster' flowAccumulation(x, weight=NULL, filename="", ...)
## S4 method for signature 'SpatRaster' flowAccumulation(x, weight=NULL, filename="", ...)
x |
SpatRaster with flow direction, see |
weight |
SpatRaster with weight/score daa. For example, cell area or precipitation |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
The algorithm is an adaptation of the one proposed by Zhou at al, 2019.
SpatRaster
Emanuele Cordano
Zhou, G., Wei, H. & Fu, S. A fast and simple algorithm for calculating flow accumulation matrices from raster digital elevation. Front. Earth Sci. 13, 317–326 (2019). doi:10.1007/s11707-018-0725-9. Also see: https://ica-abs.copernicus.org/articles/1/434/2019/
elev1 <- array(NA,c(9,9)) elev2 <- elev1 dx <- 1 dy <- 1 for (r in 1:nrow(elev1)) { y <- (r-5)*dx for (c in 1:ncol(elev1)) { x <- (c-5)*dy elev1[r,c] <- 5*(x^2+y^2) elev2[r,c] <- 10+5*(abs(x))-0.001*y } } ## Elevation raster elev1 <- rast(elev1) elev2 <- rast(elev2) t(array(elev1[],rev(dim(elev1)[1:2]))) t(array(elev2[],rev(dim(elev2)[1:2]))) plot(elev1) plot(elev2) ## Flow direction raster flowdir1<- terrain(elev1,v="flowdir") flowdir2<- terrain(elev2,v="flowdir") t(array(flowdir1[],rev(dim(flowdir1)[1:2]))) t(array(flowdir2[],rev(dim(flowdir2)[1:2]))) plot(flowdir1) plot(flowdir2) ## flow_acc1 <- flowAccumulation((flowdir1)) flow_acc2 <- flowAccumulation((flowdir2)) weight <- elev1*0+10 flow_acc1w <- flowAccumulation(flowdir1,weight) flow_acc2w <- flowAccumulation(flowdir2,weight) t(array(flow_acc1w[],rev(dim(flow_acc1w)[1:2]))) t(array(flow_acc2w[],rev(dim(flow_acc2w)[1:2]))) plot(flow_acc1w) plot(flow_acc2w) ## Application wth example elevation data elev <- rast(system.file('ex/elev.tif',package="terra")) flowdir <- terrain(elev,"flowdir") weight <- cellSize(elev,unit="km") flowacc_weight <- flowAccumulation(flowdir,weight) flowacc <- flowAccumulation(flowdir)
elev1 <- array(NA,c(9,9)) elev2 <- elev1 dx <- 1 dy <- 1 for (r in 1:nrow(elev1)) { y <- (r-5)*dx for (c in 1:ncol(elev1)) { x <- (c-5)*dy elev1[r,c] <- 5*(x^2+y^2) elev2[r,c] <- 10+5*(abs(x))-0.001*y } } ## Elevation raster elev1 <- rast(elev1) elev2 <- rast(elev2) t(array(elev1[],rev(dim(elev1)[1:2]))) t(array(elev2[],rev(dim(elev2)[1:2]))) plot(elev1) plot(elev2) ## Flow direction raster flowdir1<- terrain(elev1,v="flowdir") flowdir2<- terrain(elev2,v="flowdir") t(array(flowdir1[],rev(dim(flowdir1)[1:2]))) t(array(flowdir2[],rev(dim(flowdir2)[1:2]))) plot(flowdir1) plot(flowdir2) ## flow_acc1 <- flowAccumulation((flowdir1)) flow_acc2 <- flowAccumulation((flowdir2)) weight <- elev1*0+10 flow_acc1w <- flowAccumulation(flowdir1,weight) flow_acc2w <- flowAccumulation(flowdir2,weight) t(array(flow_acc1w[],rev(dim(flow_acc1w)[1:2]))) t(array(flow_acc2w[],rev(dim(flow_acc2w)[1:2]))) plot(flow_acc1w) plot(flow_acc2w) ## Application wth example elevation data elev <- rast(system.file('ex/elev.tif',package="terra")) flowdir <- terrain(elev,"flowdir") weight <- cellSize(elev,unit="km") flowacc_weight <- flowAccumulation(flowdir,weight) flowacc <- flowAccumulation(flowdir)
Calculate focal ("moving window") values for each cell.
## S4 method for signature 'SpatRaster' focal(x, w=3, fun="sum", ..., na.policy="all", fillvalue=NA, expand=FALSE, silent=TRUE, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' focal(x, w=3, fun="sum", ..., na.policy="all", fillvalue=NA, expand=FALSE, silent=TRUE, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster |
w |
window. The window can be defined as one (for a square) or two numbers (row, col); or with an odd-sized weights matrix. See Details. |
fun |
function that takes multiple numbers, and returns a numeric vector (one or multiple numbers). For example mean, modal, min or max |
... |
additional arguments passed to |
na.policy |
character. Can be used to determine the cells of |
fillvalue |
numeric. The value of the cells in the virtual rows and columns outside of the raster |
expand |
logical. If |
silent |
logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
additional arguments for writing files as in |
focal
The window used must have odd dimensions. If you need even sides, you can use a matrix and add a column or row of NA
's to mask out values.
Window values are typically 1 or NA
to indicate whether a value is used or ignored in computations, respectively. NA
values in w
can be useful for creating non-rectangular (e.g. circular) windows.
A weights matrix of numeric values can also be supplied to w
. In the case of a weights matrix, cells with NA
weights will be ignored, and the rest of the values in the focal window will be multiplied by the corresponding weight prior to 'fun' being applied. Note, na.rm
does not need to be TRUE
if w
contains NA
values as these cells are ignored in computations.
The "mean" function is a special case, where supplying weights to w
will instead calculate a weighted mean.
The "sum" function returns NA
if all focal cells are NA
and na.rm=TRUE
. R would normally return a zero in these cases. See the difference between focal(x, fun=sum, na.rm=TRUE)
and focal(x, fun=\(i) sum(i, na.rm=TRUE))
Example weight matrices
Laplacian filter: filter=matrix(c(0,1,0,1,-4,1,0,1,0), nrow=3)
Sobel filters (for edge detection):
fx=matrix(c(-1,-2,-1,0,0,0,1,2,1), nrow=3)
fy=matrix(c(1,0,-1,2,0,-2,1,0,-1), nrow=3)
SpatRaster
When using global lon/lat rasters, the focal window "wraps around" the date-line.
focalMat
, focalValues
, focal3D
, focalPairs
, focalReg
, focalCpp
r <- rast(ncols=10, nrows=10, ext(0, 10, 0, 10)) values(r) <- 1:ncell(r) f <- focal(r, w=3, fun=function(x, ...) quantile(x, c(.25, .5, .75), ...), na.rm=TRUE) f <- focal(r, w=3, fun="mean") # the following two statements are equivalent: a <- focal(r, w=matrix(1/9, nc=3, nr=3)) b <- focal(r, w=3, fun=mean, na.rm=FALSE) # but this is different d <- focal(r, w=3, fun=mean, na.rm=TRUE) ## illustrating the effect of different ## combinations of na.rm and na.policy v <- vect(system.file("ex/lux.shp", package="terra")) r <- rast(system.file("ex/elev.tif", package="terra")) r[45:50, 45:50] <- NA # also try "mean" or "min" f <- "sum" # na.rm=FALSE plot(focal(r, 5, f) , fun=lines(v)) # na.rm=TRUE plot(focal(r, 5, f, na.rm=TRUE), fun=lines(v)) # only change cells that are NA plot(focal(r, 5, f, na.policy="only", na.rm=TRUE), fun=lines(v)) # do not change cells that are NA plot(focal(r, 5, f, na.policy="omit", na.rm=TRUE), fun=lines(v)) # does not do anything # focal(r, 5, f, na.policy="only", na.rm=FALSE)
r <- rast(ncols=10, nrows=10, ext(0, 10, 0, 10)) values(r) <- 1:ncell(r) f <- focal(r, w=3, fun=function(x, ...) quantile(x, c(.25, .5, .75), ...), na.rm=TRUE) f <- focal(r, w=3, fun="mean") # the following two statements are equivalent: a <- focal(r, w=matrix(1/9, nc=3, nr=3)) b <- focal(r, w=3, fun=mean, na.rm=FALSE) # but this is different d <- focal(r, w=3, fun=mean, na.rm=TRUE) ## illustrating the effect of different ## combinations of na.rm and na.policy v <- vect(system.file("ex/lux.shp", package="terra")) r <- rast(system.file("ex/elev.tif", package="terra")) r[45:50, 45:50] <- NA # also try "mean" or "min" f <- "sum" # na.rm=FALSE plot(focal(r, 5, f) , fun=lines(v)) # na.rm=TRUE plot(focal(r, 5, f, na.rm=TRUE), fun=lines(v)) # only change cells that are NA plot(focal(r, 5, f, na.policy="only", na.rm=TRUE), fun=lines(v)) # do not change cells that are NA plot(focal(r, 5, f, na.policy="omit", na.rm=TRUE), fun=lines(v)) # does not do anything # focal(r, 5, f, na.policy="only", na.rm=FALSE)
Calculate focal ("moving window") values for the three-dimensional neighborhood (window) of focal cells. See focal
for two-dimensional focal computation.
## S4 method for signature 'SpatRaster' focal3D(x, w=3, fun=mean, ..., na.policy="all", fillvalue=NA, pad=FALSE, padvalue=fillvalue, expand=FALSE, silent=TRUE, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' focal3D(x, w=3, fun=mean, ..., na.policy="all", fillvalue=NA, pad=FALSE, padvalue=fillvalue, expand=FALSE, silent=TRUE, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster |
w |
window. A rectangular prism (cuboid) defined by three numbers or by a three-dimensional array. The values are used as weights, and are usually zero, one, NA, or fractions. The window used must have odd dimensions. If you desire to use even sides, you can use an array, and pad the values with rows and/or columns that contain only |
fun |
function that takes multiple numbers, and returns one or multiple numbers for each focal area. For example mean, modal, min or max |
... |
additional arguments passed to |
na.policy |
character. Can be used to determine the cells of |
fillvalue |
numeric. The value of the cells in the virtual rows and columns outside of the raster |
pad |
logical. Add virtual layers before the first and after the last layer |
padvalue |
numeric. The value of the cells in the virtual layers |
expand |
logical. Add virtual layers before the first or after the last layer that are the same as the first or last layers. If |
silent |
logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
additional arguments for writing files as in |
SpatRaster
r <- rast(system.file("ex/logo.tif", package="terra")) x <- focal3D(r, c(5,5,3), na.rm=TRUE) a <- array(c(0,1,0,1,1,1,0,1,0, rep(1,9), 0,1,0,1,1,1,0,1,0), c(3,3,3)) a[a==0] <- NA z <- focal3D(r, a, na.rm=TRUE)
r <- rast(system.file("ex/logo.tif", package="terra")) x <- focal3D(r, c(5,5,3), na.rm=TRUE) a <- array(c(0,1,0,1,1,1,0,1,0, rep(1,9), 0,1,0,1,1,1,0,1,0), c(3,3,3)) a[a==0] <- NA z <- focal3D(r, a, na.rm=TRUE)
Calculate focal values with a C++ function that iterates over cells to speed up computations by avoiding an R loop (with apply).
See focal
for an easier to use method.
## S4 method for signature 'SpatRaster' focalCpp(x, w=3, fun, ..., fillvalue=NA, silent=TRUE, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' focalCpp(x, w=3, fun, ..., fillvalue=NA, silent=TRUE, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster |
w |
window. The window can be defined as one (for a square) or two numbers (row, col); or with an odd-sized weights matrix. See the Details section in |
fun |
|
... |
additional arguments to |
fillvalue |
numeric. The value of the cells in the virtual rows and columns outside of the raster |
silent |
logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
additional arguments for writing files as in |
SpatRaster
## Not run: library(Rcpp) cppFunction( 'NumericVector sum_and_multiply(NumericVector x, double m, size_t ni, size_t nw) { NumericVector out(ni); // loop over cells size_t start = 0; for (size_t i=0; i<ni; i++) { size_t end = start + nw; // compute something for a window double v = 0; // loop over the values of a window for (size_t j=start; j<end; j++) { v += x[j]; } out[i] = v * m; start = end; } return out; }' ) nr <- nc <- 10 r <- rast(ncols=nc, nrows=nr, ext= c(0, nc, 0, nr)) values(r) <- 1:ncell(r) raw <- focalCpp(r, w=3, fun=sum_and_multiply, fillvalue=0, m=10) # same as f1 <- focal(r, w=3, fun=sum, fillvalue=0) *10 all(values(f1) == values(raw)) # and as ffun <- function(x, m) { sum(x) * m } f2 <- focal(r, w=3, fun=ffun, fillvalue=0, m=10) # You can also use an R function with focalCpp but this # is not recommended R_sm_iter <- function(x, m, ni, nw) { out <- NULL for (i in 1:ni) { start <- (i-1) * nw + 1 out[i] <- sum(x[start:(start+nw-1)]) * m } out } fr <- focalCpp(r, w=3, fun=R_sm_iter, fillvalue=0, m=10) ## End(Not run)
## Not run: library(Rcpp) cppFunction( 'NumericVector sum_and_multiply(NumericVector x, double m, size_t ni, size_t nw) { NumericVector out(ni); // loop over cells size_t start = 0; for (size_t i=0; i<ni; i++) { size_t end = start + nw; // compute something for a window double v = 0; // loop over the values of a window for (size_t j=start; j<end; j++) { v += x[j]; } out[i] = v * m; start = end; } return out; }' ) nr <- nc <- 10 r <- rast(ncols=nc, nrows=nr, ext= c(0, nc, 0, nr)) values(r) <- 1:ncell(r) raw <- focalCpp(r, w=3, fun=sum_and_multiply, fillvalue=0, m=10) # same as f1 <- focal(r, w=3, fun=sum, fillvalue=0) *10 all(values(f1) == values(raw)) # and as ffun <- function(x, m) { sum(x) * m } f2 <- focal(r, w=3, fun=ffun, fillvalue=0, m=10) # You can also use an R function with focalCpp but this # is not recommended R_sm_iter <- function(x, m, ni, nw) { out <- NULL for (i in 1:ni) { start <- (i-1) * nw + 1 out[i] <- sum(x[start:(start+nw-1)]) * m } out } fr <- focalCpp(r, w=3, fun=R_sm_iter, fillvalue=0, m=10) ## End(Not run)
Make a focal ("moving window") weight matrix for use in the focal
function. The sum of the values adds up to one.
focalMat(x, d, type=c('circle', 'Gauss', 'rectangle'), fillNA=FALSE)
focalMat(x, d, type=c('circle', 'Gauss', 'rectangle'), fillNA=FALSE)
x |
SpatRaster |
d |
numeric. If |
type |
character indicating the type of filter to be returned |
fillNA |
logical. If |
matrix that can be used with focal
r <- rast(ncols=180, nrows=180, xmin=0) focalMat(r, 2, "circle") focalMat(r, c(2,3), "rect") # Gaussian filter for square cells gf <- focalMat(r, 1, "Gauss")
r <- rast(ncols=180, nrows=180, xmin=0) focalMat(r, 2, "circle") focalMat(r, c(2,3), "rect") # Gaussian filter for square cells gf <- focalMat(r, 1, "Gauss")
Calculate values such as a correlation coefficient for focal regions in two neighboring layers. A function is applied to the first and second layer, then to the second and third layer, etc.
## S4 method for signature 'SpatRaster' focalPairs(x, w=3, fun, ..., fillvalue=NA, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' focalPairs(x, w=3, fun, ..., fillvalue=NA, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster with at least two layers |
w |
numeric or matrix to define the focal window. The window an be defined as one (for a square) or two numbers (row, col); or with an odd-sized weights matrix. See the Details section in |
fun |
a function with at least two arguments (one for each layer). There is a built-in function "pearson" (for both the weighted and the unweighted Pearson correlation coefficient. This function has an additional argument |
... |
additional arguments for |
fillvalue |
numeric. The value of the cells in the virtual rows and columns outside of the raster |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
additional arguments for writing files as in |
SpatRaster
layerCor
, focalReg
, focal
, focal3D
r <- rast(system.file("ex/logo.tif", package="terra")) set.seed(0) r[[1]] <- flip(r[[1]], "horizontal") r[[2]] <- flip(r[[2]], "vertical") + init(rast(r,1), runif) r[[3]] <- init(rast(r,1), runif) x <- focalPairs(r, w=5, "pearson", na.rm=TRUE) plot(x) # suppress warning "the standard deviation is zero" suppressWarnings(x <- focalPairs(r, w=5, "pearson", use="complete.obs")) z <- focalPairs(r, w=9, function(x, y) mean(x) + mean(y))
r <- rast(system.file("ex/logo.tif", package="terra")) set.seed(0) r[[1]] <- flip(r[[1]], "horizontal") r[[2]] <- flip(r[[2]], "vertical") + init(rast(r,1), runif) r[[3]] <- init(rast(r,1), runif) x <- focalPairs(r, w=5, "pearson", na.rm=TRUE) plot(x) # suppress warning "the standard deviation is zero" suppressWarnings(x <- focalPairs(r, w=5, "pearson", use="complete.obs")) z <- focalPairs(r, w=9, function(x, y) mean(x) + mean(y))
Calculate values for a moving-window by comparing the value in one layers with the values in one to many other layers. A typical case is the computation of the coefficients for a focal linear regression model.
## S4 method for signature 'SpatRaster' focalReg(x, w=3, fun="ols", ..., fillvalue=NA, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' focalReg(x, w=3, fun="ols", ..., fillvalue=NA, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster with at least two layers. The first is the "Y" (dependent) variable and the remainder are the "X" (independent) variables |
w |
numeric or matrix to define the focal window. The window an be defined as one (for a square) or two numbers (row, col); or with an odd-sized weights matrix. See the Details section in |
fun |
a function with at least two arguments (one for each layer). There is a built-in function "ols" for both the weighted and unweighted Ordinary Least Square regression. This function has an additional argument |
... |
additional arguments for |
fillvalue |
numeric. The value of the cells in the virtual rows and columns outside of the raster |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
additional arguments for writing files as in |
SpatRaster
r <- rast(ncols=10, nrows=10, ext(0, 10, 0, 10)) values(r) <- 1:ncell(r) x <- c(r, init(r, runif) * r) f <- focalReg(x, 3)
r <- rast(ncols=10, nrows=10, ext(0, 10, 0, 10)) values(r) <- 1:ncell(r) x <- c(r, init(r, runif) * r) f <- focalReg(x, 3)
Get a matrix in which each row had the focal values of a cell. These are the values of a cell and a rectangular window around it.
## S4 method for signature 'SpatRaster' focalValues(x, w=3, row=1, nrows=nrow(x), fill=NA)
## S4 method for signature 'SpatRaster' focalValues(x, w=3, row=1, nrows=nrow(x), fill=NA)
x |
SpatRaster or SpatVector |
w |
window. The window can be defined as one (for a square) or two odd numbers (row, col); or with an odd sized matrix |
row |
positive integer. Row number to start from, should be between 1 and nrow(x) |
nrows |
positive integer. How many rows? |
fill |
numeric used as values for imaginary cells outside the raster |
matrix
r <- rast(ncol=4, nrow=4, crs="+proj=utm +zone=1 +datum=WGS84") values(r) <- 1:ncell(r) focalValues(r)
r <- rast(ncol=4, nrow=4, crs="+proj=utm +zone=1 +datum=WGS84") values(r) <- 1:ncell(r) focalValues(r)
Assure that the nodes of outer rings of polygons are in counter-clockwise order.
## S4 method for signature 'SpatVector' forceCCW(x)
## S4 method for signature 'SpatVector' forceCCW(x)
x |
SpatVector of polygons |
SpatVector
p <- vect("POLYGON ((2 45, 2 55, 18 55, 18 45, 2 45))") pcc <- forceCCW(p) geom(pcc, wkt=TRUE)
p <- vect("POLYGON ((2 45, 2 55, 18 55, 18 45, 2 45))") pcc <- forceCCW(p) geom(pcc, wkt=TRUE)
Frequency table of the values of a SpatRaster. NA
s are not counted unless value=NA
.
You can provide a SpatVector or additional SpatRaster to define zones for which to do tabulations.
## S4 method for signature 'SpatRaster' freq(x, digits=0, value=NULL, bylayer=TRUE, usenames=FALSE, zones=NULL, wide=FALSE)
## S4 method for signature 'SpatRaster' freq(x, digits=0, value=NULL, bylayer=TRUE, usenames=FALSE, zones=NULL, wide=FALSE)
x |
SpatRaster |
digits |
integer. Used for rounding the values before tabulation. Ignored if |
value |
numeric. An optional single value to only count the number of cells with that value. This value can be |
bylayer |
logical. If |
usenames |
logical. If |
zones |
SpatRaster or SpatVector to define zones for which the tabulation should be done |
wide |
logical. Should the results by "wide" instead of "long"? |
A data.frame
with 3 columns (layer, value, count) unless bylayer=FALSE
in which case adata.frame
with two columns is returned (value, count).
r <- rast(nrows=10, ncols=10) set.seed(2) values(r) <- sample(5, ncell(r), replace=TRUE) freq(r) x <- c(r, r/3) freq(x, bylayer=FALSE) freq(x) freq(x, digits=1) freq(x, digits=-1) freq(x, value=5)
r <- rast(nrows=10, ncols=10) set.seed(2) values(r) <- sample(5, ncell(r), replace=TRUE) freq(r) x <- c(r, r/3) freq(x, bylayer=FALSE) freq(x) freq(x, digits=1) freq(x, digits=-1) freq(x, value=5)
Get the gaps between polygons of a SpatVector
## S4 method for signature 'SpatVector' gaps(x)
## S4 method for signature 'SpatVector' gaps(x)
x |
SpatVector |
SpatVector
sharedPaths
, topology
, and
fillHoles
to get or remove polygon holes
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) h <- convHull(v[-12], "NAME_1") g <- gaps(h)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) h <- convHull(v[-12], "NAME_1") g <- gaps(h)
Set the GDAL
warning level or get a data.frame
with the available GDAL drivers (file formats), or, if warn=NA
and drivers=FALSE
, you get the version numbers of one or all of the GDAL, PROJ and GEOS libraries.
GDAL
is the software library that terra builds on to read and write spatial data and for some raster data processing. PROJ
is used for transformation of coordinates ("projection") and GEOS
is used for geometric operations with vector data.
gdal(warn=NA, drivers=FALSE, lib="gdal") gdalCache(size=NA) setGDALconfig(option, value="") getGDALconfig(option)
gdal(warn=NA, drivers=FALSE, lib="gdal") gdalCache(size=NA) setGDALconfig(option, value="") getGDALconfig(option)
warn |
If |
drivers |
logical. If |
lib |
character. "gdal", "proj", or "geos", or any other value to get the versions numbers of all three |
size |
numeric. The new cache size in MB |
option |
character. GDAL configuration option name, or a "name=value" string (in which case the value argument is ignored |
value |
character. value for GDAL configuration option. Use "" to reset it to its default value |
character
describe
for file-level metadata "GDALinfo"
gdal() gdal(2) head(gdal(drivers=TRUE))
gdal() gdal(2) head(gdal(drivers=TRUE))
Get the geometry of a SpatVector. If wkt=FALSE
, this is a five-column matrix or data.frame: the vector object ID, the IDs for the parts of each object (e.g. five polygons that together are one spatial object), the x (longitude) and y (latitude) coordinates, and a flag indicating whether the part is a "hole" (only relevant for polygons).
If wkt=TRUE
, the "well-known text" representation is returned as a character vector.
## S4 method for signature 'SpatVector' geom(x, wkt=FALSE, hex=FALSE, df=FALSE, list=FALSE, xnm="x", ynm="y")
## S4 method for signature 'SpatVector' geom(x, wkt=FALSE, hex=FALSE, df=FALSE, list=FALSE, xnm="x", ynm="y")
x |
SpatVector |
wkt |
logical. If |
hex |
logical. If |
df |
logical. If |
list |
logical. If |
xnm |
character. If |
ynm |
character. If |
matrix, vector, data.frame, or list
x1 <- rbind(c(-175,-20), c(-140,55), c(10, 0), c(-140,-60)) x2 <- rbind(c(-125,0), c(0,60), c(40,5), c(15,-45)) x3 <- rbind(c(-10,0), c(140,60), c(160,0), c(140,-55)) x4 <- rbind(c(80,0), c(105,13), c(120,2), c(105,-13)) z <- rbind(cbind(object=1, part=1, x1), cbind(object=2, part=1, x2), cbind(object=3, part=1, x3), cbind(object=3, part=2, x4)) colnames(z)[3:4] <- c('x', 'y') z <- cbind(z, hole=0) z[(z[, "object"]==3 & z[,"part"]==2), "hole"] <- 1 p <- vect(z, "polygons") geom(p) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) g <- geom(v) head(g) w <- geom(v, wkt=TRUE) substr(w, 1, 60)
x1 <- rbind(c(-175,-20), c(-140,55), c(10, 0), c(-140,-60)) x2 <- rbind(c(-125,0), c(0,60), c(40,5), c(15,-45)) x3 <- rbind(c(-10,0), c(140,60), c(160,0), c(140,-55)) x4 <- rbind(c(80,0), c(105,13), c(120,2), c(105,-13)) z <- rbind(cbind(object=1, part=1, x1), cbind(object=2, part=1, x2), cbind(object=3, part=1, x3), cbind(object=3, part=2, x4)) colnames(z)[3:4] <- c('x', 'y') z <- cbind(z, hole=0) z[(z[, "object"]==3 & z[,"part"]==2), "hole"] <- 1 p <- vect(z, "polygons") geom(p) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) g <- geom(v) head(g) w <- geom(v, wkt=TRUE) substr(w, 1, 60)
Get the geometry type (points, lines, or polygons) of a SpatVector. See datatype
for the data types of the fields (attributes, variables) of a SpatVector.
## S4 method for signature 'SpatVector' geomtype(x) ## S4 method for signature 'SpatVector' is.points(x) ## S4 method for signature 'SpatVector' is.lines(x) ## S4 method for signature 'SpatVector' is.polygons(x)
## S4 method for signature 'SpatVector' geomtype(x) ## S4 method for signature 'SpatVector' is.points(x) ## S4 method for signature 'SpatVector' is.lines(x) ## S4 method for signature 'SpatVector' is.polygons(x)
x |
SpatVector |
character
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) geomtype(v) is.polygons(v) is.lines(v) is.points(v) names(v) datatype(v)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) geomtype(v) is.polygons(v) is.lines(v) is.points(v) names(v) datatype(v)
Compute global statistics, that is summarized values of an entire SpatRaster.
If x
is very large global
can fail, except when fun
is one of these built-in functions "mean", "min", "max", "sum", "prod", "range" (min and max), "rms" (root mean square), "sd" (sample standard deviation), "std" (population standard deviation), "isNA" (number of cells that are NA), "notNA" (number of cells that are not NA).
The reason that this can fail with large raster and a custom function is that all values need to be loaded into memory. To circumvent this problem you can run global
with a sample of the cells.
You can compute a weighted mean or sum by providing a SpatRaster with weights.
## S4 method for signature 'SpatRaster' global(x, fun="mean", weights=NULL, maxcell=Inf, ...)
## S4 method for signature 'SpatRaster' global(x, fun="mean", weights=NULL, maxcell=Inf, ...)
x |
SpatRaster |
fun |
function to be applied to summarize the values by zone. Either as one or more of these built-in character values: "max", "min", "mean", "sum", "range", "rms" (root mean square), "sd", "std" (population sd, using |
... |
additional arguments passed on to |
weights |
NULL or SpatRaster |
maxcell |
positive integer used to take a regular sample of |
A data.frame
with a row for each layer
zonal
for "zonal" statistics, and app
or Summary-methods
for "local" statistics, and extract
for summarizing values for polygons. Also see focal
for "focal" or "moving window" operations.
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) global(r, "sum") global(r, "mean", na.rm=TRUE) x <- c(r, r/10) global(x, c("sum", "mean", "sd"), na.rm=TRUE) global(x, function(i) min(i) / max(i))
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) global(r, "sum") global(r, "mean", na.rm=TRUE) x <- c(r, r/10) global(x, c("sum", "mean", "sd"), na.rm=TRUE) global(x, function(i) min(i) / max(i))
Create a graticule. That is, a grid of lon/lat lines that can be used to on a projected map.
The object returned, a SpatGraticule, can be plotted with plot
and lines
. There is also a crop
method.
graticule(lon=30, lat=30, crs="")
graticule(lon=30, lat=30, crs="")
lon |
numeric. Either a single number (the interval between longitudes), or a vector with longitudes |
lat |
numeric. Either a single number (the interval between latitudes), or a vector with latitudes |
crs |
character. The coordinate reference system to use |
SpatGraticule
g <- graticule(60, 30, crs="+proj=robin") g graticule(90, c(-90, -60, -23.5, 0, 23.5, 60, 90), crs="+proj=robin")
g <- graticule(60, 30, crs="+proj=robin") g graticule(90, c(-90, -60, -23.5, 0, 23.5, 60, 90), crs="+proj=robin")
The function calculates the distance to cells of a SpatRaster when the path has to go through the centers of the eight neighboring raster cells.
The default distance (when scale=1
, is meters if the coordinate reference system (CRS) of the SpatRaster is longitude/latitude (+proj=longlat
) and in the linear units of the CRS (typically meters) in other cases.
Distances are computed by summing local distances between cells, which are connected with their neighbors in 8 directions.
The shortest distance to the cells with the target
value is computed for all cells that are not NA
. Cells that are NA
cannot be traversed and are ignored, unless the target itself is NA
, in which case the distance to the nearest cell that is not NA
is computed for all cells that are NA
.
## S4 method for signature 'SpatRaster' gridDist(x, target=0, scale=1, maxiter=50, filename="", ...)
## S4 method for signature 'SpatRaster' gridDist(x, target=0, scale=1, maxiter=50, filename="", ...)
x |
SpatRaster |
target |
numeric. value of the target cells (where to compute distance to) |
scale |
numeric. Scale factor. For longitude/latitude data 1 = "m" and 1000 = "km". For planar data that is also the case of the distance unit of the crs is "m" |
maxiter |
numeric. The maximum number of iterations. Increase this number if you get the warning that |
filename |
character. output filename (optional) |
... |
additional arguments as for |
SpatRaster
See distance
for "as the crow flies" distance, and costDist
for distance across a landscape with variable friction
# global lon/lat raster r <- rast(ncol=10,nrow=10, vals=1) r[48] <- 0 r[66:68] <- NA d <- gridDist(r) plot(d) # planar crs(r) <- "+proj=utm +zone=15 +ellps=GRS80 +datum=NAD83 +units=m +no_defs" d <- gridDist(r) plot(d) # distance to cells that are not NA rr <- classify(r, cbind(1, NA)) dd <- gridDist(rr, NA)
# global lon/lat raster r <- rast(ncol=10,nrow=10, vals=1) r[48] <- 0 r[66:68] <- NA d <- gridDist(r) plot(d) # planar crs(r) <- "+proj=utm +zone=15 +ellps=GRS80 +datum=NAD83 +units=m +no_defs" d <- gridDist(r) plot(d) # distance to cells that are not NA rr <- classify(r, cbind(1, NA)) dd <- gridDist(rr, NA)
Add text to a plot that has a "halo". That is, a buffer around it to enhance visibility.
halo(x, y=NULL, labels, col="black", hc="white", hw=0.1, ...)
halo(x, y=NULL, labels, col="black", hc="white", hw=0.1, ...)
x , y
|
numeric. coordinates where the text labels should be written |
labels |
character. The text to be written |
col |
character. The main color to be used |
hc |
character. The halo color |
hw |
numeric. The halo width |
... |
additional arguments to pass to |
r <- rast(nrows=4, ncols=4) values(r) <- 1:ncell(r) plot(r, col="blue", legend=FALSE) text(-100, 20, "hello", cex=2) halo(50, 20, "hello", cex=2) halo(0, -20, "world", font=3, hc="light blue", cex=2, hw=.2) halo(0, 90, "world", font=2, cex=2, hw=.2, xpd=TRUE, pos=2) halo(0, 90, "world", col="white", font=2, hc="blue", cex=2, hw=.2, xpd=TRUE, pos=4)
r <- rast(nrows=4, ncols=4) values(r) <- 1:ncell(r) plot(r, col="blue", legend=FALSE) text(-100, 20, "hello", cex=2) halo(50, 20, "hello", cex=2) halo(0, -20, "world", font=3, hc="light blue", cex=2, hw=.2) halo(0, 90, "world", font=2, cex=2, hw=.2, xpd=TRUE, pos=2) halo(0, 90, "world", col="white", font=2, hc="blue", cex=2, hw=.2, xpd=TRUE, pos=4)
Show the head (first values) or tail (last values) of a SpatRaster or of the attributes of a SpatVector.
head(x, ...) tail(x, ...)
head(x, ...) tail(x, ...)
x |
SpatRaster or SpatVector |
... |
additional arguments passed on to other methods |
matrix (SpatRaster) or data.frame (SpatVector)
r <- rast(nrows=25, ncols=25) values(r) <- 1:ncell(r) head(r) tail(r)
r <- rast(nrows=25, ncols=25) values(r) <- 1:ncell(r) head(r) tail(r)
Create a histogram of the values of a SpatRaster. For large datasets a sample of maxcell
is used.
## S4 method for signature 'SpatRaster' hist(x, layer, maxcell=1000000, plot=TRUE, maxnl=16, main, ...)
## S4 method for signature 'SpatRaster' hist(x, layer, maxcell=1000000, plot=TRUE, maxnl=16, main, ...)
x |
SpatRaster |
layer |
positive integer or character to indicate layer numbers (or names). If missing, all layers up to |
maxcell |
integer. To regularly sample very large objects |
plot |
logical. Plot the histogram or only return the histogram values |
maxnl |
positive integer. The maximum number of layers to use. Ignored if |
main |
character. Main title(s) for the plot. Default is the value of |
... |
additional arguments. See |
This function is principally used for plotting a histogram, but it also returns an object of class "histogram" (invisibly if plot=TRUE
).
r1 <- r2 <- rast(nrows=50, ncols=50) values(r1) <- runif(ncell(r1)) values(r2) <- runif(ncell(r1)) rs <- r1 + r2 rp <- r1 * r2 opar <- par(no.readonly =TRUE) par(mfrow=c(2,2)) plot(rs, main='sum') plot(rp, main='product') hist(rs) a <- hist(rp) a x <- c(rs, rp, sqrt(rs)) hist(x) par(opar)
r1 <- r2 <- rast(nrows=50, ncols=50) values(r1) <- runif(ncell(r1)) values(r2) <- runif(ncell(r1)) rs <- r1 + r2 rp <- r1 * r2 opar <- par(no.readonly =TRUE) par(mfrow=c(2,2)) plot(rs, main='sum') plot(rp, main='product') hist(rs) a <- hist(rp) a x <- c(rs, rp, sqrt(rs)) hist(x) par(opar)
Compare two SpatRasters for equality.
First the attributes of the objects are compared. If these are the same, a the raster cells are compared as well. This can be time consuming, and you may prefer to use a sample instead with all.equal
## S4 method for signature 'SpatRaster,SpatRaster' identical(x, y)
## S4 method for signature 'SpatRaster,SpatRaster' identical(x, y)
x |
SpatRaster |
y |
SpatRaster |
single logical value
x <- sqrt(1:100) mat <- matrix(x, 10, 10) r1 <- rast(nrows=10, ncols=10, xmin=0, vals = x) r2 <- rast(nrows=10, ncols=10, xmin=0, vals = t(mat)) identical(r1, r2) identical(r1, r1*1) identical(rast(r1), rast(r2))
x <- sqrt(1:100) mat <- matrix(x, 10, 10) r1 <- rast(nrows=10, ncols=10, xmin=0, vals = x) r2 <- rast(nrows=10, ncols=10, xmin=0, vals = t(mat)) identical(r1, r2) identical(r1, r1*1) identical(rast(r1), rast(r2))
Implementation of ifelse
for SpatRasters. This method allows for a concise expression of what can otherwise be achieved with a combination of classify
, mask
, and cover
.
ifel
is an R
equivalent to the Con
method in ArcGIS (arcpy).
## S4 method for signature 'SpatRaster' ifel(test, yes, no, filename="", ...)
## S4 method for signature 'SpatRaster' ifel(test, yes, no, filename="", ...)
test |
SpatRaster with logical (TRUE/FALSE) values |
yes |
SpatRaster or numeric |
no |
SpatRaster or numeric |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(nrows=5, ncols=5, xmin=0, xmax=1, ymin=0, ymax=1) values(r) <- c(-10:0, NA, NA, NA, 0:10) x <- ifel(r > 1, 1, r) # same as a <- classify(r, cbind(1, Inf, 1)) # or b <- app(r, fun=function(i) {i[i > 1] <- 1; i}) # or d <- clamp(r, -Inf, 1) # or (not recommended for large datasets) e <- r e[e>1] <- 1 ## other examples f <- ifel(is.na(r), 100, r) z <- ifel(r > -2 & r < 2, 100, 0) # nested expressions y <- ifel(r > 1, 1, ifel(r < -1, -1, r)) k <- ifel(r > 0, r+10, ifel(r < 0, r-10, 3))
r <- rast(nrows=5, ncols=5, xmin=0, xmax=1, ymin=0, ymax=1) values(r) <- c(-10:0, NA, NA, NA, 0:10) x <- ifel(r > 1, 1, r) # same as a <- classify(r, cbind(1, Inf, 1)) # or b <- app(r, fun=function(i) {i[i > 1] <- 1; i}) # or d <- clamp(r, -Inf, 1) # or (not recommended for large datasets) e <- r e[e>1] <- 1 ## other examples f <- ifel(is.na(r), 100, r) z <- ifel(r > -2 & r < 2, 100, 0) # nested expressions y <- ifel(r > 1, 1, ifel(r < -1, -1, r)) k <- ifel(r > 0, r+10, ifel(r < 0, r-10, 3))
Plot (make a map of) the values of a SpatRaster via image
. See plot
if you need more fancy options such as a legend.
## S4 method for signature 'SpatRaster' image(x, y=1, maxcell=500000, ...)
## S4 method for signature 'SpatRaster' image(x, y=1, maxcell=500000, ...)
x |
SpatRaster |
y |
positive integer indicating the layer to be plotted, or a character indicating the name of the layer |
maxcell |
positive integer. Maximum number of cells to use for the plot |
... |
additional arguments as for |
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) image(r) image(r, col=rainbow(24))
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) image(r) image(r, col=rainbow(24))
Warp the members of a SpatRasterCollection to match the geometry of a SpatRaster.
## S4 method for signature 'SpatRasterCollection' impose(x, y, filename="", ...)
## S4 method for signature 'SpatRasterCollection' impose(x, y, filename="", ...)
x |
SpatRasterCollection |
y |
SpatRaster |
filename |
character. Output filename |
... |
list with named options for writing files as in |
SpatRaster
Create a SpatRaster with values reflecting a cell property: "x", "y", "col", "row", "cell" or "chess". Alternatively, a function can be used. In that case, cell values are initialized without reference to pre-existing values. E.g., initialize with a random number (fun=runif
). While there are more direct ways of achieving this for small objects (see examples) for which a vector with all values can be created in memory, the init
function will also work for SpatRasters with many cells.
## S4 method for signature 'SpatRaster' init(x, fun, filename="", ...)
## S4 method for signature 'SpatRaster' init(x, fun, filename="", ...)
x |
SpatRaster |
fun |
function to be applied. This must be a either single number, multiple numbers, a function, or one of a set of known character values. A function must take the number of cells as a single argument to return a vector of values with a length equal to the number of cells, such as |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(ncols=10, nrows=5, xmin=0, xmax=10, ymin=0, ymax=5) x <- init(r, fun="cell") y <- init(r, fun=runif) # initialize with a single value z <- init(r, fun=8)
r <- rast(ncols=10, nrows=5, xmin=0, xmax=10, ymin=0, ymax=5) x <- init(r, fun="cell") y <- init(r, fun=runif) # initialize with a single value z <- init(r, fun=8)
These "in-place" replacement methods assign new value to an object without making a copy. That is efficient, but if there is a copy of the object that you made by standard assignment (e.g. with y <- x
), that copy is also changed.
set.names
is the in-place replacement version of names<-
.
set.ext
is the in-place replacement version of ext<-
set.values
is the in-place replacement version of [<-
.
set.cats
is the in-place replacement version of categories
set.crs
is the in-place replacement version of crs<-
## S4 method for signature 'SpatRaster' set.names(x, value, index=1:nlyr(x), validate=FALSE) ## S4 method for signature 'SpatRasterDataset' set.names(x, value, index=1:length(x), validate=FALSE) ## S4 method for signature 'SpatVector' set.names(x, value, index=1:ncol(x), validate=FALSE) ## S4 method for signature 'SpatRaster' set.ext(x, value) ## S4 method for signature 'SpatVector' set.ext(x, value) ## S4 method for signature 'SpatRaster' set.crs(x, value) ## S4 method for signature 'SpatVector' set.crs(x, value) ## S4 method for signature 'SpatRaster' set.values(x, cells, values, layer=0) ## S4 method for signature 'SpatRaster' set.cats(x, layer=1, value, active=1) ## S4 method for signature 'SpatRaster' set.RGB(x, value, type="rgb")
## S4 method for signature 'SpatRaster' set.names(x, value, index=1:nlyr(x), validate=FALSE) ## S4 method for signature 'SpatRasterDataset' set.names(x, value, index=1:length(x), validate=FALSE) ## S4 method for signature 'SpatVector' set.names(x, value, index=1:ncol(x), validate=FALSE) ## S4 method for signature 'SpatRaster' set.ext(x, value) ## S4 method for signature 'SpatVector' set.ext(x, value) ## S4 method for signature 'SpatRaster' set.crs(x, value) ## S4 method for signature 'SpatVector' set.crs(x, value) ## S4 method for signature 'SpatRaster' set.values(x, cells, values, layer=0) ## S4 method for signature 'SpatRaster' set.cats(x, layer=1, value, active=1) ## S4 method for signature 'SpatRaster' set.RGB(x, value, type="rgb")
x |
SpatRaster |
value |
character for |
index |
positive integer indicating layer(s) to assign a name to |
validate |
logical. Make names valid and/or unique? |
cells |
cell numbers or missing |
values |
replacement values or missing to load all values into memory |
layer |
positive integer(s) indicating to which layer(s) to you want to assign these categories or to which you want to set these values. A number < 1 indicates "all layers" |
active |
positive integer indicating the active category (column number in |
type |
character. The color space. One of "rgb" "hsv", "hsi" and "hsl" |
logical (invisibly)
s <- rast(ncols=5, nrows=5, nlyrs=3) x <- s names(s) names(s) <- c("a", "b", "c") names(s) names(x) x <- s set.names(s, c("e", "f", "g")) names(s) names(x) set.ext(x, c(0,180,0,90)) f <- system.file("ex/elev.tif", package="terra") r <- rast(f) #values from file to memory set.values(r) # change values set.values(r, 1:1000, 900)
s <- rast(ncols=5, nrows=5, nlyrs=3) x <- s names(s) names(s) <- c("a", "b", "c") names(s) names(x) x <- s set.names(s, c("e", "f", "g")) names(s) names(x) set.ext(x, c(0,180,0,90)) f <- system.file("ex/elev.tif", package="terra") r <- rast(f) #values from file to memory set.values(r) # change values set.values(r, 1:1000, 900)
Make an inset map or scale the extent of a SpatVector
## S4 method for signature 'SpatVector' inset(x, e, loc="", scale=0.2, background="white", perimeter=TRUE, box=NULL, pper, pbox, offset=0.1, add=TRUE, ...) ## S4 method for signature 'SpatRaster' inset(x, e, loc="", scale=0.2, background="white", perimeter=TRUE, box=NULL, pper, pbox, offset=0.1, add=TRUE, ...) ## S4 method for signature 'SpatVector' inext(x, e, y=NULL, gap=0)
## S4 method for signature 'SpatVector' inset(x, e, loc="", scale=0.2, background="white", perimeter=TRUE, box=NULL, pper, pbox, offset=0.1, add=TRUE, ...) ## S4 method for signature 'SpatRaster' inset(x, e, loc="", scale=0.2, background="white", perimeter=TRUE, box=NULL, pper, pbox, offset=0.1, add=TRUE, ...) ## S4 method for signature 'SpatVector' inext(x, e, y=NULL, gap=0)
x |
SpatVector, SpatRaster |
e |
SpatExtent to set the size and location of the inset. Or missing |
loc |
character. One of "bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right", "center" |
scale |
numeric. The relative size of the inset, used when x is missing |
background |
color for the background of the inset. Use |
perimeter |
logical. If |
box |
SpatExtent or missing, to draw a box on the inset, e.g. to show where the map is located in a larger area |
pper |
list with graphical parameters (arguments) such as |
pbox |
list with graphical parameters (arguments) such as |
offset |
numeric. Value between 0.1 and 1 to indicate the relative distance between what is mapped and the bounding box |
add |
logical. Add the inset to the map? |
... |
additional arguments passed to plot for the drawing of |
y |
SpatVector. If not NULL, |
gap |
numeric to add space between the SpatVector and the SpatExtent |
scaled and shifted SpatVector or SpatRaster (returned invisibly)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) x <- v[v$NAME_2 == "Diekirch", ] plot(x, density=10, col="blue") inset(v) # more elaborate plot(x, density=10, col="blue") inset(v, col = "brown", border="lightgrey", perimeter=TRUE, pper=list(col="orange", lwd=3, lty=2), box=ext(x), pbox=list(col="blue", lwd=2)) cols <- rep("light grey", 12) cols[2] <- "red" e <- ext(c(6.2, 6.3, 49.9, 50)) b <- ext(x)+0.02 inset(v, e=e, col=cols, box=b) # with a SpatRaster ff <- system.file("ex/elev.tif", package="terra") r <- rast(ff) r <- crop(r, ext(x) + .01) plot(r, type="int", mar=c(2,2,2,2), plg=list(x="topright")) lines(v, lwd=1.5) lines(x, lwd=2.5) inset(v, col=cols, loc="topleft", scale=0.15) # a more complex one plot(r, plg=list(title="meter\n", shrink=.2, cex=.8)) lines(v, lwd=4, col="white") lines(v, lwd=1.5) lines(x, lwd=2.5) text(x, "NAME_2", cex=1.5, halo=TRUE) sbar(6, c(6.04, 49.785), type="bar", below="km", label=c(0,3,6), cex=.8) s <- inset(v, col=cols, box=b, scale=.2, loc="topright", background="light yellow", pbox=list(lwd=2, lty=5, col="blue")) # note the returned inset SpatVector s lines(s, col="orange")
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) x <- v[v$NAME_2 == "Diekirch", ] plot(x, density=10, col="blue") inset(v) # more elaborate plot(x, density=10, col="blue") inset(v, col = "brown", border="lightgrey", perimeter=TRUE, pper=list(col="orange", lwd=3, lty=2), box=ext(x), pbox=list(col="blue", lwd=2)) cols <- rep("light grey", 12) cols[2] <- "red" e <- ext(c(6.2, 6.3, 49.9, 50)) b <- ext(x)+0.02 inset(v, e=e, col=cols, box=b) # with a SpatRaster ff <- system.file("ex/elev.tif", package="terra") r <- rast(ff) r <- crop(r, ext(x) + .01) plot(r, type="int", mar=c(2,2,2,2), plg=list(x="topright")) lines(v, lwd=1.5) lines(x, lwd=2.5) inset(v, col=cols, loc="topleft", scale=0.15) # a more complex one plot(r, plg=list(title="meter\n", shrink=.2, cex=.8)) lines(v, lwd=4, col="white") lines(v, lwd=1.5) lines(x, lwd=2.5) text(x, "NAME_2", cex=1.5, halo=TRUE) sbar(6, c(6.04, 49.785), type="bar", below="km", label=c(0,3,6), cex=.8) s <- inset(v, col=cols, box=b, scale=.2, loc="topright", background="light yellow", pbox=list(lwd=2, lty=5, col="blue")) # note the returned inset SpatVector s lines(s, col="orange")
Interpolate points within a moving window using inverse distance weighting. The maximum number of points used can be restricted, optionally by selecting the nearest points.
## S4 method for signature 'SpatRaster,SpatVector' interpIDW(x, y, field, radius, power=2, smooth=0, maxPoints=Inf, minPoints=1, near=TRUE, fill=NA, filename="", ...) ## S4 method for signature 'SpatRaster,matrix' interpIDW(x, y, radius, power=2, smooth=0, maxPoints=Inf, minPoints=1, near=TRUE, fill=NA, filename="", ...)
## S4 method for signature 'SpatRaster,SpatVector' interpIDW(x, y, field, radius, power=2, smooth=0, maxPoints=Inf, minPoints=1, near=TRUE, fill=NA, filename="", ...) ## S4 method for signature 'SpatRaster,matrix' interpIDW(x, y, radius, power=2, smooth=0, maxPoints=Inf, minPoints=1, near=TRUE, fill=NA, filename="", ...)
x |
SpatRaster |
y |
SpatVector or matrix with three columns (x,y,z) |
field |
character. field name in SpatVector |
radius |
numeric. The radius of the circle (single number). If |
power |
numeric. Weighting power |
smooth |
numeric. Smoothing parameter |
minPoints |
numeric. The minimum number of points to use. If fewer points are found in a search ellipse it is considered empty and the fill value is returned |
maxPoints |
numeric. The maximum number of points to consider in a search area. Additional points are ignored. If fewer points are found, the fill value is returned |
near |
logical. Should the nearest points within the neighborhood be used if |
fill |
numeric. value to use to fill empty cells |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
rasterizeWin, rasterize, interpNear, interpolate
r <- rast(ncol=100, nrow=100, crs="local", xmin=0, xmax=50, ymin=0, ymax=50) set.seed(100) x <- runif(25, 5, 45) y <- runif(25, 5, 45) z <- sample(25) xyz <- cbind(x,y,z) x <- interpIDW(r, xyz, radius=5, power=1, smooth=1, maxPoints=5)
r <- rast(ncol=100, nrow=100, crs="local", xmin=0, xmax=50, ymin=0, ymax=50) set.seed(100) x <- runif(25, 5, 45) y <- runif(25, 5, 45) z <- sample(25) xyz <- cbind(x,y,z) x <- interpIDW(r, xyz, radius=5, power=1, smooth=1, maxPoints=5)
Nearest neighbor interpolation of points, using a moving window
## S4 method for signature 'SpatRaster,SpatVector' interpNear(x, y, field, radius, interpolate=FALSE, fill=NA, filename="", ...) ## S4 method for signature 'SpatRaster,matrix' interpNear(x, y, radius, interpolate=FALSE, fill=NA, filename="", ...)
## S4 method for signature 'SpatRaster,SpatVector' interpNear(x, y, field, radius, interpolate=FALSE, fill=NA, filename="", ...) ## S4 method for signature 'SpatRaster,matrix' interpNear(x, y, radius, interpolate=FALSE, fill=NA, filename="", ...)
x |
SpatRaster |
y |
SpatVector or matrix with three columns (x,y,z) |
field |
character. field name in SpatVector |
radius |
numeric. The radius of the circle (single number). If |
interpolate |
logical. Should the nearest neighbor values be linearly interpolated between points? |
fill |
numeric. value to use to fill empty cells |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
rasterizeWin, rasterize, interpIDW, interpolate
r <- rast(ncol=100, nrow=100, crs="local", xmin=0, xmax=50, ymin=0, ymax=50) set.seed(100) x <- runif(25, 5, 45) y <- runif(25, 5, 45) z <- sample(25) xyz <- cbind(x,y,z) x <- interpNear(r, xyz, radius=5) p <- vect(data.frame(xyz), geom=c("x", "y")) v <- voronoi(p) plot(x, col=rainbow(25)) lines(v) # plot(v, col=rainbow(25)); points(p)
r <- rast(ncol=100, nrow=100, crs="local", xmin=0, xmax=50, ymin=0, ymax=50) set.seed(100) x <- runif(25, 5, 45) y <- runif(25, 5, 45) z <- sample(25) xyz <- cbind(x,y,z) x <- interpNear(r, xyz, radius=5) p <- vect(data.frame(xyz), geom=c("x", "y")) v <- voronoi(p) plot(x, col=rainbow(25)) lines(v) # plot(v, col=rainbow(25)); points(p)
Make a SpatRaster with interpolated values using a fitted model object of classes such as "gstat" (gstat package) or "Krige" (fields package), or any other model that has location (e.g., "x" and "y", or "longitude" and "latitude") as predictors (independent variables). If x and y are the only predictors, it is most efficient if you provide an empty (no associated data in memory or on file) SpatRaster for which you want predictions. If there are more spatial predictor variables, provide these as a SpatRaster in the first argument of the function. If you do not have x and y locations as implicit predictors in your model you should use predict
instead.
## S4 method for signature 'SpatRaster' interpolate(object, model, fun=predict, ..., xyNames=c("x", "y"), factors=NULL, const=NULL, index = NULL, cores=1, cpkgs=NULL, na.rm=FALSE, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' interpolate(object, model, fun=predict, ..., xyNames=c("x", "y"), factors=NULL, const=NULL, index = NULL, cores=1, cpkgs=NULL, na.rm=FALSE, filename="", overwrite=FALSE, wopt=list())
object |
SpatRaster |
model |
model object |
fun |
function. Default value is "predict", but can be replaced with e.g. "predict.se" (depending on the class of |
... |
additional arguments passed to |
xyNames |
character. variable names that the model uses for the spatial coordinates. E.g., |
factors |
list with levels for factor variables. The list elements should be named with names that correspond to names in |
const |
data.frame. Can be used to add a constant for which there is no SpatRaster for model predictions. This is particularly useful if the constant is a character-like factor value |
index |
positive integer or NULL. Allows for selecting of the variable returned if the model returns multiple variables |
cores |
positive integer. If |
cpkgs |
character. The package(s) that need to be loaded on the nodes to be able to run the model.predict function (see examples in |
na.rm |
logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
SpatRaster
predict
, interpIDW
, interpNear
r <- rast(system.file("ex/elev.tif", package="terra")) ra <- aggregate(r, 10) xy <- data.frame(xyFromCell(ra, 1:ncell(ra))) v <- values(ra) i <- !is.na(v) xy <- xy[i,] v <- v[i] ## Not run: library(fields) tps <- Tps(xy, v) p <- rast(r) # use model to predict values at all locations p <- interpolate(p, tps) p <- mask(p, r) plot(p) ### change "fun" from predict to fields::predictSE to get the TPS standard error ## need to use "rast(p)" to remove the values se <- interpolate(rast(p), tps, fun=predictSE) se <- mask(se, r) plot(se) ### another predictor variable, "e" e <- (init(r, "x") * init(r, "y")) / 100000000 names(e) <- "e" z <- as.matrix(extract(e, xy)[,-1]) ## add as another independent variable xyz <- cbind(xy, z) tps2 <- Tps(xyz, v) p2 <- interpolate(e, tps2, xyOnly=FALSE) ## as a linear covariate tps3 <- Tps(xy, v, Z=z) ## Z is a separate argument in Krig.predict, so we need a new function ## Internally (in interpolate) a matrix is formed of x, y, and elev (Z) pfun <- function(model, x, ...) { predict(model, x[,1:2], Z=x[,3], ...) } p3 <- interpolate(e, tps3, fun=pfun) #### gstat examples library(gstat) library(sp) data(meuse) ### inverse distance weighted (IDW) r <- rast(system.file("ex/meuse.tif", package="terra")) mg <- gstat(id = "zinc", formula = zinc~1, locations = ~x+y, data=meuse, nmax=7, set=list(idp = .5)) z <- interpolate(r, mg, debug.level=0, index=1) z <- mask(z, r) ## with a model built with an `sf` object you need to provide custom function library(sf) sfmeuse <- st_as_sf(meuse, coords = c("x", "y"), crs=crs(r)) mgsf <- gstat(id = "zinc", formula = zinc~1, data=sfmeuse, nmax=7, set=list(idp = .5)) interpolate_gstat <- function(model, x, crs, ...) { v <- st_as_sf(x, coords=c("x", "y"), crs=crs) p <- predict(model, v, ...) as.data.frame(p)[,1:2] } zsf <- interpolate(r, mgsf, debug.level=0, fun=interpolate_gstat, crs=crs(r), index=1) zsf <- mask(zsf, r) ### kriging ### ordinary kriging v <- variogram(log(zinc)~1, ~x+y, data=meuse) mv <- fit.variogram(v, vgm(1, "Sph", 300, 1)) gOK <- gstat(NULL, "log.zinc", log(zinc)~1, meuse, locations=~x+y, model=mv) OK <- interpolate(r, gOK, debug.level=0) ## universal kriging vu <- variogram(log(zinc)~elev, ~x+y, data=meuse) mu <- fit.variogram(vu, vgm(1, "Sph", 300, 1)) gUK <- gstat(NULL, "log.zinc", log(zinc)~elev, meuse, locations=~x+y, model=mu) names(r) <- "elev" UK <- interpolate(r, gUK, debug.level=0) ## co-kriging gCoK <- gstat(NULL, 'log.zinc', log(zinc)~1, meuse, locations=~x+y) gCoK <- gstat(gCoK, 'elev', elev~1, meuse, locations=~x+y) gCoK <- gstat(gCoK, 'cadmium', cadmium~1, meuse, locations=~x+y) gCoK <- gstat(gCoK, 'copper', copper~1, meuse, locations=~x+y) coV <- variogram(gCoK) plot(coV, type='b', main='Co-variogram') coV.fit <- fit.lmc(coV, gCoK, vgm(model='Sph', range=1000)) coV.fit plot(coV, coV.fit, main='Fitted Co-variogram') coK <- interpolate(r, coV.fit, debug.level=0) plot(coK) ## End(Not run)
r <- rast(system.file("ex/elev.tif", package="terra")) ra <- aggregate(r, 10) xy <- data.frame(xyFromCell(ra, 1:ncell(ra))) v <- values(ra) i <- !is.na(v) xy <- xy[i,] v <- v[i] ## Not run: library(fields) tps <- Tps(xy, v) p <- rast(r) # use model to predict values at all locations p <- interpolate(p, tps) p <- mask(p, r) plot(p) ### change "fun" from predict to fields::predictSE to get the TPS standard error ## need to use "rast(p)" to remove the values se <- interpolate(rast(p), tps, fun=predictSE) se <- mask(se, r) plot(se) ### another predictor variable, "e" e <- (init(r, "x") * init(r, "y")) / 100000000 names(e) <- "e" z <- as.matrix(extract(e, xy)[,-1]) ## add as another independent variable xyz <- cbind(xy, z) tps2 <- Tps(xyz, v) p2 <- interpolate(e, tps2, xyOnly=FALSE) ## as a linear covariate tps3 <- Tps(xy, v, Z=z) ## Z is a separate argument in Krig.predict, so we need a new function ## Internally (in interpolate) a matrix is formed of x, y, and elev (Z) pfun <- function(model, x, ...) { predict(model, x[,1:2], Z=x[,3], ...) } p3 <- interpolate(e, tps3, fun=pfun) #### gstat examples library(gstat) library(sp) data(meuse) ### inverse distance weighted (IDW) r <- rast(system.file("ex/meuse.tif", package="terra")) mg <- gstat(id = "zinc", formula = zinc~1, locations = ~x+y, data=meuse, nmax=7, set=list(idp = .5)) z <- interpolate(r, mg, debug.level=0, index=1) z <- mask(z, r) ## with a model built with an `sf` object you need to provide custom function library(sf) sfmeuse <- st_as_sf(meuse, coords = c("x", "y"), crs=crs(r)) mgsf <- gstat(id = "zinc", formula = zinc~1, data=sfmeuse, nmax=7, set=list(idp = .5)) interpolate_gstat <- function(model, x, crs, ...) { v <- st_as_sf(x, coords=c("x", "y"), crs=crs) p <- predict(model, v, ...) as.data.frame(p)[,1:2] } zsf <- interpolate(r, mgsf, debug.level=0, fun=interpolate_gstat, crs=crs(r), index=1) zsf <- mask(zsf, r) ### kriging ### ordinary kriging v <- variogram(log(zinc)~1, ~x+y, data=meuse) mv <- fit.variogram(v, vgm(1, "Sph", 300, 1)) gOK <- gstat(NULL, "log.zinc", log(zinc)~1, meuse, locations=~x+y, model=mv) OK <- interpolate(r, gOK, debug.level=0) ## universal kriging vu <- variogram(log(zinc)~elev, ~x+y, data=meuse) mu <- fit.variogram(vu, vgm(1, "Sph", 300, 1)) gUK <- gstat(NULL, "log.zinc", log(zinc)~elev, meuse, locations=~x+y, model=mu) names(r) <- "elev" UK <- interpolate(r, gUK, debug.level=0) ## co-kriging gCoK <- gstat(NULL, 'log.zinc', log(zinc)~1, meuse, locations=~x+y) gCoK <- gstat(gCoK, 'elev', elev~1, meuse, locations=~x+y) gCoK <- gstat(gCoK, 'cadmium', cadmium~1, meuse, locations=~x+y) gCoK <- gstat(gCoK, 'copper', copper~1, meuse, locations=~x+y) coV <- variogram(gCoK) plot(coV, type='b', main='Co-variogram') coV.fit <- fit.lmc(coV, gCoK, vgm(model='Sph', range=1000)) coV.fit plot(coV, coV.fit, main='Fitted Co-variogram') coK <- interpolate(r, coV.fit, debug.level=0) plot(coK) ## End(Not run)
You can intersect SpatVectors with each other or with a SpatExtent. Intersecting points with points uses the extent of y
to get the intersection. Intersecting of points and lines is not supported because of numerical inaccuracies with that. You can use buffer
, to create polygons from lines and use these with intersect.
You can also intersect two SpatExtents.
When intersecting two SpatRasters these need to be aligned (have the same origin and spatial resolution). The values of the returned SpatRaster are TRUE
where both input rasters have values, FALSE
where one has values, and NA
in all other cells.
When intersecting a SpatExtent and a SpatRaster, the SpatExtent is first aligned to the raster cell boundaries.
See crop
for the intersection of a SpatRaster with a SpatExtent (or the extent of a SpatRaster or SpatVector) if you want a SpatRaster (not a SpatExtent) as output.
See is.related(x, y, "intersects")
to find out which geometries of a SpatVector intersect. You can spatially subset a SpatVector with another one with x[y]
.
## S4 method for signature 'SpatVector,SpatVector' intersect(x, y) ## S4 method for signature 'SpatVector,SpatExtent' intersect(x, y) ## S4 method for signature 'SpatExtent,SpatVector' intersect(x, y) ## S4 method for signature 'SpatExtent,SpatExtent' intersect(x, y) ## S4 method for signature 'SpatRaster,SpatRaster' intersect(x, y) ## S4 method for signature 'SpatRaster,SpatExtent' intersect(x, y) ## S4 method for signature 'SpatExtent,SpatRaster' intersect(x, y)
## S4 method for signature 'SpatVector,SpatVector' intersect(x, y) ## S4 method for signature 'SpatVector,SpatExtent' intersect(x, y) ## S4 method for signature 'SpatExtent,SpatVector' intersect(x, y) ## S4 method for signature 'SpatExtent,SpatExtent' intersect(x, y) ## S4 method for signature 'SpatRaster,SpatRaster' intersect(x, y) ## S4 method for signature 'SpatRaster,SpatExtent' intersect(x, y) ## S4 method for signature 'SpatExtent,SpatRaster' intersect(x, y)
x |
SpatVector, SpatExtent, or SpatRaster |
y |
SpatVector, SpatExtent, or SpatRaster |
Same as x
e1 <- ext(-10, 10, -20, 20) e2 <- ext(0, 20, -40, 5) intersect(e1, e2) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) e <- ext(5.6, 6, 49.55, 49.7) x <- intersect(v, e) p <- vect(c("POLYGON ((5.8 49.8, 6 49.9, 6.15 49.8, 6 49.6, 5.8 49.8))", "POLYGON ((6.3 49.9, 6.2 49.7, 6.3 49.6, 6.5 49.8, 6.3 49.9))"), crs=crs(v)) values(p) <- data.frame(pid=1:2, area=expanse(p)) y <- intersect(v, p) r <- s <- rast(ncol=5, nrow=5, xmin=1, xmax=5, ymin=1, ymax=5) r[5:20] <- 5:20 s[11:20] <- 11:20 rs <- intersect(r, s) u <- shift(r, .8) us <- intersect(u, s)
e1 <- ext(-10, 10, -20, 20) e2 <- ext(0, 20, -40, 5) intersect(e1, e2) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) e <- ext(5.6, 6, 49.55, 49.7) x <- intersect(v, e) p <- vect(c("POLYGON ((5.8 49.8, 6 49.9, 6.15 49.8, 6 49.6, 5.8 49.8))", "POLYGON ((6.3 49.9, 6.2 49.7, 6.3 49.6, 6.5 49.8, 6.3 49.9))"), crs=crs(v)) values(p) <- data.frame(pid=1:2, area=expanse(p)) y <- intersect(v, p) r <- s <- rast(ncol=5, nrow=5, xmin=1, xmax=5, ymin=1, ymax=5) r[5:20] <- 5:20 s[11:20] <- 11:20 rs <- intersect(r, s) u <- shift(r, .8) us <- intersect(u, s)
The values in a SpatRaster layer are by default numeric, but they can also be set to be logical (Boolean), integer, or categorical (factor).
For a SpatRaster
, as.logical
and isTRUE
is equivalent to as.bool
. isFALSE
is equivalent to !as.bool
, and as.integer
is the same as as.int
.
as.bool
and as.int
force the values into the correct range (e.g. whole integers) but in-memory cell values are still stored as numeric. They will behave like the assigned types, though, and will be written to files with that data type (if the file type supports it).
See levels
and cats
to create categorical layers by setting labels.
## S4 method for signature 'SpatRaster' is.bool(x) ## S4 method for signature 'SpatRaster' as.bool(x, filename, ...) ## S4 method for signature 'SpatRaster' is.int(x) ## S4 method for signature 'SpatRaster' as.int(x, filename, ...) ## S4 method for signature 'SpatRaster' is.factor(x) ## S4 method for signature 'SpatRaster' as.factor(x)
## S4 method for signature 'SpatRaster' is.bool(x) ## S4 method for signature 'SpatRaster' as.bool(x, filename, ...) ## S4 method for signature 'SpatRaster' is.int(x) ## S4 method for signature 'SpatRaster' as.int(x, filename, ...) ## S4 method for signature 'SpatRaster' is.factor(x) ## S4 method for signature 'SpatRaster' as.factor(x)
x |
SpatRaster |
filename |
character. Output filename |
... |
list with named options for writing files as in |
The as.*
methods return a new SpatRaster
, whereas the is.*
methods return a logical
value for each layer in x
.
levels
and cats
to create categorical layers (and set labels).
r <- rast(nrows=10, ncols=10, vals=1:100) is.bool(r) z <- as.bool(r) is.bool(z) x <- r > 25 is.bool(x) rr <- r/2 is.int(rr) is.int(round(rr))
r <- rast(nrows=10, ncols=10, vals=1:100) is.bool(r) z <- as.bool(r) is.bool(z) x <- r > 25 is.bool(x) rr <- r/2 is.int(rr) is.int(round(rr))
An empty SpatExtent has no area
An empty SpatVector has no geometries.
## S4 method for signature 'SpatExtent' is.empty(x) ## S4 method for signature 'SpatVector' is.empty(x)
## S4 method for signature 'SpatExtent' is.empty(x) ## S4 method for signature 'SpatVector' is.empty(x)
x |
SpatVector or SpatExtent |
logical
e <- ext(0,0,0,0) is.valid(e) is.empty(e) v <- vect() is.valid(v) is.empty(v)
e <- ext(0,0,0,0) is.valid(e) is.empty(e) v <- vect() is.valid(v) is.empty(v)
Test whether a SpatRaster or SpatVector has a longitude/latitude coordinate reference system (CRS), or perhaps has one. That is, when the CRS is unknown (""
) but the x coordinates are within -181 and 181 and the y coordinates are within -90.1 and 90.1. For a SpatRaster you can also test if it has a longitude/latitude CRS and it is "global" (covers all longitudes).
A warning is given if the CRS is missing or if it is specified as longitude/latitude but the coordinates do not match that.
## S4 method for signature 'SpatRaster' is.lonlat(x, perhaps=FALSE, warn=TRUE, global=FALSE) ## S4 method for signature 'SpatVector' is.lonlat(x, perhaps=FALSE, warn=TRUE) ## S4 method for signature 'character' is.lonlat(x, perhaps=FALSE, warn=TRUE)
## S4 method for signature 'SpatRaster' is.lonlat(x, perhaps=FALSE, warn=TRUE, global=FALSE) ## S4 method for signature 'SpatVector' is.lonlat(x, perhaps=FALSE, warn=TRUE) ## S4 method for signature 'character' is.lonlat(x, perhaps=FALSE, warn=TRUE)
x |
SpatRaster or SpatVector |
perhaps |
logical. If |
warn |
logical. If |
global |
logical. If |
logical or NA
r <- rast() is.lonlat(r) is.lonlat(r, global=TRUE) crs(r) <- "" is.lonlat(r) is.lonlat(r, perhaps=TRUE, warn=FALSE) crs(r) <- "+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +ellps=WGS84" is.lonlat(r)
r <- rast() is.lonlat(r) is.lonlat(r, global=TRUE) crs(r) <- "" is.lonlat(r) is.lonlat(r, perhaps=TRUE, warn=FALSE) crs(r) <- "+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +ellps=WGS84" is.lonlat(r)
Check if a SpatRaster is "rotated" and needs to be rectified before it can be used
See rectify
## S4 method for signature 'SpatRaster' is.rotated(x)
## S4 method for signature 'SpatRaster' is.rotated(x)
x |
SpatRaster |
logical. One value for each raster data *source*
r <- rast(nrows=10, ncols=10, vals=1:100) is.rotated(r)
r <- rast(nrows=10, ncols=10, vals=1:100) is.rotated(r)
Check the validity of polygons or attempt to fix it. Or check the validity of a SpatExtent.
## S4 method for signature 'SpatVector' is.valid(x, messages=FALSE, as.points=FALSE) ## S4 method for signature 'SpatVector' makeValid(x) ## S4 method for signature 'SpatExtent' is.valid(x)
## S4 method for signature 'SpatVector' is.valid(x, messages=FALSE, as.points=FALSE) ## S4 method for signature 'SpatVector' makeValid(x) ## S4 method for signature 'SpatExtent' is.valid(x)
x |
SpatVector or SpatExtent |
messages |
logical. If |
as.points |
logical. If |
logical
w <- vect("POLYGON ((0 -5, 10 0, 10 -10, 0 -5))") is.valid(w) w <- vect("POLYGON ((0 -5, 10 0, 10 -10, 4 -2, 0 -5))") is.valid(w) is.valid(w, TRUE) plot(w) points(cbind(4.54, -2.72), cex=2, col="red") e <- ext(0, 1, 0, 1) is.valid(e) ee <- ext(0, 0, 0, 0) is.valid(ee)
w <- vect("POLYGON ((0 -5, 10 0, 10 -10, 0 -5))") is.valid(w) w <- vect("POLYGON ((0 -5, 10 0, 10 -10, 4 -2, 0 -5))") is.valid(w) is.valid(w, TRUE) plot(w) points(cbind(4.54, -2.72), cex=2, col="red") e <- ext(0, 1, 0, 1) is.valid(e) ee <- ext(0, 0, 0, 0) is.valid(ee)
Compute k-means clusters for a SpatRaster. For large SpatRasters (with ncell(x) > maxcell
) this is done in two steps. First a sample of the cells is used to compute the cluster centers. Then each cell is assigned to a cluster by computing the distance to these centers.
## S4 method for signature 'SpatRaster' k_means(x, centers=3, ..., maxcell=1000000, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' k_means(x, centers=3, ..., maxcell=1000000, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster |
centers |
either the number of clusters, or a set of initial (distinct) cluster centres. If a number, a random set of (distinct) cells in |
... |
additional arguments passed to |
maxcell |
positive integer. The size of the regular sample used if it is smaller than |
filename |
character. Output filename (ignored if |
overwrite |
logical. If |
wopt |
list with additional arguments for writing files as in |
SpatRaster
f <- system.file("ex/logo.tif", package = "terra") r <- rast(f) km <- k_means(r, centers=5) km
f <- system.file("ex/logo.tif", package = "terra") r <- rast(f) km <- k_means(r, centers=5) km
Apply a function to a SpatRaster, using layers as arguments.
The number of arguments in function fun
must match the number of layers in the SpatRaster (or the number of sub-datasets in the SpatRasterDataset). For example, if you want to multiply two layers, you could use this function: fun=function(x,y){return(x*y)}
percentage: fun=function(x,y){return(100 * x / y)}
. If you combine three layers you could use fun=function(x,y,z){return((x + y) * z)}
Before you use the function, test it to make sure that it is vectorized. That is, it should work for vectors longer than one, not only for single numbers. Or if the input SpatRaster(s) have multiple layers, it should work for a matrix (multiple cells) of input data (or matrices in the case of a SpatRasterDataSet). The function must return the same number of elements as its input vectors, or multiples of that. Also make sure that the function is NA
-proof: it should returns the same number of values when some or all input values are NA
. And the function must return a vector or a matrix, not a data.frame
. To test it, run it with do.call(fun, data)
(see examples).
Use app
for summarize functions such as sum
, that take any number of arguments; and tapp
to do so for groups of layers.
## S4 method for signature 'SpatRaster' lapp(x, fun, ..., usenames=FALSE, cores=1, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterDataset' lapp(x, fun, ..., usenames=FALSE, recycle=FALSE, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' lapp(x, fun, ..., usenames=FALSE, cores=1, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterDataset' lapp(x, fun, ..., usenames=FALSE, recycle=FALSE, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster or SpatRasterDataset |
fun |
a function that takes a vector and can be applied to each cell of |
... |
additional arguments to be passed to |
usenames |
logical. Use the layer names (or dataset names if |
cores |
positive integer. If |
recycle |
logical. Recycle layers to match the subdataset with the largest number of layers |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
SpatRaster
Use sapp
or lapply
to apply a function that takes a SpatRaster as argument to each layer of a SpatRaster (that is rarely necessary).
s <- rast(system.file("ex/logo.tif", package="terra")) + 1 ss <- s[[2:1]] fvi <- function(x, y){ (x - y ) / (x + y) } # test the function data <- list(c(1:5,NA), 6:1) do.call(fvi, data) x <- lapp(ss, fun=fvi ) # which is the same as supplying the layers to "fun" # in some cases this will be much faster y <- fvi(s[[2]], s[[1]]) f2 <- function(x, y, z){ (z - y + 1) / (x + y + 1) } p1 <- lapp(s, fun=f2 ) p2 <- lapp(s[[1:2]], f2, z=200) # the usenames argument fvi2 <- function(red, green){ (red - green ) / (red + green) } names(s) x1 <- lapp(s[[1:2]], fvi2, usenames=TRUE) x2 <- lapp(s[[2:1]], fvi2, usenames=TRUE) # x1 and x2 are the same, despite the change in the order of the layers # x4 is also the same, but x3 is not x3 <- lapp(s[[2:1]], fvi2, usenames=FALSE) x4 <- lapp(s, fvi2, usenames=TRUE) # while this would fail because # there are too many layers in s # x5 <- lapp(s, fvi2, usenames=FALSE) pairs(c(x1, x2, x3, x4)) ## SpatRasterDataset x <- sds(s, s[[1]]+50) fun <- function(x, y) { x/y } # test "fun" data <- list(matrix(1:9, ncol=3), matrix(9:1, ncol=3)) do.call(fun, data) lapp(x, fun, recycle=TRUE) # the same, more concisely z <- s / (s[[1]]+50)
s <- rast(system.file("ex/logo.tif", package="terra")) + 1 ss <- s[[2:1]] fvi <- function(x, y){ (x - y ) / (x + y) } # test the function data <- list(c(1:5,NA), 6:1) do.call(fvi, data) x <- lapp(ss, fun=fvi ) # which is the same as supplying the layers to "fun" # in some cases this will be much faster y <- fvi(s[[2]], s[[1]]) f2 <- function(x, y, z){ (z - y + 1) / (x + y + 1) } p1 <- lapp(s, fun=f2 ) p2 <- lapp(s[[1:2]], f2, z=200) # the usenames argument fvi2 <- function(red, green){ (red - green ) / (red + green) } names(s) x1 <- lapp(s[[1:2]], fvi2, usenames=TRUE) x2 <- lapp(s[[2:1]], fvi2, usenames=TRUE) # x1 and x2 are the same, despite the change in the order of the layers # x4 is also the same, but x3 is not x3 <- lapp(s[[2:1]], fvi2, usenames=FALSE) x4 <- lapp(s, fvi2, usenames=TRUE) # while this would fail because # there are too many layers in s # x5 <- lapp(s, fvi2, usenames=FALSE) pairs(c(x1, x2, x3, x4)) ## SpatRasterDataset x <- sds(s, s[[1]]+50) fun <- function(x, y) { x/y } # test "fun" data <- list(matrix(1:9, ncol=3), matrix(9:1, ncol=3)) do.call(fun, data) lapp(x, fun, recycle=TRUE) # the same, more concisely z <- s / (s[[1]]+50)
Compute correlation, (weighted) covariance, or similar summary statistics that compare the values of all pairs of the layers of a SpatRaster.
## S4 method for signature 'SpatRaster' layerCor(x, fun, w, asSample=TRUE, use="everything", maxcell=Inf, ...)
## S4 method for signature 'SpatRaster' layerCor(x, fun, w, asSample=TRUE, use="everything", maxcell=Inf, ...)
x |
SpatRaster |
fun |
character. The statistic to compute: either "cov" (covariance), "weighted.cov" (weighted covariance), or "cor" (pearson correlation coefficient) or your own function that takes two vectors as argument to compute a single number |
w |
SpatRaster with the weights to compute the weighted covariance. It should have a single layer and the same geometry as |
asSample |
logical. If |
use |
character. To decide how to handle missing values. This must be (an abbreviation of) one of "everything", "complete.obs", "pairwise.complete.obs", "masked.complete". With "pairwise.complete.obs", the value for a pair of layers is computed for all cells that are not |
maxcell |
positive integer. The maximum number of cells to be used. If this is smaller than ncell(x), a regular sample of |
... |
additional arguments for |
If fun
is one of the three standard statistics, you get a list with three items: the
correlation or (weighted) covariance matrix, the (weighted) means, and the number of data cells in
each comparison. The means are also a matrix because they may depend on the combination of layers
if different cells have missing values and these are excluded from the computation. The rows of
the mean matrix represent the layer whose (weighted) mean is being calculated and the columns
represent the layer it is being paired with. Only cells with non-missing observations for both
layers are used in the calculation of the (weighted) mean. The diagonals of the mean and n
matrices are set to missing.
If fun
is a function, you get a single matrix.
For the weighted covariance:
Canty, M.J. and A.A. Nielsen, 2008. Automatic radiometric normalization of multitemporal satellite imagery with the iteratively re-weighted MAD transformation. Remote Sensing of Environment 112:1025-1036.
Nielsen, A.A., 2007. The regularized iteratively reweighted MAD method for change detection in multi- and hyperspectral data. IEEE Transactions on Image Processing 16(2):463-478.
b <- rast(system.file("ex/logo.tif", package="terra")) layerCor(b, "pearson") layerCor(b, "cov") # weigh by column number w <- init(b, fun="col") layerCor(b, "weighted.cov", w=w)
b <- rast(system.file("ex/logo.tif", package="terra")) layerCor(b, "pearson") layerCor(b, "cov") # weigh by column number w <- init(b, fun="col") layerCor(b, "weighted.cov", w=w)
Get the linear units of the coordinate reference system (crs) of a SpatRaster or SpatVector expressed in m. The value returned is used internally to transform area and perimeter measures to meters. The value returned for longitude/latitude crs is zero.
## S4 method for signature 'SpatRaster' linearUnits(x) ## S4 method for signature 'SpatVector' linearUnits(x)
## S4 method for signature 'SpatRaster' linearUnits(x) ## S4 method for signature 'SpatVector' linearUnits(x)
x |
SpatRaster or SpatVector |
numeric (meter)
x <- rast() crs(x) <- "" linearUnits(x) crs(x) <- "+proj=longlat +datum=WGS84" linearUnits(x) crs(x) <- "+proj=utm +zone=1 +units=cm" linearUnits(x) crs(x) <- "+proj=utm +zone=1 +units=km" linearUnits(x) crs(x) <- "+proj=utm +zone=1 +units=us-ft" linearUnits(x)
x <- rast() crs(x) <- "" linearUnits(x) crs(x) <- "+proj=longlat +datum=WGS84" linearUnits(x) crs(x) <- "+proj=utm +zone=1 +units=cm" linearUnits(x) crs(x) <- "+proj=utm +zone=1 +units=km" linearUnits(x) crs(x) <- "+proj=utm +zone=1 +units=us-ft" linearUnits(x)
Add a vector geometries to a plot (map) with points
, lines
, or polys
.
These are simpler alternatives for plot(x, add=TRUE)
These methods also work for a small(!) SpatRaster. Only cells that are not NA in the first layer are used.
## S4 method for signature 'SpatVector' points(x, col, cex=0.7, pch=16, alpha=1, ...) ## S4 method for signature 'SpatVector' lines(x, y=NULL, col, lwd=1, lty=1, arrows=FALSE, alpha=1, ...) ## S4 method for signature 'SpatVector' polys(x, col, border="black", lwd=1, lty=1, alpha=1, ...) ## S4 method for signature 'SpatRaster' points(x, ...) ## S4 method for signature 'SpatRaster' lines(x, mx=10000, ...) ## S4 method for signature 'SpatRaster' polys(x, mx=10000, dissolve=TRUE, ...) ## S4 method for signature 'SpatExtent' points(x, col="black", alpha=1, ...) ## S4 method for signature 'SpatExtent' lines(x, col="black", alpha=1, ...) ## S4 method for signature 'SpatExtent' polys(x, col, alpha=1, ...)
## S4 method for signature 'SpatVector' points(x, col, cex=0.7, pch=16, alpha=1, ...) ## S4 method for signature 'SpatVector' lines(x, y=NULL, col, lwd=1, lty=1, arrows=FALSE, alpha=1, ...) ## S4 method for signature 'SpatVector' polys(x, col, border="black", lwd=1, lty=1, alpha=1, ...) ## S4 method for signature 'SpatRaster' points(x, ...) ## S4 method for signature 'SpatRaster' lines(x, mx=10000, ...) ## S4 method for signature 'SpatRaster' polys(x, mx=10000, dissolve=TRUE, ...) ## S4 method for signature 'SpatExtent' points(x, col="black", alpha=1, ...) ## S4 method for signature 'SpatExtent' lines(x, col="black", alpha=1, ...) ## S4 method for signature 'SpatExtent' polys(x, col, alpha=1, ...)
x |
SpatVector or SpatExtent |
y |
missing or SpatVector. If both |
col |
character. Colors |
border |
character. color(s) of the polygon borders. Use |
cex |
numeric. point size magnifier. See |
pch |
positive integer, point type. See |
alpha |
number between 0 and 1 to set transparency |
lwd |
numeric, line-width. See |
lty |
positive integer, line type. See |
arrows |
logical. If |
mx |
positive number. If the number of cells of SpatRaster |
dissolve |
logical. Should boundaries between cells with the same value be removed? |
... |
additional graphical arguments such as |
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) r <- rast(v) values(r) <- 1:ncell(r) plot(r) lines(v) points(v)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) r <- rast(v) values(r) <- 1:ncell(r) plot(r) lines(v) points(v)
Divide a SpatRaster into "tiles". The cells of another SpatRaster (normally with a much lower resolution) or a SpatVector with polygon geometry can be used to define the tiles. You can also provide one or two numbers to indicate the number of rows and columns per tile.
getTileExtents
returns the extents of the (virtual) tiles, while makeTiles
creates files for the tiles and returns their filenames.
## S4 method for signature 'SpatRaster' makeTiles(x, y, filename="tile_.tif", extend=FALSE, na.rm=FALSE, buffer=0, overwrite=FALSE, ...) ## S4 method for signature 'SpatRaster' getTileExtents(x, y, extend=FALSE, buffer=0)
## S4 method for signature 'SpatRaster' makeTiles(x, y, filename="tile_.tif", extend=FALSE, na.rm=FALSE, buffer=0, overwrite=FALSE, ...) ## S4 method for signature 'SpatRaster' getTileExtents(x, y, extend=FALSE, buffer=0)
x |
SpatRaster |
y |
SpatRaster or SpatVector defining the zones; or numeric specifying the number of rows and columns for each zone (1 or 2 numbers if the number of rows and columns is not the same) |
filename |
character. Output filename template. Filenames will be altered by adding the tile number for each tile |
extend |
logical. If |
na.rm |
logical. If |
buffer |
integer. The number of additional rows and columns added to each tile. Can be a single number, or two numbers to specify a separate number of rows and columns. This allows for creating overlapping tiles that can be used for computing spatial context dependent values with e.g. |
overwrite |
logical. If |
... |
additional arguments for writing files as in |
character (filenames) or matrix (extents)
vrt
to create a virtual raster from tiles and crop
for sub-setting arbitrary parts of a SpatRaster.
r <- rast(ncols=100, nrows=100) values(r) <- 1:ncell(r) x <- rast(ncols=2, nrows=2) getTileExtents(r, x) getTileExtents(r, x, buffer=3) filename <- paste0(tempfile(), "_.tif") ff <- makeTiles(r, x, filename) ff vrt(ff)
r <- rast(ncols=100, nrows=100) values(r) <- 1:ncell(r) x <- rast(ncols=2, nrows=2) getTileExtents(r, x) getTileExtents(r, x, buffer=3) filename <- paste0(tempfile(), "_.tif") ff <- makeTiles(r, x, filename) ff vrt(ff)
Create a VRT header file for a "flat binary" raster file that needs a header file to be able to read it, but does not have it.
makeVRT(filename, nrow, ncol, nlyr=1, extent, xmin, ymin, xres, yres=xres, xycenter=TRUE, crs="+proj=longlat", lyrnms="", datatype, NAflag=NA, bandorder="BIL", byteorder="LSB", toptobottom=TRUE, offset=0, scale=1)
makeVRT(filename, nrow, ncol, nlyr=1, extent, xmin, ymin, xres, yres=xres, xycenter=TRUE, crs="+proj=longlat", lyrnms="", datatype, NAflag=NA, bandorder="BIL", byteorder="LSB", toptobottom=TRUE, offset=0, scale=1)
filename |
character. raster filename (without the ".vrt" extension) |
nrow |
positive integer, the number of rows |
ncol |
positive integer, the number of columns |
nlyr |
positive integer, the number of layers |
extent |
SpatExtent or missing |
xmin |
numeric. minimum x coordinate (only used if |
ymin |
numeric. minimum y coordinate (only used if |
xres |
positive number. x resolution |
yres |
positive number. y resolution) |
xycenter |
logical. If |
crs |
character. Coordinate reference system description |
lyrnms |
character. Layer names |
datatype |
character. One of "INT2S", "INT4S", "INT1U", "INT2U", "INT4U", "FLT4S", "FLT8S". If missing, this is guessed from the file size (INT1U for 1 byte per value, INT2S for 2 bytes and FLT4S for 4 bytes per value). This may be wrong because, for example, 2 bytes per value may in fact be INT2U (with the U for unsigned) values |
NAflag |
numeric. The value used as the "NA flag" |
bandorder |
character. One of "BIL", "BIP", or "BSQ". That is Band Interleaved by Line, or by Pixel, or Band SeQuential |
byteorder |
character. One of "LSB", "MSB". "MSB" is common for files generated on Linux systems, whereas "LSB" is common for files generated on windows |
toptobottom |
logical. If |
offset |
numeric. offset to be applied |
scale |
numeric. scale to be applied |
character (.VRT filename)
vrt
to create a vrt for a collection of raster tiles
Helper function for creating custom map elements that are aligned with the axes of a map (base plot created with a SpatRaster and/or SpatVector). For example, you may need to know the coordinates for the upper-left corner of a map to add some information there.
Unlike the standard base plot, terra keeps the axis aligned with the data. For that reason you cannot use par()$usr
to get these coordinates.
The coordinates returned by this function are used in, for example, add_legend
such that a legend can be automatically placed in the a particular corner.
This function only returns meaningful results of the active plot (canvas) was create with a call to plot
with a SpatRaster or SpatVector as first argument.
map_extent()
map_extent()
r <- rast(xmin=0, xmax=10, ymin=0, ymax=10, res=1, vals=1:100) plot(r) map_extent() par()$usr
r <- rast(xmin=0, xmax=10, ymin=0, ymax=10, res=1, vals=1:100) plot(r) map_extent() par()$usr
Get a color palette for mapping. These palettes were copied from GRASS.
map.pal(name, n=50, ...)
map.pal(name, n=50, ...)
name |
character (name of a palette, see Details), or missing (to get the available names) |
n |
numeric. The number of colors |
... |
additional arguments that are passed to |
Name | Description |
aspect | aspect oriented grey colors |
bcyr | blue through cyan through yellow to red |
bgyr | blue through green through yellow to red |
blues | white to blue |
byg | blue through yellow to green |
byr | blue through yellow to red |
curvature | for terrain curvatures |
differences | differences oriented colors |
elevation | maps relative ranges of raster values to elevation color ramp |
grass | GRASS GIS green (perceptually uniform) |
greens | white to green |
grey | grey scale |
grey.eq | histogram-equalized grey scale |
grey.log | histogram logarithmic transformed grey scale |
gyr | green through yellow to red |
haxby | relative colors for bathymetry or topography |
inferno | perceptually uniform sequential color table inferno |
magma | perceptually uniform sequential color table magma |
oranges | white to orange |
plasma | perceptually uniform sequential color table plasma |
rainbow | rainbow color table |
ramp | color ramp |
random | random color table |
reds | white to red |
roygbiv | |
rstcurv | terrain curvature |
ryb | red through yellow to blue |
ryg | red through yellow to green |
sepia | yellowish-brown through to white |
viridis | perceptually uniform sequential color table viridis |
water | water depth |
wave | color wave |
none
map.pal("elevation", 10) r <- rast(system.file("ex/elev.tif", package="terra")) plot(r, col=map.pal("elevation")) map.pal()
map.pal("elevation", 10) r <- rast(system.file("ex/elev.tif", package="terra")) plot(r, col=map.pal("elevation")) map.pal()
If x
is a SpatRaster
:
Create a new SpatRaster that has the same values as SpatRaster x
, except for the cells that are NA
(or other maskvalue
) in another SpatRaster (the 'mask'), or the cells that are not covered by a SpatVector or SpatExtent. These cells become NA
(or another updatevalue
).
If x
is a SpatVector or SpatExtent:
Select geometries of x
that intersect, or not intersect, with the geometries of y
.
## S4 method for signature 'SpatRaster,SpatRaster' mask(x, mask, inverse=FALSE, maskvalues=NA, updatevalue=NA, filename="", ...) ## S4 method for signature 'SpatRaster,SpatVector' mask(x, mask, inverse=FALSE, updatevalue=NA, touches=TRUE, filename="", ...) ## S4 method for signature 'SpatRaster,SpatExtent' mask(x, mask, inverse=FALSE, updatevalue=NA, touches=TRUE, filename="", ...) ## S4 method for signature 'SpatVector,SpatVector' mask(x, mask, inverse=FALSE) ## S4 method for signature 'SpatVector,SpatExtent' mask(x, mask, inverse=FALSE)
## S4 method for signature 'SpatRaster,SpatRaster' mask(x, mask, inverse=FALSE, maskvalues=NA, updatevalue=NA, filename="", ...) ## S4 method for signature 'SpatRaster,SpatVector' mask(x, mask, inverse=FALSE, updatevalue=NA, touches=TRUE, filename="", ...) ## S4 method for signature 'SpatRaster,SpatExtent' mask(x, mask, inverse=FALSE, updatevalue=NA, touches=TRUE, filename="", ...) ## S4 method for signature 'SpatVector,SpatVector' mask(x, mask, inverse=FALSE) ## S4 method for signature 'SpatVector,SpatExtent' mask(x, mask, inverse=FALSE)
x |
SpatRaster or SpatVector |
mask |
SpatRaster or SpatVector |
inverse |
logical. If |
maskvalues |
numeric. The value(s) in |
updatevalue |
numeric. The value that masked cells should become (if they are not |
touches |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) msk <- ifel(r < 400, NA, 1) m <- mask(r, msk) f <- system.file("ex/lux.shp", package="terra") v <- vect(f)[1,] mv1 <- mask(r, v) mv2 <- crop(r, v, mask=TRUE)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) msk <- ifel(r < 400, NA, 1) m <- mask(r, msk) f <- system.file("ex/lux.shp", package="terra") v <- vect(f)[1,] mv1 <- mask(r, v) mv2 <- crop(r, v, mask=TRUE)
match
returns a SpatRaster with the position of the matched values. The cell values are the index of the table argument.
%in%
returns a 0/1 (FALSE/TRUE) SpatRaster indicating if the cells values were matched or not.
match(x, table, nomatch = NA_integer_, incomparables = NULL) x %in% table
match(x, table, nomatch = NA_integer_, incomparables = NULL) x %in% table
x |
SpatRaster |
table |
vector of the values to be matched against |
nomatch |
the value to be returned in the case when no match is found. Note that it is coerced to integer |
incomparables |
a vector of values that cannot be matched. Any value in x matching a value in this vector is assigned the nomatch value. For historical reasons, FALSE is equivalent to NULL |
SpatRaster
r <- rast(nrows=10, ncols=10) values(r) <- 1:100 m <- match(r, c(5:10, 50:55)) n <- r %in% c(5:10, 50:55)
r <- rast(nrows=10, ncols=10) values(r) <- 1:100 m <- match(r, c(5:10, 50:55)) n <- r %in% c(5:10, 50:55)
Standard mathematical methods for computations with SpatRasters. Computations are local (applied on a cell by cell basis). If multiple SpatRasters are used, these must have the same extent and resolution. These have been implemented:
abs, sign, sqrt, ceiling, floor, trunc, cummax, cummin, cumprod, cumsum, log, log10, log2, log1p, acos, acosh, asin, asinh, atan, atanh, exp, expm1, cos, cosh, sin, sinh, tan, tanh, round, signif
Instead of directly calling these methods, you can also provide their name to the math
method. This is useful if you want to provide an output filename.
The following methods have been implemented for SpatExtent
: round, floor, ceiling
round
has also been implemented for SpatVector
, to round the coordinates of the geometries.
## S4 method for signature 'SpatRaster' sqrt(x) ## S4 method for signature 'SpatRaster' log(x, base=exp(1)) ## S4 method for signature 'SpatRaster' round(x, digits=0) ## S4 method for signature 'SpatRaster' math(x, fun, digits=0, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatVector' round(x, digits=4) ## S4 method for signature 'SpatRaster' cumsum(x)
## S4 method for signature 'SpatRaster' sqrt(x) ## S4 method for signature 'SpatRaster' log(x, base=exp(1)) ## S4 method for signature 'SpatRaster' round(x, digits=0) ## S4 method for signature 'SpatRaster' math(x, fun, digits=0, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatVector' round(x, digits=4) ## S4 method for signature 'SpatRaster' cumsum(x)
x |
SpatRaster |
base |
a positive or complex number: the base with respect to which logarithms are computed |
digits |
Number of digits for rounding |
fun |
character. Math function name |
filename |
character. Output filename |
overwrite |
logical. If |
... |
additional arguments for writing files as in |
SpatRaster or SpatExtent
See app
to use mathematical functions not implemented by the package, and Arith-methods
for arithmetical operations. Use roll
for rolling functions.
r1 <- rast(ncols=10, nrows=10) v <- runif(ncell(r1)) v[10:20] <- NA values(r1) <- v r2 <- rast(r1) values(r2) <- 1:ncell(r2) / ncell(r2) r <- c(r1, r2) s <- sqrt(r) # same as math(r, "sqrt") round(s, 1) cumsum(r)
r1 <- rast(ncols=10, nrows=10) v <- runif(ncell(r1)) v[10:20] <- NA values(r1) <- v r2 <- rast(r1) values(r2) <- 1:ncell(r2) / ncell(r2) r <- c(r1, r2) s <- sqrt(r) # same as math(r, "sqrt") round(s, 1) cumsum(r)
mem_info
prints the amount of RAM that is required and available to process a SpatRaster.
free_RAM
returns the amount of RAM that is available
mem_info(x, n=1) free_RAM()
mem_info(x, n=1) free_RAM()
x |
SpatRaster |
n |
positive integer. The number of copies of |
free_RAM returns the amount of available RAM in kilobytes
mem_info(rast()) free_RAM()
mem_info(rast()) free_RAM()
Merge multiple SpatRasters to create a new SpatRaster with a larger spatial extent. The SpatRasters must have the same origin and spatial resolution. In areas where the SpatRasters overlap, the values of the SpatRaster that is first in the sequence of arguments (or in the SpatRasterCollection) will be retained (unless first=FALSE
). Cells that are NA
are ignored unless na.rm=FALSE
There is also a method for merging SpatVector with a data.frame; that is, to join the data.frame to the attribute table of the SpatVector.
## S4 method for signature 'SpatRaster,SpatRaster' merge(x, y, ..., first=TRUE, na.rm=TRUE, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterCollection,missing' merge(x, first=TRUE, na.rm=TRUE, filename="", ...) ## S4 method for signature 'SpatVector,data.frame' merge(x, y, ...)
## S4 method for signature 'SpatRaster,SpatRaster' merge(x, y, ..., first=TRUE, na.rm=TRUE, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterCollection,missing' merge(x, first=TRUE, na.rm=TRUE, filename="", ...) ## S4 method for signature 'SpatVector,data.frame' merge(x, y, ...)
x |
SpatRaster, SpatRasterCollection, or SpatVector |
y |
missing if |
... |
if |
first |
logical. If |
na.rm |
logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
SpatRaster or SpatVector
Combining tiles with vrt
may be more efficient than using merge
. See mosaic
for averaging overlapping regions.
See classify
to merge a SpatRaster
and a data.frame
and union
to combine SpatExtent objects.
x <- rast(xmin=-110, xmax=-80, ymin=40, ymax=70, res=1, vals=1) y <- rast(xmin=-85, xmax=-55, ymax=60, ymin=30, res=1, vals=2) z <- rast(xmin=-60, xmax=-30, ymax=50, ymin=20, res=1, vals=3) m1 <- merge(x, y, z) m2 <- merge(z, y, x) m3 <- merge(y, x, z) # if you have many SpatRasters, it may be convenient # to make a SpatRasterCollection rlist <- list(x, y, z) rsrc <- sprc(rlist) m <- merge(rsrc) ## SpatVector with data.frame f <- system.file("ex/lux.shp", package="terra") p <- vect(f) dfr <- data.frame(District=p$NAME_1, Canton=p$NAME_2, Value=round(runif(length(p), 100, 1000))) dfr <- dfr[1:5, ] pm <- merge(p, dfr, all.x=TRUE, by.x=c('NAME_1', 'NAME_2'), by.y=c('District', 'Canton')) pm values(pm)
x <- rast(xmin=-110, xmax=-80, ymin=40, ymax=70, res=1, vals=1) y <- rast(xmin=-85, xmax=-55, ymax=60, ymin=30, res=1, vals=2) z <- rast(xmin=-60, xmax=-30, ymax=50, ymin=20, res=1, vals=3) m1 <- merge(x, y, z) m2 <- merge(z, y, x) m3 <- merge(y, x, z) # if you have many SpatRasters, it may be convenient # to make a SpatRasterCollection rlist <- list(x, y, z) rsrc <- sprc(rlist) m <- merge(rsrc) ## SpatVector with data.frame f <- system.file("ex/lux.shp", package="terra") p <- vect(f) dfr <- data.frame(District=p$NAME_1, Canton=p$NAME_2, Value=round(runif(length(p), 100, 1000))) dfr <- dfr[1:5, ] pm <- merge(p, dfr, all.x=TRUE, by.x=c('NAME_1', 'NAME_2'), by.y=c('District', 'Canton')) pm values(pm)
Combine SpatRasters with partly overlapping time-stamps to create a single time series. If there is no overlap between the SpatRasters there is no point in using this function (use c
instead).
Also note that time gaps are not filled. You can use fillTime
to do that.
## S4 method for signature 'SpatRasterDataset' mergeTime(x, fun=mean, filename="", ...)
## S4 method for signature 'SpatRasterDataset' mergeTime(x, fun=mean, filename="", ...)
x |
SpatRasterDataset |
fun |
A function that reduces a vector to a single number, such as |
filename |
character. Output filename |
... |
list with named options for writing files as in |
SpatRaster
r <- rast(system.file("ex/logo.tif", package="terra")) s1 <- c(r, r) time(s1) <- as.Date("2001-01-01") + 0:5 s1 <- s1/10 time(s1) <- as.Date("2001-01-07") + 0:5 s2 <- s1*10 time(s2) <- as.Date("2001-01-05") + 0:5 x <- sds(s1, s1, s2) m <- mergeTime(x, mean)
r <- rast(system.file("ex/logo.tif", package="terra")) s1 <- c(r, r) time(s1) <- as.Date("2001-01-01") + 0:5 s1 <- s1/10 time(s1) <- as.Date("2001-01-07") + 0:5 s2 <- s1*10 time(s2) <- as.Date("2001-01-05") + 0:5 x <- sds(s1, s1, s2) m <- mergeTime(x, mean)
Get metadata associated with the sources or layers of a SpatRaster
## S4 method for signature 'SpatRaster' meta(x, layers=FALSE)
## S4 method for signature 'SpatRaster' meta(x, layers=FALSE)
x |
SpatRaster |
layers |
logical. Should the layer level metadata be returned? |
list
You can set arbitrary metadata to a SpatRaster using "name=value" tags.
## S4 replacement method for signature 'SpatRaster' metags(x, layer=NULL)<-value ## S4 method for signature 'SpatRaster' metags(x, layer=NULL, name=NULL)
## S4 replacement method for signature 'SpatRaster' metags(x, layer=NULL)<-value ## S4 method for signature 'SpatRaster' metags(x, layer=NULL, name=NULL)
x |
SpatRaster |
layer |
NULL or positive integer. If the value is NULL, the tags assigned or returned are for the SpatRaster. Otherwise for the layer number(s) |
name |
character |
value |
character of "name=value" or two-column matrix |
SpatRaster (metags<-
), or named character (metags
)
r <- rast(ncol=5, nrow=5) m <- cbind(c("one", "two", "three"), c("ABC", "123", "hello")) metags(r) <- m metags(r) metags(r) <- c("another_tag=another_value", "one more=this value") metags(r) metags(r) <- c(another_tag="44", `one more`="that value") metags(r) metags(r, name="two") # remove a tag metags(r) <- cbind("one", "") metags(r) <- "two=" metags(r) # remove all metags metags(r) <- NULL metags(r)
r <- rast(ncol=5, nrow=5) m <- cbind(c("one", "two", "three"), c("ABC", "123", "hello")) metags(r) <- m metags(r) metags(r) <- c("another_tag=another_value", "one more=this value") metags(r) metags(r) <- c(another_tag="44", `one more`="that value") metags(r) metags(r, name="two") # remove a tag metags(r) <- cbind("one", "") metags(r) <- "two=" metags(r) # remove all metags metags(r) <- NULL metags(r)
Compute the mode for each cell across the layers of a SpatRaster. The mode, or modal value, is the most frequent value in a set of values.
## S4 method for signature 'SpatRaster' modal(x, ..., ties="first", na.rm=FALSE, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' modal(x, ..., ties="first", na.rm=FALSE, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster |
... |
additional argument of the same type as |
ties |
character. Indicates how to treat ties. Either "random", "lowest", "highest", "first", or "NA" |
na.rm |
logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
SpatRaster
r <- rast(system.file("ex/logo.tif", package="terra")) r <- c(r/2, r, r*2) m <- modal(r)
r <- rast(system.file("ex/logo.tif", package="terra")) r <- c(r/2, r, r*2) m <- modal(r)
Combine adjacent and (partly) overlapping SpatRasters to form a single new SpatRaster. Values in overlapping cells are averaged (by default) or can be computed with another function.
The SpatRasters must have the same origin and spatial resolution.
This method is similar to the simpler, but much faster, merge
method.
## S4 method for signature 'SpatRaster,SpatRaster' mosaic(x, y, ..., fun="mean", filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterCollection,missing' mosaic(x, fun="mean", filename="", ...)
## S4 method for signature 'SpatRaster,SpatRaster' mosaic(x, y, ..., fun="mean", filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterCollection,missing' mosaic(x, fun="mean", filename="", ...)
x |
SpatRaster |
y |
object of same class as |
... |
additional SpatRasters |
fun |
character. One of "mean", "median", "min", "max", "modal", "sum", "first", "last" |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
SpatRaster
x <- rast(xmin=-110, xmax=-60, ymin=40, ymax=70, res=1, vals=1) y <- rast(xmin=-95, xmax=-45, ymax=60, ymin=30, res=1, vals=2) z <- rast(xmin=-80, xmax=-30, ymax=50, ymin=20, res=1, vals=3) m1 <- mosaic(x, y, z) m2 <- mosaic(z, y, x) # with many SpatRasters, make a SpatRasterCollection from a list rlist <- list(x, y, z) rsrc <- sprc(rlist) m <- mosaic(rsrc)
x <- rast(xmin=-110, xmax=-60, ymin=40, ymax=70, res=1, vals=1) y <- rast(xmin=-95, xmax=-45, ymax=60, ymin=30, res=1, vals=2) z <- rast(xmin=-80, xmax=-30, ymax=50, ymin=20, res=1, vals=3) m1 <- mosaic(x, y, z) m2 <- mosaic(z, y, x) # with many SpatRasters, make a SpatRasterCollection from a list rlist <- list(x, y, z) rsrc <- sprc(rlist) m <- mosaic(rsrc)
Find geometries that are NA; or remove geometries and/or records that are NA
.
## S4 method for signature 'SpatVector' is.na(x) ## S4 method for signature 'SpatVector' na.omit(object, field=NA, geom=FALSE)
## S4 method for signature 'SpatVector' is.na(x) ## S4 method for signature 'SpatVector' na.omit(object, field=NA, geom=FALSE)
x |
SpatVector |
object |
SpatVector |
field |
character or NA. If |
geom |
logical. If |
SpatVector
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v$test <- c(1,2,NA) nrow(v) x <- na.omit(v, "test") nrow(x)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v$test <- c(1,2,NA) nrow(v) x <- na.omit(v, "test") nrow(x)
The main purpose of this method is to allow correct reading of a SpatRaster that is based on a file that has an incorrect NA flag. The file is not changed, but flagged value is set to NA when values are read from the file ("lazy evaluation"). In contrast, if the values are in memory the change is made immediately.
To change values, it is generally better to use classify
## S4 method for signature 'SpatRaster' NAflag(x) ## S4 replacement method for signature 'SpatRaster' NAflag(x)<-value
## S4 method for signature 'SpatRaster' NAflag(x) ## S4 replacement method for signature 'SpatRaster' NAflag(x)<-value
x |
SpatRaster |
value |
numeric. The value to be interpreted as NA; set this before reading the values from the file. This can be a single value, or multiple values, one for each data source (file / subdataset) |
none or numeric
s <- rast(system.file("ex/logo.tif", package="terra"))[[1]] NAflag(s) <- 255 plot(s) NAflag(s)
s <- rast(system.file("ex/logo.tif", package="terra"))[[1]] NAflag(s) <- 255 plot(s) NAflag(s)
Get or set the names of the layers of a SpatRaster or the attributes of a SpatVector.
See set.names
for in-place setting of names.
## S4 method for signature 'SpatRaster' names(x) ## S4 replacement method for signature 'SpatRaster' names(x)<-value ## S4 method for signature 'SpatRasterDataset' names(x) ## S4 replacement method for signature 'SpatRasterDataset' names(x)<-value ## S4 method for signature 'SpatVector' names(x) ## S4 replacement method for signature 'SpatVector' names(x)<-value
## S4 method for signature 'SpatRaster' names(x) ## S4 replacement method for signature 'SpatRaster' names(x)<-value ## S4 method for signature 'SpatRasterDataset' names(x) ## S4 replacement method for signature 'SpatRasterDataset' names(x)<-value ## S4 method for signature 'SpatVector' names(x) ## S4 replacement method for signature 'SpatVector' names(x)<-value
x |
SpatRaster, SpatRasterDataset, or SpatVector |
value |
character (vector) |
character
terra enforces neither unique nor valid names. See make.unique
to create unique names and make.names
to make syntactically valid names.
s <- rast(ncols=5, nrows=5, nlyrs=3) nlyr(s) names(s) names(s) <- c("a", "b", "c") names(s) # SpatVector names f <- system.file("ex/lux.shp", package="terra") v <- vect(f) names(v) names(v) <- paste0(substr(names(v), 1, 2), "_", 1:ncol(v)) names(v)
s <- rast(ncols=5, nrows=5, nlyrs=3) nlyr(s) names(s) names(s) <- c("a", "b", "c") names(s) # SpatVector names f <- system.file("ex/lux.shp", package="terra") v <- vect(f) names(v) names(v) <- paste0(substr(names(v), 1, 2), "_", 1:ncol(v)) names(v)
Identify geometries that are near to each other. Either get the index of all geometries within a certain distance, or the k nearest neighbors, or (with nearest
) get the nearest points between two geometries.
## S4 method for signature 'SpatVector' nearby(x, y=NULL, distance=0, k=1, centroids=TRUE, symmetrical=TRUE) ## S4 method for signature 'SpatVector' nearest(x, y, pairs=FALSE, centroids=TRUE, lines=FALSE)
## S4 method for signature 'SpatVector' nearby(x, y=NULL, distance=0, k=1, centroids=TRUE, symmetrical=TRUE) ## S4 method for signature 'SpatVector' nearest(x, y, pairs=FALSE, centroids=TRUE, lines=FALSE)
x |
SpatVector |
y |
SpatVector or NULL |
distance |
numeric. maximum distance |
k |
positive integer. number of neighbors. Ignored if |
centroids |
logical. Should the centroids of polygons be used? |
symmetrical |
logical. If |
pairs |
logical. If |
lines |
logical. If |
matrix
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) nearby(v, distance=12000)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) nearby(v, distance=12000)
Compute the number of immediate adjacent cells flowing into each cell
## S4 method for signature 'SpatRaster' NIDP(x, filename="",...)
## S4 method for signature 'SpatRaster' NIDP(x, filename="",...)
x |
SpatRaster with flow-direction. see |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
NDIP is computed first to compute flow-accumulation with the algorithm by Zhou at al, 2019.
SpatRaster
Emanuele Cordano
Zhou, G., Wei, H. & Fu, S. A fast and simple algorithm for calculating flow accumulation matrices from raster digital elevation. Front. Earth Sci. 13, 317–326 (2019). https://doi.org/10.1007/s11707-018-0725-9 https://link.springer.com/article/10.1007/s11707-018-0725-9
elev1 <- array(NA,c(9,9)) elev2 <- elev1 dx <- 1 dy <- 1 for (r in 1:nrow(elev1)) { y <- (r-5)*dx for (c in 1:ncol(elev1)) { x <- (c-5)*dy elev1[r,c] <- 5*(x^2+y^2) elev2[r,c] <- 10+5*(abs(x))-0.001*y ### 5*(x^2+y^2) } } ## Elevation Raster elev1 <- rast(elev1) elev2 <- rast(elev2) t(array(elev1[],rev(dim(elev1)[1:2]))) t(array(elev2[],rev(dim(elev2)[1:2]))) plot(elev1) plot(elev2) ## Flow Direction Raster flowdir1<- terrain(elev1,v="flowdir") flowdir2<- terrain(elev2,v="flowdir") t(array(flowdir1[],rev(dim(flowdir1)[1:2]))) t(array(flowdir2[],rev(dim(flowdir2)[1:2]))) plot(flowdir1) plot(flowdir2) ## nidp1 <- NIDP((flowdir1)) nidp2 <- NIDP((flowdir2)) t(array(nidp1[],rev(dim(nidp1)[1:2]))) t(array(nidp2[],rev(dim(nidp2)[1:2]))) plot(nidp1) plot(nidp2)
elev1 <- array(NA,c(9,9)) elev2 <- elev1 dx <- 1 dy <- 1 for (r in 1:nrow(elev1)) { y <- (r-5)*dx for (c in 1:ncol(elev1)) { x <- (c-5)*dy elev1[r,c] <- 5*(x^2+y^2) elev2[r,c] <- 10+5*(abs(x))-0.001*y ### 5*(x^2+y^2) } } ## Elevation Raster elev1 <- rast(elev1) elev2 <- rast(elev2) t(array(elev1[],rev(dim(elev1)[1:2]))) t(array(elev2[],rev(dim(elev2)[1:2]))) plot(elev1) plot(elev2) ## Flow Direction Raster flowdir1<- terrain(elev1,v="flowdir") flowdir2<- terrain(elev2,v="flowdir") t(array(flowdir1[],rev(dim(flowdir1)[1:2]))) t(array(flowdir2[],rev(dim(flowdir2)[1:2]))) plot(flowdir1) plot(flowdir2) ## nidp1 <- NIDP((flowdir1)) nidp2 <- NIDP((flowdir2)) t(array(nidp1[],rev(dim(nidp1)[1:2]))) t(array(nidp2[],rev(dim(nidp2)[1:2]))) plot(nidp1) plot(nidp2)
Normalize the longitude of geometries, move them if they are outside of the -180 to 180 degrees range.
## S4 method for signature 'SpatVector' normalize.longitude(x)
## S4 method for signature 'SpatVector' normalize.longitude(x)
x |
SpatVector |
SpatVector
rotate for SpatRaster
p <- vect("POLYGON ((120 10, 230 75, 230 -75, 120 10))") normalize.longitude(p)
p <- vect("POLYGON ((120 10, 230 75, 230 -75, 120 10))") normalize.longitude(p)
Add a (North) arrow to a map
north(xy=NULL, type=1, label="N", angle=0, d, head=0.1, xpd=TRUE, ...)
north(xy=NULL, type=1, label="N", angle=0, d, head=0.1, xpd=TRUE, ...)
xy |
numeric. x and y coordinate to place the arrow. It can also be one of following character values: "bottomleft", "bottom", "bottomright", topleft", "top", "topright", "left", "right", or NULL |
type |
integer between 1 and 12, or a character (unicode) representation of a right pointing arrow such as |
label |
character, to be printed near the arrow |
angle |
numeric. The angle of the arrow in degrees |
d |
numeric. Distance covered by the arrow in plot coordinates. Only applies to |
head |
numeric. The size of the arrow "head", for |
xpd |
logical. If |
... |
graphical arguments to be passed to other methods |
none
f <- system.file("ex/meuse.tif", package="terra") r <- rast(f) plot(r) north() north(c(178550, 332500), d=250) ## Not run: f <- system.file("ex/elev.tif", package="terra") r <- rast(f) plot(r, type="interval") sbar(15, c(6.3, 50), type="bar", below="km", label=c(0,7.5,15), cex=.8) north(type=3, cex=.8) north(xy=c(6.7, 49.9), type=2, angle=45, label="NE") north(xy=c(6.6, 49.7), type=5, cex=1.25) north(xy=c(5.5, 49.6), type=9) north(d=.05, xy=c(5.5, 50), angle=180, label="S", lwd=2, col="blue") ## all arrows r <- rast(res=10) values(r) <- 1 plot(r, col="white", axes=FALSE, legend=FALSE, mar=c(0,0,0,0), reset=TRUE) for (i in 1:12) { x = -200+i*30 north(xy=cbind(x,30), type=i) text(x, -20, i, xpd=TRUE) } ## End(Not run)
f <- system.file("ex/meuse.tif", package="terra") r <- rast(f) plot(r) north() north(c(178550, 332500), d=250) ## Not run: f <- system.file("ex/elev.tif", package="terra") r <- rast(f) plot(r, type="interval") sbar(15, c(6.3, 50), type="bar", below="km", label=c(0,7.5,15), cex=.8) north(type=3, cex=.8) north(xy=c(6.7, 49.9), type=2, angle=45, label="NE") north(xy=c(6.6, 49.7), type=5, cex=1.25) north(xy=c(5.5, 49.6), type=9) north(d=.05, xy=c(5.5, 50), angle=180, label="S", lwd=2, col="blue") ## all arrows r <- rast(res=10) values(r) <- 1 plot(r, col="white", axes=FALSE, legend=FALSE, mar=c(0,0,0,0), reset=TRUE) for (i in 1:12) { x = -200+i*30 north(xy=cbind(x,30), type=i) text(x, -20, i, xpd=TRUE) } ## End(Not run)
Shortcut method to avoid the two-step !is.na(x)
## S4 method for signature 'SpatRaster' not.na(x, falseNA, filename="", ...)
## S4 method for signature 'SpatRaster' not.na(x, falseNA, filename="", ...)
x |
SpatRaster |
falseNA |
logical. Should the result be |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(ncols=10, nrows=10, vals=1) r[10:20] <- NA x <- not.na(r)
r <- rast(ncols=10, nrows=10, vals=1) r[10:20] <- NA x <- not.na(r)
Get or set general options.
terraOptions(..., print=TRUE)
terraOptions(..., print=TRUE)
... |
option names and values (see Details). Or missing, to get or show the current options |
print |
logical. If |
The following options are available.
memfrac - value between 0 and 0.9 (larger values give a warning). The fraction of RAM that may be used by the program.
memmin - if memory required is below this threshold (in GB), the memory is assumed to be available. Otherwise, terra checks if it is available.
memmax - the maximum amount of RAM (in GB) that terra is allowed to use when processing a raster dataset. Should be less than what is detected (see mem_info
), and higher values are ignored. Set it to a negative number or NA to not set this option. terraOptions
only shows the value of memmax
if it is set.
tempdir - directory where temporary files are written. The default what is returned by tempdir()
.
datatype - default data type. See writeRaster
todisk - logical. If TRUE
write all raster data to disk (temp file if no file name is specified). For debugging.
progress - non-negative integer. A progress bar is shown if the number of chunks in which the data is processed is larger than this number. No progress bar is shown if the value is zero
verbose - logical. If TRUE
debugging info is printed for some functions
list. Invisibly if print=TRUE
It is possible to set your own default options in "etc/.Rprofile.site" of your R installation like this
options(terra_default=list(tempdir="d:/temp", memfrac=.4))
But that may not be a good practice. It is clearer to set your favorite options at the beginning of each script.
terraOptions() terraOptions(memfrac=0.5, tempdir = "c:/temp") terraOptions(progress=10) terraOptions()
terraOptions() terraOptions(memfrac=0.5, tempdir = "c:/temp") terraOptions(progress=10) terraOptions()
Get or set the coordinates of the point of origin of a SpatRaster. This is the point closest to (0, 0) that you could get if you moved towards that point in steps of the x and y resolution.
## S4 method for signature 'SpatRaster' origin(x) ## S4 replacement method for signature 'SpatRaster' origin(x)<-value
## S4 method for signature 'SpatRaster' origin(x) ## S4 replacement method for signature 'SpatRaster' origin(x)<-value
x |
SpatRaster |
value |
numeric vector of length 1 or 2 |
A vector of two numbers (x and y coordinates)
r <- rast(xmin=-0.5, xmax = 9.5, ncols=10) origin(r) origin(r) <- c(0,0) r
r <- rast(xmin=-0.5, xmax = 9.5, ncols=10) origin(r) origin(r) <- c(0,0) r
Pair plots of layers in a SpatRaster. This is a wrapper around graphics function pairs
.
## S4 method for signature 'SpatRaster' pairs(x, hist=TRUE, cor=TRUE, use="pairwise.complete.obs", maxcells=100000, ...)
## S4 method for signature 'SpatRaster' pairs(x, hist=TRUE, cor=TRUE, use="pairwise.complete.obs", maxcells=100000, ...)
x |
SpatRaster |
hist |
logical. If TRUE a histogram of the values is shown on the diagonal |
cor |
logical. If TRUE the correlation coefficient is shown in the upper panels |
use |
argument passed to the |
maxcells |
integer. Number of pixels to sample from each layer of a large SpatRaster |
... |
additional arguments (graphical parameters) |
r <-rast(system.file("ex/elev.tif", package="terra")) s <- c(r, 1/r, sqrt(r)) names(s) <- c("elevation", "inverse", "sqrt") pairs(s) # to make indvidual histograms: hist(r) # or scatter plots: plot(s[[1]], s[[2]])
r <-rast(system.file("ex/elev.tif", package="terra")) s <- c(r, 1/r, sqrt(r)) names(s) <- c("elevation", "inverse", "sqrt") pairs(s) # to make indvidual histograms: hist(r) # or scatter plots: plot(s[[1]], s[[2]])
Show multiple maps that share a single legend.
## S4 method for signature 'SpatRaster' panel(x, main, loc.main="topleft", nc, nr, maxnl=16, maxcell=500000, box=FALSE, pax=list(), plg=list(), range=NULL, ...)
## S4 method for signature 'SpatRaster' panel(x, main, loc.main="topleft", nc, nr, maxnl=16, maxcell=500000, box=FALSE, pax=list(), plg=list(), range=NULL, ...)
x |
SpatRaster |
main |
character. Main plot titles (one for each layer to be plotted). You can use arguments |
loc.main |
numeric of character to set the location of the main title. Either two coordinates, or a character value such as "topleft") |
nc |
positive integer. Optional. The number of columns to divide the plotting device in (when plotting multiple layers) |
nr |
positive integer. Optional. The number of rows to divide the plotting device in (when plotting multiple layers) |
maxnl |
positive integer. Maximum number of layers to plot (for a multi-layer object) |
maxcell |
positive integer. Maximum number of cells to use for the plot |
box |
logical. Should a box be drawn around the map? |
plg |
see |
pax |
see |
range |
numeric. minimum and maximum values to be used for the continuous legend |
... |
arguments passed to |
plot
and see rasterVis::levelplot
and tidyterra::autoplot
for more sophisticated panel plots.
r <- rast(system.file("ex/elev.tif", package="terra")) v <- vect(system.file("ex/lux.shp", package="terra")) x <- c(r, r/2, r*2, r) names(x) <- paste0("(", LETTERS[1:4], ")") panel(x) panel(x, fun=\()lines(v), loc.main="topright")
r <- rast(system.file("ex/elev.tif", package="terra")) v <- vect(system.file("ex/lux.shp", package="terra")) x <- c(r, r/2, r*2, r) names(x) <- paste0("(", LETTERS[1:4], ")") panel(x) panel(x, fun=\()lines(v), loc.main="topright")
Detect patches (clumps). Patches are groups of cells that are surrounded by cells that are NA
. Set zeroAsNA
to TRUE
to also identify patches separated by cells with values of zero.
## S4 method for signature 'SpatRaster' patches(x, directions=4, zeroAsNA=FALSE, allowGaps=TRUE, filename="", ...)
## S4 method for signature 'SpatRaster' patches(x, directions=4, zeroAsNA=FALSE, allowGaps=TRUE, filename="", ...)
x |
SpatRaster |
directions |
integer indicating which cells are considered adjacent. Should be 8 (Queen's case) or 4 (Rook's case) |
zeroAsNA |
logical. If |
allowGaps |
logical. If |
filename |
character. Output filename |
... |
options for writing files as in |
SpatRaster. Cell values are patch numbers
r <- rast(nrows=18, ncols=36, xmin=0) r[1:2, 5:8] <- 1 r[5:8, 2:6] <- 1 r[7:12, 22:36] <- 1 r[15:16, 18:29] <- 1 p <- patches(r) # zero as background instead of NA r <- rast(nrows=10, ncols=10, xmin=0, vals=0) r[3, 3] <- 10 r[4, 4] <- 10 r[5, 5:8] <- 12 r[6, 6:9] <- 12 # treat zeros as NA p4 <- patches(r, zeroAsNA=TRUE) p8 <- patches(r, 8, zeroAsNA=TRUE) ### patches for different values # remove zeros manually rr <- classify(r, cbind(0, NA)) # make layers for each value s <- segregate(rr, keep=TRUE, other=NA) p <- patches(s) ### patch ID values are not guaranteed to be consecutive r <- rast(nrows=5, ncols=10, xmin=0) set.seed(0) values(r)<- round(runif(ncell(r))*0.7) rp <- patches(r, directions=8, zeroAsNA=TRUE) plot(rp, type="classes"); text(rp) ## unless you set allowGaps=FALSE rp <- patches(r, directions=8, zeroAsNA=TRUE, allowGaps=FALSE) plot(rp, type="classes"); text(rp) ### use zonal to remove small patches f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- classify(r, cbind(-Inf, 400, NA)) y <- patches(x) # remove patches smaller than 100 ha rz <- zonal(cellSize(y, unit="ha"), y, sum, as.raster=TRUE) s <- ifel(rz < 250, NA, y)
r <- rast(nrows=18, ncols=36, xmin=0) r[1:2, 5:8] <- 1 r[5:8, 2:6] <- 1 r[7:12, 22:36] <- 1 r[15:16, 18:29] <- 1 p <- patches(r) # zero as background instead of NA r <- rast(nrows=10, ncols=10, xmin=0, vals=0) r[3, 3] <- 10 r[4, 4] <- 10 r[5, 5:8] <- 12 r[6, 6:9] <- 12 # treat zeros as NA p4 <- patches(r, zeroAsNA=TRUE) p8 <- patches(r, 8, zeroAsNA=TRUE) ### patches for different values # remove zeros manually rr <- classify(r, cbind(0, NA)) # make layers for each value s <- segregate(rr, keep=TRUE, other=NA) p <- patches(s) ### patch ID values are not guaranteed to be consecutive r <- rast(nrows=5, ncols=10, xmin=0) set.seed(0) values(r)<- round(runif(ncell(r))*0.7) rp <- patches(r, directions=8, zeroAsNA=TRUE) plot(rp, type="classes"); text(rp) ## unless you set allowGaps=FALSE rp <- patches(r, directions=8, zeroAsNA=TRUE, allowGaps=FALSE) plot(rp, type="classes"); text(rp) ### use zonal to remove small patches f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- classify(r, cbind(-Inf, 400, NA)) y <- patches(x) # remove patches smaller than 100 ha rz <- zonal(cellSize(y, unit="ha"), y, sum, as.raster=TRUE) s <- ifel(rz < 250, NA, y)
This method returns the length of lines or the perimeter of polygons.
When the crs is not longitude/latitude, you may get more accurate results by first unprojecting the SpatVector (you can use project
to transform the crs to longitude/latitude)
## S4 method for signature 'SpatVector' perim(x)
## S4 method for signature 'SpatVector' perim(x)
x |
SpatVector |
numeric (m)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) perim(v)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) perim(v)
Perspective plot of a SpatRaster. This is an implementation of a generic function in the graphics package.
## S4 method for signature 'SpatRaster' persp(x, maxcells=100000, ...)
## S4 method for signature 'SpatRaster' persp(x, maxcells=100000, ...)
x |
SpatRaster. Only the first layer is used |
maxcells |
integer > 0. Maximum number of cells to use for the plot. If |
... |
Any argument that can be passed to |
persp
, contour
, plot
r <- rast(system.file("ex/elev.tif", package="terra")) persp(r)
r <- rast(system.file("ex/elev.tif", package="terra")) persp(r)
find pits (depressions with no outlet )
## S4 method for signature 'SpatRaster' pitfinder(x,filename="",...)
## S4 method for signature 'SpatRaster' pitfinder(x,filename="",...)
x |
SpatRaster wih flow-direcion. See |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
A SpatRaster-class
(raster) map containing value 1 for the pits and value 0 elsewhere.
Emanuele Cordano
terrain
,watershed
,flowAccumulation
,NIDP
## Creation of a Digital Elevation Model elev <- array(NA,c(9,9)) dx <- 1 dy <- 1 for (r in 1:nrow(elev)) { x <- (r-5)*dx for (c in 1:ncol(elev)) { y <- (c-5)*dy elev[r,c] <- 10+5*(x^2+y^2) } } elev <- cbind(elev,elev,elev,elev) elev <- rbind(elev,elev,elev,elev) elev <- rast(elev) ## Flow Directions flowdir<- terrain(elev,v="flowdir") t(array(flowdir[],rev(dim(flowdir)[1:2]))) ## Pit Detect pits <- pitfinder(flowdir) ## Application wth example DEM elev <- rast(system.file('ex/elev.tif',package="terra")) flowdir <- terrain(elev,"flowdir") pits <- pitfinder(flowdir)
## Creation of a Digital Elevation Model elev <- array(NA,c(9,9)) dx <- 1 dy <- 1 for (r in 1:nrow(elev)) { x <- (r-5)*dx for (c in 1:ncol(elev)) { y <- (c-5)*dy elev[r,c] <- 10+5*(x^2+y^2) } } elev <- cbind(elev,elev,elev,elev) elev <- rbind(elev,elev,elev,elev) elev <- rast(elev) ## Flow Directions flowdir<- terrain(elev,v="flowdir") t(array(flowdir[],rev(dim(flowdir)[1:2]))) ## Pit Detect pits <- pitfinder(flowdir) ## Application wth example DEM elev <- rast(system.file('ex/elev.tif',package="terra")) flowdir <- terrain(elev,"flowdir") pits <- pitfinder(flowdir)
Plot the values of a SpatRaster or SpatVector to make an interactive leaflet map that is displayed in a browser.
## S4 method for signature 'SpatRaster' plet(x, y=1, col, alpha=0.8, main=names(x), tiles=c("Streets", "Esri.WorldImagery", "OpenTopoMap"), wrap=TRUE, maxcell=500000, legend="bottomright", shared=FALSE, panel=FALSE, collapse=TRUE, map=NULL) ## S4 method for signature 'SpatVector' plet(x, y="", col,fill=0.2, main=y, cex=1, lwd=2, border="black", alpha=1, popup=TRUE, label=FALSE, split=FALSE, tiles=c("Streets", "Esri.WorldImagery", "OpenTopoMap"), wrap=TRUE, legend="bottomright", collapse=FALSE, type=NULL, breaks=NULL, breakby="eqint", sort=TRUE, decreasing=FALSE, map=NULL, ...) ## S4 method for signature 'SpatVectorCollection' plet(x, col, fill=0, cex=1, lwd=2, border="black", alpha=1, popup=TRUE, label=FALSE, tiles=c("Streets", "Esri.WorldImagery", "OpenTopoMap"), wrap=TRUE, legend="bottomright", collapse=FALSE, map=NULL) ## S4 method for signature 'leaflet' lines(x, y, col, lwd=2, alpha=1, ...) ## S4 method for signature 'leaflet' points(x, y, col, cex=1, alpha=1, popup=FALSE, ...) ## S4 method for signature 'leaflet' polys(x, y, col, fill=0.2, lwd=2, border="black", alpha=1, popup=TRUE, label=FALSE, ...)
## S4 method for signature 'SpatRaster' plet(x, y=1, col, alpha=0.8, main=names(x), tiles=c("Streets", "Esri.WorldImagery", "OpenTopoMap"), wrap=TRUE, maxcell=500000, legend="bottomright", shared=FALSE, panel=FALSE, collapse=TRUE, map=NULL) ## S4 method for signature 'SpatVector' plet(x, y="", col,fill=0.2, main=y, cex=1, lwd=2, border="black", alpha=1, popup=TRUE, label=FALSE, split=FALSE, tiles=c("Streets", "Esri.WorldImagery", "OpenTopoMap"), wrap=TRUE, legend="bottomright", collapse=FALSE, type=NULL, breaks=NULL, breakby="eqint", sort=TRUE, decreasing=FALSE, map=NULL, ...) ## S4 method for signature 'SpatVectorCollection' plet(x, col, fill=0, cex=1, lwd=2, border="black", alpha=1, popup=TRUE, label=FALSE, tiles=c("Streets", "Esri.WorldImagery", "OpenTopoMap"), wrap=TRUE, legend="bottomright", collapse=FALSE, map=NULL) ## S4 method for signature 'leaflet' lines(x, y, col, lwd=2, alpha=1, ...) ## S4 method for signature 'leaflet' points(x, y, col, cex=1, alpha=1, popup=FALSE, ...) ## S4 method for signature 'leaflet' polys(x, y, col, fill=0.2, lwd=2, border="black", alpha=1, popup=TRUE, label=FALSE, ...)
x |
SpatRaster, SpatVector, or leaflet object |
y |
missing, or positive integer, or character (variable or layer name) indicating the layer(s) to be plotted. If |
col |
character. Vector of colors or color generating function |
alpha |
Number between 0 and 1 to set the transparency for lines (0 is transparent, 1 is opaque) |
fill |
Number between 0 and 1 to set the transparency for polygon areas (0 is transparent, 1 is opaque) |
tiles |
character or NULL. Names of background tile providers |
wrap |
logical. if |
maxcell |
positive integer. Maximum number of cells to use for the plot |
legend |
character to indicate the legend position ("bottomleft", "bottomright", "topleft" or "topright") or NULL to suppress the legend |
main |
character. Title for the legend. The length should be 1 if |
shared |
logical. Should the legend be the same for all rasters (if multiple layers of SpatRaster |
map |
leaflet object |
... |
additional arguments for drawing points, lines, or polygons passed on the the relevant leaflet function |
border |
character. Color for the polygon borders |
collapse |
logical. Should the layers "control" panel be collapsed? |
split |
logical. If |
cex |
numeric. point size magnifier. See |
lwd |
numeric, line-width. See |
popup |
logical. Should pop-ups be created? |
label |
logical. Should mouse-over labels be added? |
panel |
logical. Should SpatRaster layers be shown as a panel" |
type |
character. Type of map/legend. One of "classes", or "interval". If not specified, the type is chosen based on the data. Use "" to suppress the legend |
breaks |
numeric. Either a single number to indicate the number of breaks desired, or the actual breaks. When providing this argument, the default legend becomes "interval" |
breakby |
character or function. Either "eqint" for equal interval breaks, "cases" for equal quantile breaks. If a function is supplied it should take a single argument (a vector of values) and create groups |
sort |
logical. If |
decreasing |
logical. If |
## Not run: if (require(leaflet) && (packageVersion("leaflet") > "2.1.1")) { v <- vect(system.file("ex/lux.shp", package="terra")) p <- spatSample(as.polygons(v, ext=T), 30) values(p) = data.frame(id=11:40, name=letters[1:30]) m <- plet(v, "NAME_1", tiles="", border="blue") m <- points(m, p, col="red", cex=2, popup=T) lines(m, v, lwd=1, col="white") plet(v, "NAME_1", split=TRUE, alpha=.2) |> points(p, col="gray", cex=2, popup=TRUE, clusterOptions = markerClusterOptions()) s <- svc(v, p) names(s) <- c("the polys", "set of points") plet(s, col=c("red", "blue"), lwd=1) r <- rast(system.file("ex/elev.tif", package="terra")) plet(r, main="Hi\nthere", tiles=NULL) |> lines(v, lwd=1) plet(r, tiles="OpenTopoMap") |> lines(v, lwd=2, col="blue") x <- c(r, 50*classify(r, 5)) names(x) <- c("first", "second") # each their own legend plet(x, 1:2, collapse=FALSE) |> lines(v, lwd=2, col="blue") # shared legend plet(x, 1:2, shared=TRUE, collapse=FALSE) |> lines(v, lwd=2, col="blue") } ## End(Not run)
## Not run: if (require(leaflet) && (packageVersion("leaflet") > "2.1.1")) { v <- vect(system.file("ex/lux.shp", package="terra")) p <- spatSample(as.polygons(v, ext=T), 30) values(p) = data.frame(id=11:40, name=letters[1:30]) m <- plet(v, "NAME_1", tiles="", border="blue") m <- points(m, p, col="red", cex=2, popup=T) lines(m, v, lwd=1, col="white") plet(v, "NAME_1", split=TRUE, alpha=.2) |> points(p, col="gray", cex=2, popup=TRUE, clusterOptions = markerClusterOptions()) s <- svc(v, p) names(s) <- c("the polys", "set of points") plet(s, col=c("red", "blue"), lwd=1) r <- rast(system.file("ex/elev.tif", package="terra")) plet(r, main="Hi\nthere", tiles=NULL) |> lines(v, lwd=1) plet(r, tiles="OpenTopoMap") |> lines(v, lwd=2, col="blue") x <- c(r, 50*classify(r, 5)) names(x) <- c("first", "second") # each their own legend plet(x, 1:2, collapse=FALSE) |> lines(v, lwd=2, col="blue") # shared legend plet(x, 1:2, shared=TRUE, collapse=FALSE) |> lines(v, lwd=2, col="blue") } ## End(Not run)
Plot the values of a SpatRaster or SpatVector to make a map.
See points
, lines
or polys
to add a SpatVector to an existing map (or use argument add=TRUE
).
There is a separate help file for plotting a SpatGraticule
or SpatExtent
.
## S4 method for signature 'SpatRaster,numeric' plot(x, y=1, col, type=NULL, mar=NULL, legend=TRUE, axes=!add, plg=list(), pax=list(), maxcell=500000, smooth=FALSE, range=NULL, fill_range=FALSE, levels=NULL, all_levels=FALSE, breaks=NULL, breakby="eqint", fun=NULL, colNA=NULL, alpha=NULL, sort=FALSE, decreasing=FALSE, grid=FALSE, ext=NULL, reset=FALSE, add=FALSE, buffer=FALSE, background=NULL, box=axes, clip=TRUE, ...) ## S4 method for signature 'SpatRaster,missing' plot(x, y, main, mar=NULL, nc, nr, maxnl=16, maxcell=500000, add=FALSE, ...) ## S4 method for signature 'SpatRaster,character' plot(x, y, ...) ## S4 method for signature 'SpatVector,character' plot(x, y, col=NULL, type=NULL, mar=NULL, add=FALSE, legend=TRUE, axes=!add, main="", buffer=TRUE, background=NULL, grid=FALSE, ext=NULL, sort=TRUE, decreasing=FALSE, plg=list(), pax=list(), nr, nc, colNA=NA, alpha=NULL, box=axes, clip=TRUE, ...) ## S4 method for signature 'SpatVector,numeric' plot(x, y, ...) ## S4 method for signature 'SpatVector,missing' plot(x, y, values=NULL, ...) ## S4 method for signature 'SpatVectorCollection,missing' plot(x, y, main, mar=NULL, nc, nr, maxnl=16, ...)
## S4 method for signature 'SpatRaster,numeric' plot(x, y=1, col, type=NULL, mar=NULL, legend=TRUE, axes=!add, plg=list(), pax=list(), maxcell=500000, smooth=FALSE, range=NULL, fill_range=FALSE, levels=NULL, all_levels=FALSE, breaks=NULL, breakby="eqint", fun=NULL, colNA=NULL, alpha=NULL, sort=FALSE, decreasing=FALSE, grid=FALSE, ext=NULL, reset=FALSE, add=FALSE, buffer=FALSE, background=NULL, box=axes, clip=TRUE, ...) ## S4 method for signature 'SpatRaster,missing' plot(x, y, main, mar=NULL, nc, nr, maxnl=16, maxcell=500000, add=FALSE, ...) ## S4 method for signature 'SpatRaster,character' plot(x, y, ...) ## S4 method for signature 'SpatVector,character' plot(x, y, col=NULL, type=NULL, mar=NULL, add=FALSE, legend=TRUE, axes=!add, main="", buffer=TRUE, background=NULL, grid=FALSE, ext=NULL, sort=TRUE, decreasing=FALSE, plg=list(), pax=list(), nr, nc, colNA=NA, alpha=NULL, box=axes, clip=TRUE, ...) ## S4 method for signature 'SpatVector,numeric' plot(x, y, ...) ## S4 method for signature 'SpatVector,missing' plot(x, y, values=NULL, ...) ## S4 method for signature 'SpatVectorCollection,missing' plot(x, y, main, mar=NULL, nc, nr, maxnl=16, ...)
x |
SpatRaster or SpatVector |
y |
missing or positive integer or name indicating the layer(s) to be plotted |
col |
character vector to specify the colors to use. The default is |
type |
character. Type of map/legend. One of "continuous", "classes", or "interval". If not specified, the type is chosen based on the data |
mar |
numeric vector of length 4 to set the margins of the plot (to make space for the legend). The default is (3.1, 3.1, 2.1, 7.1) for a single plot with a legend and (3.1, 3.1, 2.1, 2.1) otherwise. The default for a RGB raster is 0. Use |
legend |
logical or character. If not |
axes |
logical. Draw axes? |
buffer |
logical. If |
background |
background color. Default is no color (white) |
box |
logical. Should a box be drawn around the map? |
clip |
logical. Should the axes be clipped to the extent of |
plg |
list with parameters for drawing the legend. For the classes and interval type legend see the arguments for Some of these do not apply to a continuous legend, or they behave a little differently. For example, only the placement keywords "left", "right", "top", and "bottom" are recognized; and when using these keywords, the legend is placed outside of the map rectangle. Additional parameters for continuous legends include:
|
pax |
list with parameters for drawing axes. See the arguments for |
maxcell |
positive integer. Maximum number of cells to use for the plot |
smooth |
logical. If |
range |
numeric. minimum and maximum values to be used for the continuous legend |
fill_range |
logical. If |
levels |
character. labels for the legend when |
all_levels |
logical. If |
breaks |
numeric. Either a single number to indicate the number of breaks desired, or the actual breaks. When providing this argument, the default legend becomes "interval" |
breakby |
character or function. Either "eqint" for equal interval breaks, "cases" for equal quantile breaks. If a function is supplied, it should take a single argument (a vector of values) and create groups |
fun |
function to be called after plotting each SpatRaster layer to add something to each map (such as text, legend, lines). For example, with SpatVector |
colNA |
character. color for the NA values |
alpha |
Either a single numeric between 0 and 1 to set the transparency for all colors (0 is transparent, 1 is opaque) or a SpatRaster with values between 0 and 1 to set the transparency by cell. To set the transparency for a given color, set it to the colors directly |
sort |
logical. If |
decreasing |
logical. If |
grid |
logical. If |
nc |
positive integer. Optional. The number of columns to divide the plotting device in (when plotting multiple layers) |
nr |
positive integer. Optional. The number of rows to divide the plotting device in (when plotting multiple layers) |
main |
character. Main plot titles (one for each layer to be plotted). You can use arguments |
maxnl |
positive integer. Maximum number of layers to plot (for a multi-layer object) |
add |
logical. If |
ext |
SpatExtent. Can be use instead of xlim and ylim to set the extent of the plot |
reset |
logical. If |
values |
Either a vector with values to be used for plotting or a two-column data.frame, where the first column matches a variable in |
... |
arguments passed to |
Add map elements: text, sbar, north, add_legend, add_box
plot a SpatGraticule
or SpatExtent
,
multiple layers: plotRGB
, panel
other plot types: scatterplot, hist, pairs, density, persp, contour, boxplot, barplot
## SpatRaster f <- system.file("ex/elev.tif", package="terra") r <- rast(f) plot(r) plot(r, type="interval") e <- c(6.37, 6.41, 49.9, 50.1) plot(r, plg=list(ext=e, title="Legend\nTitle", title.cex=0.9), pax=list(side=1:4, retro=TRUE)) north(cbind(5.8, 50.1)) d <- classify(r, c(100,200,300,400,500,600)) plot(d, type="classes") plot(d, type="interval", breaks=1:5) plot(d, type="interval", breaks=c(1,4,5), plg=list(legend=c("1-4", "4-5"))) plot(d, type="classes", xlim=c(5.6, 6.6), plg=list(legend=c("Mr", "Xx", "As", "Zx", "Bb"), x="bottomleft")) x <- trunc(r/200) levels(x) <- data.frame(id=0:2, element=c("earth", "wind", "fire")) plot(x, plg=list(x="topright"),mar=c(2,2,2,2)) oldpar <- par(no.readonly=TRUE) # two plots with the same legend dev.new(width=6, height=4, noRStudioGD = TRUE) par(mfrow=c(1,2)) plot(r, range=c(50,600), mar=c(1,1,1,4)) plot(r/2, range=c(50,600), mar=c(1,1,1,4)) # as we only need one legend: par(mfrow=c(1,2)) plot(r, range=c(50,600), mar=c(2, 2, 2, 2), plg=list(size=0.9, cex=.8), pax=list(side=1:2, cex.axis=.6), box=FALSE) #text(182500, 335000, "Two maps, one plot", xpd=NA) plot(r/2, range=c(50,600), mar=c(2, 2, 2, 2), legend=FALSE, pax=list(side=c(1,4), cex.axis=.6), box=FALSE) par(oldpar) # multi-layer with RGB s <- rast(system.file("ex/logo.tif", package="terra")) s plot(s) # remove RGB plot(s*1) # or use layers plot(s, 1) plot(s, 1:3) # fix legend by linking values and colors x = rast(nrows = 2, ncols = 2, vals=1) y = rast(nrows = 2, ncols = 2, vals=c(1,2,2,1)) cols = data.frame(id=1:2, col=c("red", "blue")) plot(c(x,y), col=cols) r = rast(nrows=10, ncols=10, vals=1:100) dr = data.frame(from=c(5,33,66,150), to=c(33, 66, 95,200), col=rainbow(4)) plot(r, col=dr) ### SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) plot(v) plot(v, "NAME_2", col=rainbow(12), border=c("gray", "blue"), lwd=3) plot(v, 2, pax=list(side=1:2), plg=list(x=6.16, y=50.17, cex=.8), xlim=c(5.7, 6.7)) plot(v, 4, pax=list(side=1:2), plg=list(x=6.2, y=50.2, ncol=2), main="", box=FALSE) plot(v, 1, plg=list(x=5.8, y=49.37, horiz=TRUE, cex=1.1), main="", mar=c(5,2,0.5,0.5)) plot(v, density=1:12, angle=seq(18, 360, 20), col=rainbow(12)) plot(v, "AREA", type="interval", breaks=3, mar=c(3.1, 3.1, 2.1, 3.1), plg=list(x="topright"), main="") plot(v, "AREA", type="interval", breaks=c(0,200,250,350), mar=c(2,2,2,2), xlim=c(5.7, 6.75), plg=list(legend=c("<200", "200-250", ">250"), cex=1, bty="o", x=6.3, y=50.15, box.lwd=2, bg="light yellow", title="My legend"))
## SpatRaster f <- system.file("ex/elev.tif", package="terra") r <- rast(f) plot(r) plot(r, type="interval") e <- c(6.37, 6.41, 49.9, 50.1) plot(r, plg=list(ext=e, title="Legend\nTitle", title.cex=0.9), pax=list(side=1:4, retro=TRUE)) north(cbind(5.8, 50.1)) d <- classify(r, c(100,200,300,400,500,600)) plot(d, type="classes") plot(d, type="interval", breaks=1:5) plot(d, type="interval", breaks=c(1,4,5), plg=list(legend=c("1-4", "4-5"))) plot(d, type="classes", xlim=c(5.6, 6.6), plg=list(legend=c("Mr", "Xx", "As", "Zx", "Bb"), x="bottomleft")) x <- trunc(r/200) levels(x) <- data.frame(id=0:2, element=c("earth", "wind", "fire")) plot(x, plg=list(x="topright"),mar=c(2,2,2,2)) oldpar <- par(no.readonly=TRUE) # two plots with the same legend dev.new(width=6, height=4, noRStudioGD = TRUE) par(mfrow=c(1,2)) plot(r, range=c(50,600), mar=c(1,1,1,4)) plot(r/2, range=c(50,600), mar=c(1,1,1,4)) # as we only need one legend: par(mfrow=c(1,2)) plot(r, range=c(50,600), mar=c(2, 2, 2, 2), plg=list(size=0.9, cex=.8), pax=list(side=1:2, cex.axis=.6), box=FALSE) #text(182500, 335000, "Two maps, one plot", xpd=NA) plot(r/2, range=c(50,600), mar=c(2, 2, 2, 2), legend=FALSE, pax=list(side=c(1,4), cex.axis=.6), box=FALSE) par(oldpar) # multi-layer with RGB s <- rast(system.file("ex/logo.tif", package="terra")) s plot(s) # remove RGB plot(s*1) # or use layers plot(s, 1) plot(s, 1:3) # fix legend by linking values and colors x = rast(nrows = 2, ncols = 2, vals=1) y = rast(nrows = 2, ncols = 2, vals=c(1,2,2,1)) cols = data.frame(id=1:2, col=c("red", "blue")) plot(c(x,y), col=cols) r = rast(nrows=10, ncols=10, vals=1:100) dr = data.frame(from=c(5,33,66,150), to=c(33, 66, 95,200), col=rainbow(4)) plot(r, col=dr) ### SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) plot(v) plot(v, "NAME_2", col=rainbow(12), border=c("gray", "blue"), lwd=3) plot(v, 2, pax=list(side=1:2), plg=list(x=6.16, y=50.17, cex=.8), xlim=c(5.7, 6.7)) plot(v, 4, pax=list(side=1:2), plg=list(x=6.2, y=50.2, ncol=2), main="", box=FALSE) plot(v, 1, plg=list(x=5.8, y=49.37, horiz=TRUE, cex=1.1), main="", mar=c(5,2,0.5,0.5)) plot(v, density=1:12, angle=seq(18, 360, 20), col=rainbow(12)) plot(v, "AREA", type="interval", breaks=3, mar=c(3.1, 3.1, 2.1, 3.1), plg=list(x="topright"), main="") plot(v, "AREA", type="interval", breaks=c(0,200,250,350), mar=c(2,2,2,2), xlim=c(5.7, 6.75), plg=list(legend=c("<200", "200-250", ">250"), cex=1, bty="o", x=6.3, y=50.15, box.lwd=2, bg="light yellow", title="My legend"))
Plot a SpatExtent. Use lines
to add a SpatExtent to an existing map.
See plot
for plotting other object types.
## S4 method for signature 'SpatExtent,missing' plot(x, y, ...)
## S4 method for signature 'SpatExtent,missing' plot(x, y, ...)
x |
SpatExtent |
y |
missing |
... |
additional graphical arguments for lines |
r <- rast() plot(ext(r))
r <- rast() plot(ext(r))
Plot a SpatGraticule. You can create a SpatGraticule with graticule
.
## S4 method for signature 'SpatGraticule,missing' plot(x, y, background=NULL, col="black", mar=NULL, labels=TRUE, retro=FALSE, lab.loc=c(1,1), lab.lon=NULL, lab.lat=NULL, lab.cex=0.65, lab.col="black", off.lat=0.25, off.lon=0.25, box=FALSE, box.col="black", add=FALSE, ...)
## S4 method for signature 'SpatGraticule,missing' plot(x, y, background=NULL, col="black", mar=NULL, labels=TRUE, retro=FALSE, lab.loc=c(1,1), lab.lon=NULL, lab.lat=NULL, lab.cex=0.65, lab.col="black", off.lat=0.25, off.lon=0.25, box=FALSE, box.col="black", add=FALSE, ...)
x |
SpatRaster or SpatVector |
y |
missing or positive integer or name indicating the layer(s) to be plotted |
background |
background color. If NULL, no background is drawn |
mar |
numeric vector of length 4 to set the margins of the plot. To make space for the legend you may use something like |
col |
character. Color for the graticule lines |
labels |
logical. If |
retro |
logical. If |
lab.loc |
numeric. The first number indicates where the longitude graticule labels should be drawn (1=bottom, 2=top, NA=not drawn, any other number=top and bottom). The second number indicates where the latitude graticule labels should be drawn (1=left, 2=right, NA=not drawn, any other number=left and right) |
lab.lon |
positive integers between 1 and the number of labels, indicating which longitude graticule labels should be included |
lab.lat |
positive integers between 1 and the number of labels, indicating which latitude graticule labels should be included |
lab.cex |
double. size of the label font |
lab.col |
character. color of the labels |
off.lon |
numeric. longitude labels offset |
off.lat |
numeric. latitude labels offset |
box |
logical. If |
box.col |
character. color of the outer lines of the graticule if |
add |
logical. Add the graticule to the current plot? |
... |
additional graphical arguments passed to |
graticule
, plot
,
points
, lines
, polys
, image
, scatterplot
,
scale bar: sbar
, north arrow: north
g <- graticule(60, 30, crs="+proj=robin") plot(g, background="azure", col="red", lty=2, box=TRUE) plot(g, background="azure", col="light gray", lab.loc=c(1,2), lab.lon=c(2,4,6), lab.lat=3:5, lty=3, retro=TRUE)
g <- graticule(60, 30, crs="+proj=robin") plot(g, background="azure", col="red", lty=2, box=TRUE) plot(g, background="azure", col="light gray", lab.loc=c(1,2), lab.lon=c(2,4,6), lab.lat=3:5, lty=3, retro=TRUE)
Make a Red-Green-Blue plot based on three layers in a SpatRaster. The layers (sometimes referred to as "bands" because they may represent different bandwidths in the electromagnetic spectrum) are combined such that they represent the red, green and blue channel. This function can be used to make "true" (or "false") color images from Landsat and other multi-spectral satellite images.
Note that the margins of the plot are set to zero (no axes or titles are visible) but can be set with the mar
argument.
An alternative way to plot RGB images is to first use colorize
to create a single layer SpatRaster with a color-table and then use plot
.
## S4 method for signature 'SpatRaster' plotRGB(x, r=1, g=2, b=3, a=NULL, scale=NULL, mar=0, stretch=NULL, smooth=TRUE, colNA="white", alpha=NULL, bgalpha=NULL, zlim=NULL, zcol=FALSE, axes=FALSE ,...)
## S4 method for signature 'SpatRaster' plotRGB(x, r=1, g=2, b=3, a=NULL, scale=NULL, mar=0, stretch=NULL, smooth=TRUE, colNA="white", alpha=NULL, bgalpha=NULL, zlim=NULL, zcol=FALSE, axes=FALSE ,...)
x |
SpatRaster |
r |
integer between 1 and |
g |
integer between 1 and |
b |
integer between 1 and |
a |
NULL or integer between 1 and |
scale |
integer. Maximum (possible) value in the three channels. Defaults to 255 or to the maximum value of |
mar |
numeric vector recycled to length 4 to set the margins of the plot. Use |
stretch |
character. Option to stretch the values to increase contrast: "lin" (linear) or "hist" (histogram). The linear stretch uses |
smooth |
logical. If |
colNA |
color. The color used for cells that have NA values |
alpha |
transparency. Integer between 0 (transparent) and 255 (opaque) |
bgalpha |
Background transparency. Integer between 0 (transparent) and 255 (opaque) |
zlim |
numeric vector of length 2. Range of values to plot (optional). If this is set, and |
zcol |
logical. If |
axes |
logical. If |
... |
graphical parameters as in |
b <- rast(system.file("ex/logo.tif", package="terra")) plotRGB(b) plotRGB(b, mar=2) plotRGB(b, 3, 2, 1) b[1000:2000] <- NA plotRGB(b, 3, 2, 1, stretch="hist")
b <- rast(system.file("ex/logo.tif", package="terra")) plotRGB(b) plotRGB(b, mar=2) plotRGB(b, 3, 2, 1) b[1000:2000] <- NA plotRGB(b, 3, 2, 1, stretch="hist")
Compute principal components for SpatRaster layers. This method may be preferred to princomp
for its greater numerical accuracy. However, it is slower and for very large rasters it can only be done with a sample. This may be good enough but see princomp
if you want to use all values. Unlike princomp
, in this method the sample variances are used with n-1
as the denominator.
## S4 method for signature 'SpatRaster' prcomp(x, retx=TRUE, center=TRUE, scale.=FALSE, tol=NULL, rank.=NULL, maxcell=Inf)
## S4 method for signature 'SpatRaster' prcomp(x, retx=TRUE, center=TRUE, scale.=FALSE, tol=NULL, rank.=NULL, maxcell=Inf)
x |
SpatRaster |
retx |
a logical value indicating whether the rotated variables should be returned |
center |
a logical value indicating whether the variables should be shifted to be zero centered. Alternately, a vector of length equal the number of columns of x can be supplied. The value is passed to |
scale. |
a logical value indicating whether the variables should be scaled to have unit variance before the analysis takes place. The default is FALSE for consistency with S, but in general scaling is advisable. Alternatively, a vector of length equal the number of columns of x can be supplied. The value is passed to |
tol |
a value indicating the magnitude below which components should be omitted. (Components are omitted if their standard deviations are less than or equal to tol times the standard deviation of the first component.) With the default null setting, no components are omitted (unless |
rank. |
optionally, a number specifying the maximal rank, i.e., maximal number of principal components to be used. Can be set as alternative or in addition to tol, useful notably when the desired rank is considerably smaller than the dimensions of the matrix |
maxcell |
positive integer. The maximum number of cells to be used. If this is smaller than ncell(x), a regular sample of |
prcomp object
prcomp
may change the layer names if they are not valid. See make.names
. In that case, you will get a warning, and would need to also make the layer names of x
valid before using predict
. Even better would be to change them before calling prcomp
.
f <- system.file("ex/logo.tif", package = "terra") r <- rast(f) pca <- prcomp(r) x <- predict(r, pca) # use "index" to get a subset of the components p <- predict(r, pca, index=1:2)
f <- system.file("ex/logo.tif", package = "terra") r <- rast(f) pca <- prcomp(r) x <- predict(r, pca) # use "index" to get a subset of the components p <- predict(r, pca, index=1:2)
Make a SpatRaster with predictions from a fitted model object (for example, obtained with glm
or randomForest
). The first argument is a SpatRaster object with the predictor variables. The names
in the SpatRaster should exactly match those expected by the model. Any regression like model for which a predict method has been implemented (or can be implemented) can be used.
The method should work if the model's predict function returns a vector, matrix or data.frame (or a list that can be coerced to a data.frame). In other cases it may be necessary to provide a custom "predict" function that wraps the model's predict function to return the values in the required form. See the examples.
This approach of using model predictions is commonly used in remote sensing (for the classification of satellite images) and in ecology, for species distribution modeling.
## S4 method for signature 'SpatRaster' predict(object, model, fun=predict, ..., const=NULL, na.rm=FALSE, index=NULL, cores=1, cpkgs=NULL, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' predict(object, model, fun=predict, ..., const=NULL, na.rm=FALSE, index=NULL, cores=1, cpkgs=NULL, filename="", overwrite=FALSE, wopt=list())
object |
SpatRaster |
model |
fitted model of any class that has a "predict" method (or for which you can supply a similar method as |
fun |
function. The predict function that takes |
... |
additional arguments for |
const |
data.frame. Can be used to add a constant value as a predictor variable so that you do not need to make a SpatRaster layer for it |
na.rm |
logical. If |
index |
integer or character. Can be used to to select a subset of the model output variables |
cores |
positive integer. If |
cpkgs |
character. The package(s) that need to be loaded on the nodes to be able to run the model.predict function (see examples) |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
SpatRaster
interpolate
for spatial model prediction
logo <- rast(system.file("ex/logo.tif", package="terra")) names(logo) <- c("red", "green", "blue") p <- matrix(c(48, 48, 48, 53, 50, 46, 54, 70, 84, 85, 74, 84, 95, 85, 66, 42, 26, 4, 19, 17, 7, 14, 26, 29, 39, 45, 51, 56, 46, 38, 31, 22, 34, 60, 70, 73, 63, 46, 43, 28), ncol=2) a <- matrix(c(22, 33, 64, 85, 92, 94, 59, 27, 30, 64, 60, 33, 31, 9, 99, 67, 15, 5, 4, 30, 8, 37, 42, 27, 19, 69, 60, 73, 3, 5, 21, 37, 52, 70, 74, 9, 13, 4, 17, 47), ncol=2) xy <- rbind(cbind(1, p), cbind(0, a)) # extract predictor values for points e <- extract(logo, xy[,2:3]) # combine with response (excluding the ID column) v <- data.frame(cbind(pa=xy[,1], e)) #build a model, here with glm model <- glm(formula=pa~., data=v) #predict to a raster r1 <- predict(logo, model) plot(r1) points(p, bg='blue', pch=21) points(a, bg='red', pch=21) # logistic regression model <- glm(formula=pa~., data=v, family="binomial") r1log <- predict(logo, model, type="response") # to get the probability and standard error r1se <- predict(logo, model, se.fit=TRUE) # or provide a custom predict function predfun <- function(model, data) { v <- predict(model, data, se.fit=TRUE) cbind(p=as.vector(v$fit), se=as.vector(v$se.fit)) } r2 <- predict(logo, model, fun=predfun) ### principal components of a SpatRaster pca <- prcomp(logo) # or use sampling if you have a large raster # and cannot process all cell values sr <- spatSample(logo, 100000, "regular") pca <- prcomp(sr) x <- predict(logo, pca) plot(x) ## parallelization ## Not run: ## simple case with GLM model <- glm(formula=pa~., data=v) p <- predict(logo, model, cores=2) ## The above does not work with a model from a contributed ## package, as the package needs to be loaded in each core. ## Below are three approaches to deal with that library(randomForest) rfm <- randomForest(formula=pa~., data=v) ## approach 0 (not parallel) rp0 <- predict(logo, rfm) ## approach 1, use the "cpkgs" argument rp1 <- predict(logo, rfm, cores=2, cpkgs="randomForest") ## approach 2, write a custom predict function that loads the package rfun <- function(mod, dat, ...) { library(randomForest) predict(mod, dat, ...) } rp2 <- predict(logo, rfm, fun=rfun, cores=2) ## approach 3, write a parallelized custom predict function rfun <- function(mod, dat, ...) { ncls <- length(cls) nr <- nrow(dat) s <- split(dat, rep(1:ncls, each=ceiling(nr/ncls), length.out=nr)) unlist( parallel::clusterApply(cls, s, function(x, ...) predict(mod, x, ...)) ) } library(parallel) cls <- parallel::makeCluster(2) parallel::clusterExport(cls, c("rfm", "rfun", "randomForest")) rp3 <- predict(logo, rfm, fun=rfun) parallel::stopCluster(cls) plot(c(rp0, rp1, rp2, rp3)) ### with two output variables (probabilities for each class) v$pa <- as.factor(v$pa) rfm2 <- randomForest(formula=pa~., data=v) rfp <- predict(logo, rfm2, cores=2, type="prob", cpkgs="randomForest") ## End(Not run)
logo <- rast(system.file("ex/logo.tif", package="terra")) names(logo) <- c("red", "green", "blue") p <- matrix(c(48, 48, 48, 53, 50, 46, 54, 70, 84, 85, 74, 84, 95, 85, 66, 42, 26, 4, 19, 17, 7, 14, 26, 29, 39, 45, 51, 56, 46, 38, 31, 22, 34, 60, 70, 73, 63, 46, 43, 28), ncol=2) a <- matrix(c(22, 33, 64, 85, 92, 94, 59, 27, 30, 64, 60, 33, 31, 9, 99, 67, 15, 5, 4, 30, 8, 37, 42, 27, 19, 69, 60, 73, 3, 5, 21, 37, 52, 70, 74, 9, 13, 4, 17, 47), ncol=2) xy <- rbind(cbind(1, p), cbind(0, a)) # extract predictor values for points e <- extract(logo, xy[,2:3]) # combine with response (excluding the ID column) v <- data.frame(cbind(pa=xy[,1], e)) #build a model, here with glm model <- glm(formula=pa~., data=v) #predict to a raster r1 <- predict(logo, model) plot(r1) points(p, bg='blue', pch=21) points(a, bg='red', pch=21) # logistic regression model <- glm(formula=pa~., data=v, family="binomial") r1log <- predict(logo, model, type="response") # to get the probability and standard error r1se <- predict(logo, model, se.fit=TRUE) # or provide a custom predict function predfun <- function(model, data) { v <- predict(model, data, se.fit=TRUE) cbind(p=as.vector(v$fit), se=as.vector(v$se.fit)) } r2 <- predict(logo, model, fun=predfun) ### principal components of a SpatRaster pca <- prcomp(logo) # or use sampling if you have a large raster # and cannot process all cell values sr <- spatSample(logo, 100000, "regular") pca <- prcomp(sr) x <- predict(logo, pca) plot(x) ## parallelization ## Not run: ## simple case with GLM model <- glm(formula=pa~., data=v) p <- predict(logo, model, cores=2) ## The above does not work with a model from a contributed ## package, as the package needs to be loaded in each core. ## Below are three approaches to deal with that library(randomForest) rfm <- randomForest(formula=pa~., data=v) ## approach 0 (not parallel) rp0 <- predict(logo, rfm) ## approach 1, use the "cpkgs" argument rp1 <- predict(logo, rfm, cores=2, cpkgs="randomForest") ## approach 2, write a custom predict function that loads the package rfun <- function(mod, dat, ...) { library(randomForest) predict(mod, dat, ...) } rp2 <- predict(logo, rfm, fun=rfun, cores=2) ## approach 3, write a parallelized custom predict function rfun <- function(mod, dat, ...) { ncls <- length(cls) nr <- nrow(dat) s <- split(dat, rep(1:ncls, each=ceiling(nr/ncls), length.out=nr)) unlist( parallel::clusterApply(cls, s, function(x, ...) predict(mod, x, ...)) ) } library(parallel) cls <- parallel::makeCluster(2) parallel::clusterExport(cls, c("rfm", "rfun", "randomForest")) rp3 <- predict(logo, rfm, fun=rfun) parallel::stopCluster(cls) plot(c(rp0, rp1, rp2, rp3)) ### with two output variables (probabilities for each class) v$pa <- as.factor(v$pa) rfm2 <- randomForest(formula=pa~., data=v) rfp <- predict(logo, rfm2, cores=2, type="prob", cpkgs="randomForest") ## End(Not run)
Compute principal components for SpatRaster layers. This method can use all values to compute the principal components, even for very large rasters. This is because it computes the covariance matrix by processing the data in chunks, if necessary, using layerCor
. The population covariance is used (not the sample, with n-1
denominator, covariance).
Alternatively, you can specify maxcell
or sample raster values to a data.frame to speed up calculations for very large rasters (see the examples below).
See prcomp
for an alternative method that has higher numerical accuracy, but is slower, and for very large rasters can only be accomplished with a sample since all values must be read into memory.
## S4 method for signature 'SpatRaster' princomp(x, cor=FALSE, fix_sign=TRUE, use="pairwise.complete.obs", maxcell=Inf)
## S4 method for signature 'SpatRaster' princomp(x, cor=FALSE, fix_sign=TRUE, use="pairwise.complete.obs", maxcell=Inf)
x |
SpatRaster |
cor |
logical. If |
fix_sign |
logical. If |
use |
character. To decide how to handle missing values. This must be (an abbreviation of) one of the strings "everything", "complete.obs", "pairwise.complete.obs", or "masked.complete". With "pairwise.complete.obs", the covariance between a pair of layers is computed for all cells that are not |
maxcell |
positive integer. The maximum number of cells to be used. If this is smaller than ncell(x), a regular sample of |
princomp object
Alex Ilich and Robert Hijmans, based on a similar method by Benjamin Leutner
f <- system.file("ex/logo.tif", package = "terra") r <- rast(f) pca <- princomp(r) x <- predict(r, pca) # use "index" to get a subset of the components p <- predict(r, pca, index=1:2) ### use princomp directly pca2 <- princomp(values(r), fix_sign = TRUE) p2 <- predict(r, pca2) ### may need to use sampling with a large raster ### here with prcomp instead of princomp sr <- spatSample(r, 100000, "regular") pca3 <- prcomp(sr) p3 <- predict(r, pca3)
f <- system.file("ex/logo.tif", package = "terra") r <- rast(f) pca <- princomp(r) x <- predict(r, pca) # use "index" to get a subset of the components p <- predict(r, pca, index=1:2) ### use princomp directly pca2 <- princomp(values(r), fix_sign = TRUE) p2 <- predict(r, pca2) ### may need to use sampling with a large raster ### here with prcomp instead of princomp sr <- spatSample(r, 100000, "regular") pca3 <- prcomp(sr) p3 <- predict(r, pca3)
Change the coordinate reference system ("project") of a SpatVector, SpatRaster or a matrix with coordinates.
## S4 method for signature 'SpatVector' project(x, y, partial = FALSE) ## S4 method for signature 'SpatRaster' project(x, y, method, mask=FALSE, align_only=FALSE, res=NULL, origin=NULL, threads=FALSE, filename="", ..., use_gdal=TRUE, by_util = FALSE) ## S4 method for signature 'SpatExtent' project(x, from, to) ## S4 method for signature 'matrix' project(x, from, to)
## S4 method for signature 'SpatVector' project(x, y, partial = FALSE) ## S4 method for signature 'SpatRaster' project(x, y, method, mask=FALSE, align_only=FALSE, res=NULL, origin=NULL, threads=FALSE, filename="", ..., use_gdal=TRUE, by_util = FALSE) ## S4 method for signature 'SpatExtent' project(x, from, to) ## S4 method for signature 'matrix' project(x, from, to)
x |
SpatRaster, SpatVector, SpatExtent or matrix (with x and y columns) whose coordinates to project |
y |
if ( You can use the following formats to define coordinate reference systems: WKT, PROJ.4 (e.g., If |
partial |
logical. If |
method |
character. Method used for estimating the new cell values of a SpatRaster. One of:
|
mask |
logical. If |
align_only |
logical. If |
res |
numeric. Can be used to set the resolution of the output raster if |
origin |
numeric. Can be used to set the origin of the output raster if |
threads |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
use_gdal |
logical. If |
by_util |
logical. If |
from |
character. Coordinate reference system of |
to |
character. Output coordinate reference system |
SpatVector or SpatRaster
The PROJ.4 notation of coordinate reference systems has been partly deprecated in the GDAL/PROJ library that is used by this function. You can still use this notation, but *only* with the WGS84 datum. Other datums are silently ignored.
Transforming (projecting) raster data is fundamentally different from transforming vector data. Vector data can be transformed and back-transformed without loss in precision and without changes in the values. This is not the case with raster data. In each transformation the values for the new cells are estimated in some fashion. Therefore, if you need to match raster and vector data for analysis, you should generally transform the vector data.
When using this method with a SpatRaster
, the preferable approach is to provide a template SpatRaster
as argument y
. The template is then another raster dataset that you want your data to align with. If you do not have a template to begin with, you can do project(rast(x), crs)
and then manipulate the output to get the template you want. For example, where possible use whole numbers for the extent and resolution so that you do not have to worry about small differences in the future. You can use commands like dim(z) = c(180, 360)
or res(z) <- 100000
.
The output resolution should generally be similar to the input resolution, but there is no "correct" resolution in raster transformation. It is not obvious what this resolution is if you are using lon/lat data that spans a large North-South extent.
## SpatRaster a <- rast(ncols=40, nrows=40, xmin=-110, xmax=-90, ymin=40, ymax=60, crs="+proj=longlat +datum=WGS84") values(a) <- 1:ncell(a) newcrs="+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +datum=WGS84" b <- rast(ncols=94, nrows=124, xmin=-944881, xmax=935118, ymin=4664377, ymax=7144377, crs=newcrs) w <- project(a, b) ## SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) crs(v, proj=TRUE) cat(crs(v), "\n") project(v, "+proj=moll") project(v, "EPSG:2169")
## SpatRaster a <- rast(ncols=40, nrows=40, xmin=-110, xmax=-90, ymin=40, ymax=60, crs="+proj=longlat +datum=WGS84") values(a) <- 1:ncell(a) newcrs="+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +datum=WGS84" b <- rast(ncols=94, nrows=124, xmin=-944881, xmax=935118, ymin=4664377, ymax=7144377, crs=newcrs) w <- project(a, b) ## SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) crs(v, proj=TRUE) cat(crs(v), "\n") project(v, "+proj=moll") project(v, "EPSG:2169")
Compute quantiles for each cell across the layers of a SpatRaster.
You can use use global(x, fun=quantile)
to instead compute quantiles across cells for each layer.
You can also use this method to compute quantiles of the numeric variables of a SpatVector.
## S4 method for signature 'SpatRaster' quantile(x, probs=seq(0, 1, 0.25), na.rm=FALSE, filename="", ...) ## S4 method for signature 'SpatVector' quantile(x, probs=seq(0, 1, 0.25), ...)
## S4 method for signature 'SpatRaster' quantile(x, probs=seq(0, 1, 0.25), na.rm=FALSE, filename="", ...) ## S4 method for signature 'SpatVector' quantile(x, probs=seq(0, 1, 0.25), ...)
x |
SpatRaster or SpatVector |
probs |
numeric vector of probabilities with values in [0,1] |
na.rm |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster with layers representing quantiles
r <- rast(system.file("ex/logo.tif", package="terra")) rr <- c(r/2, r, r*2) qr <- quantile(rr) qr ## Not run: # same but slower qa <- app(rr, quantile) ## End(Not run) #quantile by layer instead of by cell qg <- global(r, quantile)
r <- rast(system.file("ex/logo.tif", package="terra")) rr <- c(r/2, r, r*2) qr <- quantile(rr) qr ## Not run: # same but slower qa <- app(rr, quantile) ## End(Not run) #quantile by layer instead of by cell qg <- global(r, quantile)
Query a SpatVectorProxy to extract a subset
## S4 method for signature 'SpatVectorProxy' query(x, start=1, n=nrow(x), vars=NULL, where=NULL, extent=NULL, filter=NULL, sql=NULL, what="")
## S4 method for signature 'SpatVectorProxy' query(x, start=1, n=nrow(x), vars=NULL, where=NULL, extent=NULL, filter=NULL, sql=NULL, what="")
x |
SpatVectorProxy |
start |
positive integer. The record to start reading at |
n |
positive integer. The number of records requested |
vars |
character. Variable names. Must be a subset of |
where |
character. expression like "NAME_1='California' AND ID > 3" , to subset records. Note that start and n are applied after executing the where statement |
extent |
Spat* object. The extent of the object is used as a spatial filter to select the geometries to read. Ignored if |
filter |
SpatVector. Used as a spatial filter to select geometries to read (the convex hull is used for lines or points) |
sql |
character. Arbitrary SQL statement. If used, arguments "start", "n", "vars" and "where" are ignored |
what |
character indicating what to read. Either |
SpatVector
f <- system.file("ex/lux.shp", package="terra") v <- vect(f, proxy=TRUE) v x <- query(v, vars=c("ID_2", "NAME_2"), start=5, n=2) x query(v, vars=c("ID_2", "NAME_1", "NAME_2"), where="NAME_1='Grevenmacher' AND ID_2 > 6") ## with an extent e <- ext(5.9, 6.3, 49.9, 50) x <- query(v, extent=e) ## with polygons p <- as.polygons(e) x <- query(v, filter=p) x
f <- system.file("ex/lux.shp", package="terra") v <- vect(f, proxy=TRUE) v x <- query(v, vars=c("ID_2", "NAME_2"), start=5, n=2) x query(v, vars=c("ID_2", "NAME_1", "NAME_2"), where="NAME_1='Grevenmacher' AND ID_2 > 6") ## with an extent e <- ext(5.9, 6.3, 49.9, 50) x <- query(v, extent=e) ## with polygons p <- as.polygons(e) x <- query(v, filter=p) x
Fill layers with cell-varying ranges defined by a start and end SpatRaster. The range must start at 1 and end at a user-defined maximum. Output values are either zero (not in the range) or one (in the range).
For example, for a cell with start=3
, end=5
and with limit=8
, the output for that cell would be 0,0,1,1,1,0,0,0
## S4 method for signature 'SpatRaster' rangeFill(x, limit, circular=FALSE, filename="", ...)
## S4 method for signature 'SpatRaster' rangeFill(x, limit, circular=FALSE, filename="", ...)
x |
SpatRaster with at two layers. The cell values of the first layer indicate the start of the range (1 based); the cell values are indicate the end of the range |
limit |
numeric > 1. The range size |
circular |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
x <- y <- rast(ncol=2, nrow=2) values(x) <- c(NA, 1:3) values(y) <- c(NA, 4:6) r <- rangeFill(c(x, y), 8)
x <- y <- rast(ncol=2, nrow=2) values(x) <- c(NA, 1:3) values(y) <- c(NA, 4:6) r <- rangeFill(c(x, y), 8)
Apply a function to a range of the layers of a SpatRaster that varies by cell. The range is specified for each cell with one or two SpatRasters (arguments first
and last
). For either first
or last
you can use a single number instead.
You cannot use single numbers for both first
and last
because in that case you could use app
or Summary-methods
, perhaps subset
ting the layers of a SpatRaster.
See selectRange
to create a new SpatRaster by extracting one or more values starting at a cell-varying layer.
## S4 method for signature 'SpatRaster' rapp(x, first, last, fun, ..., allyrs=FALSE, fill=NA, clamp=FALSE, circular=FALSE, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' rapp(x, first, last, fun, ..., allyrs=FALSE, fill=NA, clamp=FALSE, circular=FALSE, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster |
first |
SpatRaster or positive integer between 1 and nlyr(x), indicating the first layer in the range of layers to be considered |
last |
SpatRaster or positive integer between 1 and nlyr(x), indicating the last layer in the range to be considered |
fun |
function to be applied |
... |
additional arguments passed to |
allyrs |
logical. If |
fill |
numeric. The fill value for the values outside of the range, for when |
clamp |
logical. If |
circular |
logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
SpatRaster
selectRange
, app
, Summary-methods
, lapp
, tapp
r <- rast(ncols=9, nrows=9) values(r) <- 1:ncell(r) s <- c(r, r, r, r, r, r) s <- s * 1:6 s[1:2] <- NA start <- end <- rast(r) start[] <- 1:3 end[] <- 4:6 a <- rapp(s, start, end, fun="mean") b <- rapp(s, start, 2, fun="mean") # cumsum from start to nlyr(x). return all layers r <- rapp(s, start, nlyr(s), cumsum, allyrs=TRUE, fill=0) # return only the final value rr <- rapp(s, start, nlyr(s), function(i) max(cumsum(i)))
r <- rast(ncols=9, nrows=9) values(r) <- 1:ncell(r) s <- c(r, r, r, r, r, r) s <- s * 1:6 s[1:2] <- NA start <- end <- rast(r) start[] <- 1:3 end[] <- 4:6 a <- rapp(s, start, end, fun="mean") b <- rapp(s, start, 2, fun="mean") # cumsum from start to nlyr(x). return all layers r <- rapp(s, start, nlyr(s), cumsum, allyrs=TRUE, fill=0) # return only the final value rr <- rapp(s, start, nlyr(s), function(i) max(cumsum(i)))
Methods to create a SpatRaster. These objects can be created from scratch, from a filename, or from another object.
A SpatRaster represents a spatially referenced surface divided into three dimensional cells (rows, columns, and layers).
When a SpatRaster is created from a file, it does not load the cell (pixel) values into memory (RAM). It only reads the parameters that describe the geometry of the SpatRaster, such as the number of rows and columns and the coordinate reference system. The actual values will be read when needed.
## S4 method for signature 'character' rast(x, subds=0, lyrs=NULL, drivers=NULL, opts=NULL, win=NULL, snap="near", vsi=FALSE, raw=FALSE) ## S4 method for signature 'missing' rast(x, nrows=180, ncols=360, nlyrs=1, xmin=-180, xmax=180, ymin=-90, ymax=90, crs, extent, resolution, vals, names, time, units) ## S4 method for signature 'SpatRaster' rast(x, nlyrs=nlyr(x), names, vals, keeptime=TRUE, keepunits=FALSE, props=FALSE, tags=FALSE) ## S4 method for signature 'matrix' rast(x, type="", crs="", digits=6, extent=NULL) ## S4 method for signature 'data.frame' rast(x, type="xyz", crs="", digits=6, extent=NULL) ## S4 method for signature 'array' rast(x, crs="", extent=NULL) ## S4 method for signature 'list' rast(x, warn=TRUE) ## S4 method for signature 'SpatRasterDataset' rast(x) ## S4 method for signature 'SpatVector' rast(x, ...) ## S4 method for signature 'SpatExtent' rast(x, ...)
## S4 method for signature 'character' rast(x, subds=0, lyrs=NULL, drivers=NULL, opts=NULL, win=NULL, snap="near", vsi=FALSE, raw=FALSE) ## S4 method for signature 'missing' rast(x, nrows=180, ncols=360, nlyrs=1, xmin=-180, xmax=180, ymin=-90, ymax=90, crs, extent, resolution, vals, names, time, units) ## S4 method for signature 'SpatRaster' rast(x, nlyrs=nlyr(x), names, vals, keeptime=TRUE, keepunits=FALSE, props=FALSE, tags=FALSE) ## S4 method for signature 'matrix' rast(x, type="", crs="", digits=6, extent=NULL) ## S4 method for signature 'data.frame' rast(x, type="xyz", crs="", digits=6, extent=NULL) ## S4 method for signature 'array' rast(x, crs="", extent=NULL) ## S4 method for signature 'list' rast(x, warn=TRUE) ## S4 method for signature 'SpatRasterDataset' rast(x) ## S4 method for signature 'SpatVector' rast(x, ...) ## S4 method for signature 'SpatExtent' rast(x, ...)
x |
filename (character), missing, SpatRaster, SpatRasterDataset, SpatExtent, SpatVector, matrix, array, list of SpatRasters. For other types it will be attempted to create a SpatRaster via ('as(x, "SpatRaster")' |
subds |
positive integer or character to select a sub-dataset. If zero or "", all sub-datasets are returned (if possible) |
lyrs |
positive integer or character to select a subset of layers (a.k.a. "bands") |
drivers |
character. GDAL drivers to consider |
opts |
character. GDAL dataset open options |
win |
SpatExtent to set a |
snap |
character. One of "near", "in", or "out", to indicate how the extent of |
vsi |
logical. If |
raw |
logical. If |
nrows |
positive integer. Number of rows |
ncols |
positive integer. Number of columns |
nlyrs |
positive integer. Number of layers |
xmin |
minimum x coordinate (left border) |
xmax |
maximum x coordinate (right border) |
ymin |
minimum y coordinate (bottom border) |
ymax |
maximum y coordinate (top border) |
crs |
character. Description of the Coordinate Reference System (map projection) in |
keeptime |
logical. If |
keepunits |
logical. If |
props |
logical. If |
tags |
logical. If |
extent |
object of class SpatExtent. If present, the arguments xmin, xmax, ymin and ymax are ignored |
resolution |
numeric vector of length 1 or 2 to set the spatial resolution (see |
vals |
numeric. An optional vector with cell values (if fewer values are provided, these are recycled to reach the number of cells) |
names |
character. An optional vector with layer names (must match the number of layers) |
time |
time or date stamps for each layer |
units |
character. units for each layer |
type |
character. If the value is |
digits |
integer to set the precision for detecting whether points are on a regular grid (a low number of digits is a low precision). Only used when |
warn |
logical. If |
... |
additional arguments passed on to the |
Files are read with the GDAL library. GDAL guesses the file format from the name, and/or tries reading it with different "drivers" (see gdal
) until it succeeds. In very few cases this may cause a file to be opened with the wrong driver, and some information may be lost. For example, when a netCDF file is opened with the HDF5 driver. You can avoid that by using argument rast("filename.ncdf", drivers="NETCDF")
These classes hold a C++ pointer to the data "reference class" and that creates some limitations. They cannot be recovered from a saved R session either or directly passed to nodes on a computer cluster. Generally, you should use writeRaster
to save SpatRaster objects to disk (and pass a filename or cell values of cluster nodes). Also see wrap
.
SpatRaster
sds
to create a SpatRasterDataset (4 dimensions) and vect
for vector (points, lines, polygons) data
# Create a SpatRaster from scratch x <- rast(nrows=108, ncols=21, xmin=0, xmax=10) # Create a SpatRaster from a file f <- system.file("ex/elev.tif", package="terra") r <- rast(f) s <- rast(system.file("ex/logo.tif", package="terra")) # Create a skeleton with no associated cell values rast(s) # from a matrix m <- matrix(1:25, nrow=5, ncol=5) rm <- rast(m) # from a "xyz" data.frame d <- as.data.frame(rm, xy=TRUE) head(d) rast(d, type="xyz")
# Create a SpatRaster from scratch x <- rast(nrows=108, ncols=21, xmin=0, xmax=10) # Create a SpatRaster from a file f <- system.file("ex/elev.tif", package="terra") r <- rast(f) s <- rast(system.file("ex/logo.tif", package="terra")) # Create a skeleton with no associated cell values rast(s) # from a matrix m <- matrix(1:25, nrow=5, ncol=5) rm <- rast(m) # from a "xyz" data.frame d <- as.data.frame(rm, xy=TRUE) head(d) rast(d, type="xyz")
Transfer values associated with the geometries of vector data to a raster
## S4 method for signature 'SpatVector,SpatRaster' rasterize(x, y, field="", fun, ..., background=NA, touches=FALSE, update=FALSE, cover=FALSE, by=NULL, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'matrix,SpatRaster' rasterize(x, y, values=1, fun, ..., background=NA, update=FALSE, by=NULL, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatVector,SpatRaster' rasterize(x, y, field="", fun, ..., background=NA, touches=FALSE, update=FALSE, cover=FALSE, by=NULL, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'matrix,SpatRaster' rasterize(x, y, values=1, fun, ..., background=NA, update=FALSE, by=NULL, filename="", overwrite=FALSE, wopt=list())
x |
SpatVector or a two-column matrix (point coordinates) |
y |
SpatRaster |
field |
character or numeric. If |
values |
typically a numeric vector of length |
fun |
summarizing function for when there are multiple geometries in one cell. For lines and polygons you can only use |
... |
additional arguments passed to |
background |
numeric. Value to put in the cells that are not covered by any of the features of |
touches |
logical. If |
update |
logical. If |
cover |
logical. If |
by |
character or numeric value(s) to split |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with additional arguments for writing files as in |
SpatRaster
rasterizeGeom
, rasterizeWin
, mask
r <- rast(xmin=0, ncols=18, nrows=18) # generate points set.seed(1) p <- spatSample(r, 1000, xy=TRUE, replace=TRUE) # rasterize points as a matrix x <- rasterize(p, r, fun=sum) y <- rasterize(p, r, value=1:nrow(p), fun=max) # rasterize points as a SpatVector pv <- vect(p) xv <- rasterize(pv, r, fun=sum) # Polygons f <- system.file("ex/lux.shp", package="terra") v <- vect(f) r <- rast(v, ncols=75, nrows=100) z <- rasterize(v, r, "NAME_2") plot(z) lines(v)
r <- rast(xmin=0, ncols=18, nrows=18) # generate points set.seed(1) p <- spatSample(r, 1000, xy=TRUE, replace=TRUE) # rasterize points as a matrix x <- rasterize(p, r, fun=sum) y <- rasterize(p, r, value=1:nrow(p), fun=max) # rasterize points as a SpatVector pv <- vect(p) xv <- rasterize(pv, r, fun=sum) # Polygons f <- system.file("ex/lux.shp", package="terra") v <- vect(f) r <- rast(v, ncols=75, nrows=100) z <- rasterize(v, r, "NAME_2") plot(z) lines(v)
Rasterization of geometric properties of vector data. You can get the count of the number of geometries in each cell; the area covered by polygons; the length of the lines; or the number of lines that cross the boundary of each cell. See rasterize
for standard rasterization (of attribute values associated with geometries).
The area of polygons is intended for summing the area of polygons that are relatively small relative to the raster cells, and for when there may be multiple polygons per cell. See rasterize(fun="sum")
for counting large polygons and rasterize(cover=TRUE)
to get the fraction that is covered by larger polygons.
## S4 method for signature 'SpatVector,SpatRaster' rasterizeGeom(x, y, fun="count", unit="m", filename="", ...)
## S4 method for signature 'SpatVector,SpatRaster' rasterizeGeom(x, y, fun="count", unit="m", filename="", ...)
x |
SpatVector |
y |
SpatRaster |
fun |
character. "count", "area", "length", or "crosses" |
unit |
character. "m" or "km" |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) r <- rast(v, res=.1) # length of lines lns <- as.lines(v) x <- rasterizeGeom(lns, r, fun="length", "km") # count of points set.seed(44) pts <- spatSample(v, 100) y <- rasterizeGeom(pts, r) # area of polygons pols <- buffer(pts, 1000) z <- rasterizeGeom(pols, r, fun="area")
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) r <- rast(v, res=.1) # length of lines lns <- as.lines(v) x <- rasterizeGeom(lns, r, fun="length", "km") # count of points set.seed(44) pts <- spatSample(v, 100) y <- rasterizeGeom(pts, r) # area of polygons pols <- buffer(pts, 1000) z <- rasterizeGeom(pols, r, fun="area")
Rasterize points using a circle (or ellipse) as moving window. For each raster cell, the points (x, y
) that fall within the window centered on that cell are considered. A function is used to compute a summary value (e.g. "mean") for the values (z
) associated with these points.
This can result in much smoother results compared to the standard rasterize
method.
## S4 method for signature 'SpatVector,SpatRaster' rasterizeWin(x, y, field, win="circle", pars, fun, ..., cvars=FALSE, minPoints=1, fill=NA, filename="", wopt=list()) ## S4 method for signature 'data.frame,SpatRaster' rasterizeWin(x, y, win="circle", pars, fun, ..., cvars=FALSE, minPoints=1, fill=NA, filename="", wopt=list())
## S4 method for signature 'SpatVector,SpatRaster' rasterizeWin(x, y, field, win="circle", pars, fun, ..., cvars=FALSE, minPoints=1, fill=NA, filename="", wopt=list()) ## S4 method for signature 'data.frame,SpatRaster' rasterizeWin(x, y, win="circle", pars, fun, ..., cvars=FALSE, minPoints=1, fill=NA, filename="", wopt=list())
x |
SpatVector or matrix with at least three columns ((x, y) coordinates and a variable to be rasterized) |
y |
SpatRaster |
field |
character. field name in SpatVector |
win |
character to choose the window type. Can be "circle", "ellipse", "rectangle", or "buffer" |
pars |
parameters to define the window. If |
fun |
function to summarize the values for each cell. If |
... |
additional named arguments passed to |
minPoints |
numeric. The minimum number of points to use. If fewer points are found in a search ellipse it is considered empty and the fill value is returned |
fill |
numeric. value to use to fill cells with empty search areas |
cvars |
logical. When using multiple fields, should |
filename |
character. Output filename |
wopt |
list with additional arguments for writing files as in |
SpatRaster
rasterize
, rasterizeGeom
, interpNear
, interpIDW
r <- rast(ncol=100, nrow=100, crs="local", xmin=0, xmax=50, ymin=0, ymax=50) set.seed(100) x <- runif(50, 5, 45) y <- runif(50, 5, 45) z <- sample(50) xyz <- data.frame(x,y,z) r <- rasterizeWin(xyz, r, fun="count", pars=5) rfuns <- c("count", "min", "max", "mean") x <- lapply(rfuns, function(f) rasterizeWin(xyz, r, fun=f, pars=5)) names(x) <- rfuns x <- rast(x) #plot(x)
r <- rast(ncol=100, nrow=100, crs="local", xmin=0, xmax=50, ymin=0, ymax=50) set.seed(100) x <- runif(50, 5, 45) y <- runif(50, 5, 45) z <- sample(50) xyz <- data.frame(x,y,z) r <- rasterizeWin(xyz, r, fun="count", pars=5) rfuns <- c("count", "min", "max", "mean") x <- lapply(rfuns, function(f) rasterizeWin(xyz, r, fun=f, pars=5)) names(x) <- rfuns x <- rast(x) #plot(x)
Get a matrix with the combination of row, column, and layer numbers
## S4 method for signature 'SpatRaster' rcl(x, row=NULL, col=NULL, lyr=NULL)
## S4 method for signature 'SpatRaster' rcl(x, row=NULL, col=NULL, lyr=NULL)
x |
SpatRaster |
row |
positive integer that are row number(s), a list thereof, or NULL for all rows |
col |
as above for columns |
lyr |
as above for layers |
If a list is used for at least one of row
, col
or lyr
, these are evaluated in parallel. That is combinations are made for each list element, not across list elements. If, in this case another argument is not a list it has to have either length 1 (used for all cases) or have the same length as the (longest) list, in which case the value is coerced into a list with as.list
If multiple arguments are a list but they have different lengths, theyare recycled to the longest list.
matrix
x <- rast(ncol=5, nrow=5, nlyr=2) values(x) <- 1:size(x) rcl(x, 1, 2:3, 1:2) i <- rcl(x, 1, list(1:2, 3:4), 1:2) i # get the values for these cells x[i]
x <- rast(ncol=5, nrow=5, nlyr=2) values(x) <- 1:size(x) rcl(x, 1, 2:3, 1:2) i <- rcl(x, 1, list(1:2, 3:4), 1:2) i # get the values for these cells x[i]
Methods to read from or write chunks of values to or from a file. These are low level methods for programmers. Use writeRaster if you want to save an entire SpatRaster to file in one step. It is much easier to use.
To write chunks, begin by opening a file with writeStart
, then write values to it in chunks using the list that is returned by writeStart
. When writing is done, close the file with writeStop
.
blocks
only returns chunk size information. This can be useful when reading, but not writing, raster data.
## S4 method for signature 'SpatRaster' readStart(x) ## S4 method for signature 'SpatRaster' readStop(x) ## S4 method for signature 'SpatRaster' readValues(x, row=1, nrows=nrow(x), col=1, ncols=ncol(x), mat=FALSE, dataframe=FALSE, ...) ## S4 method for signature 'SpatRaster,character' writeStart(x, filename="", overwrite=FALSE, n=4, sources="", ...) ## S4 method for signature 'SpatRaster' writeStop(x) ## S4 method for signature 'SpatRaster,vector' writeValues(x, v, start, nrows) ## S4 method for signature 'SpatRaster' blocks(x, n=4) fileBlocksize(x)
## S4 method for signature 'SpatRaster' readStart(x) ## S4 method for signature 'SpatRaster' readStop(x) ## S4 method for signature 'SpatRaster' readValues(x, row=1, nrows=nrow(x), col=1, ncols=ncol(x), mat=FALSE, dataframe=FALSE, ...) ## S4 method for signature 'SpatRaster,character' writeStart(x, filename="", overwrite=FALSE, n=4, sources="", ...) ## S4 method for signature 'SpatRaster' writeStop(x) ## S4 method for signature 'SpatRaster,vector' writeValues(x, v, start, nrows) ## S4 method for signature 'SpatRaster' blocks(x, n=4) fileBlocksize(x)
x |
SpatRaster |
filename |
character. Output filename |
v |
vector with cell values to be written |
start |
integer. Row number (counting starts at 1) from where to start writing |
row |
positive integer. Row number to start from, should be between 1 and nrow(x) |
nrows |
positive integer. How many rows? |
col |
positive integer. Column number to start from, should be between 1 and ncol(x) |
ncols |
positive integer. How many columns? Default is the number of columns left after the start column |
mat |
logical. If |
dataframe |
logical. If |
overwrite |
logical. If |
n |
positive integer indicating how many copies the data may be in memory at any point in time. This is used to determine how many blocks (large) datasets need to be read |
sources |
character. Filenames that may not be overwritten because they are used as input to the function. Can be obtained with |
... |
For For |
readValues
returns a vector, matrix, or data.frame
writeStart
returns a list that can be used for processing the file in chunks.
The other methods invisibly return a logical value indicating whether they were successful or not. Their purpose is the side-effect of opening or closing files.
Rectify a rotated SpatRaster into a non-rotated object
## S4 method for signature 'SpatRaster' rectify(x, method="bilinear", aoi=NULL, snap=TRUE, filename="", ...)
## S4 method for signature 'SpatRaster' rectify(x, method="bilinear", aoi=NULL, snap=TRUE, filename="", ...)
x |
SpatRaster to be rectified |
method |
character. Method used to for resampling. See |
aoi |
SpatExtent or SpatRaster to crop |
snap |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
Run a regression model for each cell of a SpatRaster. The independent variable can either be defined by a vector, or another SpatRaster to make it spatially variable.
## S4 method for signature 'SpatRaster,numeric' regress(y, x, formula=y~x, na.rm=FALSE, cores=1, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatRaster,SpatRaster' regress(y, x, formula=y~x, na.rm=FALSE, cores=1, filename="", overwrite=FALSE, ...)
## S4 method for signature 'SpatRaster,numeric' regress(y, x, formula=y~x, na.rm=FALSE, cores=1, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatRaster,SpatRaster' regress(y, x, formula=y~x, na.rm=FALSE, cores=1, filename="", overwrite=FALSE, ...)
y |
SpatRaster |
x |
SpatRaster or numeric (of the same length as |
formula |
regression formula in the general form of |
na.rm |
logical. Remove NA values? |
cores |
positive integer. If |
filename |
character. Output filename |
overwrite |
logical. If |
... |
list with named options for writing files as in |
SpatRaster
s <- rast(system.file("ex/logo.tif", package="terra")) x <- regress(s, 1:nlyr(s))
s <- rast(system.file("ex/logo.tif", package="terra")) x <- regress(s, 1:nlyr(s))
relate
returns a logical matrix indicating the presence or absence of a specific spatial relationships between the geometries in x
and y
.
is.related
returns a logical vector indicating the presence or absence of a specific spatial relationships between x
and any of the geometries in y
## S4 method for signature 'SpatVector,SpatVector' relate(x, y, relation, pairs=FALSE, na.rm=TRUE) ## S4 method for signature 'SpatVector,missing' relate(x, y, relation, pairs=FALSE, na.rm=TRUE) ## S4 method for signature 'SpatVector,SpatVector' is.related(x, y, relation)
## S4 method for signature 'SpatVector,SpatVector' relate(x, y, relation, pairs=FALSE, na.rm=TRUE) ## S4 method for signature 'SpatVector,missing' relate(x, y, relation, pairs=FALSE, na.rm=TRUE) ## S4 method for signature 'SpatVector,SpatVector' is.related(x, y, relation)
x |
SpatVector or SpatExtent |
y |
missing or as for |
relation |
character. One of "intersects", "touches", "crosses", "overlaps", "within", "contains", "covers", "coveredby", "disjoint". Or a "DE-9IM" string such as "FF*FF****". See wikipedia or geotools doc |
pairs |
logical. If |
na.rm |
logical. If |
matrix (relate) or vector (is.related)
adjacent
, nearby
, intersect
, crop
# polygons p1 <- vect("POLYGON ((0 0, 8 0, 8 9, 0 9, 0 0))") p2 <- vect("POLYGON ((5 6, 15 6, 15 15, 5 15, 5 6))") p3 <- vect("POLYGON ((8 2, 9 2, 9 3, 8 3, 8 2))") p4 <- vect("POLYGON ((2 6, 3 6, 3 8, 2 8, 2 6))") p5 <- vect("POLYGON ((2 12, 3 12, 3 13, 2 13, 2 12))") p6 <- vect("POLYGON ((10 4, 12 4, 12 7, 11 7, 11 6, 10 6, 10 4))") p <- rbind(p1, p2, p3, p4, p5, p6) plot(p, col=rainbow(6, alpha=.5)) lines(p, lwd=2) text(p) ## relate SpatVectors relate(p1, p2, "intersects") relate(p1, p3, "touches") relate(p1, p5, "disjoint") relate(rbind(p1, p2), p4, "disjoint") ## relate geometries within SpatVectors # which are completely separated? relate(p, relation="disjoint") # which touch (not overlap or within)? relate(p, relation="touches") # which overlap (not merely touch, and not within)? relate(p, relation="overlaps") # which are within (not merely overlap)? relate(p, relation="within") # do they touch or overlap or are within? relate(p, relation="intersects") all(relate(p, relation="intersects") == (relate(p, relation="overlaps") | relate(p, relation="touches") | relate(p, relation="within"))) #for polygons, "coveredby" is "within" relate(p, relation="coveredby") # polygons, lines, and points pp <- rbind(p1, p2) L1 <- vect("LINESTRING(1 11, 4 6, 10 6)") L2 <- vect("LINESTRING(8 14, 12 10)") L3 <- vect("LINESTRING(1 8, 12 14)") lns <- rbind(L1, L2, L3) pts <- vect(cbind(c(7,10,10), c(3,5,6))) plot(pp, col=rainbow(2, alpha=.5)) text(pp, paste0("POL", 1:2), halo=TRUE) lines(pp, lwd=2) lines(lns, col=rainbow(3), lwd=4) text(lns, paste0("L", 1:3), halo=TRUE) points(pts, cex=1.5) text(pts, paste0("PT", 1:3), halo=TRUE, pos=4) relate(lns, relation="crosses") relate(lns, pp, relation="crosses") relate(lns, pp, relation="touches") relate(lns, pp, relation="intersects") relate(lns, pp, relation="within") # polygons can contain lines or points, not the other way around relate(lns, pp, relation="contains") relate(pp, lns, relation="contains") # points and lines can be covered by polygons relate(lns, pp, relation="coveredby") relate(pts, pp, "within") relate(pts, pp, "touches") relate(pts, lns, "touches")
# polygons p1 <- vect("POLYGON ((0 0, 8 0, 8 9, 0 9, 0 0))") p2 <- vect("POLYGON ((5 6, 15 6, 15 15, 5 15, 5 6))") p3 <- vect("POLYGON ((8 2, 9 2, 9 3, 8 3, 8 2))") p4 <- vect("POLYGON ((2 6, 3 6, 3 8, 2 8, 2 6))") p5 <- vect("POLYGON ((2 12, 3 12, 3 13, 2 13, 2 12))") p6 <- vect("POLYGON ((10 4, 12 4, 12 7, 11 7, 11 6, 10 6, 10 4))") p <- rbind(p1, p2, p3, p4, p5, p6) plot(p, col=rainbow(6, alpha=.5)) lines(p, lwd=2) text(p) ## relate SpatVectors relate(p1, p2, "intersects") relate(p1, p3, "touches") relate(p1, p5, "disjoint") relate(rbind(p1, p2), p4, "disjoint") ## relate geometries within SpatVectors # which are completely separated? relate(p, relation="disjoint") # which touch (not overlap or within)? relate(p, relation="touches") # which overlap (not merely touch, and not within)? relate(p, relation="overlaps") # which are within (not merely overlap)? relate(p, relation="within") # do they touch or overlap or are within? relate(p, relation="intersects") all(relate(p, relation="intersects") == (relate(p, relation="overlaps") | relate(p, relation="touches") | relate(p, relation="within"))) #for polygons, "coveredby" is "within" relate(p, relation="coveredby") # polygons, lines, and points pp <- rbind(p1, p2) L1 <- vect("LINESTRING(1 11, 4 6, 10 6)") L2 <- vect("LINESTRING(8 14, 12 10)") L3 <- vect("LINESTRING(1 8, 12 14)") lns <- rbind(L1, L2, L3) pts <- vect(cbind(c(7,10,10), c(3,5,6))) plot(pp, col=rainbow(2, alpha=.5)) text(pp, paste0("POL", 1:2), halo=TRUE) lines(pp, lwd=2) lines(lns, col=rainbow(3), lwd=4) text(lns, paste0("L", 1:3), halo=TRUE) points(pts, cex=1.5) text(pts, paste0("PT", 1:3), halo=TRUE, pos=4) relate(lns, relation="crosses") relate(lns, pp, relation="crosses") relate(lns, pp, relation="touches") relate(lns, pp, relation="intersects") relate(lns, pp, relation="within") # polygons can contain lines or points, not the other way around relate(lns, pp, relation="contains") relate(pp, lns, relation="contains") # points and lines can be covered by polygons relate(lns, pp, relation="coveredby") relate(pts, pp, "within") relate(pts, pp, "touches") relate(pts, lns, "touches")
Replicate layers in a SpatRaster
## S4 method for signature 'SpatRaster' rep(x, ...)
## S4 method for signature 'SpatRaster' rep(x, ...)
x |
SpatRaster |
... |
arguments as in |
SpatRaster
s <- rast(system.file("ex/logo.tif", package="terra")) x <- rep(s, 2) nlyr(x) names(x) x
s <- rast(system.file("ex/logo.tif", package="terra")) x <- rep(s, 2) nlyr(x) names(x) x
Replace a layer of a SpatRaster, or an attribute variable of a SpatVector
## S4 replacement method for signature 'SpatRaster' x$name <- value ## S4 replacement method for signature 'SpatVector' x$name<-value ## S4 replacement method for signature 'SpatExtent' x$name <- value
## S4 replacement method for signature 'SpatRaster' x$name <- value ## S4 replacement method for signature 'SpatVector' x$name<-value ## S4 replacement method for signature 'SpatExtent' x$name <- value
x |
SpatRaster, SpatVector or SpatExtent |
name |
character. If |
value |
if |
Same as x
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v$ID_1 <- LETTERS[1:12] v$new <- sample(12) values(v)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v$ID_1 <- LETTERS[1:12] v$new <- sample(12) values(v)
Replace the layers of SpatRaster with (layers from) another SpatRaster or replace variables of a SpatVector. You can also create new layers/variables with these methods.
## S4 replacement method for signature 'SpatRaster,numeric' x[[i]] <- value ## S4 replacement method for signature 'SpatRaster,character' x[[i]] <- value ## S4 replacement method for signature 'SpatVector,numeric' x[[i]] <- value ## S4 replacement method for signature 'SpatVector,character' x[[i]] <- value
## S4 replacement method for signature 'SpatRaster,numeric' x[[i]] <- value ## S4 replacement method for signature 'SpatRaster,character' x[[i]] <- value ## S4 replacement method for signature 'SpatVector,numeric' x[[i]] <- value ## S4 replacement method for signature 'SpatVector,character' x[[i]] <- value
x |
SpatRaster or SpatVector |
i |
if |
value |
if |
SpatRaster
# raster s <- rast(system.file("ex/logo.tif", package="terra")) s[["red"]] <- mean(s) s[[2]] <- sqrt(s[[1]]) # vector v <- vect(system.file("ex/lux.shp", package="terra")) v[["ID_1"]] <- 12:1
# raster s <- rast(system.file("ex/logo.tif", package="terra")) s[["red"]] <- mean(s) s[[2]] <- sqrt(s[[1]]) # vector v <- vect(system.file("ex/lux.shp", package="terra")) v[["ID_1"]] <- 12:1
Replace values of a SpatRaster. These are convenience functions for smaller objects only. For larger rasters see link{classify}
or subst
## S4 replacement method for signature 'SpatRaster,ANY,ANY,ANY' x[i, j, k] <- value ## S4 replacement method for signature 'SpatVector,ANY,ANY' x[i, j] <- value ## S4 replacement method for signature 'SpatExtent,numeric,missing' x[i, j] <- value
## S4 replacement method for signature 'SpatRaster,ANY,ANY,ANY' x[i, j, k] <- value ## S4 replacement method for signature 'SpatVector,ANY,ANY' x[i, j] <- value ## S4 replacement method for signature 'SpatExtent,numeric,missing' x[i, j] <- value
x |
SpatRaster |
i |
row numbers. numeric, logical, or missing for all rows. Can also be a SpatRaster or SpatVector |
j |
column numbers. numeric, logical or missing for all columns |
k |
layer number. numeric, logical or missing for all layers |
value |
numeric, matrix, or data.frame |
SpatRaster
classify, subst, set.values, values, [[<-
## SpatRaster r <- rast(ncols=5, nrows=5, xmin=0, xmax=5, ymin=0, ymax=5) r[] <- 1:25 r[1,] <- 5 r[,2] <- 10 r[r>10] <- NA ## SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v[2,2] <- "hello" v[1,] <- v[10,] v[,3] <- v[,1] v[2, "NAME_2"] <- "terra" head(v, 3)
## SpatRaster r <- rast(ncols=5, nrows=5, xmin=0, xmax=5, ymin=0, ymax=5) r[] <- 1:25 r[1,] <- 5 r[,2] <- 10 r[r>10] <- NA ## SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) v[2,2] <- "hello" v[1,] <- v[10,] v[,3] <- v[,1] v[2, "NAME_2"] <- "terra" head(v, 3)
resample transfers values between SpatRaster objects that do not align (have a different origin and/or resolution). See project
to change the coordinate reference system (crs).
If the origin and extent of the input and output are the same, you should consider using these other functions instead: aggregate
, disagg
, extend
or crop
.
## S4 method for signature 'SpatRaster,SpatRaster' resample(x, y, method, threads=FALSE, filename="", ...)
## S4 method for signature 'SpatRaster,SpatRaster' resample(x, y, method, threads=FALSE, filename="", ...)
x |
SpatRaster to be resampled |
y |
SpatRaster with the geometry that |
method |
character. Method used for estimating the new cell values. One of:
|
threads |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
aggregate
, disagg
, crop
, project
r <- rast(nrows=3, ncols=3, xmin=0, xmax=10, ymin=0, ymax=10) values(r) <- 1:ncell(r) s <- rast(nrows=25, ncols=30, xmin=1, xmax=11, ymin=-1, ymax=11) x <- resample(r, s, method="bilinear") opar <- par(no.readonly =TRUE) par(mfrow=c(1,2)) plot(r) plot(x) par(opar)
r <- rast(nrows=3, ncols=3, xmin=0, xmax=10, ymin=0, ymax=10) values(r) <- 1:ncell(r) s <- rast(nrows=25, ncols=30, xmin=1, xmax=11, ymin=-1, ymax=11) x <- resample(r, s, method="bilinear") opar <- par(no.readonly =TRUE) par(mfrow=c(1,2)) plot(r) plot(x) par(opar)
Rescale a SpatVector or SpatRaster. This may be useful to make small inset
maps or for georeferencing.
## S4 method for signature 'SpatRaster' rescale(x, fx=0.5, fy=fx, x0, y0) ## S4 method for signature 'SpatVector' rescale(x, fx=0.5, fy=fx, x0, y0)
## S4 method for signature 'SpatRaster' rescale(x, fx=0.5, fy=fx, x0, y0) ## S4 method for signature 'SpatVector' rescale(x, fx=0.5, fy=fx, x0, y0)
x |
SpatVector or SpatRaster |
fx |
numeric > 0. The horizontal scaling factor |
fy |
numeric > 0. The vertical scaling factor |
x0 |
numeric. x-coordinate of the center of rescaling. If missing, the center of the extent of |
y0 |
numeric. y-coordinate of the center of rescaling. If missing, the center of the extent of |
Same as x
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) w <- rescale(v, 0.2) plot(v) lines(w, col="red")
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) w <- rescale(v, 0.2) plot(v) lines(w, col="red")
With RGB
you can get or set the layers to be used as Red, Green and Blue when plotting a SpatRaster. Currently, a benefit of this is that plot
will send the object to plotRGB
. You can also associated the layers with another color space (HSV, HSI or HSL)
With colorize
you can convert a three-layer RGB SpatRaster into other color spaces. You can also convert it into a single-layer SpatRaster with a color-table.
## S4 method for signature 'SpatRaster' RGB(x) ## S4 replacement method for signature 'SpatRaster' RGB(x, ..., type="rgb")<-value ## S4 method for signature 'SpatRaster' colorize(x, to="hsv", alpha=FALSE, stretch=NULL, grays=FALSE, NAzero=FALSE, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatRaster' has.RGB(x, strict=TRUE)
## S4 method for signature 'SpatRaster' RGB(x) ## S4 replacement method for signature 'SpatRaster' RGB(x, ..., type="rgb")<-value ## S4 method for signature 'SpatRaster' colorize(x, to="hsv", alpha=FALSE, stretch=NULL, grays=FALSE, NAzero=FALSE, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatRaster' has.RGB(x, strict=TRUE)
x |
SpatRaster |
value |
vector of three (or four) positive integers indicating the layers that are red, green and blue (and optionally a fourth transparency layer). Or |
type |
character. The color space. One of "rgb" "hsv", "hsi" and "hsl" |
to |
character. The color space to transform the values to. If |
alpha |
logical. Should an alpha (transparency) channel be included? Only used if |
stretch |
character. Option to stretch the values to increase contrast: "lin" (linear) or "hist" (histogram). Only used for transforming RGB to col |
grays |
logical. If |
NAzero |
logical. If |
strict |
logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
... |
additional arguments for writing files as in |
r <- rast(system.file("ex/logo.tif", package="terra")) plot(r) has.RGB(r) RGB(r) <- NULL has.RGB(r) plot(r) RGB(r) <- c(3,1,2) plot(r) RGB(r) <- 1:3 x <- colorize(r, "col") y <- colorize(r, "hsv") z <- colorize(y, "rgb")
r <- rast(system.file("ex/logo.tif", package="terra")) plot(r) has.RGB(r) RGB(r) <- NULL has.RGB(r) plot(r) RGB(r) <- c(3,1,2) plot(r) RGB(r) <- 1:3 x <- colorize(r, "col") y <- colorize(r, "hsv") z <- colorize(y, "rgb")
Compute "rolling" or "moving" values, such as the "rolling average" for each cell in a SpatRaster.
See focal
for spatially moving averages and similar computations. And see cumsum
and other cum* functions to compute cumulate values.
## S4 method for signature 'SpatRaster' roll(x, n, fun=mean, type="around", circular=FALSE, na.rm=FALSE, filename="", ..., wopt=list()) ## S4 method for signature 'numeric' roll(x, n, fun=mean, type="around", circular=FALSE, na.rm=FALSE, ...)
## S4 method for signature 'SpatRaster' roll(x, n, fun=mean, type="around", circular=FALSE, na.rm=FALSE, filename="", ..., wopt=list()) ## S4 method for signature 'numeric' roll(x, n, fun=mean, type="around", circular=FALSE, na.rm=FALSE, ...)
x |
SpatRaster or numeric |
n |
integer > 1. The size of the "window", that is, the number of sequential cells to use in |
fun |
a function like mean, min, max, sum |
type |
character. One of "around", "to", or "from". The choice indicates which values should be used in the computation. The focal cell is always used. If type is "around", |
circular |
logical. If |
na.rm |
logical. If |
filename |
character. Output filename |
... |
additional arguments for |
wopt |
list with named options for writing files as in |
Same as x
## numeric roll(1:12, 3, mean) roll(1:12, 3, mean, "to") roll(1:12, 3, mean, circular=TRUE) ## SpatRaster r <- rast(ncol=2, nrow=2, nlyr=10, vals=1) r[1,2] = 2 r[2,2] = 4 roll(r, n=3, "sum", "from", na.rm=FALSE) |> values() roll(r, n=3, "sum", "from", na.rm=TRUE) |> values() roll(r, n=3, "sum", "from", circular=TRUE) |> values() roll(r, n=3, "sum", "to", na.rm=TRUE) |> values() roll(r, n=3, "sum", "around", circular=TRUE) |> values()
## numeric roll(1:12, 3, mean) roll(1:12, 3, mean, "to") roll(1:12, 3, mean, circular=TRUE) ## SpatRaster r <- rast(ncol=2, nrow=2, nlyr=10, vals=1) r[1,2] = 2 r[2,2] = 4 roll(r, n=3, "sum", "from", na.rm=FALSE) |> values() roll(r, n=3, "sum", "from", na.rm=TRUE) |> values() roll(r, n=3, "sum", "from", circular=TRUE) |> values() roll(r, n=3, "sum", "to", na.rm=TRUE) |> values() roll(r, n=3, "sum", "around", circular=TRUE) |> values()
Rotate a SpatRaster that has longitude coordinates from 0 to 360, to standard coordinates between -180 and 180 degrees (or vice-versa). Longitude between 0 and 360 is frequently used in global climate models.
Rotate a SpatVector as for a SpatRaster split=TRUE
, or to correct for coordinates that are connected across the date line (and end up at the "other side" of the longitude scale) are reconnected.
## S4 method for signature 'SpatRaster' rotate(x, left=TRUE, filename="", ...) ## S4 method for signature 'SpatVector' rotate(x, longitude=0, split=FALSE, left=TRUE, normalize=FALSE)
## S4 method for signature 'SpatRaster' rotate(x, left=TRUE, filename="", ...) ## S4 method for signature 'SpatVector' rotate(x, longitude=0, split=FALSE, left=TRUE, normalize=FALSE)
x |
SpatRaster or SpatVector |
left |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
longitude |
numeric. The longitude around which to rotate |
split |
logical. Should geometries be split at |
normalize |
logical. Should the output be normalized to longitudes between -180 and 180? See |
SpatRaster
x <- rast(nrows=9, ncols=18, nl=3, xmin=0, xmax=360) v <- rep(as.vector(t(matrix(1:ncell(x), nrow=9, ncol=18))), 3) values(x) <- v z <- rotate(x) ## Not run: #SpatVector p <- rbind(c(3847903, 1983584 ), c(3847903, 5801864), c(8301883, 5801864), c(8301883, 1983584 )) p <- vect(p, "polygons", crs="+init=EPSG:3347") d <- densify(p, 100000) g <- project(d, "+proj=longlat") x <- rotate(g, 50) plot(g) lines(x, col="red") ## End(Not run) ## rotate countries to 0-360 longitude #w <- geodata::world(path=".") #x <- rotate(w, long=0, split=TRUE, left=FALSE)
x <- rast(nrows=9, ncols=18, nl=3, xmin=0, xmax=360) v <- rep(as.vector(t(matrix(1:ncell(x), nrow=9, ncol=18))), 3) values(x) <- v z <- rotate(x) ## Not run: #SpatVector p <- rbind(c(3847903, 1983584 ), c(3847903, 5801864), c(8301883, 5801864), c(8301883, 1983584 )) p <- vect(p, "polygons", crs="+init=EPSG:3347") d <- densify(p, 100000) g <- project(d, "+proj=longlat") x <- rotate(g, 50) plot(g) lines(x, col="red") ## End(Not run) ## rotate countries to 0-360 longitude #w <- geodata::world(path=".") #x <- rotate(w, long=0, split=TRUE, left=FALSE)
The function takes two coordinate reference system descriptions and compares them for equality.
same.crs(x, y)
same.crs(x, y)
x |
character, SpatRaster, SpatVector, CRS, or other object that returns something intelligible with |
y |
same types as for |
logical
r <- rast() same.crs(r, "+proj=longlat") same.crs(r, "+proj=utm +zone=1")
r <- rast() same.crs(r, "+proj=longlat") same.crs(r, "+proj=utm +zone=1")
Apply to all layers of a SpatRaster a function that only takes a single layer SpatRaster and returns a SpatRaster (these are rare). In most cases you can also use lapply
or sapply
for this.
Or apply the same method to each sub-dataset (SpatRaster) in a SpatRasterDataset
## S4 method for signature 'SpatRaster' sapp(x, fun, ..., filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterDataset' sapp(x, fun, ..., filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' sapp(x, fun, ..., filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRasterDataset' sapp(x, fun, ..., filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster or SpatRasterDataset |
fun |
if |
... |
additional arguments to be passed to |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
SpatRaster
s <- rast(system.file("ex/logo.tif", package="terra")) + 1 #SpatRasterDataset sd <- sds(s*2, s/2) y <- sapp(sd, mean) z <- sapp(sd, \(i) 2 * mean(i))
s <- rast(system.file("ex/logo.tif", package="terra")) + 1 #SpatRasterDataset sd <- sds(s*2, s/2) y <- sapp(sd, mean) z <- sapp(sd, \(i) 2 * mean(i))
Add a scale bar to a map
sbar(d, xy=NULL, type="line", divs=2, below="", lonlat=NULL, labels, adj=c(0.5, -1), lwd=2, xpd=TRUE, ticks=FALSE, scaleby=1, halo=TRUE, ...)
sbar(d, xy=NULL, type="line", divs=2, below="", lonlat=NULL, labels, adj=c(0.5, -1), lwd=2, xpd=TRUE, ticks=FALSE, scaleby=1, halo=TRUE, ...)
d |
numeric. Distance covered by the scale bar. For the scale bar, it should be in the units of the coordinates of the plot (map), and in km for angular (longitude/latitude) data; see argument |
xy |
numeric. x and y coordinate to place the scale bar. It can also be one of following character values: "bottomleft", "bottom", "bottomright", topleft", "top", "topright", "left", "right", or NULL |
type |
for |
divs |
number of divisions for a bar: 2 or 4 |
below |
character. Text to go below the scale bar (e.g., "kilometers") |
lonlat |
logical or NULL. If logical, |
labels |
vector of three numbers to label the scale bar (beginning, midpoint, end) |
adj |
adjustment for text placement |
lwd |
line width for the "line" type of the scale bar |
xpd |
logical. If |
ticks |
logical or numeric. If not |
scaleby |
numeric. If |
halo |
logical. If |
... |
graphical arguments to be passed to other methods |
none
f <- system.file("ex/meuse.tif", package="terra") r <- rast(f) plot(r) sbar() sbar(1000, xy=c(178500, 333500), type="bar", divs=4, cex=.8) sbar(1000, xy="bottomright", divs=3, cex=.8, ticks=TRUE) north(d=250, c(178550, 332500)) f <- system.file("ex/elev.tif", package="terra") r <- rast(f) plot(r, type="interval") sbar(20, c(6.2, 50.1), type="bar", cex=.8, divs=4) sbar(15, c(6.3, 50), type="bar", below="km", label=c(0,7.5,15), cex=.8) sbar(15, c(6.65, 49.8), cex=.8, label=c(0,"km",15)) north(type=2) sbar(15, c(6.65, 49.7), cex=.8, label="15 kilometer", lwd=5) sbar(15, c(6.65, 49.6), divs=4, cex=.8, below="km")
f <- system.file("ex/meuse.tif", package="terra") r <- rast(f) plot(r) sbar() sbar(1000, xy=c(178500, 333500), type="bar", divs=4, cex=.8) sbar(1000, xy="bottomright", divs=3, cex=.8, ticks=TRUE) north(d=250, c(178550, 332500)) f <- system.file("ex/elev.tif", package="terra") r <- rast(f) plot(r, type="interval") sbar(20, c(6.2, 50.1), type="bar", cex=.8, divs=4) sbar(15, c(6.3, 50), type="bar", below="km", label=c(0,7.5,15), cex=.8) sbar(15, c(6.65, 49.8), cex=.8, label=c(0,"km",15)) north(type=2) sbar(15, c(6.65, 49.7), cex=.8, label="15 kilometer", lwd=5) sbar(15, c(6.65, 49.6), divs=4, cex=.8, below="km")
Center and/or scale raster data. For details see scale
## S4 method for signature 'SpatRaster' scale(x, center=TRUE, scale=TRUE)
## S4 method for signature 'SpatRaster' scale(x, center=TRUE, scale=TRUE)
x |
SpatRaster |
center |
logical or numeric. If |
scale |
logical or numeric. If |
SpatRaster
r <- rast(system.file("ex/logo.tif", package="terra")) s <- scale(r) ## the equivalent, computed in steps m <- global(r, "mean") rr <- r - m[,1] rms <- global(rr, "rms") ss <- rr / rms[,1]
r <- rast(system.file("ex/logo.tif", package="terra")) s <- scale(r) ## the equivalent, computed in steps m <- global(r, "mean") rr <- r - m[,1] rms <- global(rr, "rms") ss <- rr / rms[,1]
Scatterplot of the values of two SpatRaster layers
## S4 method for signature 'SpatRaster,SpatRaster' plot(x, y, maxcell=100000, warn=TRUE, nc, nr, maxnl=16, smooth=FALSE, gridded=FALSE, ncol=25, nrow=25, ...)
## S4 method for signature 'SpatRaster,SpatRaster' plot(x, y, maxcell=100000, warn=TRUE, nc, nr, maxnl=16, smooth=FALSE, gridded=FALSE, ncol=25, nrow=25, ...)
x |
SpatRaster |
y |
SpatRaster |
maxcell |
positive integer. Maximum number of cells to use for the plot |
nc |
positive integer. Optional. The number of columns to divide the plotting device in (when plotting multiple layers) |
nr |
positive integer. Optional. The number of rows to divide the plotting device in (when plotting multiple layers) |
maxnl |
positive integer. Maximum number of layers to plot (for multi-layer objects) |
smooth |
logical. If |
gridded |
logical. If |
warn |
boolean. Show a warning if a sample of the pixels is used (for scatterplot only) |
ncol |
positive integer. Number of columns for gridding |
nrow |
positive integer. Number of rows for gridding |
... |
additional graphical arguments |
s <- rast(system.file("ex/logo.tif", package="terra")) plot(s[[1]], s[[2]]) plot(s, sqrt(s[[3:1]]))
s <- rast(system.file("ex/logo.tif", package="terra")) plot(s[[1]], s[[2]]) plot(s, sqrt(s[[3:1]]))
These functions can be used to get or set the scale (gain) and offset parameters used to transform values when reading raster data from a file. The parameters are applied to the raw values using the formula below:
value <- value * scale + offset
The default value for scale is 1 and for offset is 0. 'scale' is sometimes referred to as 'gain'.
Note that setting the scale and/or offset are intended to be used with values that are stored in a file. When values are memory, assigning scale or offset values will lead to the immediate computation of new values; in such cases it would be clearer to use Arith-methods
.
## S4 method for signature 'SpatRaster' scoff(x) ## S4 replacement method for signature 'SpatRaster' scoff(x)<-value
## S4 method for signature 'SpatRaster' scoff(x) ## S4 replacement method for signature 'SpatRaster' scoff(x)<-value
x |
SpatRaster |
value |
two-column matrix with scale (first column) and offset (second column) for each layer. Or |
matrix or changed SpatRaster
r <- rast(system.file("ex/elev.tif", package="terra")) minmax(r) scoff(r) r[4603] scoff(r) <- cbind(10, 5) minmax(r) scoff(r) r[4603]
r <- rast(system.file("ex/elev.tif", package="terra")) minmax(r) scoff(r) r[4603] scoff(r) <- cbind(10, 5) minmax(r) scoff(r) r[4603]
Methods to create a SpatRasterDataset. This is an object to hold "sub-datasets", each a SpatRaster that in most cases will have multiple layers.
See describe
for getting information about the sub-datasets present in a file.
## S4 method for signature 'missing' sds(x) ## S4 method for signature 'character' sds(x, ids=0, opts=NULL, raw=FALSE) ## S4 method for signature 'SpatRaster' sds(x, ...) ## S4 method for signature 'list' sds(x) ## S4 method for signature 'array' sds(x, crs="", extent=NULL)
## S4 method for signature 'missing' sds(x) ## S4 method for signature 'character' sds(x, ids=0, opts=NULL, raw=FALSE) ## S4 method for signature 'SpatRaster' sds(x, ...) ## S4 method for signature 'list' sds(x) ## S4 method for signature 'array' sds(x, crs="", extent=NULL)
x |
character (filename), or SpatRaster, or list of SpatRasters, or missing. If multiple filenames are provided, it is attempted to make SpatRasters from these, and combine them into a SpatRasterDataset |
ids |
optional. vector of integer subdataset ids. Ignored if the first value is not a positive integer |
opts |
character. GDAL dataset open options |
raw |
logical. If |
crs |
character. Description of the Coordinate Reference System (map projection) in |
extent |
|
... |
additional |
SpatRasterDataset
s <- rast(system.file("ex/logo.tif", package="terra")) x <- sds(s, s/2) names(x) <- c("first", "second") x length(x) # extract the second SpatRaster x[2] a <- array(1:9, c(3,3,3,3)) sds(a)
s <- rast(system.file("ex/logo.tif", package="terra")) x <- sds(s, s/2) names(x) <- c("first", "second") x length(x) # extract the second SpatRaster x[2] a <- array(1:9, c(3,3,3,3)) sds(a)
Create a SpatRaster with a layer for each class (value, or subset of the values) in the input SpatRaster. For example, if the input has vegetation types, this function will create a layer (presence/absence; dummy variable) for each of these classes.
This is called "one-hot encoding" or "dummy encoding" (for a dummy encoding scheme you can remove (any) one of the output layers as it is redundant).
## S4 method for signature 'SpatRaster' segregate(x, classes=NULL, keep=FALSE, other=0, round=FALSE, digits=0, filename="", ...)
## S4 method for signature 'SpatRaster' segregate(x, classes=NULL, keep=FALSE, other=0, round=FALSE, digits=0, filename="", ...)
x |
SpatRaster |
classes |
numeric. The values (classes) for which layers should be made. If |
keep |
logical. If |
other |
numeric. Value to assign to cells that are not of the class represented by a layer |
round |
logical. Should the values be rounded first? |
digits |
integer. Number of digits to round the values to |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(nrows=5, ncols=5) values(r) <- rep(c(1:4, NA), each=5) b <- segregate(r) bb <- segregate(r, keep=TRUE, other=NA)
r <- rast(nrows=5, ncols=5) values(r) <- rep(c(1:4, NA), each=5) b <- segregate(r) bb <- segregate(r, keep=TRUE, other=NA)
Geometrically subset SpatRaster or SpatVector (to be done) by drawing on a plot (map).
## S4 method for signature 'SpatRaster' sel(x, ...) ## S4 method for signature 'SpatVector' sel(x, use="rec", show=TRUE, col="cyan", draw=TRUE, ...)
## S4 method for signature 'SpatRaster' sel(x, ...) ## S4 method for signature 'SpatVector' sel(x, use="rec", show=TRUE, col="cyan", draw=TRUE, ...)
x |
SpatRaster or SpatVector |
use |
character indicating what to draw. One of "rec" (rectangle) or "pol" (polygon) |
show |
logical. If |
col |
color to be used for drawing if |
draw |
logical. If |
... |
additional graphics arguments for drawing the selected geometries |
SpatRaster or SpatVector
crop
and intersect
to make an intersection and click
and text
to see cell values or geometry attributes.
Use draw
to draw a SpatExtent of SpatVector that you want to keep.
## Not run: # select a subset of a SpatRaster r <- rast(nrows=10, ncols=10) values(r) <- 1:ncell(r) plot(r) s <- sel(r) # now click on the map twice # plot the selection on a new canvas: x11() plot(s) # vector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) plot(v) x <- sel(v) # now click on the map twice x ## End(Not run)
## Not run: # select a subset of a SpatRaster r <- rast(nrows=10, ncols=10) values(r) <- 1:ncell(r) plot(r) s <- sel(r) # now click on the map twice # plot the selection on a new canvas: x11() plot(s) # vector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) plot(v) x <- sel(v) # now click on the map twice x ## End(Not run)
Identify n cells that have the highest of lowest values in the first layer of a SpatRaster.
## S4 method for signature 'SpatRaster' selectHighest(x, n, low=FALSE)
## S4 method for signature 'SpatRaster' selectHighest(x, n, low=FALSE)
x |
SpatRaster. Only the first layer is processed |
n |
The number of cells to select |
low |
logical. If |
SpatRaster
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- selectHighest(r, 1000) y <- selectHighest(r, 1000, TRUE) m <- merge(y-1, x) levels(m) <- data.frame(id=0:1, elevation=c("low", "high")) plot(m)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- selectHighest(r, 1000) y <- selectHighest(r, 1000, TRUE) m <- merge(y-1, x) levels(m) <- data.frame(id=0:1, elevation=c("low", "high")) plot(m)
Use a single layer SpatRaster to select cell values from different layers in a multi-layer SpatRaster. The values of the SpatRaster to select layers (y
) should be whole numbers between 1
and nlyr(x)
(values outside this range are ignored).
See rapp
for applying a function to a range of variable size.
See extract
for extraction of values by cell, point, or otherwise.
## S4 method for signature 'SpatRaster' selectRange(x, y, z=1, repint=0, filename="", ...)
## S4 method for signature 'SpatRaster' selectRange(x, y, z=1, repint=0, filename="", ...)
x |
SpatRaster |
y |
SpatRaster. Cell values must be positive integers. They indicate the first layer to select for each cell |
z |
positive integer. The number of layers to select |
repint |
integer > 1 and < nlyr(x) allowing for repeated selection at a fixed interval. For example, if |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(ncols=10, nrows=10) values(r) <- 1 s <- c(r, r+2, r+5) s <- c(s, s) set.seed(1) values(r) <- sample(3, ncell(r), replace=TRUE) x <- selectRange(s, r) x <- selectRange(s, r, 3)
r <- rast(ncols=10, nrows=10) values(r) <- 1 s <- c(r, r+2, r+5) s <- c(s, s) set.seed(1) values(r) <- sample(3, ncell(r), replace=TRUE) x <- selectRange(s, r) x <- selectRange(s, r, 3)
serialize and saveRDS for SpatVector, SpatRaster, SpatRasterDataset and SpatRasterCollection. Note that these objects will first be "packed" with wrap
, and after unserialize/readRDS they need to be unpacked with rast
or vect
.
Extensive use of these functions is not recommended. Especially for SpatRaster it is generally much more efficient to use writeRaster
and write, e.g., a GTiff file.
## S4 method for signature 'SpatRaster' saveRDS(object, file="", ascii = FALSE, version = NULL, compress=TRUE, refhook = NULL) ## S4 method for signature 'SpatRasterDataset' saveRDS(object, file="", ascii = FALSE, version = NULL, compress=TRUE, refhook = NULL) ## S4 method for signature 'SpatRasterCollection' saveRDS(object, file="", ascii = FALSE, version = NULL, compress=TRUE, refhook = NULL) ## S4 method for signature 'SpatVector' saveRDS(object, file="", ascii = FALSE, version = NULL, compress=TRUE, refhook = NULL) ## S4 method for signature 'SpatRaster' serialize(object, connection, ascii = FALSE, xdr = TRUE, version = NULL, refhook = NULL) ## S4 method for signature 'SpatVector' serialize(object, connection, ascii = FALSE, xdr = TRUE, version = NULL, refhook = NULL)
## S4 method for signature 'SpatRaster' saveRDS(object, file="", ascii = FALSE, version = NULL, compress=TRUE, refhook = NULL) ## S4 method for signature 'SpatRasterDataset' saveRDS(object, file="", ascii = FALSE, version = NULL, compress=TRUE, refhook = NULL) ## S4 method for signature 'SpatRasterCollection' saveRDS(object, file="", ascii = FALSE, version = NULL, compress=TRUE, refhook = NULL) ## S4 method for signature 'SpatVector' saveRDS(object, file="", ascii = FALSE, version = NULL, compress=TRUE, refhook = NULL) ## S4 method for signature 'SpatRaster' serialize(object, connection, ascii = FALSE, xdr = TRUE, version = NULL, refhook = NULL) ## S4 method for signature 'SpatVector' serialize(object, connection, ascii = FALSE, xdr = TRUE, version = NULL, refhook = NULL)
object |
SpatVector, SpatRaster, SpatRasterDataset or SpatRasterCollection |
file |
file name to save object to |
connection |
see |
ascii |
|
version |
|
compress |
|
refhook |
|
xdr |
Packed* object
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) p <- serialize(v, NULL) head(p) x <- unserialize(p) x
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) p <- serialize(v, NULL) head(p) x <- unserialize(p) x
Set cell values of a SpatRaster or the attributes of a SpatVector. For large SpatRasters use init
instead to set values.
## S4 replacement method for signature 'SpatRaster,ANY' values(x)<-value ## S4 method for signature 'SpatRaster,ANY' setValues(x, values, keeptime=TRUE, keepunits=TRUE, keepnames=FALSE, props=FALSE) ## S4 replacement method for signature 'SpatVector,ANY' values(x)<-value
## S4 replacement method for signature 'SpatRaster,ANY' values(x)<-value ## S4 method for signature 'SpatRaster,ANY' setValues(x, values, keeptime=TRUE, keepunits=TRUE, keepnames=FALSE, props=FALSE) ## S4 replacement method for signature 'SpatVector,ANY' values(x)<-value
x |
SpatRaster or SpatVector |
value |
For SpatRaster: numeric, matrix or data.frame. The length of the numeric values must match the total number of cells (ncell(x) * nlyr(x)), or be a single value. The number of columns of the matrix or data.frame must match the number of layers of For SpatVector: data.frame, matrix, vector, or NULL |
values |
Same as for |
keeptime |
logical. If |
keepunits |
logical. If |
keepnames |
logical. If |
props |
logical. If |
The same object type as x
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- setValues(r, 1:ncell(r)) x values(x) <- runif(ncell(x)) x head(x) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) values(v) <- data.frame(ID=1:12, name=letters[1:12]) head(v)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- setValues(r, 1:ncell(r)) x values(x) <- runif(ncell(x)) x head(x) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) values(v) <- data.frame(ID=1:12, name=letters[1:12]) head(v)
Compute hill shade from slope and aspect layers (both in radians). Slope and aspect can be computed with function terrain
.
A hill shade layer is often used as a backdrop on top of which another, semi-transparent, layer is drawn.
shade(slope, aspect, angle=45, direction=0, normalize=FALSE, filename="", overwrite=FALSE, ...)
shade(slope, aspect, angle=45, direction=0, normalize=FALSE, filename="", overwrite=FALSE, ...)
slope |
SpatRasterwith slope values (in radians) |
aspect |
SpatRaster with aspect values (in radians) |
angle |
The elevation angle(s) of the light source (sun), in degrees |
direction |
The direction (azimuth) angle(s) of the light source (sun), in degrees |
normalize |
Logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
... |
additional arguments for writing files as in |
Horn, B.K.P., 1981. Hill shading and the reflectance map. Proceedings of the IEEE 69(1):14-47
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) alt <- disagg(r, 10, method="bilinear") slope <- terrain(alt, "slope", unit="radians") aspect <- terrain(alt, "aspect", unit="radians") hill <- shade(slope, aspect, 40, 270) plot(hill, col=grey(0:100/100), legend=FALSE, mar=c(2,2,1,4)) plot(alt, col=rainbow(25, alpha=0.35), add=TRUE) # A better hill shade may be achieved by combining # different angles and directions. For example h <- shade(slope, aspect, angle = c(45, 45, 45, 80), direction = c(225, 270, 315, 135)) h <- Reduce(mean, h)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) alt <- disagg(r, 10, method="bilinear") slope <- terrain(alt, "slope", unit="radians") aspect <- terrain(alt, "aspect", unit="radians") hill <- shade(slope, aspect, 40, 270) plot(hill, col=grey(0:100/100), legend=FALSE, mar=c(2,2,1,4)) plot(alt, col=rainbow(25, alpha=0.35), add=TRUE) # A better hill shade may be achieved by combining # different angles and directions. For example h <- shade(slope, aspect, angle = c(45, 45, 45, 80), direction = c(225, 270, 315, 135)) h <- Reduce(mean, h)
Shift a SpatRaster, SpatVector or SpatExtent to another location.
## S4 method for signature 'SpatRaster' shift(x, dx=0, dy=0, filename="", ...) ## S4 method for signature 'SpatVector' shift(x, dx=0, dy=0) ## S4 method for signature 'SpatExtent' shift(x, dx=0, dy=0)
## S4 method for signature 'SpatRaster' shift(x, dx=0, dy=0, filename="", ...) ## S4 method for signature 'SpatVector' shift(x, dx=0, dy=0) ## S4 method for signature 'SpatExtent' shift(x, dx=0, dy=0)
x |
SpatRaster, SpatVector or SpatExtent |
dx |
numeric. The shift in horizontal direction |
dy |
numeric. The shift in vertical direction |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
Same as x
r <- rast(xmin=0, xmax=1, ymin=0, ymax=1) r <- shift(r, dx=1, dy=-1) e <- ext(r) shift(e, 5, 5)
r <- rast(xmin=0, xmax=1, ymin=0, ymax=1) r <- shift(r, dx=1, dy=-1) e <- ext(r) shift(e, 5, 5)
Apply a sieve filter. That is, remove "noise", by changing small clumps of cells with a value that is different from the surrounding cells, to the value of the largest neighboring clump.
Note that the input raster data is rounded to integers.
## S4 method for signature 'SpatRaster' sieve(x, threshold, directions=8, filename="", ...)
## S4 method for signature 'SpatRaster' sieve(x, threshold, directions=8, filename="", ...)
x |
SpatRaster, single layer with elevation values. Values should have the same unit as the map units |
threshold |
positive integer. Only clumps smaller than this threshold will be removed |
directions |
numeric to indicate which cells are connected. Either |
filename |
character. Output filename |
... |
Options for writing files as in |
r <- rast(nrows=18, ncols=18, xmin=0, vals=0, crs="local") r[2, 5] <- 1 r[5:8, 2:3] <- 2 r[7:12, 10:15] <- 3 r[15:16, 15:18] <- 4 freq(r, bylayer=FALSE) x <- sieve(r, 8) y <- sieve(r, 9)
r <- rast(nrows=18, ncols=18, xmin=0, vals=0, crs="local") r[2, 5] <- 1 r[5:8, 2:3] <- 2 r[7:12, 10:15] <- 3 r[15:16, 15:18] <- 4 freq(r, bylayer=FALSE) x <- sieve(r, 8) y <- sieve(r, 9)
Reduce the number of nodes used to represent geometries.
## S4 method for signature 'SpatVector' simplifyGeom(x, tolerance=0.1, preserveTopology=TRUE, makeValid=TRUE)
## S4 method for signature 'SpatVector' simplifyGeom(x, tolerance=0.1, preserveTopology=TRUE, makeValid=TRUE)
x |
SpatVector of lines or polygons |
tolerance |
numeric. The minimum distance between nodes in units of the crs (i.e. degrees for long/lat) |
preserveTopology |
logical. If |
makeValid |
logical. If |
SpatVector
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) w <- simplifyGeom(v, .02, makeValid=FALSE) e <- erase(w) g <- gaps(e) plot(e, lwd=5, border="light gray") polys(g, col="red", border="red")
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) w <- simplifyGeom(v, .02, makeValid=FALSE) e <- erase(w) g <- gaps(e) plot(e, lwd=5, border="light gray") polys(g, col="red", border="red")
Sort the cell values of a SpatRaster across layers. You can also compute the sorting order.
Or sort the records of SpatVector (or data.frame) by specifying the column number(s) or names(s) to sort on.
## S4 method for signature 'SpatRaster' sort(x, decreasing=FALSE, order=FALSE, filename="", ...) ## S4 method for signature 'SpatVector' sort(x, v, decreasing=FALSE)
## S4 method for signature 'SpatRaster' sort(x, decreasing=FALSE, order=FALSE, filename="", ...) ## S4 method for signature 'SpatVector' sort(x, v, decreasing=FALSE)
x |
SpatRaster |
decreasing |
logical. If |
order |
logical. If |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
v |
character or numeric indicating the column(s) to sort on |
SpatRaster
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) r <- c(r, r/2, r*2) sort(r) ord <- sort(r, order=TRUE) # these two are the same ord[[1]] which.min(r)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) r <- c(r, r/2, r*2) sort(r) ord <- sort(r, order=TRUE) # these two are the same ord[[1]] which.min(r)
Get the data sources of a SpatRaster or SpatVector or related object. Sources are either files (or similar resources) or "", meaning that they are in memory. You can use hasValues
to check if in-memory layers actually have cell values.
## S4 method for signature 'SpatRaster' sources(x, nlyr=FALSE, bands=FALSE) ## S4 method for signature 'SpatVector' sources(x) ## S4 method for signature 'SpatRaster' hasValues(x) ## S4 method for signature 'SpatRaster' inMemory(x, bylayer=FALSE)
## S4 method for signature 'SpatRaster' sources(x, nlyr=FALSE, bands=FALSE) ## S4 method for signature 'SpatVector' sources(x) ## S4 method for signature 'SpatRaster' hasValues(x) ## S4 method for signature 'SpatRaster' inMemory(x, bylayer=FALSE)
x |
SpatRaster, SpatRasterCollection, SpatVector or SpatVectorProxy |
nlyr |
logical. If |
bands |
logical. If |
bylayer |
logical. If |
A vector of filenames, or ""
when there is no filename, if nlyr
and bands
are both FALSE
. Otherwise a data.frame
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) s <- rast(r) values(s) <- 1:ncell(s) rs <- c(r,r,s,r) sources(rs) hasValues(r) x <- rast() hasValues(x)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) s <- rast(r) values(s) <- 1:ncell(s) rs <- c(r,r,s,r) sources(rs) hasValues(r) x <- rast() hasValues(x)
Objects of class SpatExtent are used to define the spatial extent (extremes) of objects of the SpatRaster class.
You can use the ext
function to create SpatExtent objects, or to extract them from a SpatRaster, SpatVector or related objects.
display values of a SpatExtent object
e <- ext(-180, 180, -90, 90) e
e <- ext(-180, 180, -90, 90) e
A SpatRaster
represents a rectangular part of the world that is sub-divided into rectangular cells of equal area (in terms of the units of the coordinate reference system). For each cell can have multiple values ("layers").
An object of the SpatRaster
class can point to one or more files on disk that hold the cell values, and/or it can hold these values in memory. These objects can be created with the rast
method.
A SpatRasterDataset
is a collection of sub-datasets, where each is a SpatRaster
for the same area (extent) and coordinate reference system, but possibly with a different resolution. Sub-datasets are often used to capture variables (e.g. temperature and precipitation), or a fourth dimension (e.g. height, depth or time) if the sub-datasets already have three dimensions (multiple layers).
A SpatRasterCollection
is a collection of SpatRasters with no restriction in the extent or other geometric parameters.
rast()
rast()
Take a spatial sample from a SpatRaster, SpatVector or SpatExtent. Sampling a SpatVector or SpatExtent always returns a SpatVector of points.
With a SpatRaster, you can get cell values, cell numbers (cells=TRUE
), coordinates (xy=TRUE
) or (when method="regular"
and as.raster=TRUE
) get a new SpatRaster with the same extent, but fewer cells.
In order to assure regularity when requesting a regular sample, the number of cells or points returned may not be exactly the same as the size
requested.
## S4 method for signature 'SpatRaster' spatSample(x, size, method="random", replace=FALSE, na.rm=FALSE, as.raster=FALSE, as.df=TRUE, as.points=FALSE, values=TRUE, cells=FALSE, xy=FALSE, ext=NULL, warn=TRUE, weights=NULL, exp=5, exhaustive=FALSE) ## S4 method for signature 'SpatVector' spatSample(x, size, method="random", strata=NULL, chess="") ## S4 method for signature 'SpatExtent' spatSample(x, size, method="random", lonlat, as.points=FALSE)
## S4 method for signature 'SpatRaster' spatSample(x, size, method="random", replace=FALSE, na.rm=FALSE, as.raster=FALSE, as.df=TRUE, as.points=FALSE, values=TRUE, cells=FALSE, xy=FALSE, ext=NULL, warn=TRUE, weights=NULL, exp=5, exhaustive=FALSE) ## S4 method for signature 'SpatVector' spatSample(x, size, method="random", strata=NULL, chess="") ## S4 method for signature 'SpatExtent' spatSample(x, size, method="random", lonlat, as.points=FALSE)
x |
SpatRaster, SpatVector or SpatExtent |
size |
numeric. The sample size. If |
method |
character. Should be "regular" or "random", If |
replace |
logical. If |
na.rm |
logical. If |
as.raster |
logical. If |
as.df |
logical. If |
as.points |
logical. If |
values |
logical. If |
cells |
logical. If |
xy |
logical. If |
ext |
SpatExtent or NULL to restrict sampling to a subset of the area of |
warn |
logical. Give a warning if the sample size returned is smaller than requested |
weights |
SpatRaster. Used to provide weights when |
strata |
if not NULL, stratified random sampling is done, taking |
chess |
character. One of "", "white", or "black". For stratified sampling if |
lonlat |
logical. If |
exp |
numeric >= 1. "Expansion factor" that is multiplied with |
exhaustive |
logical. If |
numeric matrix, data.frame, SpatRaster or SpatVector
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) s <- spatSample(r, 10, as.raster=TRUE) spatSample(r, 5) spatSample(r, 5, na.rm=TRUE) spatSample(r, 5, "regular") ## if you require cell numbers and/or coordinates size <- 6 spatSample(r, 6, "random", cells=TRUE, xy=TRUE, values=FALSE) # regular, with values spatSample(r, 6, "regular", cells=TRUE, xy=TRUE) # stratified rr <- rast(ncol=10, nrow=10, names="stratum") set.seed(1) values(rr) <- round(runif(ncell(rr), 1, 3)) spatSample(rr, 2, "stratified", xy=TRUE) s <- spatSample(rr, 5, "stratified", as.points=TRUE) plot(rr, plg=list(title="raster")) plot(s, 1, add=TRUE, plg=list(x=185, y=1, title="points")) ## SpatExtent e <- ext(r) spatSample(e, 10, "random", lonlat=TRUE) ## SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) # sample the geometries i <- sample(v, 3) # sample points in geometries p <- spatSample(v, 3)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) s <- spatSample(r, 10, as.raster=TRUE) spatSample(r, 5) spatSample(r, 5, na.rm=TRUE) spatSample(r, 5, "regular") ## if you require cell numbers and/or coordinates size <- 6 spatSample(r, 6, "random", cells=TRUE, xy=TRUE, values=FALSE) # regular, with values spatSample(r, 6, "regular", cells=TRUE, xy=TRUE) # stratified rr <- rast(ncol=10, nrow=10, names="stratum") set.seed(1) values(rr) <- round(runif(ncell(rr), 1, 3)) spatSample(rr, 2, "stratified", xy=TRUE) s <- spatSample(rr, 5, "stratified", as.points=TRUE) plot(rr, plg=list(title="raster")) plot(s, 1, add=TRUE, plg=list(x=185, y=1, title="points")) ## SpatExtent e <- ext(r) spatSample(e, 10, "random", lonlat=TRUE) ## SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f) # sample the geometries i <- sample(v, 3) # sample points in geometries p <- spatSample(v, 3)
SpatVector
can represent points, lines or polygons.
SpatVectorCollection
can hold a collection of SpatVectors
SpatVectorProxy
is a SpatVector for which the data are on-disk in-stead of in memory.
Spin (rotate) the geometry of a SpatVector.
## S4 method for signature 'SpatVector' spin(x, angle, x0, y0)
## S4 method for signature 'SpatVector' spin(x, angle, x0, y0)
x |
SpatVector |
angle |
numeric. Angle of rotation in degrees |
x0 |
numeric. x-coordinate of the center of rotation. If missing, the center of the extent of |
y0 |
numeric. y-coordinate of the center of rotation. If missing, the center of the extent of |
SpatVector
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) w <- spin(v, 180) plot(v) lines(w, col="red") # lower-right corner as center e <- as.vector(ext(v)) x <- spin(v, 45, e[1], e[3])
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) w <- spin(v, 180) plot(v) lines(w, col="red") # lower-right corner as center e <- as.vector(ext(v)) x <- spin(v, 45, e[1], e[3])
Split a SpatRaster by layer, or a SpatVector by attributes. You can also split the geometry of a polygon SpatVector with another SpatVector.
## S4 method for signature 'SpatRaster,ANY' split(x, f) ## S4 method for signature 'SpatVector,ANY' split(x, f) ## S4 method for signature 'SpatVector,SpatVector' split(x, f)
## S4 method for signature 'SpatRaster,ANY' split(x, f) ## S4 method for signature 'SpatVector,ANY' split(x, f) ## S4 method for signature 'SpatVector,SpatVector' split(x, f)
x |
SpatRaster or SpatVector |
f |
If |
list or SpatVector
## split layers s <- rast(system.file("ex/logo.tif", package="terra")) y <- split(s, c(1,2,1)) sds(y) ## split attributes v <- vect(system.file("ex/lux.shp", package="terra")) x <- split(v, "NAME_1") ## split geometries v <- v[1:5,] line <- vect(matrix(c(5.79, 6.22, 5.75, 6.1, 5.8, 50.14, 50.05, 49.88, 49.85, 49.71), ncol=2), "line") s <- split(v, line)
## split layers s <- rast(system.file("ex/logo.tif", package="terra")) y <- split(s, c(1,2,1)) sds(y) ## split attributes v <- vect(system.file("ex/lux.shp", package="terra")) x <- split(v, "NAME_1") ## split geometries v <- v[1:5,] line <- vect(matrix(c(5.79, 6.22, 5.75, 6.1, 5.8, 50.14, 50.05, 49.88, 49.85, 49.71), ncol=2), "line") s <- split(v, line)
Methods to create a SpatRasterCollection. This is an object to hold a collection (list) of SpatRasters. There are no restrictions on the similarity of the SpatRaster geometry.
They can be used to combine several SpatRasters to be used with merge
or mosaic
You can create a SpatRasterCollection from a file with subdatasets.
## S4 method for signature 'character' sprc(x, ids=0, opts=NULL, raw=FALSE) ## S4 method for signature 'SpatRaster' sprc(x, ...) ## S4 method for signature 'list' sprc(x) ## S4 method for signature 'missing' sprc(x)
## S4 method for signature 'character' sprc(x, ids=0, opts=NULL, raw=FALSE) ## S4 method for signature 'SpatRaster' sprc(x, ...) ## S4 method for signature 'list' sprc(x) ## S4 method for signature 'missing' sprc(x)
x |
SpatRaster, list with SpatRasters, missing, or filename |
ids |
optional. vector of integer subdataset ids. Ignored if the first value is not a positive integer |
opts |
character. GDAL dataset open options |
raw |
logical. If |
... |
additional SpatRasters |
SpatRasterCollection
x <- rast(xmin=-110, xmax=-50, ymin=40, ymax=70, ncols=60, nrows=30) y <- rast(xmin=-80, xmax=-20, ymax=60, ymin=30) res(y) <- res(x) values(x) <- 1:ncell(x) values(y) <- 1:ncell(y) z <- sprc(x, y) z
x <- rast(xmin=-110, xmax=-50, ymin=40, ymax=70, ncols=60, nrows=30) y <- rast(xmin=-80, xmax=-20, ymax=60, ymin=30) res(y) <- res(x) values(x) <- 1:ncell(x) values(y) <- 1:ncell(y) z <- sprc(x, y) z
Linear or histogram equalization stretch of values in a SpatRaster.
For linear stretch, provide the desired output range (minv
and maxv
) and the lower and upper bounds in the original data, either as quantiles (minq
and maxq
, or as cell values (smin
and smax
). If smin
and smax
are both not NA
, minq
and maxq
are ignored.
For histogram equalization, these arguments are ignored, but you can provide the desired scale of the output and the maximum number of cells that is used to compute the histogram (empirical cumulative distribution function).
## S4 method for signature 'SpatRaster' stretch(x, minv=0, maxv=255, minq=0, maxq=1, smin=NA, smax=NA, histeq=FALSE, scale=1, maxcell=500000, filename="", ...)
## S4 method for signature 'SpatRaster' stretch(x, minv=0, maxv=255, minq=0, maxq=1, smin=NA, smax=NA, histeq=FALSE, scale=1, maxcell=500000, filename="", ...)
x |
SpatRaster |
minv |
numeric >= 0 and smaller than maxv. lower bound of stretched value |
maxv |
numeric <= 255 and larger than maxv. upper bound of stretched value |
minq |
numeric >= 0 and smaller than maxq. lower quantile bound of original value. Ignored if smin is supplied |
maxq |
numeric <= 1 and larger than minq. upper quantile bound of original value. Ignored if smax is supplied |
smin |
numeric < smax. user supplied lower value for the layers, to be used instead of a quantile computed by the function itself |
smax |
numeric > smin. user supplied upper value for the layers, to be used instead of a quantile computed by the function itself |
histeq |
logical. If |
scale |
numeric. The scale (maximum value) of the output if |
maxcell |
positive integer. The size of the regular sample used to compute the histogram |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(nc=10, nr=10) values(r) <- rep(1:25, 4) rs <- stretch(r) s <- c(r, r*2) sr <- stretch(s)
r <- rast(nc=10, nr=10) values(r) <- rep(1:25, 4) rs <- stretch(r) s <- c(r, r*2) sr <- stretch(s)
Select a subset of layers from a SpatRaster or select a subset of records (row) and/or variables (columns) from a SpatVector.
## S4 method for signature 'SpatRaster' subset(x, subset, negate=FALSE, NSE=FALSE, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatVector' subset(x, subset, select, drop=FALSE, NSE=FALSE)
## S4 method for signature 'SpatRaster' subset(x, subset, negate=FALSE, NSE=FALSE, filename="", overwrite=FALSE, ...) ## S4 method for signature 'SpatVector' subset(x, subset, select, drop=FALSE, NSE=FALSE)
x |
SpatRaster or SpatVector |
subset |
if if |
select |
expression, indicating columns to select |
negate |
logical. If |
NSE |
logical. If |
drop |
logical. If |
filename |
character. Output filename |
overwrite |
logical. If |
... |
additional arguments for writing files as in |
if x
is a SpatRaster
: SpatRaster
if x
is a SpatVector
: SpatVector or, if drop=TRUE
, a data.frame
.
### SpatRaster s <- rast(system.file("ex/logo.tif", package="terra")) subset(s, 2:3) subset(s, c(3,2,3,1)) #equivalent to s[[ c(3,2,3,1) ]] s[[c("red", "green")]] s$red # expression based (partial) matching of names with single brackets s["re"] s["^re"] # not with double brackets # s[["re"]] ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) subset(v, v$NAME_1 == "Diekirch", c("NAME_1", "NAME_2")) subset(v, NAME_1 == "Diekirch", c(NAME_1, NAME_2), NSE=TRUE) # or like this v[2:3,] v[1:2, 2:3] v[1:2, c("NAME_1", "NAME_2")]
### SpatRaster s <- rast(system.file("ex/logo.tif", package="terra")) subset(s, 2:3) subset(s, c(3,2,3,1)) #equivalent to s[[ c(3,2,3,1) ]] s[[c("red", "green")]] s$red # expression based (partial) matching of names with single brackets s["re"] s["^re"] # not with double brackets # s[["re"]] ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) subset(v, v$NAME_1 == "Diekirch", c("NAME_1", "NAME_2")) subset(v, NAME_1 == "Diekirch", c(NAME_1, NAME_2), NSE=TRUE) # or like this v[2:3,] v[1:2, 2:3] v[1:2, c("NAME_1", "NAME_2")]
Select a subset of layers from a SpatRaster or select a subset of records (row) and/or variables (columns) from a SpatVector.
## S4 method for signature 'SpatExtent' x$name
## S4 method for signature 'SpatExtent' x$name
x |
SpatRaster, SpatVector or SpatExtent |
name |
character. If |
if x
is a SpatRaster
: SpatRaster
if x
is a SpatVector
: SpatVector or, if drop=TRUE
, a data.frame
.
### SpatRaster s <- rast(system.file("ex/logo.tif", package="terra")) subset(s, 2:3) subset(s, c(3,2,3,1)) #equivalent to s[[ c(3,2,3,1) ]] s[[c("red", "green")]] s$red # expression based (partial) matching of names with single brackets s["re"] s["^re"] # not with double brackets # s[["re"]] ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) v[2:3,] v[1:2, 2:3] subset(v, v$NAME_1 == "Diekirch", c("NAME_1", "NAME_2")) subset(v, NAME_1 == "Diekirch", c(NAME_1, NAME_2), NSE=TRUE)
### SpatRaster s <- rast(system.file("ex/logo.tif", package="terra")) subset(s, 2:3) subset(s, c(3,2,3,1)) #equivalent to s[[ c(3,2,3,1) ]] s[[c("red", "green")]] s$red # expression based (partial) matching of names with single brackets s["re"] s["^re"] # not with double brackets # s[["re"]] ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) v[2:3,] v[1:2, 2:3] subset(v, v$NAME_1 == "Diekirch", c("NAME_1", "NAME_2")) subset(v, NAME_1 == "Diekirch", c(NAME_1, NAME_2), NSE=TRUE)
Select a subset of layers from a SpatRaster or select a subset of records (row) and/or variables (columns) from a SpatVector.
## S4 method for signature 'SpatRaster,numeric,missing' x[[i, j]] ## S4 method for signature 'SpatRasterDataset,ANY,ANY' x[[i, j, drop=TRUE]] ## S4 method for signature 'SpatVector,numeric,missing' x[[i, j, drop=FALSE]]
## S4 method for signature 'SpatRaster,numeric,missing' x[[i, j]] ## S4 method for signature 'SpatRasterDataset,ANY,ANY' x[[i, j, drop=TRUE]] ## S4 method for signature 'SpatVector,numeric,missing' x[[i, j, drop=FALSE]]
x |
SpatRaster or SpatVector |
i |
if if |
j |
missing, or, for SpatRasterDataset only, numeric |
drop |
logical. If |
if x
is a SpatRaster
or SpatRasterDataset
: SpatRaster
if x
is a SpatVector
: a data.frame
.
### SpatRaster s <- rast(system.file("ex/logo.tif", package="terra")) s[[ 1:2 ]] s[[c("red", "green")]] # expression based (partial) matching of names with single brackets s["re"] s["^re"] # does not with double brackets # s[["re"]] ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) v[[2:3]] # to keep the geometry use v[,2:3]
### SpatRaster s <- rast(system.file("ex/logo.tif", package="terra")) s[[ 1:2 ]] s[[c("red", "green")]] # expression based (partial) matching of names with single brackets s["re"] s["^re"] # does not with double brackets # s[["re"]] ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) v[[2:3]] # to keep the geometry use v[,2:3]
Extract values from a SpatRaster; a subset of records (row) and/or variables (columns) from a SpatVector; or a number from a SpatExtent.
You can use indices (row, column, layer or cell numbers) to extract. You can also use other Spat* objects.
## S4 method for signature 'SpatRaster,ANY,ANY,ANY' x[i, j, k] ## S4 method for signature 'SpatVector,numeric,numeric' x[i, j, drop=FALSE] ## S4 method for signature 'SpatVector,SpatVector,missing' x[i, j] ## S4 method for signature 'SpatExtent,numeric,missing' x[i, j]
## S4 method for signature 'SpatRaster,ANY,ANY,ANY' x[i, j, k] ## S4 method for signature 'SpatVector,numeric,numeric' x[i, j, drop=FALSE] ## S4 method for signature 'SpatVector,SpatVector,missing' x[i, j] ## S4 method for signature 'SpatExtent,numeric,missing' x[i, j]
x |
SpatRaster, SpatVector or SpatExtent |
i |
if if if |
j |
numeric, logical, or missing to select columns |
k |
numeric, character, or missing to select layers |
drop |
logical. If |
numeric if x
is a SpatExtent.
Same as x
if drop=FALSE
. Otherwise a data.frame
### SpatRaster f <- system.file("ex/elev.tif", package="terra") r <- rast(f) r[3638] rowColFromCell(r, 2638) r[39, 28] x <- r[39:40, 28:29, drop=FALSE] as.matrix(x, wide=TRUE) ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) v[2:3,] v[1:2, 2:3] v[1:2, 2:3, drop=TRUE]
### SpatRaster f <- system.file("ex/elev.tif", package="terra") r <- rast(f) r[3638] rowColFromCell(r, 2638) r[39, 28] x <- r[39:40, 28:29, drop=FALSE] as.matrix(x, wide=TRUE) ### SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) v[2:3,] v[1:2, 2:3] v[1:2, 2:3, drop=TRUE]
Substitute(replace) cell values of a SpatRaster with a new value. See classify
for more complex/flexible replacement.
## S4 method for signature 'SpatRaster' subst(x, from, to, others=NULL, raw=FALSE, filename="", ...)
## S4 method for signature 'SpatRaster' subst(x, from, to, others=NULL, raw=FALSE, filename="", ...)
x |
SpatRaster |
from |
numeric value(s). Normally a vector of the same length as 'to'. If |
to |
numeric value(s). Normally a vector of the same length as 'from'. If |
others |
numeric. If not |
raw |
logical. If |
filename |
character. Output filename |
... |
Additional arguments for writing files as in |
SpatRaster
r <- rast(ncols=5, nrows=5, xmin=0, xmax=1, ymin=0, ymax=1, crs="") r <- init(r, 1:6) x <- subst(r, 3, 7) x <- subst(r, 2:3, NA) x <- subst(x, NA, 10) # multiple output layers z <- subst(r, 2:3, cbind(20,30)) # multiple input layers rr <- c(r, r+1, r+2) m <- rbind(c(1:3), c(3:5)) zz <- subst(rr, m, c(100, 200))
r <- rast(ncols=5, nrows=5, xmin=0, xmax=1, ymin=0, ymax=1, crs="") r <- init(r, 1:6) x <- subst(r, 3, 7) x <- subst(r, 2:3, NA) x <- subst(x, NA, 10) # multiple output layers z <- subst(r, 2:3, cbind(20,30)) # multiple input layers rr <- c(r, r+1, r+2) m <- rbind(c(1:3), c(3:5)) zz <- subst(rr, m, c(100, 200))
Compute summary statistics for cells, either across layers or between layers (parallel summary).
The following summary methods are available for SpatRaster: any, anyNA, all, allNA, max, min, mean, median, prod, range, stdev, sum, which.min, which.max
. See modal
to compute the mode and app
to compute summary statistics that are not included here.
Because generic functions are used, the method applied is chosen based on the first argument: "x
". This means that if r
is a SpatRaster, mean(r, 5)
will work, but mean(5, r)
will not work.
The mean
method has an argument "trim" that is ignored.
If pop=TRUE
stdev
computes the population standard deviation, computed as:
f <- function(x) sqrt(sum((x-mean(x))^2) / length(x))
This is different than the sample standard deviation returned by sd
(which uses n-1
as denominator).
## S4 method for signature 'SpatRaster' min(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' max(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' range(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' prod(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' sum(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' any(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' all(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' range(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' which.min(x) ## S4 method for signature 'SpatRaster' which.max(x) ## S4 method for signature 'SpatRaster' stdev(x, ..., pop=TRUE, na.rm=FALSE) ## S4 method for signature 'SpatRaster' mean(x, ..., trim=NA, na.rm=FALSE) ## S4 method for signature 'SpatRaster' median(x, na.rm=FALSE, ...) ## S4 method for signature 'SpatRaster' anyNA(x) ## S4 method for signature 'SpatRaster' countNA(x, n=0) ## S4 method for signature 'SpatRaster' noNA(x, falseNA=FALSE) ## S4 method for signature 'SpatRaster' allNA(x, falseNA=FALSE)
## S4 method for signature 'SpatRaster' min(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' max(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' range(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' prod(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' sum(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' any(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' all(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' range(x, ..., na.rm=FALSE) ## S4 method for signature 'SpatRaster' which.min(x) ## S4 method for signature 'SpatRaster' which.max(x) ## S4 method for signature 'SpatRaster' stdev(x, ..., pop=TRUE, na.rm=FALSE) ## S4 method for signature 'SpatRaster' mean(x, ..., trim=NA, na.rm=FALSE) ## S4 method for signature 'SpatRaster' median(x, na.rm=FALSE, ...) ## S4 method for signature 'SpatRaster' anyNA(x) ## S4 method for signature 'SpatRaster' countNA(x, n=0) ## S4 method for signature 'SpatRaster' noNA(x, falseNA=FALSE) ## S4 method for signature 'SpatRaster' allNA(x, falseNA=FALSE)
x |
SpatRaster |
... |
additional SpatRasters or numeric values; and arguments |
na.rm |
logical. If |
trim |
ignored |
pop |
logical. If |
falseNA |
logical. If |
n |
integer. If |
Additional argument par
can be used for "parallel" summarizing a SpatRaster and a numeric or logical value. If a SpatRaster x
has three layers, max(x, 5)
will return a single layer (the number five is treated as a layer in which all cells have value five). In contrast max(x, 5, par=TRUE)
returns three layers (the number five is treated as another SpatRaster with a single layer with all cells having the value five.
SpatRaster
app
, Math-methods
, modal
, which.lyr
set.seed(0) r <- rast(nrows=10, ncols=10, nlyrs=3) values(r) <- runif(ncell(r) * nlyr(r)) x <- mean(r) # note how this returns one layer x <- sum(c(r, r[[2]]), 5) # and this returns three layers y <- sum(r, r[[2]], 5) max(r) ## when adding a number, do you want 1 layer or all layers? # 1 layer max(r, 0.5) # all layers max(r, 0.5, par=TRUE) y <- stdev(r) # not the same as yy <- app(r, sd) z <- stdev(r, r*2) x <- mean(r, filename=paste0(tempfile(), ".tif")) v <- values(r) set.seed(3) v[sample(length(v), 50)] <- NA values(r) <- v is.na(r) anyNA(r) allNA(r) countNA(r) countNA(r, 2)
set.seed(0) r <- rast(nrows=10, ncols=10, nlyrs=3) values(r) <- runif(ncell(r) * nlyr(r)) x <- mean(r) # note how this returns one layer x <- sum(c(r, r[[2]]), 5) # and this returns three layers y <- sum(r, r[[2]], 5) max(r) ## when adding a number, do you want 1 layer or all layers? # 1 layer max(r, 0.5) # all layers max(r, 0.5, par=TRUE) y <- stdev(r) # not the same as yy <- app(r, sd) z <- stdev(r, r*2) x <- mean(r, filename=paste0(tempfile(), ".tif")) v <- values(r) set.seed(3) v[sample(length(v), 50)] <- NA values(r) <- v is.na(r) anyNA(r) allNA(r) countNA(r) countNA(r, 2)
Compute summary statistics (min, max, mean, and quartiles) for SpatRaster using base summary
method. A sample is used for very large files.
For single or other statistics see Summary-methods
, global
, and quantile
## S4 method for signature 'SpatRaster' summary(object, size=100000, warn=TRUE, ...) ## S4 method for signature 'SpatVector' summary(object, ...)
## S4 method for signature 'SpatRaster' summary(object, size=100000, warn=TRUE, ...) ## S4 method for signature 'SpatVector' summary(object, ...)
object |
SpatRaster or SpatVector |
size |
positive integer. Size of a regular sample used for large datasets (see |
warn |
logical. If |
... |
additional arguments passed on to the base |
matrix with (an estimate of) the median, minimum and maximum values, the first and third quartiles, and the number of cells with NA
values
Summary-methods
, global
, quantile
set.seed(0) r <- rast(nrows=10, ncols=10, nlyrs=3) values(r) <- runif(nlyr(r)*ncell(r)) summary(r)
set.seed(0) r <- rast(nrows=10, ncols=10, nlyrs=3) values(r) <- runif(nlyr(r)*ncell(r)) summary(r)
Methods to create a SpatVectorCollection. This is an object to hold "sub-datasets", each a SpatVector, perhaps of different geometry type.
## S4 method for signature 'missing' svc(x) ## S4 method for signature 'SpatVector' svc(x, ...) ## S4 method for signature 'list' svc(x) ## S4 method for signature 'character' svc(x, layer="", query="", extent=NULL, filter=NULL)
## S4 method for signature 'missing' svc(x) ## S4 method for signature 'SpatVector' svc(x, ...) ## S4 method for signature 'list' svc(x) ## S4 method for signature 'character' svc(x, layer="", query="", extent=NULL, filter=NULL)
x |
SpatVector, character (filename), list with SpatVectors, or missing |
... |
Additional |
layer |
character. layer name to select a layer from a file (database) with multiple layers |
query |
character. An query to subset the dataset in the OGR-SQL dialect |
extent |
Spat* object. The extent of the object is used as a spatial filter to select the geometries to read. Ignored if |
filter |
SpatVector. Used as a spatial filter to select geometries to read (the convex hull is used for lines or points). It is guaranteed that all features that overlap with the extent of filter will be returned. It can happen that additional geometries are returned |
SpatVectorCollection
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) x <- svc() x <- svc(v, v[1:3,], as.lines(v[3:5,]), as.points(v)) length(x) x # extract x[3] # replace x[2] <- as.lines(v[1,])
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) x <- svc() x <- svc(v, v[1:3,], as.lines(v[3:5,]), as.points(v)) length(x) x # extract x[3] # replace x[2] <- as.lines(v[1,])
Symmetrical difference of polygons
## S4 method for signature 'SpatVector,SpatVector' symdif(x, y)
## S4 method for signature 'SpatVector,SpatVector' symdif(x, y)
x |
SpatVector |
y |
SpatVector |
SpatVector
p <- vect(system.file("ex/lux.shp", package="terra")) b <- as.polygons(ext(6, 6.4, 49.75, 50)) #sd <- symdif(p, b) #plot(sd, col=rainbow(12))
p <- vect(system.file("ex/lux.shp", package="terra")) b <- as.polygons(ext(6, 6.4, 49.75, 50)) #sd <- symdif(p, b) #plot(sd, col=rainbow(12))
Apply a function to subsets of layers of a SpatRaster (similar to tapply
and aggregate
). The layers are combined based on the index
.
The number of layers in the output SpatRaster equals the number of unique values in index
times the number of values that the supplied function returns for a single vector of numbers.
For example, if you have a SpatRaster with 6 layers, you can use index=c(1,1,1,2,2,2)
and fun=sum
. This will return a SpatRaster with two layers. The first layer is the sum of the first three layers in the input SpatRaster, and the second layer is the sum of the last three layers in the input SpatRaster. Indices are recycled such that index=c(1,2)
would also return a SpatRaster with two layers (one based on the odd layers (1,3,5), the other based on the even layers (2,4,6)).
The index can also be one of the following values to group by time period (if x
has the appropriate time
values): "years", "months", "yearmonths", "week" (the ISO 8601 week number, see Details), "yearweeks", "days", "doy" (day of the year), "7days" (seven-day periods starting at Jan 1 of each year), "10days", or "15days". It can also be a function that makes groups from time values.
See app
or Summary-methods
if you want to use a more efficient function that returns multiple layers based on all layers in the SpatRaster.
## S4 method for signature 'SpatRaster' tapp(x, index, fun, ..., cores=1, filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster' tapp(x, index, fun, ..., cores=1, filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster |
index |
factor or numeric (integer). Vector of length |
fun |
function to be applied. The following functions have been re-implemented in C++ for speed: "sum", "mean", "median", "modal", "which", "which.min", "which.max", "min", "max", "prod", "any", "all", "sd", "std", "first". To use the base-R function for say, "min", you could use something like |
... |
additional arguments passed to |
cores |
positive integer. If |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
"week" follows the ISO 8601 definition. Weeks start on Monday. If the week containing 1 January has four or more days in the new year, then it is considered week "01". Otherwise, it is the last week of the previous year (week "52" or "53", and the next week is week 1.
SpatRaster
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) s <- c(r, r, r, r, r, r) s <- s * 1:6 b1 <- tapp(s, index=c(1,1,1,2,2,2), fun=sum) b1 b2 <- tapp(s, c(1,2,3,1,2,3), fun=sum) b2
r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) s <- c(r, r, r, r, r, r) s <- s * 1:6 b1 <- tapp(s, index=c(1,1,1,2,2,2), fun=sum) b1 b2 <- tapp(s, c(1,2,3,1,2,3), fun=sum) b2
Compute terrain characteristics from elevation data. The elevation values should be in the same units as the map units (typically meter) for projected (planar) raster data. They should be in meter when the coordinate reference system is longitude/latitude.
For accuracy, always compute these values on the original data (do not first change the projection). Distances (needed for slope and aspect) for longitude/latitude data are computed on the WGS84 ellipsoid with Karney's algorithm.
## S4 method for signature 'SpatRaster' terrain(x, v="slope", neighbors=8, unit="degrees", filename="", ...)
## S4 method for signature 'SpatRaster' terrain(x, v="slope", neighbors=8, unit="degrees", filename="", ...)
x |
SpatRaster, single layer with elevation values. Values should have the same unit as the map units, or in meters when the crs is longitude/latitude |
v |
character. One or more of these options: slope, aspect, TPI, TRI, TRIriley, TRIrmsd, roughness, flowdir (see Details) |
unit |
character. "degrees" or "radians" for the output of "slope" and "aspect" |
neighbors |
integer. Indicating how many neighboring cells to use to compute slope or aspect with. Either 8 (queen case) or 4 (rook case) |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
When neighbors=4
, slope and aspect are computed according to Fleming and Hoffer (1979) and Ritter (1987). When neighbors=8
, slope and aspect are computed according to Horn (1981). The Horn algorithm may be best for rough surfaces, and the Fleming and Hoffer algorithm may be better for smoother surfaces (Jones, 1997; Burrough and McDonnell, 1998).
If slope = 0, aspect is set to 0.5*pi radians (or 90 degrees if unit="degrees"). When computing slope or aspect, the coordinate reference system of x
must be known for the algorithm to differentiate between planar and longitude/latitude data.
terrain
is not vectorized over "neighbors" or "unit" – only the first value is used.
flowdir returns the "flow direction" (of water), that is the direction of the greatest drop in elevation (or the smallest rise if all neighbors are higher). They are encoded as powers of 2 (0 to 7). The cell to the right of the focal cell is 1, the one below that is 2, and so on:
32 | 64 | 128 |
16 | x | 1 |
8 | 4 | 2 |
Cells without lower neighboring cells are encoded as zero.
If two cells have the same drop in elevation, a random cell is picked. That is not ideal as it may prevent the creation of connected flow networks. ArcGIS implements the approach of Greenlee (1987) and I might adopt that in the future.
Most terrain indices are according to Wilson et al. (2007), as in gdaldem. TRI (Terrain Ruggedness Index) is the mean of the absolute differences between the value of a cell and its 8 surrounding cells. TPI (Topographic Position Index) is the difference between the value of a cell and the mean value of its 8 surrounding cells. Roughness is the difference between the maximum and the minimum value of a cell and its 8 surrounding cells.
TRIriley (TRI according to Riley et al., 2007) returns the square root of summed squared differences between the value of a cell and its 8 surrounding cells. TRIrmsd computes the square root of the mean of the squared differences between these cells.
These measures can also be computed with focal
functions:
TRI <- focal(x, w=3, fun=\(x) sum(abs(x[-5]-x[5]))/8)
TPI <- focal(x, w=3, fun=\(x) x[5] - mean(x[-5]))
rough <- focal(x, w=3, fun=\(x) max(x) - min(x))
Burrough, P., and R.A. McDonnell, 1998. Principles of Geographical Information Systems. Oxford University Press.
Fleming, M.D. and Hoffer, R.M., 1979. Machine processing of Landsat MSS data and DMA topographic data for forest cover type mapping. LARS Technical Report 062879. Laboratory for Applications of Remote Sensing, Purdue University, West Lafayette, Indiana.
Horn, B.K.P., 1981. Hill shading and the reflectance map. Proceedings of the IEEE 69:14-47
Jones, K.H., 1998. A comparison of algorithms used to compute hill slope as a property of the DEM. Computers & Geosciences 24: 315-323
Karney, C.F.F., 2013. Algorithms for geodesics, J. Geodesy 87: 43-55. doi:10.1007/s00190-012-0578-z.
Riley, S.J., De Gloria, S.D., Elliot, R. (1999): A Terrain Ruggedness that Quantifies Topographic Heterogeneity. Intermountain Journal of Science 5: 23-27.
Ritter, P., 1987. A vector-based terrain and aspect generation algorithm. Photogrammetric Engineering and Remote Sensing 53: 1109-1111
Wilson et al 2007, Multiscale Terrain Analysis of Multibeam Bathymetry Data for Habitat Mapping on the Continental Slope. Marine Geodesy 30:3-35
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- terrain(r, "slope")
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- terrain(r, "slope")
Plots labels, that is a textual (rather than color) representation of values, on top an existing plot (map).
## S4 method for signature 'SpatRaster' text(x, labels, digits=0, halo=FALSE, ...) ## S4 method for signature 'SpatVector' text(x, labels, halo=FALSE, inside=FALSE, ...)
## S4 method for signature 'SpatRaster' text(x, labels, digits=0, halo=FALSE, ...) ## S4 method for signature 'SpatVector' text(x, labels, halo=FALSE, inside=FALSE, ...)
x |
SpatRaster or SpatVector |
labels |
character. Optional. Vector of labels with |
digits |
integer. How many digits should be used? |
halo |
logical. If |
inside |
logical. Should the text always be placed inside one the sub-geometries? |
... |
additional arguments to pass to graphics function |
r <- rast(nrows=4, ncols=4) values(r) <- 1:ncell(r) plot(r) text(r) plot(r) text(r, halo=TRUE, hc="blue", col="white", hw=0.2) plot(r, col=rainbow(16)) text(r, col=c("black", "white"), vfont=c("sans serif", "bold"), cex=2)
r <- rast(nrows=4, ncols=4) values(r) <- 1:ncell(r) plot(r) text(r) plot(r) text(r, halo=TRUE, hc="blue", col="white", hw=0.2) plot(r, col=rainbow(16)) text(r, col=c("black", "white"), vfont=c("sans serif", "bold"), cex=2)
Combines data sources within a SpatRaster (that are in memory, or from the same file) to allow for faster processing.
Or combine sub-datasets into a SpatRaster.
## S4 method for signature 'SpatRaster' tighten(x) ## S4 method for signature 'SpatRasterDataset' tighten(x)
## S4 method for signature 'SpatRaster' tighten(x) ## S4 method for signature 'SpatRasterDataset' tighten(x)
x |
SpatRaster or SpatRasterDataset |
SpatRaster
r <- rast(nrow=5, ncol=9, vals=1:45) x <- c(r, r*2, r*3) x tighten(x)
r <- rast(nrow=5, ncol=9, vals=1:45) x <- c(r, r*2, r*3) x tighten(x)
Get or set the time of the layers of a SpatRaster. Time can be stored as POSIXlt
(date and time, with a resolution of seconds, and a time zone), Date
, "months", "years", or "yearmonths".
timeInfo
and has.time
are helper functions to understand what a time data a SpatRaster has.
## S4 method for signature 'SpatRaster' has.time(x) ## S4 method for signature 'SpatRaster' time(x, format="") ## S4 replacement method for signature 'SpatRaster' time(x, tstep="")<-value ## S4 method for signature 'SpatRaster' timeInfo(x)
## S4 method for signature 'SpatRaster' has.time(x) ## S4 method for signature 'SpatRaster' time(x, format="") ## S4 replacement method for signature 'SpatRaster' time(x, tstep="")<-value ## S4 method for signature 'SpatRaster' timeInfo(x)
x |
SpatRaster or SpatRasterDataset |
format |
One of "", "seconds" (POSIXlt), "days" (Date), "yearmonths" (decimal years), "years", "months". If "", the returned format is (based on) the format that was used to set the time |
value |
|
tstep |
One of "years", "months", "yearmonths". Used when |
time
: POSIXlt, Date, or numeric
timeInfo
: data.frame with time step and time zone information (if available)
has.time
: logical
s <- rast(system.file("ex/logo.tif", package="terra")) # Date" d <- as.Date("2001-05-04") + 0:2 time(s) <- d time(s) # POSIX (date/time with a resolution of seconds) time(s) <- as.POSIXlt(d) time(s) # with time zone time(s) <- as.POSIXlt(Sys.time(), "America/New_York") + 0:2 time(s) timeInfo(s) # years time(s, tstep="years") <- 2000 + 0:2 s time(s, tstep="months") <- 1:3 s
s <- rast(system.file("ex/logo.tif", package="terra")) # Date" d <- as.Date("2001-05-04") + 0:2 time(s) <- d time(s) # POSIX (date/time with a resolution of seconds) time(s) <- as.POSIXlt(d) time(s) # with time zone time(s) <- as.POSIXlt(Sys.time(), "America/New_York") + 0:2 time(s) timeInfo(s) # years time(s, tstep="years") <- 2000 + 0:2 s time(s, tstep="months") <- 1:3 s
List and optionally remove temporary files created by the terra package. These files are created when an output SpatRaster may be too large to store in memory (RAM). This can happen when no filename is provided to a function and when using functions where you cannot provide a filename.
Temporary files are automatically removed at the end of each R session that ends normally. You can use tmpFiles
to see the files in the current sessions, including those that are orphaned (not connect to a SpatRaster object any more) and from other (perhaps old) sessions, and remove all the temporary files.
tmpFiles(current=TRUE, orphan=FALSE, old=FALSE, remove=FALSE)
tmpFiles(current=TRUE, orphan=FALSE, old=FALSE, remove=FALSE)
current |
logical. If |
orphan |
logical. If |
old |
logical. If |
remove |
logical. If |
character
tmpFiles()
tmpFiles()
makeNodes
create nodes on lines
mergeLines
connect lines to form polygons
removeDupNodes
removes duplicate nodes in geometries and optionally rounds the coordinates
emptyGeoms
returns the indices of empty (null) geometries. is.na
also checks if any of the coordinates is NA
.
snap
makes boundaries of geometries identical if they are very close to each other.
## S4 method for signature 'SpatVector' mergeLines(x) ## S4 method for signature 'SpatVector' snap(x, y=NULL, tolerance) ## S4 method for signature 'SpatVector' removeDupNodes(x, digits = -1) ## S4 method for signature 'SpatVector' makeNodes(x)
## S4 method for signature 'SpatVector' mergeLines(x) ## S4 method for signature 'SpatVector' snap(x, y=NULL, tolerance) ## S4 method for signature 'SpatVector' removeDupNodes(x, digits = -1) ## S4 method for signature 'SpatVector' makeNodes(x)
x |
SpatVector of lines or polygons |
y |
SpatVector of lines or polygons to snap to. If |
tolerance |
numeric. Snapping tolerance (distance between geometries) |
digits |
numeric. Number of digits used in rounding. Ignored if < 0 |
SpatVector
sharedPaths
, gaps
, simplifyGeom
, forceCCW
p1 <- as.polygons(ext(0,1,0,1)) p2 <- as.polygons(ext(1.1,2,0,1)) p <- rbind(p1, p2) y <- snap(p, tol=.15) plot(p, lwd=3, col="light gray") lines(y, col="red", lwd=2)
p1 <- as.polygons(ext(0,1,0,1)) p2 <- as.polygons(ext(1.1,2,0,1)) p <- rbind(p1, p2) y <- snap(p, tol=.15) plot(p, lwd=3, col="light gray") lines(y, col="red", lwd=2)
Transpose a SpatRaster or SpatVector
## S4 method for signature 'SpatRaster' t(x) ## S4 method for signature 'SpatVector' t(x) ## S4 method for signature 'SpatRaster' trans(x, filename="", ...)
## S4 method for signature 'SpatRaster' t(x) ## S4 method for signature 'SpatVector' t(x) ## S4 method for signature 'SpatRaster' trans(x, filename="", ...)
x |
SpatRaster or SpatVector |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(nrows=18, ncols=36) values(r) <- 1:ncell(r) tr1 <- t(r) tr2 <- trans(r) ttr <- trans(tr2)
r <- rast(nrows=18, ncols=36) values(r) <- 1:ncell(r) tr1 <- t(r) tr2 <- trans(r) ttr <- trans(tr2)
Trim (shrink) a SpatRaster by removing outer rows and columns that are NA
or another value.
## S4 method for signature 'SpatRaster' trim(x, padding=0, value=NA, filename="", ...)
## S4 method for signature 'SpatRaster' trim(x, padding=0, value=NA, filename="", ...)
x |
SpatRaster |
padding |
integer. Number of outer rows/columns to keep |
value |
numeric. The value of outer rows or columns that are to be removed |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
r <- rast(ncols=10, nrows=10, xmin=0,xmax=10,ymin=0,ymax=10) v <- rep(NA, ncell(r)) v[c(12,34,69)] <- 1:3 values(r) <- v s <- trim(r)
r <- rast(ncols=10, nrows=10, xmin=0,xmax=10,ymin=0,ymax=10) v <- rep(NA, ncell(r)) v[c(12,34,69)] <- 1:3 values(r) <- v s <- trim(r)
If you want to append polygon SpatVectors use rbind
instead of union
. union
will also intersect overlapping polygons between, not within, objects. Union for lines and points simply combines the two data sets; without any geometric intersections. This is equivalent to rbind
. Attributes are joined.
If x
and y
have a different geometry type, a SpatVectorCollection is returned.
If a single SpatVector is supplied, overlapping polygons are intersected. Original attributes are lost. New attributes allow for determining how many, and which, polygons overlapped.
SpatExtent: Objects are combined into their union; this is equivalent to +
.
## S4 method for signature 'SpatVector,SpatVector' union(x, y) ## S4 method for signature 'SpatVector,missing' union(x, y) ## S4 method for signature 'SpatExtent,SpatExtent' union(x, y)
## S4 method for signature 'SpatVector,SpatVector' union(x, y) ## S4 method for signature 'SpatVector,missing' union(x, y) ## S4 method for signature 'SpatExtent,SpatExtent' union(x, y)
x |
SpatVector or SpatExtent |
y |
Same as |
SpatVector or SpatExtent
merge
and mosaic
to union SpatRasters.
crop
and extend
for the union of SpatRaster and SpatExtent.
merge
for merging a data.frame with attributes of a SpatVector.
aggregate
to dissolve SpatVector objects.
e1 <- ext(-10, 10, -20, 20) e2 <- ext(0, 20, -40, 5) union(e1, e2) #SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) v <- v[,3:4] p <- vect(c("POLYGON ((5.8 49.8, 6 49.9, 6.15 49.8, 6 49.65, 5.8 49.8))", "POLYGON ((6.3 49.9, 6.2 49.7, 6.3 49.6, 6.5 49.8, 6.3 49.9))"), crs=crs(v)) values(p) <- data.frame(pid=1:2, value=expanse(p)) u <- union(v, p) plot(u, "pid") b <- buffer(v, 1000) u <- union(b) u$sum <- rowSums(as.data.frame(u)) plot(u, "sum")
e1 <- ext(-10, 10, -20, 20) e2 <- ext(0, 20, -40, 5) union(e1, e2) #SpatVector v <- vect(system.file("ex/lux.shp", package="terra")) v <- v[,3:4] p <- vect(c("POLYGON ((5.8 49.8, 6 49.9, 6.15 49.8, 6 49.65, 5.8 49.8))", "POLYGON ((6.3 49.9, 6.2 49.7, 6.3 49.6, 6.5 49.8, 6.3 49.9))"), crs=crs(v)) values(p) <- data.frame(pid=1:2, value=expanse(p)) u <- union(v, p) plot(u, "pid") b <- buffer(v, 1000) u <- union(b) u$sum <- rowSums(as.data.frame(u)) plot(u, "sum")
This method returns the unique values in a SpatRaster, or removes duplicates records (geometry and attributes) in a SpatVector.
## S4 method for signature 'SpatRaster' unique(x, incomparables=FALSE, digits=NA, na.rm=TRUE, as.raster=FALSE) ## S4 method for signature 'SpatVector' unique(x, incomparables=FALSE, ...)
## S4 method for signature 'SpatRaster' unique(x, incomparables=FALSE, digits=NA, na.rm=TRUE, as.raster=FALSE) ## S4 method for signature 'SpatVector' unique(x, incomparables=FALSE, ...)
x |
SpatRaster or SpatVector |
incomparables |
logical. If |
digits |
integer. The number of digits for rounding the values before finding the unique values. Use |
na.rm |
logical. If |
as.raster |
logical. If |
... |
additional arguments passed on to |
If x
is a SpatRaster: data.frame or list (if incomparables=FALSE
)
If x
is a SpatVector: SpatVector
r <- rast(ncols=5, nrows=5) values(r) <- rep(1:5, each=5) unique(r) s <- c(r, round(r/3)) unique(s) unique(s,TRUE) unique(s, as.raster=TRUE) v <- vect(cbind(x=c(1:5,1:5), y=c(5:1,5:1)), crs="+proj=utm +zone=1 +datum=WGS84") nrow(v) u <- unique(v) nrow(u) values(v) <- c(1:5, 1:3, 5:4) unique(v)
r <- rast(ncols=5, nrows=5) values(r) <- rep(1:5, each=5) unique(r) s <- c(r, round(r/3)) unique(s) unique(s,TRUE) unique(s, as.raster=TRUE) v <- vect(cbind(x=c(1:5,1:5), y=c(5:1,5:1)), crs="+proj=utm +zone=1 +datum=WGS84") nrow(v) u <- unique(v) nrow(u) values(v) <- c(1:5, 1:3, 5:4) unique(v)
Get or set the units of the layers of a SpatRaster or the datasets in a SpatRasterDataSet.
## S4 method for signature 'SpatRaster' units(x) ## S4 replacement method for signature 'SpatRaster' units(x)<-value ## S4 method for signature 'SpatRasterDataset' units(x) ## S4 replacement method for signature 'SpatRasterDataset' units(x)<-value
## S4 method for signature 'SpatRaster' units(x) ## S4 replacement method for signature 'SpatRaster' units(x)<-value ## S4 method for signature 'SpatRasterDataset' units(x) ## S4 replacement method for signature 'SpatRasterDataset' units(x)<-value
x |
SpatRaster |
value |
character |
character
s <- rast(system.file("ex/logo.tif", package="terra")) units(s) <- c("m/s", "kg", "ha") units(s) s units(s) <- "kg" units(s)
s <- rast(system.file("ex/logo.tif", package="terra")) units(s) <- c("m/s", "kg", "ha") units(s) s units(s) <- "kg" units(s)
Change the contents of a file that is the data source of a SpatRaster. BE CAREFUL as you are overwriting values in an existing file.
## S4 method for signature 'SpatRaster' update(object, names=FALSE, crs=FALSE, extent=FALSE)
## S4 method for signature 'SpatRaster' update(object, names=FALSE, crs=FALSE, extent=FALSE)
object |
SpatRaster |
names |
logical. Should the names be updated? |
crs |
logical. Should the coordinate reference system be updated? |
extent |
logical. Should the extent be updated? |
SpatRaster (invisibly)
s <- rast(system.file("ex/logo.tif", package="terra")) fname <- paste0(tempfile(), ".tif") x <- writeRaster(s, fname) names(x) <- c("A", "B", "C") ext(x) <- ext(x) + 1 crs(x) <- "+proj=utm +zone=1" update(x, names=TRUE, crs=TRUE, extent=TRUE) rast(fname)
s <- rast(system.file("ex/logo.tif", package="terra")) fname <- paste0(tempfile(), ".tif") x <- writeRaster(s, fname) names(x) <- c("A", "B", "C") ext(x) <- ext(x) + 1 crs(x) <- "+proj=utm +zone=1" update(x, names=TRUE, crs=TRUE, extent=TRUE) rast(fname)
Get the cell values of a SpatRaster or the attributes of a SpatVector.
By default all values returned are numeric. This is because a vector or matrix can only store one data type, and a SpatRaster may consist of multiple data types. However, if all layers have integer or logical values, the returned values also have that datatype.
Note that with values(x, dataframe=TRUE)
and as.data.frame(x)
the values returned match the type of each layer, and can be a mix of numeric, logical, integer, and factor.
## S4 method for signature 'SpatRaster' values(x, mat=TRUE, dataframe=FALSE, row=1, nrows=nrow(x), col=1, ncols=ncol(x), na.rm=FALSE, ...) ## S4 method for signature 'SpatVector' values(x, ...)
## S4 method for signature 'SpatRaster' values(x, mat=TRUE, dataframe=FALSE, row=1, nrows=nrow(x), col=1, ncols=ncol(x), na.rm=FALSE, ...) ## S4 method for signature 'SpatVector' values(x, ...)
x |
SpatRaster or SpatVector |
mat |
logical. If |
dataframe |
logical. If |
row |
positive integer. Row number to start from, should be between 1 and nrow(x) |
nrows |
positive integer. How many rows? |
col |
positive integer. Column number to start from, should be between 1 and ncol(x) |
ncols |
positive integer. How many columns? Default is the number of columns left after the start column |
na.rm |
logical. Remove |
... |
additional arguments passed to |
If x
is a SpatRaster
, and mat=FALSE
, the values are returned as a vector. In cell-order by layer. If mat=TRUE
, a matrix is returned in which the values of each layer are represented by a column (with ncell(x)
rows). The values per layer are in cell-order, that is, from top-left, to top-right and then down by row. Use as.matrix(x, wide=TRUE)
for an alternative matrix representation where the number of rows and columns matches that of x
.
matrix or data.frame
raster values that are NA
(missing) are represented by NaN
(not-a-number) unless argument dataframe
is TRUE
.
values<-
, focalValues
, as.data.frame
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) r x <- values(r) x[3650:3655, ] r[3650:3655] ff <- system.file("ex/lux.shp", package="terra") v <- vect(ff) y <- values(v) head(y)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) r x <- values(r) x[3650:3655, ] r[3650:3655] ff <- system.file("ex/lux.shp", package="terra") v <- vect(ff) y <- values(v) head(y)
Set or get names for each dataset (variable) in a SpatRasterDataset.
Each SpatRaster _data source_ can also have a variable name and a long variable name. They are set when reading a file with possibly multiple sub-datasets (e.g. netcdf or hdf5 format) into a single SpatRaster. Each sub-datset is a seperate "data-source" in the SpatRaster. Note that newly created or derived SpatRasters always have a single variable (data source), and therefore the variable names are lost when processing a multi-variable SpatRaster. Thus the variable names are mostly useful to understand a SpatRaster created from some files and for managing SpatRasterDatasets.
See link{names}
for the more commonly used _layer_ names.
## S4 method for signature 'SpatRaster' varnames(x) ## S4 replacement method for signature 'SpatRaster' varnames(x)<-value ## S4 method for signature 'SpatRaster' longnames(x) ## S4 replacement method for signature 'SpatRaster' longnames(x)<-value ## S4 method for signature 'SpatRasterDataset' varnames(x) ## S4 replacement method for signature 'SpatRasterDataset' varnames(x)<-value ## S4 method for signature 'SpatRasterDataset' longnames(x) ## S4 replacement method for signature 'SpatRasterDataset' longnames(x)<-value
## S4 method for signature 'SpatRaster' varnames(x) ## S4 replacement method for signature 'SpatRaster' varnames(x)<-value ## S4 method for signature 'SpatRaster' longnames(x) ## S4 replacement method for signature 'SpatRaster' longnames(x)<-value ## S4 method for signature 'SpatRasterDataset' varnames(x) ## S4 replacement method for signature 'SpatRasterDataset' varnames(x)<-value ## S4 method for signature 'SpatRasterDataset' longnames(x) ## S4 replacement method for signature 'SpatRasterDataset' longnames(x)<-value
x |
SpatRaster, SpatRasterDataset |
value |
character (vector) |
character
terra enforces neither unique nor valid names. See make.unique
to create unique names and {make.names}
to make syntactically valid names.
s <- rast(ncols=5, nrows=5, nlyrs=3) names(s) <- c("a", "b", "c") x <- sds(s, s) varnames(x) <- c("one", "two") x
s <- rast(ncols=5, nrows=5, nlyrs=3) names(s) <- c("a", "b", "c") x <- sds(s, s) varnames(x) <- c("one", "two") x
Methods to create a SpatVector from a filename or other R object.
A filename can be for a shapefile or any spatial file format.
You can use a data.frame to make a SpatVector of points; or a "geom" matrix to make a SpatVector of any supported geometry (see examples and geom
).
You can supply a list of SpatVectors to append them into a single SpatVector.
SpatVectors can also be created from "Well Known Text", and from spatial vector data objects defined in the sf
or sp
packages.
## S4 method for signature 'character' vect(x, layer="", query="", extent=NULL, filter=NULL, crs="", proxy=FALSE, what="", opts=NULL) ## S4 method for signature 'matrix' vect(x, type="points", atts=NULL, crs="") ## S4 method for signature 'data.frame' vect(x, geom=c("lon", "lat"), crs="", keepgeom=FALSE) ## S4 method for signature 'list' vect(x, type="points", crs="") ## S4 method for signature 'SpatExtent' vect(x, crs="") ## S4 method for signature 'SpatVectorCollection' vect(x) ## S4 method for signature 'sf' vect(x)
## S4 method for signature 'character' vect(x, layer="", query="", extent=NULL, filter=NULL, crs="", proxy=FALSE, what="", opts=NULL) ## S4 method for signature 'matrix' vect(x, type="points", atts=NULL, crs="") ## S4 method for signature 'data.frame' vect(x, geom=c("lon", "lat"), crs="", keepgeom=FALSE) ## S4 method for signature 'list' vect(x, type="points", crs="") ## S4 method for signature 'SpatExtent' vect(x, crs="") ## S4 method for signature 'SpatVectorCollection' vect(x) ## S4 method for signature 'sf' vect(x)
x |
character. A filename; or a "Well Known Text" string; SpatExtent, data.frame (to make a SpatVector of points); a "geom" matrix to make a SpatVector of any supported geometry (see examples and |
layer |
character. layer name to select a layer from a file (database) with multiple layers |
query |
character. A query to subset the dataset in the OGR-SQL dialect |
extent |
Spat* object. The extent of the object is used as a spatial filter to select the geometries to read. Ignored if |
filter |
SpatVector. Used as a spatial filter to select geometries to read (the convex hull is used for lines or points). It is guaranteed that all features that overlap with the extent of filter will be returned. It can happen that additional geometries are returned |
type |
character. Geometry type. Must be "points", "lines", or "polygons" |
atts |
data.frame with the attributes. The number of rows must match the number of geometrical elements |
crs |
character. The coordinate reference system in one of the following formats: WKT/WKT2, <authority>:<code>, or PROJ-string notation (see |
proxy |
logical. If |
what |
character indicating what to read. Either |
opts |
character. GDAL dataset open options |
geom |
character. The field name(s) with the geometry data. Either two names for x and y coordinates of points, or a single name for a single column with WKT geometries |
keepgeom |
logical. If |
SpatVector
### SpatVector from file f <- system.file("ex/lux.shp", package="terra") f v <- vect(f) v ## subsetting (large) files ## with attribute query v <- vect(f, query="SELECT NAME_1, NAME_2, ID_2 FROM lux WHERE ID_2 < 4") ## with an extent e <- ext(5.9, 6.3, 49.9, 50) v <- vect(f, extent=e) ## with polygons p <- as.polygons(e) v <- vect(f, filter=p) ### SpatVector from a geom matrix x1 <- rbind(c(-180,-20), c(-140,55), c(10, 0), c(-140,-60)) x2 <- rbind(c(-10,0), c(140,60), c(160,0), c(140,-55)) x3 <- rbind(c(-125,0), c(0,60), c(40,5), c(15,-45)) hole <- rbind(c(80,0), c(105,13), c(120,2), c(105,-13)) z <- rbind(cbind(object=1, part=1, x1, hole=0), cbind(object=2, part=1, x3, hole=0), cbind(object=3, part=1, x2, hole=0), cbind(object=3, part=1, hole, hole=1)) colnames(z)[3:4] <- c('x', 'y') p <- vect(z, "polygons") p z[z[, "hole"]==1, "object"] <- 4 lns <- vect(z[,1:4], "lines") plot(p) lines(lns, col="red", lwd=2) ### from wkt v <- vect("POLYGON ((0 -5, 10 0, 10 -10, 0 -5))") wkt <- c("MULTIPOLYGON ( ((40 40, 20 45, 45 30, 40 40)), ((20 35, 10 30, 10 10, 30 5, 45 20, 20 35),(30 20, 20 15, 20 25, 30 20)))", "POLYGON ((0 -5, 10 0, 10 -10, 0 -5))") w <- vect(wkt) # combine two SpatVectors vw <- rbind(w, v) # add a data.frame d <- data.frame(id=1:2, name=c("a", "b")) values(w) <- d # add data.frame on creation, here from a geom matrix g <- geom(w) d <- data.frame(id=1:2, name=c("a", "b")) m <- vect(g, "polygons", atts=d, crs="+proj=longlat +datum=WGS84") ### SpatVector from a data.frame d$wkt <- wkt x <- vect(d, geom="wkt") d$wkt <- NULL d$lon <- c(0,10) d$lat <- c(0,10) x <- vect(d, geom=c("lon", "lat")) # SpatVector to sf #sf::st_as_sf(x)
### SpatVector from file f <- system.file("ex/lux.shp", package="terra") f v <- vect(f) v ## subsetting (large) files ## with attribute query v <- vect(f, query="SELECT NAME_1, NAME_2, ID_2 FROM lux WHERE ID_2 < 4") ## with an extent e <- ext(5.9, 6.3, 49.9, 50) v <- vect(f, extent=e) ## with polygons p <- as.polygons(e) v <- vect(f, filter=p) ### SpatVector from a geom matrix x1 <- rbind(c(-180,-20), c(-140,55), c(10, 0), c(-140,-60)) x2 <- rbind(c(-10,0), c(140,60), c(160,0), c(140,-55)) x3 <- rbind(c(-125,0), c(0,60), c(40,5), c(15,-45)) hole <- rbind(c(80,0), c(105,13), c(120,2), c(105,-13)) z <- rbind(cbind(object=1, part=1, x1, hole=0), cbind(object=2, part=1, x3, hole=0), cbind(object=3, part=1, x2, hole=0), cbind(object=3, part=1, hole, hole=1)) colnames(z)[3:4] <- c('x', 'y') p <- vect(z, "polygons") p z[z[, "hole"]==1, "object"] <- 4 lns <- vect(z[,1:4], "lines") plot(p) lines(lns, col="red", lwd=2) ### from wkt v <- vect("POLYGON ((0 -5, 10 0, 10 -10, 0 -5))") wkt <- c("MULTIPOLYGON ( ((40 40, 20 45, 45 30, 40 40)), ((20 35, 10 30, 10 10, 30 5, 45 20, 20 35),(30 20, 20 15, 20 25, 30 20)))", "POLYGON ((0 -5, 10 0, 10 -10, 0 -5))") w <- vect(wkt) # combine two SpatVectors vw <- rbind(w, v) # add a data.frame d <- data.frame(id=1:2, name=c("a", "b")) values(w) <- d # add data.frame on creation, here from a geom matrix g <- geom(w) d <- data.frame(id=1:2, name=c("a", "b")) m <- vect(g, "polygons", atts=d, crs="+proj=longlat +datum=WGS84") ### SpatVector from a data.frame d$wkt <- wkt x <- vect(d, geom="wkt") d$wkt <- NULL d$lon <- c(0,10) d$lat <- c(0,10) x <- vect(d, geom=c("lon", "lat")) # SpatVector to sf #sf::st_as_sf(x)
List or remove layers from a vector file that supports layers such as GPGK
vector_layers(filename, delete="", return_error=FALSE)
vector_layers(filename, delete="", return_error=FALSE)
filename |
character. filename |
delete |
character. layers to be deleted (ignored if the value is |
return_error |
logical. If |
Use elevation data to compute the locations that can be seen, or how much higher they would have to be to be seen, from a certain position. The raster data coordinate reference system must planar (not lon/lat), with the elevation values in the same unit as the distance unit of the coordinate reference system.
## S4 method for signature 'SpatRaster' viewshed(x, loc, observer=1.80, target=0, curvcoef=6/7, output="yes/no", filename="", ...)
## S4 method for signature 'SpatRaster' viewshed(x, loc, observer=1.80, target=0, curvcoef=6/7, output="yes/no", filename="", ...)
x |
SpatRaster, single layer with elevation values. Values should have the same unit as the map units |
loc |
location (x and y coordinates) or a cell number |
observer |
numeric. The height above the elevation data of the observer |
target |
numeric. The height above the elevation data of the targets |
curvcoef |
numeric. Coefficient to consider the effect of the curvature of the earth and refraction of the atmosphere. The elevation values are corrected with: |
output |
character. Can be "yes/no" to get a binary (logical) output showing what areas are visible; "land" to get the height above the current elevation that would be visible; or "sea" the elevation above sea level that would be visible |
filename |
character. Output filename |
... |
Options for writing files as in |
The algorithm used is by Wang et al.: https://www.asprs.org/wp-content/uploads/pers/2000journal/january/2000_jan_87-90.pdf.
if (gdal() >= 3.1) { f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- project(r, "EPSG:2169") p <- cbind(70300, 96982) v <- viewshed(x, p, 0, 0, 0.85714) }
if (gdal() >= 3.1) { f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- project(r, "EPSG:2169") p <- cbind(70300, 96982) v <- viewshed(x, p, 0, 0, 0.85714) }
Get a Voronoi diagram or Delaunay triangles for points, or the nodes of lines or polygons
## S4 method for signature 'SpatVector' voronoi(x, bnd=NULL, tolerance=0, as.lines=FALSE, deldir=FALSE) ## S4 method for signature 'SpatVector' delaunay(x, tolerance=0, as.lines=FALSE)
## S4 method for signature 'SpatVector' voronoi(x, bnd=NULL, tolerance=0, as.lines=FALSE, deldir=FALSE) ## S4 method for signature 'SpatVector' delaunay(x, tolerance=0, as.lines=FALSE)
x |
SpatVector |
bnd |
SpatVector to set the outer boundary of the voronoi diagram |
tolerance |
numeric >= 0, snapping tolerance (0 is no snapping) |
as.lines |
logical. If |
deldir |
logical. If |
SpatVector
wkt <- c("MULTIPOLYGON ( ((40 40, 20 45, 45 30, 40 40)), ((20 35, 10 30, 10 10, 30 5, 45 20, 20 35),(30 20, 20 15, 20 25, 30 20)))", "POLYGON ((0 -5, 10 0, 10 -10, 0 -5))") x <- vect(wkt) v <- voronoi(x) v d <- delaunay(x) d plot(v, lwd=2, col=rainbow(15)) lines(x, col="gray", lwd=2) points(x)
wkt <- c("MULTIPOLYGON ( ((40 40, 20 45, 45 30, 40 40)), ((20 35, 10 30, 10 10, 30 5, 45 20, 20 35),(30 20, 20 15, 20 25, 30 20)))", "POLYGON ((0 -5, 10 0, 10 -10, 0 -5))") x <- vect(wkt) v <- voronoi(x) v d <- delaunay(x) d plot(v, lwd=2, col=rainbow(15)) lines(x, col="gray", lwd=2) points(x)
Create a Virtual Raster Dataset (VRT) from a collection of file-based raster datasets (tiles). See gdalbuildvrt for details.
## S4 method for signature 'character' vrt(x, filename="", options=NULL, overwrite=FALSE, set_names=FALSE, return_filename=FALSE)
## S4 method for signature 'character' vrt(x, filename="", options=NULL, overwrite=FALSE, set_names=FALSE, return_filename=FALSE)
x |
character. Filenames of raster "tiles". That is, files that have data for, typically non-overlapping, sub-regions of an raster. See |
filename |
character. output VRT filename |
options |
character. All arguments as separate vector elements. Options as for gdalbuildvrt |
overwrite |
logical. Should |
set_names |
logical. Add the layer names of the first tile to the vrt? |
return_filename |
logical. If |
SpatRaster
A VRT can reference very many datasets. These are not all opened at the same time. The default is to open not more than 100 files. To increase performance, this maximum limit can be increased by setting the GDAL_MAX_DATASET_POOL_SIZE configuration option to a bigger value with setGDALconfig
. Note that a typical user process on Linux is limited to 1024 simultaneously opened files.
makeTiles
to create tiles; makeVRT
to create a .vrt file for a binary raster file that does not have a header file. vrt_tiles
to get the filenames of the tiles in a VRT.
r <- rast(ncols=100, nrows=100) values(r) <- 1:ncell(r) x <- rast(ncols=2, nrows=2) filename <- paste0(tempfile(), "_.tif") ff <- makeTiles(r, x, filename) ff #vrtfile <- paste0(tempfile(), ".vrt") #v <- vrt(ff, vrtfile) ## output in lower resolution #vrtfile <- paste0(tempfile(), ".vrt") #v <- vrt(ff, vrtfile, options = c("-tr", 5, 5)) #head(readLines(vrtfile)) #v
r <- rast(ncols=100, nrows=100) values(r) <- 1:ncell(r) x <- rast(ncols=2, nrows=2) filename <- paste0(tempfile(), "_.tif") ff <- makeTiles(r, x, filename) ff #vrtfile <- paste0(tempfile(), ".vrt") #v <- vrt(ff, vrtfile) ## output in lower resolution #vrtfile <- paste0(tempfile(), ".vrt") #v <- vrt(ff, vrtfile, options = c("-tr", 5, 5)) #head(readLines(vrtfile)) #v
Get the filenames of the tiles in a Virtual Raster Dataset (VRT)
vrt_tiles(x)
vrt_tiles(x)
x |
character (filename) or SpatRaster |
character
delineate the area covered by a catchment from a SpatRaster with flow direction and a pour-point (catchment outlet).
## S4 method for signature 'SpatRaster' watershed(x, pourpoint, filename="",...)
## S4 method for signature 'SpatRaster' watershed(x, pourpoint, filename="",...)
x |
SpatRaster with flow direction. See |
pourpoint |
matrix or SpatVector with the pour point location |
filename |
character. Output filename |
... |
additional arguments for writing files as in |
SpatRaster
Ezio Crestaz, Emanuele Cordano, Roman Seliger
elev <- rast(system.file('ex/elev_vinschgau.tif', package="terra")) flowdir <- terrain(elev, "flowdir") ## pour point at Naturns pp <- cbind(653358.3, 5168222) w <- watershed(flowdir, pp)
elev <- rast(system.file('ex/elev_vinschgau.tif', package="terra")) flowdir <- terrain(elev, "flowdir") ## pour point at Naturns pp <- cbind(653358.3, 5168222) w <- watershed(flowdir, pp)
Compute the weighted mean for each cell of the layers of a SpatRaster. The weights can be spatially variable or not.
## S4 method for signature 'SpatRaster,numeric' weighted.mean(x, w, na.rm=FALSE, filename="", ...) ## S4 method for signature 'SpatRaster,SpatRaster' weighted.mean(x, w, na.rm=FALSE, filename="", ...)
## S4 method for signature 'SpatRaster,numeric' weighted.mean(x, w, na.rm=FALSE, filename="", ...) ## S4 method for signature 'SpatRaster,SpatRaster' weighted.mean(x, w, na.rm=FALSE, filename="", ...)
x |
SpatRaster |
w |
A vector of weights (one number for each layer), or for spatially variable weights, a SpatRaster with weights (should have the same extent, resolution and number of layers as x) |
na.rm |
Logical. Should missing values be removed? |
filename |
character. Output filename |
... |
options for writing files as in |
SpatRaster
Summary-methods
, weighted.mean
b <- rast(system.file("ex/logo.tif", package="terra")) # give least weight to first layer, most to last layer wm1 <- weighted.mean(b, w=1:3) # spatially varying weights # weigh by column number w1 <- init(b, "col") # weigh by row number w2 <- init(b, "row") w <- c(w1, w2, w2) wm2 <- weighted.mean(b, w=w)
b <- rast(system.file("ex/logo.tif", package="terra")) # give least weight to first layer, most to last layer wm1 <- weighted.mean(b, w=1:3) # spatially varying weights # weigh by column number w1 <- init(b, "col") # weigh by row number w2 <- init(b, "row") w <- c(w1, w2, w2) wm2 <- weighted.mean(b, w=w)
This method returns the cell numbers for the cells with the min or max values of each layer in a SpatRaster.
## S4 method for signature 'SpatRaster' where.min(x, values=TRUE, list=FALSE) ## S4 method for signature 'SpatRaster' where.max(x, values=TRUE, list=FALSE)
## S4 method for signature 'SpatRaster' where.min(x, values=TRUE, list=FALSE) ## S4 method for signature 'SpatRaster' where.max(x, values=TRUE, list=FALSE)
x |
SpatRaster |
values |
logical. If |
list |
logical. If |
matrix or list
which
and Summary-methods
for which.min
and which.max
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) where.min(r)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) where.min(r)
This method returns a single layer SpatRaster with cell values indicating the first layer in the input that is TRUE
. All numbers that are not zero (or FALSE
), are considered to be TRUE
.
## S4 method for signature 'SpatRaster' which.lyr(x)
## S4 method for signature 'SpatRaster' which.lyr(x)
x |
SpatRaster |
SpatRaster
isTRUE
, which
, See Summary-methods
for which.min
and which.max
s <- rast(system.file("ex/logo.tif", package="terra")) x <- which.lyr(s > 100)
s <- rast(system.file("ex/logo.tif", package="terra")) x <- which.lyr(s > 100)
width
returns the minimum diameter of the geometry, defined as the smallest band that contains the geometry, where a band is a strip of the plane defined by two parallel lines. This can be thought of as the smallest hole that the geometry can be moved through, with a single rotation.
clearance
returns the minimum clearance of a geometry. The minimum clearance is the smallest amount by which a vertex could be moved to produce an invalid polygon, a non-simple linestring, or a multipoint with repeated points. If a geometry has a minimum clearance of 'mc', it can be said that:
No two distinct vertices in the geometry are separated by less than 'mc' No vertex is closer than 'mc' to a line segment of which it is not an endpoint. If the minimum clearance cannot be defined for a geometry (such as with a single point, or a multipoint whose points are identical, NA is returned.
## S4 method for signature 'SpatVector' width(x, as.lines=FALSE) ## S4 method for signature 'SpatVector' clearance(x, as.lines=FALSE)
## S4 method for signature 'SpatVector' width(x, as.lines=FALSE) ## S4 method for signature 'SpatVector' clearance(x, as.lines=FALSE)
x |
SpatVector of lines or polygons |
as.lines |
logical. If |
numeric or SpatVector
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) width(v) clearance(v)
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) width(v) clearance(v)
Assign a window (area of interest) to a SpatRaster with a SpatExtent
, or set it to NULL
to remove the window. This is similar to crop
without actually creating a new dataset.
The window is intersect with the extent of the SpatRaster. It is envisioned that in a future version, the window may also go outside these boundaries.
## S4 replacement method for signature 'SpatRaster' window(x)<-value ## S4 method for signature 'SpatRaster' window(x)
## S4 replacement method for signature 'SpatRaster' window(x)<-value ## S4 method for signature 'SpatRaster' window(x)
x |
SpatRaster |
value |
SpatExtent |
none for window<-
and logical for window
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) global(r, "mean", na.rm=TRUE) e <- ext(c(5.9, 6,49.95, 50)) window(r) <- e global(r, "mean", na.rm=TRUE) r x <- rast(f) xe <- crop(x, e) global(xe, "mean", na.rm=TRUE) b <- c(xe, r) window(b) b window(r) <- NULL r
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) global(r, "mean", na.rm=TRUE) e <- ext(c(5.9, 6,49.95, 50)) window(r) <- e global(r, "mean", na.rm=TRUE) r x <- rast(f) xe <- crop(x, e) global(xe, "mean", na.rm=TRUE) b <- c(xe, r) window(b) b window(r) <- NULL r
Use wrap
to pack a SpatVector or SpatRaster* to create a Packed* object. Packed objects can be passed over a connection that serializes (e.g. to nodes on a computer cluster). At the receiving end they need to be unpacked with unwrap
.
## S4 method for signature 'SpatRaster' wrap(x, proxy=FALSE) ## S4 method for signature 'SpatRasterDataset' wrap(x, proxy=FALSE) ## S4 method for signature 'SpatRasterCollection' wrap(x, proxy=FALSE) ## S4 method for signature 'SpatVector' wrap(x) ## S4 method for signature 'ANY' unwrap(x)
## S4 method for signature 'SpatRaster' wrap(x, proxy=FALSE) ## S4 method for signature 'SpatRasterDataset' wrap(x, proxy=FALSE) ## S4 method for signature 'SpatRasterCollection' wrap(x, proxy=FALSE) ## S4 method for signature 'SpatVector' wrap(x) ## S4 method for signature 'ANY' unwrap(x)
x |
SpatVector, SpatRaster, SpatRasterDataset or SpatRasterCollection |
proxy |
logical. If |
wrap
: Packed* object
unwrap
: SpatVector, SpatRaster, SpatRasterCollection, SpatRasterDataset
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) p <- wrap(v) p vv <- vect(p) vv
f <- system.file("ex/lux.shp", package="terra") v <- vect(f) p <- wrap(v) p vv <- vect(p) vv
Use wrap
to pack a SpatRaster with caching options. See wrap
for the general approach that is easier and better to use in most cases.
This method allows for specifying a folder, or filenames, to cache all sources of a SpatRaster in a specific location (on disk).
## S4 method for signature 'SpatRaster' wrapCache(x, filename=NULL, path=NULL, overwrite=FALSE, ...)
## S4 method for signature 'SpatRaster' wrapCache(x, filename=NULL, path=NULL, overwrite=FALSE, ...)
x |
SpatRaster |
filename |
character. A single filename, or one filename per SpatRaster data source. If not |
path |
character. If not |
overwrite |
Should existing files be overwritten when |
... |
Additional arguments for |
PackedSpatRaster
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- wrapCache(r, path=tempdir()) x
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) x <- wrapCache(r, path=tempdir()) x
Write a SpatRaster or SpatRasterDataset to a NetCDF file.
When using a SpatRasterDataset, the varname, longname, and unit should be set in the object (see examples).
Always use the ".nc"
or ".cdf"
file extension to assure that the file can be properly read again by GDAL
## S4 method for signature 'SpatRaster' writeCDF(x, filename, varname, longname="", unit="", split=FALSE, ...) ## S4 method for signature 'SpatRasterDataset' writeCDF(x, filename, overwrite=FALSE, zname="time", atts="", gridmap="", prec="float", compression=NA, missval, ...)
## S4 method for signature 'SpatRaster' writeCDF(x, filename, varname, longname="", unit="", split=FALSE, ...) ## S4 method for signature 'SpatRasterDataset' writeCDF(x, filename, overwrite=FALSE, zname="time", atts="", gridmap="", prec="float", compression=NA, missval, ...)
x |
SpatRaster or SpatRasterDataset |
filename |
character. Output filename |
varname |
character. Name of the dataset |
longname |
character. Long name of the dataset |
unit |
character. Unit of the data |
split |
logical. If |
atts |
character. A vector of additional global attributes to write. The must be formatted like c("x=a value", "y=abc") |
gridmap |
character. The crs is always writting to the file in standard formats. With this argument you can also write the format commonly used in netcdf files. Something like |
overwrite |
logical. If |
zname |
character. The name of the "time" dimension |
prec |
character. One of "double", "float", "integer", "short", "byte" or "char" |
compression |
Can be set to an integer between 1 (least compression) and 9 (most compression) |
missval |
numeric, the number used to indicate missing values |
... |
additional arguments passed on to the SpatRasterDataset method, and from there possibly to |
SpatRaster or SpatDataSet
see writeRaster
for writing other file formats
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) fname <- paste0(tempfile(), ".nc") rr <- writeCDF(r, fname, overwrite=TRUE, varname="alt", longname="elevation in m above sea level", unit="m") a <- rast(ncols=5, nrows=5, nl=50) values(a) <- 1:prod(dim(a)) time(a) <- as.Date("2020-12-31") + 1:nlyr(a) aa <- writeCDF(a, fname, overwrite=TRUE, varname="power", longname="my nice data", unit="U/Pa") b <- sqrt(a) s <- sds(a, b) names(s) <- c("temp", "prec") longnames(s) <- c("temperature (C)", "precipitation (mm)") units(s) <- c("°C", "mm") ss <- writeCDF(s, fname, overwrite=TRUE) # for CRAN file.remove(fname)
f <- system.file("ex/elev.tif", package="terra") r <- rast(f) fname <- paste0(tempfile(), ".nc") rr <- writeCDF(r, fname, overwrite=TRUE, varname="alt", longname="elevation in m above sea level", unit="m") a <- rast(ncols=5, nrows=5, nl=50) values(a) <- 1:prod(dim(a)) time(a) <- as.Date("2020-12-31") + 1:nlyr(a) aa <- writeCDF(a, fname, overwrite=TRUE, varname="power", longname="my nice data", unit="U/Pa") b <- sqrt(a) s <- sds(a, b) names(s) <- c("temp", "prec") longnames(s) <- c("temperature (C)", "precipitation (mm)") units(s) <- c("°C", "mm") ss <- writeCDF(s, fname, overwrite=TRUE) # for CRAN file.remove(fname)
Write a SpatRaster to a file.
## S4 method for signature 'SpatRaster,character' writeRaster(x, filename, overwrite=FALSE, ...)
## S4 method for signature 'SpatRaster,character' writeRaster(x, filename, overwrite=FALSE, ...)
x |
SpatRaster |
filename |
character. Output filename. Can be a single filename, or as many filenames as |
overwrite |
logical. If |
... |
additional arguments for for writing files. See Details |
In writeRaster, and in other methods that generate SpatRasters, options for writing raster files to disk can be provided as additional arguments or, in a few cases, as the wopt
argument (a named list) if the additional arguments are already used for a different purpose. See terraOptions
to get or set default values. The following options are available:
name | description |
datatype
|
values accepted are "INT1U", "INT2U", "INT2S", "INT4U", "INT4S", "FLT4S", "FLT8S". With GDAL >= 3.5 you can also use "INT8U" and "INT8S". And with GDAL >= 3.7 you can use also use "INT1S". See gdal to discover the GDAL version you are using.
The first three letters indicate whether the datatype is an integer (whole numbers) of a real number ("float", decimal numbers), the fourth character indicates the number of bytes used for each number. Higher values allow for storing larger numbers and/or more precision; but create larger files. The "S" or "U" indicate whether the values are signed (both negative and positive) or unsigned (zero and positive values only). |
filetype
|
file format expresses as GDAL driver names. If this argument is not supplied, the driver is derived from the filename. You can use gdal(drivers=TRUE) to see what drivers are available in your installation |
gdal
|
GDAL driver specific datasource creation options. See the GDAL documentation. For example, with the GeoTiff file format you can use gdal=c("COMPRESS=DEFLATE", "TFW=YES") . |
tempdir
|
the path where temporary files are to be written to. |
progress
|
positive integer. If the number of chunks is larger, a progress bar is shown. |
memfrac
|
numeric between 0 and 0.9 (higher values give a warning). The fraction of available RAM that terra is allowed to use. |
memmax
|
memmax - the maximum amount of RAM (in GB) that terra can use when processing a raster dataset. Should be less than what is detected (see mem_info , and higher values are ignored. Set it to a negative number or NA to ignore this value). |
names
|
output layer names. |
NAflag
|
numeric. value to represent missing (NA or NaN ) values. See note |
scale
|
numeric. Cell values written to disk are divided by this value (default is 1). See scoff
|
offset
|
numeric. Value that is subtracted from the cell values written to disk (default is 0). See
scoff |
verbose
|
logical. If TRUE debugging information is printed |
steps
|
positive integers. In how many steps (chunks) do you want to process the data (for debugging) |
todisk
|
logical. If TRUE processing operates as if the dataset is very large and needs to be written to a temporary file (for debugging). |
SpatRaster. This function is used for the side-effect of writing values to a file.
GeoTiff files are, by default, written with LZW compression. If you do not want compression, use gdal="COMPRESS=NONE"
.
When writing integer values the lowest available value (given the datatype) is used to represent NA
for signed types, and the highest value is used for unsigned values. This can be a problem with byte data (between 0 and 255) as the value 255 is reserved for NA
. To keep the value 255, you need to set another value as NAflag
, or do not set a NAflag
(with NAflag=NA
)
see writeCDF
for writing NetCDF files.
r <- rast(nrows=5, ncols=5, vals=1:25) # create a temporary filename for the example f <- file.path(tempdir(), "test.tif") writeRaster(r, f, overwrite=TRUE) writeRaster(r, f, overwrite=TRUE, gdal=c("COMPRESS=NONE", "TFW=YES"), datatype='INT1U') ## Or with a wopt argument: writeRaster(r, f, overwrite=TRUE, wopt= list(gdal=c("COMPRESS=NONE"), datatype='INT1U')) ## remove the file unlink(f)
r <- rast(nrows=5, ncols=5, vals=1:25) # create a temporary filename for the example f <- file.path(tempdir(), "test.tif") writeRaster(r, f, overwrite=TRUE) writeRaster(r, f, overwrite=TRUE, gdal=c("COMPRESS=NONE", "TFW=YES"), datatype='INT1U') ## Or with a wopt argument: writeRaster(r, f, overwrite=TRUE, wopt= list(gdal=c("COMPRESS=NONE"), datatype='INT1U')) ## remove the file unlink(f)
Write a SpatVector to a file. You can choose one of many file formats.
## S4 method for signature 'SpatVector,character' writeVector(x, filename, filetype=NULL, layer=NULL, insert=FALSE, overwrite=FALSE, options="ENCODING=UTF-8")
## S4 method for signature 'SpatVector,character' writeVector(x, filename, filetype=NULL, layer=NULL, insert=FALSE, overwrite=FALSE, options="ENCODING=UTF-8")
x |
SpatVector |
filename |
character. Output filename |
filetype |
character. A file format associated with a GDAL "driver" such as "ESRI Shapefile". See |
layer |
character. Output layer name. If |
insert |
logical. If |
overwrite |
logical. If |
options |
character. Format specific GDAL options such as "ENCODING=UTF-8". Use NULL or "" to not use any options |
v <- vect(cbind(1:5,1:5)) crs(v) <- "+proj=longlat +datum=WGS84" v$id <- 1:length(v) v$name <- letters[1:length(v)] tmpf1 <- paste0(tempfile(), ".gpkg") writeVector(v, tmpf1, overwrite=TRUE) x <- vect(tmpf1) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) tmpf2 <- paste0(tempfile(), ".gpkg") writeVector(v, tmpf2, overwrite=TRUE) y <- vect(tmpf2)
v <- vect(cbind(1:5,1:5)) crs(v) <- "+proj=longlat +datum=WGS84" v$id <- 1:length(v) v$name <- letters[1:length(v)] tmpf1 <- paste0(tempfile(), ".gpkg") writeVector(v, tmpf1, overwrite=TRUE) x <- vect(tmpf1) f <- system.file("ex/lux.shp", package="terra") v <- vect(f) tmpf2 <- paste0(tempfile(), ".gpkg") writeVector(v, tmpf2, overwrite=TRUE) y <- vect(tmpf2)
Apply a function to the values of each cell of two (multilayer) SpatRasters.
## S4 method for signature 'SpatRaster,SpatRaster' xapp(x, y, fun, ..., filename="", overwrite=FALSE, wopt=list())
## S4 method for signature 'SpatRaster,SpatRaster' xapp(x, y, fun, ..., filename="", overwrite=FALSE, wopt=list())
x |
SpatRaster |
y |
SpatRaster with the same geometry as |
fun |
a function that operates on two vectors |
... |
additional arguments for |
filename |
character. Output filename |
overwrite |
logical. If |
wopt |
list with named options for writing files as in |
SpatRaster
app
, lapp
, tapp
, Math-methods
, roll
r <- rast(ncols=10, nrows=10, nlyr=5) set.seed(1) r <- init(r, runif) s <- init(r, runif) x <- xapp(r, s, fun=cor)
r <- rast(ncols=10, nrows=10, nlyr=5) set.seed(1) r <- init(r, runif) s <- init(r, runif) x <- xapp(r, s, fun=cor)
Get or set single values of an extent. Values can be set for a SpatExtent or SpatRaster, but not for a SpatVector)
## S4 method for signature 'SpatExtent' xmin(x) ## S4 method for signature 'SpatExtent' xmax(x) ## S4 method for signature 'SpatExtent' ymin(x) ## S4 method for signature 'SpatExtent' ymax(x) ## S4 method for signature 'SpatRaster' xmin(x) ## S4 method for signature 'SpatRaster' xmax(x) ## S4 method for signature 'SpatRaster' ymin(x) ## S4 method for signature 'SpatRaster' ymax(x) ## S4 method for signature 'SpatVector' xmin(x) ## S4 method for signature 'SpatVector' xmax(x) ## S4 method for signature 'SpatVector' ymin(x) ## S4 method for signature 'SpatVector' ymax(x) ## S4 replacement method for signature 'SpatRaster,numeric' xmin(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' xmax(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' ymin(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' ymax(x)<-value
## S4 method for signature 'SpatExtent' xmin(x) ## S4 method for signature 'SpatExtent' xmax(x) ## S4 method for signature 'SpatExtent' ymin(x) ## S4 method for signature 'SpatExtent' ymax(x) ## S4 method for signature 'SpatRaster' xmin(x) ## S4 method for signature 'SpatRaster' xmax(x) ## S4 method for signature 'SpatRaster' ymin(x) ## S4 method for signature 'SpatRaster' ymax(x) ## S4 method for signature 'SpatVector' xmin(x) ## S4 method for signature 'SpatVector' xmax(x) ## S4 method for signature 'SpatVector' ymin(x) ## S4 method for signature 'SpatVector' ymax(x) ## S4 replacement method for signature 'SpatRaster,numeric' xmin(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' xmax(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' ymin(x)<-value ## S4 replacement method for signature 'SpatRaster,numeric' ymax(x)<-value
x |
SpatRaster, SpatExtent, or SpatVector |
value |
numeric |
SpatExtent or numeric coordinate
r <- rast() ext(r) ext(c(0, 20, 0, 20)) xmin(r) xmin(r) <- 0 xmin(r)
r <- rast() ext(r) ext(c(0, 20, 0, 20)) xmin(r) xmin(r) <- 0 xmin(r)
Get coordinates of the center of raster cells for a row, column, or cell number of a SpatRaster. Or get row, column, or cell numbers from coordinates or from each other.
Cell numbers start at 1 in the upper left corner, and increase from left to right, and then from top to bottom.
The last cell number equals the number of cells of the SpatRaster (see ncell
).
Row numbers start at 1 at the top, column numbers start at 1 at the left.
When computing row, column, or cell numbers from coordinates, and coordinates fall on the edge of two or four cells, they are assigned to the right-most and/or lowest cell. That is, in these cases of ambiguity, the highest row, column, or cell number is returned.
## S4 method for signature 'SpatRaster,numeric' xFromCol(object, col) ## S4 method for signature 'SpatRaster,numeric' yFromRow(object, row) ## S4 method for signature 'SpatRaster,numeric' xyFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' xFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' yFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' colFromX(object, x) ## S4 method for signature 'SpatRaster,numeric' rowFromY(object, y) ## S4 method for signature 'SpatRaster,numeric,numeric' cellFromRowCol(object, row, col) ## S4 method for signature 'SpatRaster,numeric,numeric' cellFromRowColCombine(object, row, col) ## S4 method for signature 'SpatRaster,numeric,numeric' rowColCombine(object, row, col) ## S4 method for signature 'SpatRaster,numeric' rowFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' colFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' rowColFromCell(object, cell) ## S4 method for signature 'SpatRaster,matrix' cellFromXY(object, xy)
## S4 method for signature 'SpatRaster,numeric' xFromCol(object, col) ## S4 method for signature 'SpatRaster,numeric' yFromRow(object, row) ## S4 method for signature 'SpatRaster,numeric' xyFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' xFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' yFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' colFromX(object, x) ## S4 method for signature 'SpatRaster,numeric' rowFromY(object, y) ## S4 method for signature 'SpatRaster,numeric,numeric' cellFromRowCol(object, row, col) ## S4 method for signature 'SpatRaster,numeric,numeric' cellFromRowColCombine(object, row, col) ## S4 method for signature 'SpatRaster,numeric,numeric' rowColCombine(object, row, col) ## S4 method for signature 'SpatRaster,numeric' rowFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' colFromCell(object, cell) ## S4 method for signature 'SpatRaster,numeric' rowColFromCell(object, cell) ## S4 method for signature 'SpatRaster,matrix' cellFromXY(object, xy)
object |
SpatRaster |
cell |
integer. cell number(s) |
col |
integer. column number(s) or missing (equivalent to all columns) |
row |
integer. row number(s) or missing (equivalent to all rows) |
x |
x coordinate(s) |
y |
y coordinate(s) |
xy |
matrix of x and y coordinates |
xFromCol, yFromCol, xFromCell, yFromCell: vector of x or y coordinates
xyFromCell: matrix(x,y) with coordinate pairs
colFromX, rowFromY, cellFromXY, cellFromRowCol, rowFromCell, colFromCell: vector of row, column, or cell numbers
rowColFromCell, rowColCombine: matrix of row and column numbers
r <- rast() xFromCol(r, c(1, 120, 180)) yFromRow(r, 90) xyFromCell(r, 10000) xyFromCell(r, c(0, 1, 32581, ncell(r), ncell(r)+1)) cellFromRowCol(r, 5, 5) cellFromRowCol(r, 1:2, 1:2) cellFromRowCol(r, 1, 1:3) # all combinations cellFromRowColCombine(r, 1:2, 1:2) colFromX(r, 10) rowFromY(r, 10) xy <- cbind(lon=c(10,5), lat=c(15, 88)) cellFromXY(r, xy) # if no row/col specified all are returned range(xFromCol(r)) length(yFromRow(r))
r <- rast() xFromCol(r, c(1, 120, 180)) yFromRow(r, 90) xyFromCell(r, 10000) xyFromCell(r, c(0, 1, 32581, ncell(r), ncell(r)+1)) cellFromRowCol(r, 5, 5) cellFromRowCol(r, 1:2, 1:2) cellFromRowCol(r, 1, 1:3) # all combinations cellFromRowColCombine(r, 1:2, 1:2) colFromX(r, 10) rowFromY(r, 10) xy <- cbind(lon=c(10,5), lat=c(15, 88)) cellFromXY(r, xy) # if no row/col specified all are returned range(xFromCol(r)) length(yFromRow(r))
Compute zonal statistics, that is summarize values of a SpatRaster for each "zone" defined by another SpatRaster, or by a SpatVector with polygon geometry.
If fun
is a true R function
, the <SpatRaster,SpatRaster> method may fail when using very large SpatRasters, except for the functions ("mean", "min", "max", "sum", "isNA", and "notNA").
You can also summarize values of a SpatVector for each polygon (zone) defined by another SpatVector.
## S4 method for signature 'SpatRaster,SpatRaster' zonal(x, z, fun="mean", ..., w=NULL, wide=TRUE, as.raster=FALSE, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRaster,SpatVector' zonal(x, z, fun="mean", na.rm=FALSE, w=NULL, weights=FALSE, exact=FALSE, touches=FALSE, small=TRUE, as.raster=FALSE, as.polygons=FALSE, wide=TRUE, filename="", wopt=list()) ## S4 method for signature 'SpatVector,SpatVector' zonal(x, z, fun=mean, ..., weighted=FALSE, as.polygons=FALSE)
## S4 method for signature 'SpatRaster,SpatRaster' zonal(x, z, fun="mean", ..., w=NULL, wide=TRUE, as.raster=FALSE, filename="", overwrite=FALSE, wopt=list()) ## S4 method for signature 'SpatRaster,SpatVector' zonal(x, z, fun="mean", na.rm=FALSE, w=NULL, weights=FALSE, exact=FALSE, touches=FALSE, small=TRUE, as.raster=FALSE, as.polygons=FALSE, wide=TRUE, filename="", wopt=list()) ## S4 method for signature 'SpatVector,SpatVector' zonal(x, z, fun=mean, ..., weighted=FALSE, as.polygons=FALSE)
x |
SpatRaster or SpatVector |
z |
SpatRaster with cell-values representing zones or a SpatVector with each polygon geometry representing a zone. |
fun |
function to be applied to summarize the values by zone. Either as character: "mean", "min", "max", "sum", "isNA", and "notNA" and, for relatively small SpatRasters, a proper function |
... |
additional arguments passed to fun, such as |
w |
SpatRaster with weights. Should have a single-layer with non-negative values |
wide |
logical. Should the values returned in a wide format? For the |
as.raster |
logical. If |
filename |
character. Output filename (ignored if |
overwrite |
logical. If |
wopt |
list with additional arguments for writing files as in |
weights |
logical. If |
exact |
logical. If |
touches |
logical. If |
small |
logical. If |
weighted |
logical. If |
as.polygons |
logical. Should the zonal statistics be combined with the geometry of |
na.rm |
logical. If |
A data.frame
with a value for each zone, or a SpatRaster, or SpatVector of polygons.
See global
for "global" statistics (i.e., all of x
is considered a single zone), app
for local statistics, and extract
for an alternative way to summarize values of a SpatRaster with a SpatVector. With aggregate
you can compute statistics for cell blocks defined by a number of rows and columns.
### SpatRaster, SpatRaster r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) z <- rast(r) values(z) <- rep(c(1:2, NA, 3:4), each=20) names(z) <- "zone" zonal(r, z, "sum", na.rm=TRUE) # with weights w <- init(r, "col") zonal(r, z, w=w, "mean", na.rm=TRUE) # multiple layers r <- rast(system.file("ex/logo.tif", package = "terra")) # zonal layer z <- rast(r, 1) names(z) <- "zone" values(z) <- rep(c(1:2, NA, c(3:4)), each=ncell(r)/5, length.out=ncell(r)) zonal(r, z, "mean", na.rm = TRUE) # raster of zonal values zr <- zonal(r, z, "mean", na.rm = TRUE, as.raster=TRUE) ### SpatRaster, SpatVector x <- rast(ncol=2,nrow=2, vals=1:4, xmin=0, xmax=1, ymin=0, ymax=1, crs="+proj=utm +zone=1") p <- as.polygons(x) pp <- shift(p, .2) r <- disagg(x, 4) zonal(r, p) zonal(r, p, sum) zonal(x, pp, exact=TRUE) zonal(c(x, x*10), pp, w=x) ### SpatVector, SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f)[,c(2,4)] p <- spatSample(v, 100) values(p) <- data.frame(b2=1:100, ssep1=100:1) zonal(p, v, mean)
### SpatRaster, SpatRaster r <- rast(ncols=10, nrows=10) values(r) <- 1:ncell(r) z <- rast(r) values(z) <- rep(c(1:2, NA, 3:4), each=20) names(z) <- "zone" zonal(r, z, "sum", na.rm=TRUE) # with weights w <- init(r, "col") zonal(r, z, w=w, "mean", na.rm=TRUE) # multiple layers r <- rast(system.file("ex/logo.tif", package = "terra")) # zonal layer z <- rast(r, 1) names(z) <- "zone" values(z) <- rep(c(1:2, NA, c(3:4)), each=ncell(r)/5, length.out=ncell(r)) zonal(r, z, "mean", na.rm = TRUE) # raster of zonal values zr <- zonal(r, z, "mean", na.rm = TRUE, as.raster=TRUE) ### SpatRaster, SpatVector x <- rast(ncol=2,nrow=2, vals=1:4, xmin=0, xmax=1, ymin=0, ymax=1, crs="+proj=utm +zone=1") p <- as.polygons(x) pp <- shift(p, .2) r <- disagg(x, 4) zonal(r, p) zonal(r, p, sum) zonal(x, pp, exact=TRUE) zonal(c(x, x*10), pp, w=x) ### SpatVector, SpatVector f <- system.file("ex/lux.shp", package="terra") v <- vect(f)[,c(2,4)] p <- spatSample(v, 100) values(p) <- data.frame(b2=1:100, ssep1=100:1) zonal(p, v, mean)
Zoom in on a map (plot) by providing a new extent, by default this is done by clicking twice on the map.
## S4 method for signature 'SpatRaster' zoom(x, e=draw(), maxcell=100000, layer=1, new=FALSE, ...) ## S4 method for signature 'SpatVector' zoom(x, e=draw(), new=FALSE, ...)
## S4 method for signature 'SpatRaster' zoom(x, e=draw(), maxcell=100000, layer=1, new=FALSE, ...) ## S4 method for signature 'SpatVector' zoom(x, e=draw(), new=FALSE, ...)
x |
SpatRaster |
e |
SpatExtent |
maxcell |
positive integer. Maximum number of cells used for the map |
layer |
positive integer to select the layer to be used |
new |
logical. If |
... |
additional arguments passed to |
SpatExtent (invisibly)