Package 'terra'

Description of the methods in the terra package

Description

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.

———————————————————————————————————————

SpatRaster

———————————————————————————————————————

I. Creating, combining and sub-setting

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
---------------------------	------------------------------------------------------------------------------------------

II. Changing the spatial extent or resolution

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
---------------------------	------------------------------------------------------------------------------------------

III. Local (cell based) methods

Apply-like methods

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
---------------------------	------------------------------------------------------------------------------------------

Arithmetic, logical, and standard math methods

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
---------------------------	------------------------------------------------------------------------------------------

Other methods

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
---------------------------	------------------------------------------------------------------------------------------

IV. Zonal and global methods

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
---------------------------	------------------------------------------------------------------------------------------

V. Situation (spatial context) based methods

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
---------------------------	------------------------------------------------------------------------------------------

VI. Model predictions

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
---------------------------	------------------------------------------------------------------------------------------

VII. Accessing cell values

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
---------------------------	------------------------------------------------------------------------------------------

VIII. Getting and setting dimensions

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

IX. Computing row, column, cell numbers and coordinates

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
---------------------------	------------------------------------------------------------------------------------------

X. Time related methods

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
---------------------------	------------------------------------------------------------------------------------------

XI. Methods for categorical rasters

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
---------------------------	------------------------------------------------------------------------------------------

XII. Writing SpatRaster files

Basic

writeRaster	Write all values of SpatRaster to disk. You can set the filetype, datatype, compression.
writeCDF	Write SpatRaster data to a netCDF file
---------------------------	------------------------------------------------------------------------------------------

Advanced

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

XIII. Miscellaneous SpatRaster methods

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?
---------------------------	------------------------------------------------------------------------------------------

XIV. SpatRasterDataset

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
---------------------------	------------------------------------------------------------------------------------------

XV. SpatRasterCollections

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
---------------------------	------------------------------------------------------------------------------------------

SpatVector

———————————————————————————————————————

XVI. Create SpatVector objects

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
---------------------------	------------------------------------------------------------------------------------------

XVII. Properties of SpatVector objects

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
---------------------------	------------------------------------------------------------------------------------------

XVIII. Geometric queries

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
---------------------------	------------------------------------------------------------------------------------------

XIX. Geometric operations

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
---------------------------	------------------------------------------------------------------------------------------

XX. SpatVector attributes

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
---------------------------	------------------------------------------------------------------------------------------

XXI. Change geometries (for display, experimentation)

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

XXII. Geometry properties and topology

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
---------------------------	------------------------------------------------------------------------------------------

XXIII. SpatVectorCollections

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
---------------------------	------------------------------------------------------------------------------------------

Other classes

———————————————————————————————————————

XXIV. SpatExtent

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

XXV. SpatGraticule

graticule	Create a graticule
crop	crop a graticule
plot<SpatGraticule>	plot a graticule
---------------------------	------------------------------------------------------------------------------------------

General methods

———————————————————————————————————————

XXVI. Conversion between spatial data objects from different packages

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
---------------------------	------------------------------------------------------------------------------------------

XXVII. Plotting

Maps

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
---------------------------	------------------------------------------------------------------------------------------

Interacting with a map

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
---------------------------	------------------------------------------------------------------------------------------

Other plots

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
---------------------------	------------------------------------------------------------------------------------------

Comparison with the raster package

———————————————————————————————————————

XXVIII. New method names

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

XXIX. Changed behavior

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

Authors

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.

Acknowledgments

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.

---

Active category

Description

Get or set the active category of a multi-categorical SpatRaster layer

Usage

## S4 method for signature 'SpatRaster'
activeCat(x, layer=1)
## S4 replacement method for signature 'SpatRaster'
activeCat(x, layer=1)<-value

Arguments

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

Value

integer

See Also

levels, cats

Examples

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 or to a SpatRasterDataset or SpatRasterCollection

Description

