st_apply apply a function to array dimensions: aggregate over space, time, or something else

# S3 method for stars
st_apply(
  X,
  MARGIN,
  FUN,
  ...,
  CLUSTER = NULL,
  PROGRESS = FALSE,
  FUTURE = FALSE,
  rename = TRUE,
  .fname
)

Arguments

X

object of class stars

MARGIN

see apply; index number(s) or name(s) of the dimensions over which FUN will be applied

FUN

see apply and do see below at details.

...

arguments passed on to FUN

CLUSTER

cluster to use for parallel apply; see makeCluster

PROGRESS

logical; if TRUE, use pbapply::pbapply to show progress bar

FUTURE

logical;if TRUE, use future.apply::future_apply

rename

logical; if TRUE and X has only one attribute and FUN is a simple function name, rename the attribute of the returned object to the function name

.fname

function name for the new attribute name (if one or more dimensions are reduced) or the new dimension (if a new dimension is created); if missing, the name of FUN is used

Value

object of class stars with accordingly reduced number of dimensions; in case FUN returns more than one value, a new dimension is created carrying the name of the function used; see the examples.

Details

FUN is a function which either operates on a single object, which will be the data of each iteration step over dimensions MARGIN, or a function that has as many arguments as there are elements in such an object. See the NDVI examples below. Note that the second form can be very much faster e.g. when a trivial function is not being called for every pixel, but only once (example).

Examples

tif = system.file("tif/L7_ETMs.tif", package = "stars") x = read_stars(tif) st_apply(x, 1:2, mean) # mean band value for each pixel
#> stars object with 2 dimensions and 1 attribute #> attribute(s): #> Min. 1st Qu. Median Mean 3rd Qu. Max. #> mean 25.5 53.33333 68.33333 68.91242 82 255 #> dimension(s): #> from to offset delta refsys point values x/y #> x 1 349 288776 28.5 UTM Zone 25, Southern Hem... FALSE NULL [x] #> y 1 352 9120761 -28.5 UTM Zone 25, Southern Hem... FALSE NULL [y]
st_apply(x, c("x", "y"), mean) # equivalent to the above
#> stars object with 2 dimensions and 1 attribute #> attribute(s): #> Min. 1st Qu. Median Mean 3rd Qu. Max. #> mean 25.5 53.33333 68.33333 68.91242 82 255 #> dimension(s): #> from to offset delta refsys point values x/y #> x 1 349 288776 28.5 UTM Zone 25, Southern Hem... FALSE NULL [x] #> y 1 352 9120761 -28.5 UTM Zone 25, Southern Hem... FALSE NULL [y]
st_apply(x, 3, mean) # mean of all pixels for each band
#> stars object with 1 dimensions and 1 attribute #> attribute(s): #> Min. 1st Qu. Median Mean 3rd Qu. Max. #> mean 59.23541 61.07112 65.96675 68.91242 76.25445 83.18266 #> dimension(s): #> from to offset delta refsys point values #> band 1 6 NA NA NA NA NULL
st_apply(x, "band", mean) # equivalent to the above
#> stars object with 1 dimensions and 1 attribute #> attribute(s): #> Min. 1st Qu. Median Mean 3rd Qu. Max. #> mean 59.23541 61.07112 65.96675 68.91242 76.25445 83.18266 #> dimension(s): #> from to offset delta refsys point values #> band 1 6 NA NA NA NA NULL
st_apply(x, 1:2, range) # min and max band value for each pixel
#> stars object with 3 dimensions and 1 attribute #> attribute(s): #> Min. 1st Qu. Median Mean 3rd Qu. Max. #> L7_ETMs.tif 1 50 71 72.43565 96 255 #> dimension(s): #> from to offset delta refsys point values x/y #> range 1 2 NA NA NA NA NULL #> x 1 349 288776 28.5 UTM Zone 25, Southern Hem... FALSE NULL [x] #> y 1 352 9120761 -28.5 UTM Zone 25, Southern Hem... FALSE NULL [y]
fn_ndvi1 = function(x) (x[4]-x[3])/(x[4]+x[3]) # ONE argument: will be called for each pixel fn_ndvi2 = function(red,nir) (nir-red)/(nir+red) # n arguments: will be called only once ndvi1 = st_apply(x, 1:2, fn_ndvi1) ndvi2 = st_apply(x[,,,3:4], 1:2, fn_ndvi2) # note that we select bands 3 and 4 in the first argument all.equal(ndvi1, ndvi2)
#> [1] "Names: 1 string mismatch"
# to get a progress bar also in non-interactive mode, specify: if (require(pbapply)) { # install it, if FALSE pboptions(type = "timer") }
#> Loading required package: pbapply