matapply {squash}

Apply a function over z coordinates, binned by their x, y coordinates

Description

Divide the range of x and y into intervals, thus forming a matrix of bins, and apply an arbitrary function to the z values corresponding to each bin.

Usage

matapply(x, y = NULL, z = NULL, FUN,  
         nx = 50, ny = nx, 
         xlim = NULL, ylim = NULL, 
         xbreaks = NULL, ybreaks = NULL, 
         right = FALSE, include.lowest = TRUE, ...) 

Arguments

x, y, z

Numeric vectors, or possibly a matrix.

FUN

Function to summarize z values.

nx, ny

Approximate number of bins along x and y axis.

xlim, ylim

Limit the range of data points considered.

xbreaks, ybreaks

Breakpoints between bins along x and y axes.

right

Logical; if TRUE, the intervals will be closed on the right (and open on the left).

include.lowest

Logical, indicating if an x[i] equal to the lowest (or highest, for right = FALSE) breaks value should be included.

...

Further arguments to FUN.

Details

x, y and z values can be passed to squash in any form recognized by xyz.coords (e.g. individual vectors, list, data frame, formula).

Alternatively, data that is already in a matrix can be passed in any format recognized by xyzmat.coords.

FUN should accept a numeric vector and return a single numeric value (e.g. mean, median, min, max, sd).

If xbreaks is not specified, approximately nx breakpoints will be generated automatically to span the data; likewise for ybreaks and ny.

The output can be visualized with colorgram, image, etc.

Value

A list with components

x

Vector of breakpoints along the x-axis.

y

Vector of breakpoints along the y-axis.

z

Matrix of values representing the summary for each bin.

xlab

A label for the x-axis.

ylab

A label for the y-axis.

zlab

A label for the z-axis.

Note

The defaults of right and include.lowest are opposite the defaults used in cut.

See Also

This function is essentially a souped-up version of tapply.

squashgram has similar functionality but with graphical output.

Examples

  ## earthquake depths as a function of longitude, latitude
  attach(quakes)
  quakedepth <- matapply(depth ~ long + lat, FUN = mean)
  colorgram(quakedepth)

  ## iris petal length vs. sepal length and width
  ipl <- matapply(iris[,1:3], FUN = median, nx = 20, ny = 15 )
  colorgram(ipl, main = 'iris')
    
  ## Example of matrix input; here used to downsample an image 
  colorgram(volcano, colFn = terrain.colors)
  volcano2 <- matapply(volcano, FUN = mean, nx = 20)
  colorgram(volcano2, colFn = terrain.colors)