The 'terra' package implements two main classes for spatial data handling: 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.
'terra' provides methods to manipulate geographic (spatial) data in "raster" and "vector" data types. Raster data divides space into rectangular cells (pixels). Such data are also referred to as "grid" data are often used to represent spatially continuous phenomena, such as elevation or the weather. Satellite images also have this format. Raster data can be contrasted with discrete "vector" spatial data such as points, lines, polygons.
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'. A major simplification is that 'terra' has a single class "SpatRaster" for which 'raster' has three (RasterLayer, RasterStack, RasterBrick). Likewise there is a single class for vector data ("SpatVector"). Like "raster" this package should be particularly useful when using very large datasets that can not be loaded into the computer's memory. Functions will work correctly, because they they process large files in chunks, i.e., they read, compute, and write blocks of data, without loading all values into memory at once.
Furthermore, 'terra' has a "SpatDataSet" class that represents a collection of sub-datasets for the same area. Each subdataset is a SpatRaster with possibly many layers, and may, for example, represent different weather variables.
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 (for combining Raster* objects) |
c |
extent |
ext |
calc |
app |
overlay |
lapp |
stackApply |
tapp |
extend |
expand |
nlayers |
nlyr |
stackSelect |
selectRange |
reclassify, subs, cut |
classify |
cellStats |
global |
projectRaster |
project |
dropLayer |
subset |
isLonLat, isGlobalLonLat, couldBeLonLat |
isLonLat |
shapefile |
vect |
gridDistance, distanceFromPoints |
distance |
drawExtent, drawPoly, drawLine |
draw |
compareRaster |
compareGeom |
sampleRandom, sampleRegular |
spatSample |
rasterToPoints |
as.points |
rasterToPolygons |
as.polygons |
cellFromLine, cellFromPolygon, cellsFromExtent |
cells |
clump |
patches |
Also note that even if function names are the same in terra and raster, their output can be different. In most cases 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:
area |
By default, terra returns the summed area of the raster cells that are not NA. raster returns a RasterLayer. Use sum=FALSE in terra for that behavior |
| - | |
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. That is 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) |
Below is a list of some of the most important methods grouped by theme. Some of these may not have been implemented yet.
rast |
Create a SpatRaster from scratch, file, or another object |
| --------------------------- | ------------------------------------------------------------------------------------------ |
c |
Combine SpatRasters (multiple layers) (like raster::stack) |
subset or [[, or $ |
Select layers of a SpatRaster |
selectRange |
Select cell values from different layers using an index layer |
| --------------------------- | ------------------------------------------------------------------------------------------ |
Also see the methods in section XI
merge |
Combine SpatRasters with different extents (but same origin and resolution) |
mosaic |
Combine SpatRasters with different extents and a function for the values in overlapping areas |
crop |
Select a geographic subset of a SpatRaster |
expand |
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 |
| --------------------------- | ------------------------------------------------------------------------------------------ |
Arith-methods |
Arith functions (+, -, *, ^, %%, %/%, /) |
Math-methods |
Math functions like abs, sqrt, trunc, log, log10, exp, sin, round |
Logic-methods |
Logic functions (!, &, |) |
Summary-methods |
Summary functions (mean, max, min, median, sum, range, prod, any, all, stdev, which.min, which.max) |
Compare-methods |
Compare functions (==, !=, >, <, <=, >=) |
app |
Apply a function to cells of all layers(as in base::apply) |
tapp |
Apply a function to groups of layers (as in base::tapply) |
lapp |
Apply a function using the layers as variables |
rapp |
Apply a function to a spatially variable range of layers |
cover |
First layer covers second layer except where the first layer is NA |
mask |
Use values from first SpatRaster except where cells of the mask SpatRaster are NA (or another value of choice) |
classify |
(Re-)classify values |
init |
Initialize cells with new values |
area |
Compute the area of cells |
| --------------------------- | ------------------------------------------------------------------------------------------ |
zonal |
Summarize a SpatRaster by zones in another SpatRaster |
global |
Summarize SpatRaster cell values with a function |
unique |
Get the unique values in a SpatRaster |
freq |
Frequency table of SpatRaster cell values |
crosstab |
Cross-tabulate two SpatRasters |
quantile |
Quantiles |
summary |
Summary of the values of a SpatRaster (quartiles and mean) |
area |
Compute the total area covered by cells |
stretch |
Stretch values |
| --------------------------- | ------------------------------------------------------------------------------------------ |
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 |
terrain |
Compute slope, aspect and other terrain characteristics from elevation data |
autocor |
Compute global or local Moran or Geary indices of spatial autocorrelation |
| --------------------------- | ------------------------------------------------------------------------------------------ |
predict |
Predict a non-spatial model to a SpatRaster |
interpolate |
Predict a spatial model to a SpatRaster |
| --------------------------- | ------------------------------------------------------------------------------------------ |
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 |
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 |
| --------------------------- | ------------------------------------------------------------------------------------------ |
Apart from the function listed below, you can also use indexing with [ with cell numbers, and row and/or column numbers
values |
Get or set all cell values (fails with very large rasters) |
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 |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| Maps | |
plot |
Plot a SpatRaster or SpatVector. The main method to create a map |
plotRGB |
Combine three layers (red, green, blue channels) into a single "real color" image |
image |
Alternative way to plot a SpatRaster |
persp |
Perspective plot of a SpatRaster |
contour |
Contour plot or filled-contour plot of a SpatRaster |
text |
Plot the values of a SpatRaster or SpatVector on top of a map |
| . | Interacting with a map |
zoom |
|
| Zoom in to a part of a map |
click |
| Query values of SpatRaster or SpatVector by clicking on a map |
select |
| Select a spatial subset of a SpatRaster or SpatVector |
draw |
| Create a SpatExtent or SpatVector by drawing on a map | . |
Other plots |
|
plot |
x-y scatter plot of the values 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 |
| --------------------------- | ------------------------------------------------------------------------------------------ |
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 (a.k.a. "bounding box") |
origin |
The origin of a SpatRaster |
crs |
The coordinate reference system (map projection) |
isLonLat |
Test if an object has (or may have) a longitude/latitude coordinate reference system; and if it has global coverage |
filename |
Filename(s) to which a SpatRaster is linked |
compareGeom |
Compare the geometry of SpatRasters |
NAvalue |
Get or set the NA value (for reading from a file) |
| --------------------------- | ------------------------------------------------------------------------------------------ |
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 |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| Basic |
writeRaster |
| Write all values of SpatRaster to disk | . |
| 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 | --------------------------- |
| ------------------------------------------------------------------------------------------ | Basic |
A SpatDataSet contains SpatRaster objects that are sub-datasets for the same area. They all have the same extent and resolution.
sds |
Create a SpatDataSet |
[ or $ |
Extract a SpatRaster |
names |
Get the names of the sub-datasets |
| --------------------------- | ------------------------------------------------------------------------------------------ |
The name in bold is the equivalent command in ArcGIS.
c |
append vector data of the same (vector) type ("rbind") |
erase or "-" |
erase parts of a polygons |
intersect or "*" |
intersect polygons |
union or "+" |
union polygons |
cover |
update and identity a polygons |
symdif |
symmetrical difference of two polygons |
aggregate |
dissolve smaller polygons into larger ones |
disaggregate |
explode: turn polygon parts into separate polygons |
crop |
clip vector data using a rectangle (SpatExtent ) |
select |
select - interactively select spatial features |
click |
identify attributes by clicking on a map |
merge |
Join table |
fill |
remove holes from polygons |
extract |
spatial queries between SpatVector and SpatRaster objects |
as.data.frame |
get attributes as a data.frame |
| --------------------------- | ------------------------------------------------------------------------------------------ |
extent |
Create a SpatExtent object |
intersect |
Intersect two SpatExtent objects |
union |
Combine two SpatExtent objects |
Math-methods |
round/floor/ceiling of the coordinates of a SpatExtent |
align |
Align a SpatExtent with a SpatRaster |
draw |
Create a SpatExtent object by drawing it on top of a map (plot) |
| --------------------------- | ------------------------------------------------------------------------------------------ |
terraOptions |
Show, set, save or get session 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? |
| --------------------------- | ------------------------------------------------------------------------------------------ |
This package is an attempt to stand on the shoulders of giants (GDAL, PROJ, GEOS, GeographicLib, Rcpp, R)