Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free
Documentation
R
terra

terra-package

The terra package

Description

terra provides methods to manipulate geographic (spatial) data in "raster" and "vector" form. Raster data divide space into rectangular cells (pixels) and they are commonly used to represent spatially continuous phenomena, such as elevation or the weather. Satellite images also have this data structure. 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 (R 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 vectors of SpatRaster or SpatVector.

These classes wrap a C++ pointer to the data, and almost all data manipulation is done in C++ (for speed). These objects cannot be directly saved to a ".Rds" file or used in cluster computing. They cannot be recovered from a saved R session either. See pack or writeRaster to work around that limitation.

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. Some of these may not have been implemented yet (they are not hyperlinked).

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

SpatRaster

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

I. Creating, combining and sub-setting SpatRaster objects

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 and/or resolution of a SpatRaster

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 Enlarge 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
disaggregate 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) computation

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 (==, !=, >, <, <=, >=)
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
Summary-methods mean, max, min, median, sum, range, prod,
any, all, stdev, which.min, which.max

Other methods

cellSize Compute the area of cells
classify (Re-)classify 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
subst Substitute (replace) cell values
which.lyr which is the first layer that is TRUE?
--------------------------- ------------------------------------------------------------------------------------------

IV. Zonal and global computation

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
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. Focal and other spatial contextual computation

focal Focal (neighborhood; moving window) functions
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
direction Direction (azimuth) to or from cells that are not NA
localFun Local association (using neighborhoods) functions
patches Find patches (clumps)
terrain Compute slope, aspect and other terrain characteristics from elevation data
autocor Compute global or local spatial autocorrelation
--------------------------- ------------------------------------------------------------------------------------------

VI. Model predictions

predict Predict a non-spatial model to a SpatRaster
interpolate Predict a spatial model to a SpatRaster
--------------------------- ------------------------------------------------------------------------------------------

VII. Accessing cell values

Ap art 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 (e.g., by cell, coordinates, polygon)
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 SpatRaster dimensions

Get or set basic parameters of SpatRasters. If there are values associated with a SpatRaster object (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
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. 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

blockSize Get suggested block size for reading and writing
writeStart Open a file for writing
writeValues Write some values
writeStop Close the file after writing
--------------------------- ------------------------------------------------------------------------------------------

XI. 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
canProcessInMemory Test whether a file can be created in memory
readStart Open file connections for efficient multi-chunck reading
readStop Close file connections
inMemory Are the cell values in memory?
fromDisk Are the cell values read from a file?

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

SpatRasterDataSet

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

XII. SpatRasterDataset

A SpatRasterDataset contains SpatRaster objects that are 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 SpatRaster objects
[ or $ Extract a SpatRaster
names Get the names of the sub-datasets

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

SpatVector

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

XIII. Create SpatVector objects

vect Create a SpatVector from a file (for example a "shapefile") or from another object
rbind append SpatVectors of the same geometry type
unique remove duplicates
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
delauny Delauny triangles
convHull Compute the convex hull of a SpatVector
fillHoles Remove or extract holes from polygons
--------------------------- ------------------------------------------------------------------------------------------

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

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

XVI. 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
disaggregate split multi-geometries into separate geometries
crop clip geometries using a rectangle (SpatExtent) or SpatVector
--------------------------- ------------------------------------------------------------------------------------------

XVII. 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
values Get the attributes of a SpatVector
values<- Set new attributes to the geometries of a SpatRaster
--------------------------- ------------------------------------------------------------------------------------------

XVIII. 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 vertially or horizontally
t transpose geometries (switch x and y)

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

Spat* Collections

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

XIX. Collections

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. A SpatVectorCollection is a vector of SpatVector objects.

svc create a SpatRasterCollection from a set of SpatRaster objects
length how many SpatRasters does the SpatRasterCollection have?
[ extract a SpatRastert

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

SpatExtent

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

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

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

General methods

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

XXI. Data type conversion

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
as.points Create points from a SpatRaster or SpatVector
as.lines Create points from a SpatRaster or SpatVector
as.polygons Create polygons from a SpatRaster
as.contour Contour lines from a SpatRaster
--------------------------- ------------------------------------------------------------------------------------------

XXII. Plotting

Maps

plot Plot a SpatRaster or SpatVector. The main method to create a map
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
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
RGB2col Combine three layers (red, green, blue channels) into a single layer with a color-table
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
inset Add a small inset (overview) map
sbar Add a scalebar

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

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

XXIII. 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 (combining Raster* objects or files) c
addLayer add<-
area cellSize
extent ext
calc app
overlay lapp
stackApply tapp
nlayers nlyr
NAvalue NAflag
stackSelect selectRange
reclassify, subs, cut classify
cellStats global
projectRaster project
dropLayer subset
isLonLat, isGlobalLonLat, couldBeLonLat is.lonlat
shapefile vect
gridDistance, distanceFromPoints distance
drawExtent, drawPoly, drawLine draw
compareRaster compareGeom
sampleRandom, sampleRegular spatSample
rasterToPoints as.points
rasterToPolygons as.polygons
cellFromLine, cellFromPolygon, cellsFromExtent cells
layerize segregate
clump patches

XXIV. 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). It other cases it simply seemed better. Here are some examples:

as.polygons By default, terra returns dissolved polygons
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)

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

Author

Except where indicated otherwise, the methods and functions in this package were written by Robert Hijmans. The configuration scripts were written by Roger Bivand for rgdal and sf. Some of the C++ code for GDAL/GEOS was adapted from code by Edzer Pebesma for sf. The progress bar code is by Karl Forner (RcppProgress). Jeroen Ooms provided the compiled GDAL and GEOS libraries for installation on windows

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 filing bug reports. The feedback and suggestions by Kendon Bell, Jean-Luc Dupouey, Gerald Nelson, and Michael Sumner have been especially helpful.

terra

Spatial Data Analysis

v1.2-10
GPL (>= 3)
Authors
Robert J. Hijmans [cre, aut] (<https://orcid.org/0000-0001-5872-2872>), Roger Bivand [ctb] (<https://orcid.org/0000-0003-2392-6140>), Karl Forner [ctb], Jeroen Ooms [ctb] (<https://orcid.org/0000-0002-4035-0289>), Edzer Pebesma [ctb] (<https://orcid.org/0000-0001-8049-7069>)
Initial release
2021-05-12

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.