loa (version 0.2.22)

4.5.plot.argument.handlers: 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)

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

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

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

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 (

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

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

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, currently all ignored.

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. pchHandler returns a vector of pch values of an appropriate length, depending on expand.outputs and ref settings.

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. zHandler expands (by wrapping) or foreshortens vectors.

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 (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
#  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


## 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 
#  myplot2(a, b, c, 
#      col.regions = "Blues") #col.regions recoloring  
#  myplot2(a, b, c, 
#      col = "red")           ##but (again) col supersedes if supplied

#  Note:
#  See also example in ?listUpdate