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

matapply {squash} | R Documentation

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

[Package squash version 1.0.8 Index]