trellis.device {lattice} | R Documentation

## Initializing Trellis Displays

### Description

Initialization of a display device with appropriate graphical parameters.

### Usage

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

### Arguments

`device` | function (or the name of one as a character string) that starts a device. Admissible values depend on the platform and how R was compiled (see `Devices`), but usually `"pdf"`, `"postscript"`, `"png"`, `"jpeg"` and at least one of `"X11"`, `"windows"` and `"quartz"` will be available.
`color` | logical, whether the display should be color or black and white. Defaults to `FALSE` for postscript devices, `TRUE` otherwise.
`theme` | list of components that changes 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. These settings are only used to modify the default settings (determined by other arguments), and need not contain all possible parameters. 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, as well as `height`, `width`, etc. See the help file for individual devices for admissible arguments.

### Details

Trellis Graphics functions obtain the default values of various graphical parameters (colors, line types, fonts, etc.) from a customizable “settings” list. This functionality is analogous to `par` for standard R graphics and, together with `lattice.options`, mostly supplants it (`par` settings are mostly ignored by Lattice). Unlike `par`, Trellis settings can be controlled separately for each different device. `canonical.theme` and `col.whitebg` produce predefined settings (a.k.a. themes), while `trellis.device` provides a high level interface to control which “theme” will be in effect when a new device is opened. `trellis.device` is called automatically when a `"trellis"` object is plotted, and the defaults can be used to provide sufficient control, so in a properly configured system it is rarely necessary for the user to call `trellis.device` explicitly.

The `canonical.theme` function is intended to provide device specific settings (e.g. light colors on a grey background for screen devices, dark colors or black and white for print devices) which were used as defaults prior to R 2.3.0. However, these defaults are not always appropriate, due to the variety of platforms and hardware settings on which R is used, as well as the fact that a plot created on a particular device may be subsequently used in many different ways. For this reason, a “safe” default is used for all devices from R 2.3.0 onwards. The old behaviour can be reinstated by setting `canonical.theme` as the default `theme` argument, e.g. by putting `options(lattice.theme = "canonical.theme")` in a startup script (see the entry for `theme` above for details).

### Value

`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 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.

### Note

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; if you feel the need to change the background, consider using the `theme` argument instead.

### Author(s)

Deepayan Sarkar Deepayan.Sarkar@R-project.org

### See Also

`Lattice` for an overview of the `lattice` package.

`Devices` for valid choices of `device` on your platform.

`trellis.par.get` and `trellis.par.set` can be used to query and modify the settings after a device has been initialized. The `par.settings` argument to high level functions, described in `xyplot`, can be used to attach transient settings to a `"trellis"` object.

[Package lattice version 0.13-8 Index]