apply_pixel.cube

Apply arithmetic expressions over all pixels of a data cube

Description

Create a proxy data cube, which applies arithmetic expressions over all pixels of a data cube. Expressions may access band values by name.

Usage

apply_pixel.cube(
  x,
  expr,
  names = NULL,
  keep_bands = FALSE,
  ...,
  FUN,
  load_pkgs = FALSE,
  load_env = FALSE
)

Arguments

Argument	Description
x	source data cube
expr	character vector with one or more arithmetic expressions (see Details)
names	optional character vector with the same length as expr to specify band names for the output cube
keep_bands	logical; keep bands of input data cube, defaults to FALSE, i.e. original bands will be dropped
…	not used
FUN	user-defined R function that is applied on all pixels (see Details)
load_pkgs	logical or character; if TRUE, all currently attached packages will be attached automatically before executing FUN in spawned R processes, specific packages can alternatively be provided as a character vector.
load_env	logical or environment; if TRUE, the current global environment will be restored automatically before executing FUN in spawned R processes, can be set to a custom environment.

Details

The function can either apply simple arithmetic C expressions given as a character vector (expr argument), or apply a custom R reducer function if FUN is provided.

In the former case, gdalcubes uses the tinyexpr library to evaluate expressions in C / C++, you can look at the library documentation to see what kind of expressions you can execute. Pixel band values can be accessed by name. Predefined variables that can be used within the expression include integer pixel indexes (ix, iy, it), and pixel coordinates (left, right, top, bottom), t0, t1), where the last two values are provided seconds since epoch time.

FUN receives values of the bands from one pixel as a (named) vector and should return a numeric vector with identical length for all pixels. Elements of the result vectors will be interpreted as bands in the result data cube. Notice that by default, since FUN is executed in a separate R process, it cannot access any variables from outside and required packages must be loaded within FUN. To restore the current environment and automatically load packages, set load_env and/or load_pkgs to TRUE.

For more details and examples on how to write user-defined functions, please refer to the gdalcubes website at https://gdalcubes.github.io/source/concepts/udfs.html.

Value

a proxy data cube object

Note

This function returns a proxy object, i.e., it will not start any computations besides deriving the shape of the result.

Examples

# create image collection from example Landsat data only 
# if not already done in other examples
if (!file.exists(file.path(tempdir(), "L8.db"))) {
  L8_files <- list.files(system.file("L8NY18", package = "gdalcubes"),
                         ".TIF", recursive = TRUE, full.names = TRUE)
  create_image_collection(L8_files, "L8_L1TP", file.path(tempdir(), "L8.db"), quiet = TRUE) 
}

# 1. Apply a C expression
L8.col = image_collection(file.path(tempdir(), "L8.db"))
v = cube_view(extent=list(left=388941.2, right=766552.4, 
              bottom=4345299, top=4744931, t0="2018-04", t1="2018-06"),
              srs="EPSG:32618", nx = 497, ny=526, dt="P1M")
L8.cube = raster_cube(L8.col, v) 
L8.cube = select_bands(L8.cube, c("B04", "B05")) 
L8.ndvi = apply_pixel(L8.cube, "(B05-B04)/(B05+B04)", "NDVI") 
L8.ndvi

A data cube proxy object

Dimensions:
         low       high count       pixel_size chunk_size
t 2018-04-01 2018-06-30     3              P1M          1
y    4345299    4744931   526 759.756653992395        384
x   388941.2   766552.4   497 759.781086519115        384

Bands:
  name offset scale nodata unit
1 NDVI      0     1    NaN     

plot(L8.ndvi)

# 2. Apply a user defined R function
L8.ndvi.noisy = apply_pixel(L8.cube, names="NDVI_noisy", 
   FUN=function(x) {
       rnorm(1, 0, 0.1) + (x["B05"]-x["B04"])/(x["B05"]+x["B04"])
   })
L8.ndvi.noisy

A data cube proxy object

Dimensions:
         low       high count       pixel_size chunk_size
t 2018-04-01 2018-06-30     3              P1M          1
y    4345299    4744931   526 759.756653992395        384
x   388941.2   766552.4   497 759.781086519115        384

Bands:
        name offset scale nodata unit
1 NDVI_noisy      0     1    NaN     

plot(L8.ndvi.noisy)