Add (in place) a SpatRaster to another SpatRaster. Comparable with c, but without copying the object.

Usage

## 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

Arguments

x	SpatRaster, SpatRasterDataset or SpatRasterCollection
value	SpatRaster

Value

SpatRaster

See Also

c

Examples

r <- rast(nrows=5, ncols=9, vals=1:45)
x <- c(r, r*2)
add(x) <- r*3
x

---

draw a box

Description

Similar to box allowing adding a box around a map. This function will place the box around the mapped area.

Usage

add_box(...)

Arguments

...	arguments passed to lines

See Also

add_legend, add_grid, add_mtext

Examples

v <- vect(system.file("ex/lux.shp", package="terra"))
plot(v)
add_box(col="red", lwd=3, xpd=TRUE)

---

add a grid to a map made with terra

Description

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

Usage

add_grid(nx=NULL, ny=nx, col="lightgray", lty="dotted", lwd=1)

Arguments

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

See Also

graticule, add_legend, add_box, add_grid, add_mtext

Examples

v <- vect(system.file("ex/lux.shp", package="terra"))
plot(v)
add_grid()

---

add a custom legend

Description

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.

Usage

add_legend(x, y, ...)

Arguments

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 legend

See Also

add_box, add_grid, add_mtext

Examples

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")

---

draw a box

Description

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.

Usage

add_mtext(text, side=3, line=0, ...)

Arguments

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 text

See Also

add_legend, add_grid, add_box

Examples

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)

---

Adjacent cells

Description

Identify cells that are adjacent to a set of raster cells. Or identify adjacent polygons

Usage

## 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)

Arguments

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 directions is a matrix it should have odd dimensions and have logical (or 0, 1) values
pairs	logical. If TRUE, a two-column matrix of pairs of adjacent cells is returned. If x is a SpatRaster and pairs is FALSE, an n*m matrix is returned where the number of rows n is length(cells) and the number of columns m is the number of neighbors requested with directions
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 TRUE and pairs=TRUE, an adjacent pair is only included once. For example, if polygon 1 is adjacent to polygon 3, the implied adjacency between 3 and 1 is not reported

Value

matrix

Note

When using global lon/lat rasters, adjacent cells at the other side of the date-line are included.

See Also

relate, nearby

Examples

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 raster or vector data

Description

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.

Usage

## 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, ...)

Arguments

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 fun, such as na.rm=TRUE
cores	positive integer. If cores > 1, a 'parallel' package cluster with that many cores is created. Ignored for C++ level implemented functions that are listed under fun
filename	character. Output filename
overwrite	logical. If TRUE, filename is overwritten
wopt	list with named options for writing files as in writeRaster
by	character. The variable(s) used to group the geometries
dissolve	logical. Should borders between aggregated geometries be dissolved?
count	logical. If TRUE and by is not NULL, a variable "agg_n" is included that shows the number of input geometries for each output geometry

Details

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

Value

SpatRaster

See Also

disagg to disaggregate

Examples

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 a SpatExtent

Description

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.

Usage

## S4 method for signature 'SpatExtent,SpatRaster'
align(x, y, snap="near")

## S4 method for signature 'SpatExtent,numeric'
align(x, y)

Arguments

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

Value

SpatExtent

See Also

ext, draw

Examples

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 equality

Description

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.

Usage

## S4 method for signature 'SpatRaster,SpatRaster'
all.equal(target, current, maxcell=100000, ...)

Arguments

target	SpatRaster
current	SpatRaster
maxcell	positive integer. The size of the regular sample used to compare cell values
...	additional arguments passed to all.equal.numeric to compare cell values

Value

Either TRUE or a character vector describing the differences between target and current.

See Also

identical, compareGeom

Examples

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 a SpatRaster

Description

Animate (sequentially plot) the layers of a SpatRaster to create a movie.

This does not work with R-Studio.

Usage

