4.7.other.panel.functions: Other panel functions argument handlers

In loa: Lattice Options and Add-Ins

Other panel functions argument handlers

Description

In development panel functions for use with lattice

Usage

parHandler(scheme = NULL, ...)


#related

getArgs(source = TRUE, local.resets = TRUE, 
         user.resets = TRUE, is.scales.lines = FALSE, 
         elements = NULL, ..., defaults = list(), 
         defaults.only = FALSE)

getPlotArgs(defaults.as = "axis.line", source = TRUE, 
         local.resets = TRUE, user.resets = TRUE, 
         elements = NULL, ..., is.scales.lines = NULL, 
         defaults.only = TRUE)

isGood4LOA(arg)

Arguments

scheme	The color scheme to apply. This can be a list of parameters to apply or a character vector for a pre-defined scheme. Current pre-defined schemes include 'greyscale' (for black and white figures).
source, local.resets, user.resets	When recovering plot arguments with getArgs or getPlotArgs, places to search for relevant parameters. If supplied these would typically be vectors or lists. If vectors, they are assumed to be col setting. If lists, they are assumed to be lists of named parameters for inclusion. There are two cases that need to be handed specially: (1) some sources, local.resets and/or user.resets may contain both axis-specific and general information, e.g. For a scales list, parameters to be applied just to the x axis in scales$x and parameters to be applied to all scales in scales. In such cases these need to be checked in order (see elements below.) (2) Some sources, e.g. axis scales, contain both text and line parameters, with e.g. line settings declared as col.line, etc., rather than col, etc., (which are intended for use with text.) When supplied these need to be handled correctly (see is.scales.lines below). local.resets and user.resets are intended as overrides for the code developer and user, respectively. These can be logicals as well as vectors or lists. If logicals they turn on/off the associated plot components (using isGood4LOA). The check/update order is source, then source$element, then local.reset, then local.reset$element, then user.reset, then user.reset$element. This means that the developer always has last say regarding the default appearance of a plot component and the user always has the very last say from the command line if the local.reset is included as a formal argument in that plot.
is.scales.lines	When recovering arguments with getArgs or getPlotArgs, should source be treated as a lattice scales list? If so, and source is checked for line parameters, line-specific terms such as col.line, etc., will be recovered as col, etc., while general terms (meant for text in scales lists) will be ignored. (Note: getPlotArgs guesses this based on defaults.as if not supplied.)
elements	When recovering arguments with getArgs or getPlotArgs, this identifies the elements in source, local.resets and user.resets that may contain case-specific information. As with lattice handling of scales axis-specific information in source$element(s) is assumed to take priority over general information in source. (Note: if elements are not declared only general/top level information in source, local.resets and user.resets is considered at present.)
...	Other arguments, often ignored.
defaults, defaults.only, defaults.as	When recovering arguments with getArgs, defaults is an optional 'fall-back' in case nothing is recovered from source, local.resets and user.resets. defaults.only is a logical: if TRUE only parameters named in defaults are searched for, otherwise all parameters are recovered. With getPlotArgs, defaults.as selects an appropriate default. This should be a trellis parameter name, e.g. 'axis.line', 'axis.text', etc. The function uses this to identify appropriate plot parameters to search for/select, e.g. pch, col, cex, etc for 'plot.symbol', and to identify default values for each of these (if defaults.only = TRUE).
arg	For isGood4LOA a plot argument that can used to turn a plot panel or panel component on or off.

Details

getArgs returns a list of parameters/values based on lattice, developer and user settings. If multiple elements are identified as containing case-specific information, the list will contain one list of plot parameters for each named element.

getPlotArgs is a variation of getArgs intended for use with panel... and l... type lattice functions. It returns a list of plot parameters for different plot components, e.g. symbols, lines, or text.

isGood4LOA is a simple workhorse that checks if a supplied arg should be used by loa. (See value and note below.)

parHandler manages the default appearance of plots.

Value

getArgs and getPlotArgs return lists of located parameters/values. For example, the call

getPlotArgs(default.as = "axis.line")

returns a list containing the lattice defaults for an axis line (alpha, col, lty and lwd) These can then be used in combination with appropriate x and y values in llines, or panel.lines calls. The arguments local.resets and user.resets can be added into the call to provide developer and user overrides. (See note below.)

isGood4LOA returns a logical (TRUE or FALSE), depending on the type of a supplied argument. This returns FALSE for NULL, for all FALSE logicals, and any arg that has previously been tagged as 'not wanted'.

parHandler returns a list a list suitable for use as par.settings with most lattice plots.

Note

getPlotArgs is intended as a 'workhorse' for plot developers, to recover lattice settings, impose their own preferences on these, and in turn to provide users with similar options to quickly override developer settings.

isGood4LOA only exists because I, perhaps wrongly, equate arg = NULL with arg = FALSE when that argument is a component of a plot defined in the plot formals. For example, in trianglePlot I want grids = NULL to turn off the plot grids much like grids = FALSE, but got fed up always writing the same everywhere. Does not mean it is right, particularly useful or even clever...

The getPlotArgs/isGood4LOA combination is a first attempt at providing plot developers with a simple tool to integrate plot argument management by lattice, the plot developer and the plot user. It is intended to be applied in the form shown in the Examples below.

Axis, tick, grid and annotation handling in trianglePlot is intended to illustrate this type of application.

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

See Also

In other packages: See xyplot in lattice.

Examples

#getPlotArgs/isGood4LOA notes

#in formals
#my.plot <- function(..., user.reset = TRUE, ...) 

#in main code body
#local.resets <- [what developer wants] 
#plot.arg <- getPlotArgs("[type]", source, local.reset, user.reset)

#in panel call
#(for panel off/on control)
#if(isGood4LOA(plot.arg)) panel...(..., plot.arg,...)

#in panel... function
#for panel component off/on control)
#if(isGood4LOA(plot.arg1)) panel...(..., plot.arg1,...)
#if(isGood4LOA(plot.arg2)) l...(..., plot.arg2,...)
#etc.

loa documentation built on Dec. 25, 2024, 3 p.m.