4.5.plot.argument.handlers {loa}

Common plot argument handlers

Description

Functions for use the routine handling of some common plot arguments.

Usage

cexHandler(z = NULL, cex = NULL, 
           cex.range = NULL, expand.outputs = TRUE, 
           ref = NULL, ..., zlim = NULL)

colHandler(z = NULL, col = NULL, 
           region = NULL, colorkey = FALSE, legend = NULL,
           pretty = FALSE, at = NULL, cuts = 20,
           col.regions = NULL, alpha.regions = NULL,
           expand.outputs = TRUE, ref = NULL, 
           ..., zlim = NULL, output="col")

colRegionsHandler(...)

pchHandler(z = NULL, pch = NULL, pch.order = NULL, 
           expand.outputs = TRUE, ref = NULL, ..., 
           zlim = NULL)

scalesHandler(...)

zHandler(z = NULL, expand.outputs = TRUE, 
           ref = NULL, ...)

Arguments

z

If supplied, a vector of values intended to used as a scale when assigning a property.

For cexHandler, the cex of, e.g., points on a scatter plot. Here, size scales are managed using a reference range cex.range, but superseded by cex settings, if also supplied.

For colHandler, the color of, e.g., points on a scatter plot. Here, color scales are managed using a colorkey method similar to that used by the lattice function levelplot, see below (arguments region, colorkey, pretty, at, cuts, col.regions and alpha.regions). If z is NULL or not supplied, all colors are set by col if supplied or as the default lattice symbol color if both z and col are not supplied.

For pchHandler, the pch of, e.g., points on a scatter plot. Here, plot symbols are managed using a reference vector pch.order, but superseded by pch settings, if also supplied.

For zHandler, any vector that should to expanded by wrapping to a given length, e.g. the length of the x (or y) data series to plotting.

cex, col, pch

For associated handlers, the parameter value(s) to be managed (i.e., cex for cexHandler, etc. Note: In all cases if these are not NULL these supersede any supplied z or ...Handler modification.

cex.range

If supplied, the range for z to be rescaled to when using this to generate a cex scale. NOTE: cex.range = FALSE disables this cex scaling and uses z values directly; cex.range = TRUE applied default scaling, equivalent to cex.range = c(0.75, 3).

region, colorkey, legend, pretty, at, cuts, col.regions, alpha.regions

The colorscale settings to be used when generating a colorkey. The most useful of these are probably col.regions which can be used to reset the color scale, alpha.regions which sets the col.region alpha transparency (0 for invisible to 1 for solid) and colorkey which can be a logical (forcing the colorkey on or off) or a list of components that can be used to fine-tune the appearance of the colorkey. Note: The generation of colorscales is handled by RColorBrewer.

pch.order

A vector of symbol ids (typically the numbers 1 to 24) to used when plotting points if, e.g. using a scatter plot. By default, all points are plotted using the first of these pch ids unless any conditioning (e.g. grouping or zcase handling) is declared and linked to pch, in which symbols are assigned in series from pch.order.

expand.outputs, ref

expand.outputs is a Logical (default TRUE): should outputs be expanded to the same length as ref? This can be useful if, e.g., coloring points on a scatter plot that may be conditioned and therefore may require subscript handling, in which case ref could be the x or y data series, or any other vector of the same length. Note: if ref is not supplied expand.outputs is ignored.

zlim

The range over which the scale is to be applied if not range(z).

output

For colHandler. The function output. Either the col vector alone (output='col') or the full list of color parameters.

...

Additional arguments, often ignored.

Details

The ...Handler functions are argument handlers intended to routinely handle some common activities associated with plotting data.

cexHandler manages symbol sizes. It generates a (hopefully) sensible cex scale for handling plot symbol size based on a supplied input (z).

colHandler manages colors. It works like the colorkey in levelplot in lattice, to generate a colorscale based on a supplied input (z).

colRegionsHandler is a wrapper for colHandler that can be used to with the col.regions argument.

scalesHandler is a crude method to avoid scales argument list structures.

zHandler expands (by wrapping) or foreshortens vectors.

Value

cexHandler returns a vector, which can be used as the cex argument in many common plotting functions (e.g. plot, xyplot).

colHandler depending on output setting returns either the col vector or a list containing elements (z, col, legend, at, col.regions and alpha.regions), which can be used to create a col series scaled by z and an associated colorkey like that generated by levelplot for other lattice functions (e.g. xyplot).

colRegionsHandler returns a vector of color values suitable for use with the col.regions argument.

scalesHandler returns the supplied arguments modified as follows: all scales... arguments are converted into a single list(...); all scales.x... and scales.y... argument are converted into list(x=list(...)) and list(y=list(...)), respectively. so e.g. scales.x.rot=45 generates scales=list(x=list(rot=45)).

pchHandler returns a vector of pch values of an appropriate length, depending on expand.outputs and ref settings.

Note

cexHandler recently revised. Default cex range now smaller, in line with feedback.

scalesHandler might not be staying.

Author(s)

Karl Ropkins

References

These function makes extensive use of code developed by others.

lattice: Sarkar, Deepayan (2008) Lattice: Multivariate Data Visualization with R. Springer, New York. ISBN 978-0-387-75968-5

RColorBrewer: Erich Neuwirth <[e-mail]> (2011). RColorBrewer: ColorBrewer palettes. R package version 1.0-5. http://CRAN.R-project.org/package=RColorBrewer

See Also

In other packages: See xyplot in lattice.

Examples

#some trivial data
a <- 1:10


##  Example 1
##  Simple plot with cex handling

myplot1 <- function(x, y, z = NULL, cex = NULL, 
                    cex.range = NULL, ...){

    #set cex
    cex <- cexHandler(z, cex, cex.range)

    #plot
    xyplot(y~x, cex = cex,...)
}

myplot1(a, a, a)

#  compare
## Not run:  
  myplot1(a, a)             #like plot(x, y)    
  myplot1(a, a, a*100)      #as myplot1(a, a, a)
                            #because cex scaled by range
  myplot1(a, b, c, 
      cex.range = c(1,5))   #cex range reset
  myplot1(a, b, c, 
      cex.range = c(10,50), 
      cex = 1)              #cex supersedes all else if supplied
## End(Not run)


## Example2
## plot function using lists/listUpdates

myplot2 <- function(x, y, z = NULL, ...){

    #my default plot
    default.args <- list(x = y~x, z = z, 
                         pch = 20, cex = 4)

    #update with whatever user supplied
    plot.args <- listUpdate(default.args, list(...))

    #col Management
    plot.args$col <- do.call(colHandler, plot.args)
    do.call(xyplot, plot.args)
}


#with colorkey based on z case
myplot2(a, a, a) 

#  compare 
## Not run: 
   myplot2(a, b, c, 
       col.regions = "Blues") #col.regions recoloring  
   myplot2(a, b, c, 
       col = "red")           ##but (again) col supersedes if supplied
## End(Not run)

#  Note:
#  See also example in ?listUpdate