imapply: Apply a function over an image

imapplyR Documentation

Apply a function over an image

Description

imapply() is a memory-efficient analogue of base::apply(). It gives the same answer, but where apply() permutes the whole array into a fresh copy before looping, imapply() gathers each sub-array directly through the stride vector. Peak memory is therefore the input plus the result, rather than twice the input plus the result, which matters once an image is larger than a comfortable fraction of memory.

Usage

imapply(x, margin, fun, ..., simplify = TRUE, threads = NULL, progress = FALSE)

voxelApply(
  x,
  fun,
  ...,
  mask = NULL,
  fill = 0,
  simplify = TRUE,
  threads = NULL,
  progress = FALSE
)

lineApply(
  x,
  fun,
  ...,
  axis = 1L,
  simplify = TRUE,
  threads = NULL,
  progress = FALSE
)

sliceApply(
  x,
  fun,
  ...,
  axis = 3L,
  simplify = TRUE,
  threads = NULL,
  progress = FALSE
)

Arguments

x

An image or a plain array.

margin

The dimensions to retain, as for base::apply().

fun

A function to apply.

...

Further arguments to fun.

simplify

Whether to simplify the result to an array where possible.

threads

Number of threads to use, or NULL to consult getOption("imply.threads"). See parallelism.

progress

FALSE for none, TRUE for a text progress bar showing the percentage complete and the rate in voxels per second, or a function of ⁠(done, total)⁠.

mask

For voxelApply(), a logical or numeric array over the spatial dimensions, an image, or NULL for none; see asMaskVector(). Locations outside it are not visited at all.

fill

The value given to locations outside mask.

axis

For lineApply(), the axis lines run along; for sliceApply(), the axis slices cut across.

Details

The remaining functions differ only in how much of the space they hand to fun at a time: a single location for voxelApply(), a one-dimensional line for lineApply(), and a two-dimensional slice for sliceApply().

In every case the values held at each location travel with the unit. So for an image with a time series at each location, voxelApply() passes one series, lineApply() passes a line's worth of series, and sliceApply() passes a slice's worth:

  dim(x) = 4 x 5 x 6 x 10, spatial = 3

  voxelApply(x, f)           f sees  10 values
  lineApply(x, f, axis = 1)  f sees  4 x 10
  sliceApply(x, f, axis = 3) f sees  4 x 5 x 10

axis always names a spatial dimension, but means what the name of each function implies: a line runs along its axis, whereas a slice is cut across its axis. Use imapply() directly to iterate over a non-spatial dimension, such as applying a function to each volume in a time series.

Value

For imapply(), as base::apply(). For voxelApply(), lineApply() and sliceApply() applied to an image, a dense image when the function returns a single value per location, line or slice, respectively, and otherwise as for imapply(). The geometry of the result is that of x with the axes traversed removed, each remaining location being placed at the centre of the line or slice it summarises, so centre() is unchanged. A plain array in gives a plain array out.


imply documentation built on Nov. 20, 2026, 5:12 p.m.