## S4 method for signature 'SpatRaster'
animate(x, pause=0.25, main, range, maxcell=50000, n=1, ...)

Arguments

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 maxcell < ncell(x), spatSample(type="regular") is used before plotting
n	integer > 0. Number of loops
...	Additional arguments passed to plot

Value

None

See Also

plot

Examples

s <- rast(system.file("ex/logo.tif", package="terra"))   
animate(s, n=1)

---

Apply a function to the cells of a SpatRaster

Description

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.

Usage

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

Arguments

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 fun=function(i) min(i) or the equivalent fun = \(i) min(i)
...	additional arguments for fun. These are typically numerical constants. They should *never* be another SpatRaster
cores	positive integer. If cores > 1, a 'parallel' package cluster with that many cores is created and used. You can also supply a cluster object. Ignored for functions that are implemented by terra in C++ (see under fun)
filename	character. Output filename
overwrite	logical. If TRUE, filename is overwritten
wopt	list with named options for writing files as in writeRaster

Details

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

Value

SpatRaster

See Also

lapp, tapp, Math-methods, roll

Examples

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)

---

Estimate values for cell values that are NA by interpolating between layers

Description

approximate 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

Usage

## S4 method for signature 'SpatRaster'
approximate(x, method="linear", yleft, yright,
            rule=1, f=0, ties=mean, z=NULL, NArule=1,filename="",  ...)

Arguments

x	SpatRaster
method	specifies the interpolation method to be used. Choices are "linear" or "constant" (step function; see the example in approx
yleft	the value to be returned before a non-NA value is encountered. The default is defined by the value of rule given below
yright	the value to be returned after the last non-NA value is encountered. The default is defined by the value of rule given below
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-NA values are encountered). If rule is 1 then NAs are returned for such points and if it is 2, the value at the closest data extreme is used. Use, e.g., rule = 2:1, if the left and right side extrapolation should differ
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 y0*(1-f)+y1*f so that f = 0) is right-continuous and f = 1 is left-continuous
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 time(x) if these are not NA or else 1:nlys(x)
NArule	single integer used to determine what to do when only a single layer with a non-NA value is encountered (and linear interpolation is not possible). The default value of 1 indicates that all layers will get this value for that cell; all other values do not change the cell values
filename	character. Output filename
...	additional arguments for writing files as in writeRaster

Value

SpatRaster

See Also

focal, fillTime

Examples

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

---

Arithmetic

Description

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): +, -, *, /, %%

Value

SpatRaster or SpatExtent

See Also

ifel to conveniently combine operations and Math-methods or app to use mathematical functions not implemented by the package.

Examples

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

Description

Create a text representation of (the skeleton of) an object

Usage

## S4 method for signature 'SpatExtent'
as.character(x)

## S4 method for signature 'SpatRaster'
as.character(x)

Arguments

x	SpatRaster

Value

character

Examples

r <- rast()
ext(r)
ext(c(0, 20, 0, 20))

---

SpatRaster or SpatVector to data.frame

Description

Coerce a SpatRaster or SpatVector to a data.frame

Usage

## 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, ...)

Arguments

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 x has point geometry, it can also be "XY" to add the coordinates of each point
xy	logical. If TRUE, the coordinates of each raster cell are included
time	logical. If TRUE, the time data is included (if available)
na.rm	logical. If TRUE, cells that have a NA value in at least one layer are removed. If the argument is set to NA only cells that have NA values in all layers are removed
cells	logical. If TRUE, the cell numbers of each raster cell are included
wide	logical. If FALSE, the data.frame returned has a "long" format
...	Additional arguments passed to the data.frame
row.names	This argument is ignored
optional	This argument is ignored

Value

data.frame

See Also

as.list, as.matrix. See geom to only extract the geometry of a SpatVector

Examples

f <- system.file("ex/lux.shp", package="terra")
v <- vect(f)
as.data.frame(v)

