3 Calculations

This section covers various methods for doing calculations with spatRasters.

3.1 Raster Math

One of raster’s claims to fame was the ease at which you could do calculations. R automatically treated each cell in a RasterLayer as if it was a number, and each cell in a RasterBrick or RasterStack as if it were a vector. There were additional functions for doing calculations on an entire layer of a raster and for applying non-vectorized functions.

Raster arithmetic and math are still very easy with spatRasters. In fact, many statistical summary functions are pre-vectorized for spatRasters, so if you want to apply them by cell, you don’t even need to use a vectorizing function like app.

#average annual temperature by cell
(annual_temp = mean(temp))

## class       : SpatRaster 
## dimensions  : 180, 180, 1  (nrow, ncol, nlyr)
## resolution  : 0.008333333, 0.008333333  (x, y)
## extent      : 5.5, 7, 49, 50.5  (xmin, xmax, ymin, ymax)
## coord. ref. : lon/lat WGS 84 (EPSG:4326) 
## source(s)   : memory
## name        :      mean 
## min value   :  6.541667 
## max value   : 10.625000

3.2 Spatial Calculations

All previous spatial calculation functionality is present. Many names have changed though as some functions have been split up into multiple functions and other functions have been collapsed into a single function. The motivation behind this is for the function names to be more descriptive in terms of what they are actually doing.

The cellSize function always returns a spatRaster of areas. While projected raster cells should all have the same area, unprojected raster cells will vary spatially, depending on their distance from the equator.

Old Functions	New Function	Operation
area, rgeos::gArea	expanse	area covered
area	cellSize	area of raster cell
distance, pointDistance, distanceFromPoints	distance	distance between objects
approxNA	approximate	Estimate values for NA cells in a raster

3.3 Local (*app) Functions

In raster, there were a number of functions that behaved similar to the apply family of functions in base R, but had a variety of mostly unrelated names: calc, cellStats, overlay etc. In terra, these have been renamed, for the most part, with the *app suffix. A few options have been added as well.

Old Functions	New Function	Operation
calc	app	apply functions to the values of each raster cell
stackApply	tapp	apply functions to cells grouped by layer
overlay	lapp	apply functions to cells using layers as arguments
	rapp	apply functions to a subset of layers that varies spatially
	sapp	apply functions to layers, similar to sapply or lapply
cellStats	global	apply functions to layers in a raster
layerStats	layerCor	compute summary stats of layers pairwise
movingFun	roll	compute function on a window moving through layers

3.4 Applying Deep Dive

There are many apply-like functions in terra, but the most commonly used ones are app, tapp, lapp and global. The app and tapp functions work similarly to their base R pseudo-homophones apply and tapply. However, they apply the the function to all the cells in a spatRaster instead of all the rows or columns of a matrix/data.frame. For both app and tapp, the applied function should take a vector as its input. app outputs a single layer spatRaster, while tapp outputs a spatRaster with as many layers as there are unique values in the index vector.

seasons = c('Winter', 'Winter', rep('Spring', 3), rep('Summer', 3), 
            rep('Fall', 3), 'Winter')

(seasonal_precip = tapp(precip, index=seasons, fun='mean'))

## class       : SpatRaster 
## dimensions  : 180, 180, 4  (nrow, ncol, nlyr)
## resolution  : 0.008333333, 0.008333333  (x, y)
## extent      : 5.5, 7, 49, 50.5  (xmin, xmax, ymin, ymax)
## coord. ref. : lon/lat WGS 84 (EPSG:4326) 
## source(s)   : memory
## names       : Winter,   Spring,   Summer,      Fall 
## min values  :     53, 53.66667, 60.33333,  55.66667 
## max values  :    127, 97.66667, 95.33333, 113.66667

lapp sounds like it should be the equivalent of lapply (“list apply”), but instead stands for “layer apply”. lapp applies a function that takes multiple values as inputs and applies it to each cell of a multilayer raster where each of the layers is used as an input. The output is a single layer spatRaster. One example of this is the NDVI (greenness) calculation for multi-spectral data.

The global function is named as a contrast to zonal, focal and the local (*app) functions. global applies a function that outputs a single value to entire layers of data instead of to each cell. Its output is a data.frame with one column for each statistic passed to the function.

For functions that take in an entire layer as input and also output an entire layer, you can use lapply, sapply or in rare cases sapp.

#remove values not inside Luxembourg
precip_lux = mask(precip, lux)

# average and range of monthly precipitation for all of Luxembourg
global(precip_lux, fun=c('mean','range'), na.rm=TRUE)

##               mean min max
## January   83.52010  62 107
## February  65.39828  53  81
## March     71.25246  57  90
## April     58.10090  50  74
## May       71.01005  65  80
## June      71.84065  64  84
## July      69.56030  60  84
## August    58.92555  52  71
## September 69.15033  61  83
## October   79.10152  66  94
## November  81.86710  67 102
## December  93.68888  75 116

# calculating custom function (coefficient of variation) by month for all of 
# Luxembourg
global(precip_lux, fun=cv, na.rm=TRUE)

##               global
## January   0.14386729
## February  0.09964252
## March     0.11190306
## April     0.08711527
## May       0.03963299
## June      0.05422691
## July      0.06041096
## August    0.05126035
## September 0.05569626
## October   0.07343647
## November  0.09897658
## December  0.10483384