im.apply {spatstat.geom} | R Documentation |
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 |
FUN |
A function that can be applied to vectors, or a character string giving the name of such a function. |
... |
Additional arguments to |
fun.handles.na |
Logical value specifying what to do when the data include
|
check |
Logical value specifying whether to check that the images in
|
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 functionFUN
is never applied to data that includeNA
values; the result is defined to beNA
whenever the data containNA
.-
If
fun.handles.na=TRUE
, the functionFUN
will be applied to all pixel data, including those which containNA
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)
Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner rolfturner@posteo.net and Ege Rubak rubak@math.aau.dk.
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)