---

Conversion to a SpatVector of lines

Description

Conversion of a SpatRaster, SpatVector or SpatExtent to a SpatVector of lines.

Usage

## 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 'matrix'
as.lines(x, crs="")

Arguments

x	SpatRaster, SpatVector, SpatExtent or matrix. If x is a matrix it should have two columns for a single line, or four columns, where each row has the start and end coordinates (x, y) for lines
crs	character. The coordinate reference system (see crs)

Value

SpatVector

See Also

as.points, as.polygons

Examples

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)
}


## with a matrix
s <- cbind(1:5, 1:5)
e <- cbind(1:5, 0)

as.lines(s)
as.lines(cbind(s, e), "+proj=longlat")

---

Coerce a Spat* object to a list

Description

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.

Usage

## 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, ...)

Arguments

x	SpatRaster, SpatRasterDataset, SpatRasterCollection, or SpatVector
geom	character or NULL. If not NULL, and x is a SpatVector, it should be either "WKT" or "HEX", to get the geometry included in Well-Known-Text or hexadecimal notation. If x has point geometry, it can also bey "XY" to add the coordinates of each point. If x is a SpatRaster, any value that is not NULL will return a list with the the parameters describing the geometry of the SpatRaster are returned
...	additional arguments. These are ignored

Value

list

See Also

see coerce for as.data.frame with a SpatRaster; and geom to only extract the geometry of a SpatVector

Examples

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 to a SpatVector of points

Description

Conversion of a SpatRaster, SpatVector or SpatExtent to a SpatVector of points.

Usage

## 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="")

Arguments

x	SpatRaster, SpatVector or SpatExtent
values	logical; include cell values as attributes?
multi	logical. If TRUE a multi-point geometry is returned
skiplast	logical. If TRUE the last point of a polygon (which is the same as the first point) is not included
na.rm	logical. If TRUE cells that are NA are ignored
na.all	logical. If TRUE cells are only ignored if na.rm=TRUE and their value is NA for all layers instead of for any layer
crs	character. The coordinate reference system (see crs)

Value

SpatVector

See Also

as.lines, as.points

Examples

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 to a SpatVector of polygons

Description

Conversion of a SpatRaster, SpatVector or SpatExtent to a SpatVector of polygons.

Usage

## 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="")

Arguments

x	SpatRaster, SpatVector or SpatExtent
round	logical; If TRUE and aggregate=TRUE, values are rounded before aggregation. If this value is FALSE the SpatVector returned can have very many polygons and can be very large
aggregate	logical; combine cells with the same values? If TRUE only the first layer in x is processed
values	logical; include cell values as attributes?
extent	logical. if TRUE, a polygon for the extent of the SpatRaster or SpatVector is returned. If x is a SpatRaster, the polygon has vertices for each row and column, not just the four corners of the raster. This can be useful for more precise projection. If that is not required, it is more efficient to get the extent represented by only the four corners with as.polygons(ext(x), crs=crs(x))
na.rm	logical. If TRUE cells that are NA are ignored
na.all	logical. If TRUE cells are only ignored if na.rm=TRUE and their value is NA for all layers instead of for any layer
digits	integer. The number of digits for rounding (if round=TRUE)
crs	character. The coordinate reference system (see crs)
...	additional arguments. For backward compatibility. Will be removed in the future

Value

SpatVector

See Also

as.lines, as.points

Examples

r <- rast(ncols=2, nrows=2)
values(r) <- 1:ncell(r)

if  (gdal() >= "3.0.0") {
	p <- as.polygons(r)
	p
}

---

Coerce to a "raster" object

Description

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!

Usage

## S4 method for signature 'SpatRaster'
as.raster(x, maxcell=500000, col)

Arguments

x	SpatRaster
maxcell	positive integer. Maximum number of cells to use for the plot
col	vector of colors. The default is map.pal("viridis", 100)

Value

