trellis.device {lattice}R Documentation

Initializing Trellis Displays


trellis.device initializes a Trellis display device with appropriate settings of the graphics control parameters.


trellis.device(device = getOption("device"),
               color = !( == "postscript"),
               theme = lattice.getOption("default.theme"),
               new = TRUE,
               retain = FALSE,
canonical.theme(name, color)


device name of a function (possibly as a character string) that initializes a device. Admissible values include "x11", "windows", "mac", "postscript", "pdf", "png", etc.
color logical, whether the display should be color or black and white. FALSE for postscript devices, TRUE otherwise.
theme list of components that change the settings of the device opened, or, a function that when called produces such a list. The function name can be supplied as a quoted string.
A possible use of this argument is to change the default settings by specifying lattice.options(default.theme = "col.whitebg"). For back-compatibility, this is initially (when lattice is loaded) set to options(lattice.theme).
If theme is a function, it will not be supplied any arguments, however, it is guaranteed that a device will already be open when it is called, so one may use .Device inside the function to ascertain what device has been opened.
new logical flag indicating whether a new device should be started. If FALSE, the options for the current device are changed to the defaults determined by the other arguments.
retain logical. If TRUE and a setting for this device already exists, then that is used instead of the defaults for this device. By default, pre-existing settings are overwritten (and lost).
name name of the device for which the setting is required, as returned by .Device
... additional parameters to be passed to the device function, most commonly file for non-screen devices.


trellis.device calls the device function to start a display, and sets an appropriate component of the variable lattice.theme (in an unexported environment named .LatticeEnv) to appropriate (device-specific) values. The device specific settings are determined by canonical.theme which returns a list (see below). The settings can subsequently be handled by the interface functions trellis.par.get and trellis.par.set.

col.whitebg returns a similar (but smaller) list that is suitable as the theme argument to trellis.device and trellis.par.set. It contains settings values which provide colors suitable for plotting on a white background. Note that the name col.whitebg is somewhat a misnomer, since it actually sets the background to transparent rather than white.


canonical.theme returns a list of components defining graphical parameter settings for Lattice displays. It is used internally in trellis.device, and can also be used as the theme argument to trellis.par.set, or even as theme in trellis.device to use the defaults for another device.
col.whitebg returns a similar but smaller list.


Trellis Graphics is designed to have a different look and feel on different devices. In particular, the default settings for ‘screen’ devices are not at all suitable for printing.

One technique often used to create printable graphs is through use of dev.print and related functions (typically via a GUI menu). Unfortunately, this only copies the display already created, and hence retains the settings used therein, instead of settings suitable for the target device.

The recommended workaround for this is to re-print the trellis object after explicitly starting the new device. The last printed trellis object is typically stored in memory, and it is possible to retrieve it using trellis.last.object.

The other option (relevant especially if the trellis plot is enhanced interactively after plotting) is to start the initial (screen) device with the settings suitable for the eventual target (print) device. For instance, a windows device can be opened with pdf settings with

trellis.device(windows, theme = canonical.theme("pdf"))

Note that earlier versions of trellis.device had a bg argument to set the background color, but this is no longer supported. If supplied, the bg argument will be passed on to the device function; however, this will have no effect on the Trellis settings. It is rarely meaningful to change the background alone, and if you feel the need to change the background, consider using the theme argument.


Deepayan Sarkar

See Also

trellis.par.set, postscript, pdf, x11, Lattice

[Package lattice version 0.12-11 Index]