C_02b_trellis.par.get {lattice}R Documentation

Graphical Parameters for Trellis Displays

Description

Functions used to query, display and modify graphical parameters for fine control of Trellis displays. Modifications are made to the settings for the currently active device only.

Usage

trellis.par.set(name, value, ..., theme, warn = TRUE, strict = FALSE)
trellis.par.get(name = NULL)
show.settings(x = NULL)

Arguments

name

A character string giving the name of a component. If unspecified in trellis.par.get(), the return value is a named list containing all the current settings (this can be used to get the valid values for name).

value

a list giving the desired value of the component. Components that are already defined as part of the current settings but are not mentioned in value will remain unchanged.

theme

a list decribing how to change the settings, similar to what is returned by trellis.par.get(). This is purely for convenience, allowing multiple calls to trellis.par.set to be condensed into one. The name of each component must be a valid name as described above, with the corresponding value a valid value as described above.

As in trellis.device, theme can also be a function that produces such a list when called. The function name can be supplied as a quoted string.

...

Multiple settings can be specified in name = value form. Equivalent to calling with theme = list(...)

warn

A logical flag, indicating whether a warning should be issued when trellis.par.get is called when no graphics device is open.

strict

Usually a logical flag, indicating whether the value should be interpreted strictly. Usually, assignment of value to the corresponding named component is fuzzy in the sense that sub-components that are absent from value but not currently NULL are retained. By specifying strict = TRUE, such values will be removed.

An even stricter interpretation is allowed by specifying strict as a numeric value larger than 1. In that case, top-level components not specified in the call will also be removed. This is primarily for internal use.

x

optional list of components that change the settings (any valid value of theme). These are used to modify the current settings (obtained by trellis.par.get) before they are displayed.

Details

The various graphical parameters (color, line type, background etc) that control the look and feel of Trellis displays are highly customizable. Also, R can produce graphics on a number of devices, and it is expected that a different set of parameters would be more suited to different devices. These parameters are stored internally in a variable named lattice.theme, which is a list whose components define settings for particular devices. The components are idenified by the name of the device they represent (as obtained by .Device), and are created as and when new devices are opened for the first time using trellis.device (or Lattice plots are drawn on a device for the first time in that session).

The initial settings for each device defaults to values appropriate for that device. In practice, this boils down to three distinct settings, one for screen devices like x11 and windows, one for black and white plots (mostly useful for postscript) and one for color printers (color postcript, pdf).

Once a device is open, its settings can be modified. When another instance of the same device is opened later using trellis.device, the settings for that device are reset to its defaults, unless otherwise specified in the call to trellis.device. But settings for different devices are treated separately, i.e., opening a postscript device will not alter the x11 settings, which will remain in effect whenever an x11 device is active.

The functions trellis.par.* are meant to be interfaces to the global settings. They always apply on the settings for the currently ACTIVE device.

trellis.par.get, called without any arguments, returns the full list of settings for the active device. With the name argument present, it returns that component only. trellis.par.get sets the value of the name component of the current active device settings to value.

trellis.par.get is usually used inside trellis functions to get graphical parameters before plotting. Modifications by users via trellis.par.set is traditionally done as follows:

add.line <- trellis.par.get("add.line")

add.line$col <- "red"

trellis.par.set("add.line", add.line)

More convenient (but not S compatible) ways to do this are

trellis.par.set(list(add.line = list(col = "red")))

and

trellis.par.set(add.line = list(col = "red"))

The actual list of the components in trellis.settings has not been finalized, so I'm not attempting to list them here. The current value can be obtained by print(trellis.par.get()). Most names should be self-explanatory.

show.settings provides a graphical display summarizing some of the values in the current settings.

Value

trellis.par.get returns a list giving parameters for that component. If name is missing, it returns the full list.

Most of the settings are graphical parameters that control various elements of a lattice plot. For details, see the examples below. The more unusual settings are described here.

grid.pars

Grid graphical parameters that are in effect globally unless overridden by specific settings.

fontsize

A list of two components (each a numeric scalar), text and points, for text and symbols respectively.

clip

A list of two components (each a character string, either "on" or "off"), panel and strip.

axis.components

A list with four components (left, top, right, bottom), each a list giving numeric mutlipliers named tck, pad1, and pad2 for corresponding grid layout units.

layout.heights

A list with numeric multipliers for grid layout heights.

layout.widths

A list with numeric multipliers for grid layout widths.

Note

In some ways, trellis.par.get and trellis.par.set together are a replacement for the par function used in traditional R graphics. In particular, changing par settings has little (if any) effect on lattice output. Since lattice plots are implemented using Grid graphics, its parameter system does have an effect unless overridden by a suitable lattice parameter setting. Such parameters can be specified as part of a lattice theme by including them in the grid.pars component (see gpar for a list of valid parameter names).

Author(s)

Deepayan Sarkar Deepayan.Sarkar@R-project.org

See Also

trellis.device, Lattice, gpar

Examples

show.settings()

tp <- trellis.par.get()

unusual <- c("grid.pars", "fontsize", "clip", "axis.components",
             "layout.heights", "layout.widths")

for (u in unusual) tp[[u]] <- NULL
names.tp <- lapply(tp, names)
unames <- sort(unique(unlist(names.tp)))
ans <- matrix(0, nrow = length(names.tp), ncol = length(unames))
rownames(ans) <- names(names.tp)
colnames(ans) <- unames
for (i in seq_along(names.tp))
    ans[i, ] <- as.numeric(unames %in% names.tp[[i]])
ans <- ans[, order(-colSums(ans))]
ans <- ans[order(rowSums(ans)), ]
ans[ans == 0] <- NA

levelplot(t(ans), colorkey = FALSE, 
          scales = list(x = list(rot = 90)),
          panel = function(x, y, z, ...) {
              panel.abline(v = unique(as.numeric(x)), 
                           h = unique(as.numeric(y)), 
                           col = "darkgrey")
              panel.xyplot(x, y, pch = 16 * z, ...)
          },
          xlab = "Graphical parameters", 
          ylab = "Setting names")
[Package lattice version 0.22-6 Index]