'raster' object

Examples

r <- rast(ncols=3, nrows=3)
values(r) <- 1:ncell(r)
as.raster(r)

---

Two argument arc-tangent

Description

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.

Usage

## S4 method for signature 'SpatRaster,SpatRaster'
atan2(y, x)

## S4 method for signature 'SpatRaster,SpatRaster'
atan_2(y, x, filename, ...)

Arguments

y	SpatRaster
x	SpatRaster
filename	character. Output filename
...	additional arguments for writing files as in writeRaster

See Also

Math-methods

Examples

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)

---

Spatial autocorrelation

Description

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

Usage

## 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)

Arguments

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 TRUE global autocorrelation is computed instead of local autocorrelation
method	character. If x is numeric or SpatRaster: "moran" for Moran's I and "geary" for Geary's C. If x is numeric also: "Gi", "Gi*" (the Getis-Ord statistics), locmor (local Moran's I) and "mean" (local mean)

Details

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.

Value

numeric or SpatRaster

References

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

See Also

The spdep package for additional and more general approaches for computing spatial autocorrelation

Examples

### 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")

---

Bar plot of a SpatRaster

Description

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.

Usage

## S4 method for signature 'SpatRaster'
barplot(height, maxcell=1000000, digits=0, breaks=NULL, col, ...)

Arguments

height	SpatRaster
maxcell	integer. To regularly subsample very large datasets
digits	integer used to determine how to round the values before tabulating. Set to NULL or to a large number if you do not want any rounding
breaks	breaks used to group the data as in cut
col	a color generating function such as rainbow (the default), or a vector of colors
...	additional arguments for plotting as in barplot

Value

A numeric vector (or matrix, when beside = TRUE) of the coordinates of the bar midpoints, useful for adding to the graph. See barplot

See Also

hist, boxplot

Examples

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)

---

bestMatch

Description

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.

Usage

## S4 method for signature 'SpatRaster,SpatVector'
bestMatch(x, y, labels="", filename="", ...)

## S4 method for signature 'SpatRaster,data.frame'
bestMatch(x, y, labels="", filename="", ...)

Arguments

x	SpatRaster
y	SpatVector or data.frame
labels	character. labels that correspond to each class (row in y
filename	character. Output filename
...	additional arguments for writing files as in writeRaster

Value

SpatRaster

Examples

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)

Description

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.

Usage

## S4 method for signature 'SpatRaster'
boundaries(x, classes=FALSE, inner=TRUE, 
         directions=8, falseval=0, filename="", ...)

Arguments

x	SpatRaster
inner	logical. If TRUE, "inner" boundaries are returned, else "outer" boundaries are returned
classes	character. Logical. If TRUE all different values are (after rounding) distinguished, as well as NA. If FALSE (the default) only edges between NA and non-NA cells are considered
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 NA
filename	character. Output filename
...	options for writing files as in writeRaster

Value

SpatRaster. Cell values are either 1 (a border) or 0 (not a border), or NA

See Also

focal, patches

Examples

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 SpatRaster data

Description

Box plot of layers in a SpatRaster

Usage

## S4 method for signature 'SpatRaster'
boxplot(x, y=NULL, maxcell=100000, ...)

Arguments

x	SpatRaster
y	NULL or a SpatRaster. If x is a SpatRaster it used to group the values of x by "zone"
maxcell	Integer. Number of cells to sample from datasets
...	additional arguments passed to graphics::boxplot

Value

boxplot returns a list (invisibly) that can be used with bxp

See Also

pairs, hist

Examples

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)

---

Create a buffer around vector geometries or raster patches

Description

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.

Usage

## 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)

Arguments

