xy.coords {grDevices}

Extracting Plotting Structures

Description

xy.coords is used by many functions to obtain x and y coordinates for plotting. The use of this common mechanism across all relevant R functions produces a measure of consistency.

Usage

xy.coords(x, y = NULL, xlab = NULL, ylab = NULL, log = NULL,
          recycle = FALSE, setLab = TRUE)

Arguments

x, y

the x and y coordinates of a set of points. Alternatively, a single argument x can be provided.

xlab, ylab

names for the x and y variables to be extracted.

log

character, "x", "y" or both, as for plot. Sets negative values to NA and gives a warning of class "log_le_0".

recycle

logical; if TRUE, recycle (rep) the shorter of x or y if their lengths differ.

setLab

logical indicating if the resulting xlab and ylab should be constructed from the “kind” of (x,y); otherwise, the arguments xlab and ylab are used.

Details

An attempt is made to interpret the arguments x and y in a way suitable for bivariate plotting (or other bivariate procedures).

If y is NULL and x is a

formula:

of the form yvar ~ xvar. xvar and yvar are used as x and y variables.

list:

containing components x and y, these are used to define plotting coordinates.

time series:

the x values are taken to be time(x) and the y values to be the time series.

matrix or data.frame with two or more columns:

the first is assumed to contain the x values and the second the y values. Note that is also true if x has columns named "x" and "y"; these names will be irrelevant here.

In any other case, the x argument is coerced to a vector and returned as y component where the resulting x is just the index vector 1:n. In this case, the resulting xlab component is set to "Index" (if setLab is true as by default).

If x (after transformation as above) inherits from class "POSIXt" it is coerced to class "POSIXct".

Value

A list with the components

x

numeric (i.e., "double") vector of abscissa values.

y

numeric vector of the same length as x.

xlab

character(1) or NULL, the ‘label’ of x.

ylab

character(1) or NULL, the ‘label’ of y.

See Also

plot.default, lines, points and lowess are examples of functions which use this mechanism.

Examples

ff <- stats::fft(1:9)
xy.coords(ff)
xy.coords(ff, xlab = "fft") # labels "Re(fft)",  "Im(fft)"

with(cars, xy.coords(dist ~ speed, NULL)$xlab ) # = "speed"

xy.coords(1:3, 1:2, recycle = TRUE) # otherwise error "lengths differ"
xy.coords(-2:10, log = "y")
##> xlab: "Index"  \\  warning: 3 y values <= 0 omitted ..
op <- options(warn = 2)# ==> warnings would be errors, we suppress the one "we know":
suppressWarnings(xy.coords(-2:10, log = "y"), classes="log_le_0") -> xy
options(op) # revert
stopifnot(is.list(xy), identical (1:13 +0,  xy$x),
          identical(c(rep(NA, 3), 1:10 +0), xy$y))