im.apply: Apply Function Pixelwise to List of Images

Description

Returns a pixel image obtained by applying a function to the values of corresponding pixels in several pixel images.

Usage

im.apply(X, FUN, …, fun.handles.na=FALSE, check=TRUE)

Arguments

A list of pixel images (objects of class "im").

FUN

A function that can be applied to vectors, or a character string giving the name of such a function.

…

Additional arguments to FUN.

fun.handles.na

Logical value specifying what to do when the data include NA values. See Details.

check

Logical value specifying whether to check that the images in X are compatible (for example that they have the same grid of pixel locations) and to convert them to compatible images if necessary.

Value

A pixel image (object of class "im").

Details

The argument X should be a list of pixel images (objects of class "im"). If the images do not have identical pixel grids, they will be converted to a common grid using harmonise.im.

At each pixel location, the values of the images in X at that pixel will be extracted as a vector. The function FUN will be applied to this vector. The result (which should be a single value) becomes the pixel value of the resulting image.

The argument fun.handles.na specifies what to do when some of the pixel values are NA.

If fun.handles.na=FALSE (the default), the function FUN is never applied to data that include NA values; the result is defined to be NA whenever the data contain NA.
If fun.handles.na=TRUE, the function FUN will be applied to all pixel data, including those which contain NA values.

Examples

Run this code

# NOT RUN {
  # list of two pixel images
  Y <- solapply(bei.extra, scaletointerval)
  plot(Y)
  im.apply(Y, max)
  im.apply(Y, sum)

  ## Example with incompatible patterns of NA values
  B <- owin(c(438, 666), c(80, 310))
  Y[[1]][B] <- NA
  opa <- par(mfrow=c(2,2))
  plot(Y[[1]])
  plot(Y[[2]])
  #' Default action: NA -> NA
  plot(im.apply(Y, mean))
  #' Use NA handling in mean.default
  plot(im.apply(Y, mean, na.rm=TRUE, fun.handles.na=TRUE))
  par(opa)
# }