xy.coords             package:grDevices             R Documentation

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)

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.

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

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 '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:

     xy.coords(stats::fft(c(1:10)), NULL)

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

     xy.coords(1:3, 1:2, recycle=TRUE)
     xy.coords(-2:10,NULL, log="y")
     ##> warning: 3 y values <=0 omitted ..

