ploptions {plgraphics}

Set and Get User "Session" Options that Influence "plgraphics"s Behavior

Description

The user can set (and get) 'pl' options – mostly graphical "parameters" – which influence the behavior plgraphics functions.

Usage

ploptions(x = NULL, ploptions = NULL, list = NULL, default = NULL, 
          assign = TRUE, ...)

default.ploptions

Arguments

x

character (vector) of name(s) of ploptions to query. If x is set, all further arguments will be ignored.

ploptions

the list of options that should be inspected or modified. Defaults to usr.ploptions from the pl.envir environment. ploptions>1 is equivalent to ploptions=pl.envir$ploptions, the last (or current) list used by a high level pl function.

list

a named list of options to be set, see Details

default

character vector of option names. These ploptions will be set according to default.ploptions. default="all" or =TRUE will reset all options. If default is set, all further arguments will be ignored.

assign

logical: should the list be assigned to pl.envir$usr.ploptions? It is then permanant until changed again by calling ploptions again or the session is closed. If >1, the resulting options are stored as ploptions in pl.envir, which is changed by the high level pl functions.

...

any ploptions can be defined or modified, using name = value, as in options of basic R.

Details

If the argument list is set, it must be a named list, and each component, with name name and value value is used as described for arguments in ..., see above (in addition to such arguments).

There is an object ploptions in the pl.envir environment, which contains the ploptions that have been used (usually after modification) by the high level pl function last called. This list is used by subsequent calls of lower level pl functions. Advanced uses may want to modify this list by assigning to pl.envir$ploptions$pch, for example.

Here is an incomplete list of the components of default.ploptions, describing the suitable alternative values to be set by calling ploptions. For the full set, see ?ploptions.list.

keeppar:

logical. If TRUE, the graphical parameter settings "mar", "oma", "cex", "mgp", and "mfg" will be maintained when leaving high level pl functions, otherwise, the old values will be restored (default).

colors:

The palette to be used by pl functions

csize:

General character size, relative to par("cex")

pale:

default argument for colorpale

tickintervals:

vector of length 2. The first element is the desired number of tick intervals for axes, to be used as argument n in pretty. The second determines how many tick labels are shown in the same way, and should therefore be smaller than (or equal to) the first.

pch:

plotting symbols or characters

csize.pch:

size of plotting symbols, relative to default. This may be a function with an argument that will be the number of observations at the time it is used.

csize.plab:

size of point labels, relative to csize.pch

psize.max:

maximum value of size of plotting symbols

lty, lwd:

line type(s) and width(s)

col, pcol, lcol:

colors to be used generally and specifically for points (symbols or text) and lines, respectively, given as index of ploptions("colors"). This are often (and by default) vectors to be used for showing groups. The first element is usually black.

colors:

the palette to be used

censored.pch, censored.size, censored.pale:

...

gridlines:

can be
– a logical indicating if gridlines should be drawn. If TRUE, gridlines will be drawn at the values given in attr(.,"ticksat"); – a vector of values at which the gridlines should appear;
– a list of length 2 of such values;
– a named list. If a name equals the attribute varname of either the x or y variable, the respective component will be used.

smooth.lty, smooth.col:

line type and color. Note that if there is a smooth.group factor, group.lty and group.col are used.

smooth.lwd:

line width. If of length 2 (or more), the second element is the factor by which the line width is reduced for simulated smooths (that is, for the second to the last column of smoothline$y). It defaults to 0.7.

smooth.xtrim:

proportion of fitted values to be trimmed off on both sides when drawing a smooth line, either a number or a function that takes the number of points as its argument. The default is the simple function 2^log10(n)/n. The smoothing function may produce an attribute xtrim that is used as an additional factor to smooth.xtrim. This is applied, e.g., to suppress trimming if a straight line is fitted instead of a smooth by requiring smoothLm as the smoothing function.

smooth.minobs:

minimal number of observations needed for calculating a smooth.

smooth.band:

Indicator (logical) determining whether "low" and "high" smooth lines should be drawn. See above for their definition.

condquant...:

Conditional quantiles for censored residuals.

condquant:

logical: should bars be drawn for censored residuals? If FALSE, censored observations will be set to the median of the conditional distribution and shown by a different plotting character, see argument censored of ploptions. If NULL, the standard plotting character will be used.

condquant.probrange:

range for probabilities. If the probability corresponding to the censored part of the distribution is outside the range, bars will not be drawn.

condquant.pale:

factor by which the pcol color will be paled to show the points (condquant.pale[1]) and the bars (...[2]).

plcond...:

features of plcond.

plcond/panel:

panel function to be used

plcond.nintervals:

number of intervals into which numerical variables will be cut

plcond.extend:

proportion of neighboring intervals for which points are shown. 0 means no overlap.

plcond.col:

4 colors to be used to mark the points of the neighboing intervals: The first and second ones color the points lower or higher than the interval of the horizontal conditioning variable, and the other two regulating the same features for the vertical variable. The points which are outside the intervals of both conditioning variables will get a mixed color.

plond.pale:

minimum and maximum paling, to be applied for distance 0 and maximal distance from the interval.

plcond.cex:

symbol size, relative to cex, used to show the points outside the interval

Value

For ploptions(x), where x is the name of a pl option, the current value of the option, or NULL if it is not such a name. If x contains several (valid) names, the respective list.

For ploptions(), the list of all plptions sorted by name.

For uses setting one or more options, the important effect is a changed list usr.ploptions in the pl.envir environment that is used by the package's functions (if assign is TRUE). The (invisibly) returned value is the same list, complemented by an attribute "old" containing the previous values of those options that have been changed. This list is useful for undoing the changes to restore the previous status.

Author(s)

Werner A. Stahel

See Also

stamp; ploptions.list; pl.envir; R's own predefined options().

Examples

## get options
ploptions(c("jitter.factor", "gridlines"))
ploptions("stamp")  ## see example(stamp)
ploptions()  ## all pl options, see '?ploptions.list'

## set options
ploptions(stamp=FALSE, pch=0, col=c.colors[-1], anything="do what you want")
ploptions(c("stamp", "anything"))
ploptions(default=TRUE)  ## reset all pl options, see '?ploptions.list'

## assign to transient options 
t.plopt <- ploptions(smooth.col="purple", assign=2) 
t.plopt$smooth.col
attr(t.plopt, "old")
ploptions("smooth.col") ## unchanged
ploptions("smooth.col", ploptions=2) ## transient options
pl.envir$ploptions["smooth.col"] ## the same

## switching 'margin parameters' between those used
## outside and inside high level pl functions
par(mar=c(2,2,5,2))
plyx(Sepal.Width~Sepal.Length, data=iris, title="The famous iris data set")
par("mar")
mtext("wrong place for text",3,1, col="red")
t.plo <- plmarginpar()
par("mar")
mtext("here is the right place",3,1)

par(attr(t.plo, "oldpar"))  ## resets the 'margin parameters'
par("mar")
plyx(Sepal.Width~Sepal.Length, data=iris, keeppar=TRUE)
par("mar")

## manipulating 'pl.envir$ploptions'
plyx(Sepal.Width~Sepal.Length, data=iris)
pl.envir$ploptions$pch
plpoints(7,4, csize=4)
pl.envir$ploptions$pch <- 4
plpoints(7.5,4, csize=4)