overlay: Overlay Raster objects

Description

Create a new Raster* object, based on two or more Raster* objects. (You can also use a single object, but perhaps calc is what you are looking for in that case). You should supply a function fun to set the way that the RasterLayers are combined. The number of arguments in the function must match the number of Raster objects (or take any number). For example, if you combine two RasterLayers you could use multiply: fun=function(x,y){return(x*y)} percentage: fun=function(x,y){return(100 * x / y)}. If you combine three layers you could use fun=function(x,y,z){return((x + y) * z)} Note that the function must work for vectors (not only for single numbers). That is, it must return the same number of elements as its input vectors. Alternatively, you can also supply a function such as sum, that takes n arguments (as '...'), and perhaps also has a na.rm argument, like in sum(..., na.rm). If a single mutli-layer object is provided, its layers are treated as individual RasterLayer objects if the argument "unstack=TRUE" is used. If multiple objects are provided, they should have the same number of layers, or it should be possible to recycle them (e.g., 1, 3, and 9 layers, which would return a RasterBrick with 9 layers).

Arguments

Value

Raster* object

Methods

overlay(x, y, ..., fun) 1) x and y are Raster* objects rll{ x Raster* object y Raster* object ... Additional Raster* objects fun the function to be applied. The number of arguments of the function should match the number of Raster objects, or it should take any number of arguments } 2) x is a Raster object, y is missing overlay(x, fun, unstack=TRUE) In this case, the function returns a RasterLayer based on computations that combine the individual layers of the Raster* object. If x is a RasterLayer, this is equivalent to using the calc function. overlay(x, fun, overwrite, format, datatype, progress) rll{ x RasterStack or RasterBrick object fun Function to be applied. The number of arguments of the function should match the number of layers of the RasterStack/Brick object unstack Logical. Unstack object x into individual layers? } In all cases you can also use these arguments: rll{ filename filename for the output raster. A valid filename must be provided when the data of the input rasters are on disk overwrite logical. If TRUE, existing files will be overwritten format Character. Output file type. See writeRaster progress Character. "text", "window", or "" (the default, no progress bar) }

Details

Instead of the overlay function you can also use aritmethic functions such as *, /, +, - with Raster objects (see examples). In that case you cannot specifiy an output filename. Moreover, the overlay function should be more efficient when using large data files that cannot be loaded into memory, as the use of the complex arithmetic functions might lead to the creation of many temporary files. While you can supply functions such as sum or mean, it would be more direct to use the Raster* objects are arguments to those functions (e.g. sum(r1,r2,r3)) See rasterize and extract for "overlays" involving Raster* objects and polygons, lines, or points.

Examples

Run this code

r <- raster(ncol=10, nrow=10)
r1 <- init(r, fun=runif)
r2 <- init(r, fun=runif)
r3 <- overlay(r1, r2, fun=function(x,y){return(x+y)})

# long version for multiplication
r4 <- overlay(r1, r2, fun=function(x,y){(x*y)} )

#use the individual layers of a RasterStack to get a RasterLayer
s <- stack(r1, r2)
r5 <- overlay(s, fun=function(x,y) x*y )
# equivalent to
r5c <- calc(s, fun=function(x) x[1]*x[2] )


#Combine RasterStack and RasterLayer objects (s2 has four layers. r1 (one layer) and s (two layers) are recycled) 
s2 <- stack(r1, r2, r3, r4)
b <- overlay(r1, s, s2, fun=function(x,y,z){return(x*y*z)} )

# use a single RasterLayer (same as calc function)
r6 <- overlay(r1, fun=sqrt)

# multiplication with more than two layers (make sure the number of RasterLayers matches the arguments of 'fun'
r7 <- overlay(r1, r2, r3, r4, fun=function(a,b,c,d){return(a*b+c*d)} )  
# equivalent function, efficient if values can be loaded in memory
r8 <- r1 * r2 + r3 * r4

# Also works with multi-layer objects. 
s1 <- stack(r1, r2, r3)
x <- overlay(s1, s1, fun=function(x,y)x+y+5)

# in this case the first layer of the shorter object is recycled.
# i.e., s2 is treated as stack(r1, r3, r1)
s2 <- stack(r1, r3)
y <- overlay(s1, s2, fun=sum)