x	SpatRaster or SpatVector
width	numeric. Unit is meter if x has a longitude/latitude CRS, or in the units of the coordinate reference system in other cases (typically also meter). The value should be > 0 if x is a SpatRaster. If x is a SpatVector, this argument is vectorized, meaning that you can provide a different value for each geometry in x; and you can also use the name of a variable in x that has the widths
filename	character. Output filename
...	additional arguments for writing files as in writeRaster
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 is.lonlat(x)
joinstyle	character. One of "round", "mitre" or "bevel". Ignored if is.lonlat(x)
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 is.lonlat(x)
singlesided	logical. If TRUE a buffer is constructed on only one side of each input line. Ignored if is.lonlat(x)

Value

Same as x

See Also

distance, elongate

Examples

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)

---

Combine SpatRaster or SpatVector objects

Description

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.

Usage

## 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, ...)

Arguments

x	SpatRaster, SpatVector, SpatRasterDataset or SpatVectorCollection
warn	logical. If TRUE, a warning is emitted if x is an empty SpatRaster
...	as for x (you can only combine raster with raster data and vector with vector data)

Value

Same class as x

See Also

add<-

Examples

r <- rast(nrows=5, ncols=9)
values(r) <- 1:ncell(r)
x <- c(r, r*2, r*3)

---

Cartogram

Description

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

Usage

## S4 method for signature 'SpatVector'
cartogram(x, var, type)

Arguments

x	SpatVector
var	character. A variable name in x
type	character. Cartogram type, only "nc" (non-contiguous) is currently supported

Value

SpatVector

See Also

plot, rescale

Examples

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)

---

Factors to numeric

Description

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.

Usage

## S4 method for signature 'SpatRaster'
as.numeric(x, index=NULL, filename="", ...)

## S4 method for signature 'SpatRaster'
catalyze(x, filename="", ...)

Arguments

x	SpatRaster
index	positive integer or category indicating the category to use. If NULL the active category is used
filename	character. Output filename
...	additional arguments for writing files as in writeRaster

Value

SpatRaster

See Also

activeCat, cats

Examples

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 cell numbers

Description

Get the cell numbers covered by a SpatVector or SpatExtent. Or that match values in a vector; or all non NA values.

Usage

## 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)

Arguments

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 TRUE and y has polygons, the approximate fraction of each cell that is covered is returned as well
pairs	logical. If TRUE the cell values matched area also returned
exact	logical. If TRUE and y has polygons, the exact fraction of each cell that is covered is returned as well
touches	logical. If TRUE, values for all cells touched by lines or polygons are extracted, not just those on the line render path, or whose center point is within the polygon. Not relevant for points
small	logical. If TRUE, values for all cells in touched polygons are extracted if none of the cells center points is within the polygon; even if touches=FALSE

Value

numeric vector or matrix

Examples

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)

---

Area covered by each raster cell

Description

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

Usage

## S4 method for signature 'SpatRaster'
cellSize(x, mask=FALSE, lyrs=FALSE, unit="m", transform=TRUE, rcx=100, filename="", ...)

Arguments

x	SpatRaster
mask	logical. If TRUE, cells that are NA in x are also NA in the output
lyrs	logical. If TRUE and mask=TRUE, the output has the same number of layers as x. That is only useful if cases where the layers of x have different cells that are NA
unit	character. One of "m", "km", or "ha"
transform	logical. If TRUE, planar CRS data are transformed to lon/lat for accuracy
rcx	positive integer. The maximum number of rows and columns to be used to compute area of planar data if transform=TRUE. If x has more rows and/or columns, the raster is aggregated to match this limit, and values for the original cells are estimated by bilinear interpolation (see resample). This can save a lot of time
filename	character. Output filename
...	additional arguments for writing files as in writeRaster

Value

SpatRaster

See Also

expanse

Examples

# 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))

---

Centroids

Description

Get the centroids of polygons or lines, or centroid-like points that are guaranteed to be inside the polygons or on the lines.

Usage

## S4 method for signature 'SpatVector'
centroids(x, inside=FALSE)

Arguments

