im.apply: Apply Function Pixelwise to List of Images

In spatstat.geom: Geometrical Functionality of the 'spatstat' Family

Apply Function Pixelwise to List of Images

Description

Returns a pixel image obtained by applying a given function to corresponding pixels in several pixel images.

Usage

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

Arguments

X	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.
verbose	Logical value specifying whether to print informative messages.

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; and the return value of FUN will become the pixel value of the resulting image. For example im.apply(X, mean) will return a pixel image in which the value of each pixel is the average of the corresponding pixel values in the images in X.

If the result of FUN is a vector, then the result of im.apply will be a list of images. For example im.apply(X, range) will return a list of two images containing the pixelwise minimum and pixelwise maximum, respectively, of the input images in X.

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.

Value

A pixel image (object of class "im") or a list of pixel images.

Computation details

The computation is performed efficiently using matrix operations where possible, by constructing a large matrix containing all the pixel data for all images. However, if this matrix would exceed the maximum permitted size of matrices (as given in spatstat.options("maxmatrix")), then the calculation is performed on smaller sub-images, and this is reported in a message if verbose=TRUE.

Author(s)

\spatstatAuthors

.

See Also

eval.im for algebraic operations with images.

Examples

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

  ## 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)

spatstat.geom documentation built on Aug. 8, 2025, 6:28 p.m.