trellis.device            package: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,
                    ...)

     standard.theme(name, color)
     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 initial settings should be color or
          black and white.  Defaults to 'FALSE' for postscript devices,
          'TRUE' otherwise.  Note that this only applies to the initial
          choice of colors, which can be overridden using 'theme' or
          subsequent calls to 'trellis.par.set' (and by arguments
          supplied directly in high level calls for some settings). 

   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 type (but not
     concurrently for different instances of the same device). 
     'standard.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 'standard.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 'standard.theme' as the
     default 'theme' argument, e.g. by putting 'options(lattice.theme =
     "standard.theme")' in a startup script (see the entry for 'theme'
     above for details).

Value:

     'standard.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. 'canonical.theme' is an alias for
     'standard.theme'.

     '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 of 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

References:

     Sarkar, Deepayan (2008) "Lattice: Multivariate Data Visualization
     with R", Springer. <URL: http://lmdvr.r-forge.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.