x	SpatVector
inside	logical. If TRUE the points returned are guaranteed to be inside the polygons or on the lines, but they are not the true centroids. True centroids may be outside a polygon, for example when a polygon is "bean shaped", and they are unlikely to be on their line

Value

SpatVector of points

Examples

f <- system.file("ex/lux.shp", package="terra")
v <- vect(f)
x <- centroids(v)
y <- centroids(v, TRUE)

---

Clamp values

Description

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

Usage

## 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, ...)

Arguments

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 x
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 x
values	logical. If FALSE values outside the clamping range become NA, if TRUE, they get the extreme values
filename	character. Output filename
...	additional arguments for writing files as in writeRaster

Value

SpatRaster

See Also

classify

Examples

r <- rast(ncols=10, nrows=10)
values(r) <- 1:ncell(r)
rc <- clamp(r, 25, 75) 
rc

---

clamp time series data

Description

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.

Usage

## S4 method for signature 'SpatRaster'
clamp_ts(x, min=FALSE, max=TRUE, filename="", ...)

Arguments

x	SpatRaster
min	logical. If TRUE the time-series is clamped to the minimum value
max	logical. If TRUE the time-series is clamped to the maximum value
filename	character. Output filename
...	additional arguments for writing files as in writeRaster

Value

SpatRaster

See Also

clamp, cummin, cummax

Examples

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 (or reclassify) cell values

Description

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.

Usage

## S4 method for signature 'SpatRaster'
classify(x, rcl, include.lowest=FALSE, right=TRUE, 
     others=NULL, brackets=TRUE, filename="", ...)

Arguments

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 right and include.lowest are ignored. 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 rcl (or highest value in the second column, for right=FALSE) should be included.
right	logical. If TRUE, the intervals are closed on the right (and open on the left). If FALSE they are open at the right and closed at the left. "open" means that the extreme value is *not* included in the interval. Thus, right-closed and left open is (0,1] = {x | 0 < x <= 1}. You can also close both sides with right=NA, that is only meaningful if you "from-to-becomes" classification with integers. For example to classify 1-5 -> 1, 6-10 -> 2, 11-15 -> 3. That may be easier to read and write than the equivalent 1-5 -> 1, 5-10 -> 2, 10-15 -> 3 with right=TRUE and include.lowest=TRUE
others	numeric. If not NULL all values that are not matched are set to this value. Otherwise they retain their original value.
brackets	logical. If TRUE, intervals are have parenthesis or brackets around them to indicate whether they are open or closed. Only applies if rcl is a vector (or single column matrix)
filename	character. Output filename
...	Additional arguments for writing files as in writeRaster

Value

SpatRaster

Note

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

See Also

subst for simpler from-to replacement

Examples

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)

---

Query by clicking on a map

Description

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.

Usage

## 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, ...)

Arguments

x	SpatRaster or SpatVector, or missing
n	number of clicks on the plot (map)
id	logical. If TRUE, a numeric ID is shown on the map that corresponds to the row number of the output
xy	logical. If TRUE, xy coordinates are included in the output
cell	logical. If TRUE, cell numbers are included in the output
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 locator
show	logical. Print the values after each click?
...	additional graphics parameters used if type != "n" for plotting the locations. See locator

Value

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

Note

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.

See Also

draw

Examples

## 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 to vector, matrix or array

Description

Coercion of a SpatRaster to a vector, matrix or array. Or coerce a SpatExtent to a vector or matrix

Usage

## 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, ...)

Arguments

x	SpatRaster or SpatVector
wide	logical. If FALSE each layer in the SpatRaster becomes a column in the matrix and each cell in the SpatRaster becomes a row. If TRUE each row in the SpatRaster becomes a row in the matrix and each column in the SpatRaster becomes a column in the matrix
mode	this argument is ignored
...	additional arguments (none implemented)

Value

vector, matrix, or array

See Also

as.data.frame and as.polygons

Examples

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

---