plgraphics (version 1.2)

plsmooth: Smooth and Reference Line Plotting

Description

These functions add smooths or reference lines to an existing pl plot.

Usage

plsmooth(x = NULL, y = NULL, ysec = NULL, band=NULL, power = NULL,
  group = NULL, weight = NULL, smooth = TRUE,
  plargs = NULL, ploptions = NULL, xy = TRUE, ...)
plsmoothline(smoothline = NULL, x = NULL, y = NULL, ysec = NULL,
  smooth.col = NULL, smooth.lty = NULL, smooth.lwd = NULL, 
  plargs = NULL, ploptions = NULL, marpar = NULL, ...)
plrefline(refline, x=NULL, innerrange=NULL, y=NULL,
  cutrange = c(x = TRUE, y = FALSE), plargs=NULL, ploptions=NULL, ...)

Value

plsmooth invisibly returns the data.frame needed for drawing the smooth line. The other functions return NULL

Arguments

x, y

coordinates for the horizontal and veritical axis, respectively. If NULL, they will be retrieved from plargs$pldata.

ysec

for plsmooth, plsmoothline: matrix of secondary y values. The smooths generated or given by its columns will be drawn thinner and with paled color.

band

logical: should a band (e.g., a confidence band) be drawn together with the smooth?

power

for plsmooth: smooth will be calcutated for y^power and the back-transformed. Usually, power=0.

group

for plsmooth: grouping variable. If NULL, the variable .smooth.group. column in plargs$pldata will be used if available. If group is of length 1, there will be no grouping

weight

weights of observations used for generating the smooth

smooth

logical: should smooth be done? Will almost always be TRUE

smoothline

for plsmoothline: result of a smooth fitting

smooth.col, smooth.lty, smooth.lwd

for plsmoothline: color, line type and line width for the smooth line(s). By default, they will be taken from ploptions.

refline

for plrefline: A two element vector giving intercept and slope of a straight line, or a function that returns these as the first 2 elemnts of the result's coef component, such as lm. For more possibilities, see Details.

innerrange

for plrefline: inner range in x direction - only needed if the refline should be clipped at a range different from the innerrange attribute of the horizontal variable

cutrange

for plrefline: logical vector of length 2: should the reference line(s) be cut at the inner plotting ranges in x- and y-direction? Otherwise, it will be continued outside it with the appropriate transformation.

plargs, ploptions

result of pl.control, see Details

marpar

margin parameters, if already available. By default, they will be retieved from ploptions.

xy

logical: should the coordinates be obtained as in high level graphics? This is set to FALSE to save time and avoid complications, in case the user is sure that x and y are vectors rather than formulas or variable names.

...

absorbs extra arguments

Author

Werner A. Stahel

Details

The argument refline accepts different types of values. If it is a function, it must either accept a formula (which will be y~x) as its first argument or x and y as the first two arguments.
Alternatively, refline can be a list with components x and y and possibly a component band that contains the coordinates of the line (or lines, if y is a matrix) and the width of a band around it (that is, additional lines, to be drawn with ploptions("refline.col")[2]).
In order to obtain more than one reference line, a list of such items may be given. It should not have compontents named coef, coefficients, x or y, since it would otherwise be mistaken for an argument of the types just described. The components may carry attributes lty, lwd and lcol to specify the properties of the lines individually. See Examples.

plsmooth and plrefline are very similar. They are both called by high level pl functions. plsmooth gets its smoothing function from ploptions("smooth.function"). Their properties (line type, width, color) come from different sets of pl options. plsmooth can also respect a group structure in the data.

If x or y has an attribute "numvalues", these are used as the values to calculate the smooth or the refline.

plargs and ploptions may be specified explicitly, but they are usually generated by calling pl.control.

The argument getpar is used for setting the graphical parameters mar, mgp according to ploptions? This is needed if the high level pl function has changed mar, since this change has been reversed when the function was left. By default, these graphical parameters will be retieved from pl.envir$ploptions.

See Also

pl.control

Examples

plyx(Sepal.Width ~ Sepal.Length, data=iris, smooth=TRUE,
  smooth.group=Species, pch=Species)
plsmooth(smooth.group=FALSE)

## plrefline  called from  plyx
plyx(Sepal.Width ~ Sepal.Length, data=iris, smooth=TRUE, pch=Species,
     smooth.group=iris$Species, refline=lm)
## more reference lines
plrefline(list(c(-2,1), structure(c(-2.3,1), lcol="purple", lty=1)))