Package R.devices

Description

Functions for creating plots and image files in a unified way regardless of output format (EPS, PDF, PNG, SVG, TIFF, WMF, etc.). Default device options as well as scales and aspect ratios are controlled in a uniform way across all device types. Switching output format requires minimal changes in code. This package is ideal for large-scale batch processing, because it will never leave open graphics devices or incomplete image files behind, even on errors or user interrupts.

To get started

• Vignette 'R.devices overview'

• toEPS(), toPDF(), toPNG(), ... - evaluate graphics code and atomically save plot to a figure file.

How to cite this package

To cite this package, please use:

@Manual{,
  title = {R.devices: Unified Handling of Graphics Devices},
  author = {Henrik Bengtsson},
  year = {2024},
  note = {R package version 2.17.2,
https://github.com/HenrikBengtsson/R.devices},
  url = {https://henrikbengtsson.github.io/R.devices/},
}

License

LGPL (>= 2.1).

Author(s)

Henrik Bengtsson [aut, cre, cph].

The DevEvalFileProduct class

Description

Package: R.devices
Class DevEvalFileProduct

character
~~|
~~+--BasicObject
~~~~~~~|
~~~~~~~+--DevEvalProduct
~~~~~~~~~~~~|
~~~~~~~~~~~~+--DevEvalFileProduct

Directly known subclasses:

public class DevEvalFileProduct
extends DevEvalProduct

A DevEvalFileProduct is a DevEvalProduct referring to a image file created by devEval().

Usage

DevEvalFileProduct(filename=NULL, path=NULL, ...)

Arguments

Fields

The following (virtual; calculate on-the-fly) fields are available:

• pathname: the (relative) pathname of the image file, e.g. 'figures/foo,a,b.png'. This can be used to link to image files in for instance HTML and Markdown documents.

• path, the (relative) path to the image file, e.g. 'figures/'

• filename: the filename ("basename") of the image file, e.g. 'foo,a,b.png'

• fullname: the fullname (the filename without the filename extension), e.g. 'foo,a,b'. It is recommended to use this when including images in LaTeX documents that use the \usepackage{graphicx} package.

• name: the part of the fullname before the first comma, e.g. 'foo'

• tags: the part of the fullname after the first comma, e.g. 'a,b'

• dataURI: the Base64-encoded Data URI representation of the image, e.g. 'data:image/png;base64,iVBORw0KGgoAAAA...'. This can be used to include ("inlining") image files in for instance self-contained HTML and Markdown documents.

• data: the character content of the image file. This can be used to include ("inlining") WebGL HTML-based image files in for instance self-contained HTML and Markdown documents.

Author(s)

Henrik Bengtsson

See Also

In order to retrieve the Data URI, the base64enc package must be installed.

The DevEvalProduct class

Description

Package: R.devices
Class DevEvalProduct

character
~~|
~~+--BasicObject
~~~~~~~|
~~~~~~~+--DevEvalProduct

Directly known subclasses:
DevEvalFileProduct

public class DevEvalProduct
extends BasicObject

A DevEvalProduct represents a handle to the "product" returned by devEval().

Usage

DevEvalProduct(name=NULL, tags=NULL, type=NULL, ...)

Arguments

Fields

The following (virtual; calculate on-the-fly) fields are available:

• fullname: the fullname of an image, e.g. 'foo,a,b'

• name: the part of the fullname before the first comma, e.g. 'foo'

• tags: the part of the fullname after the first comma, e.g. 'a,b'

Author(s)

Henrik Bengtsson

Non-documented objects

Description

This page contains aliases for all "non-documented" objects that R CMD check detects in this package.

Almost all of them are generic functions that have specific document for the corresponding method coupled to a specific class. Other functions are re-defined by setMethodS3() to default methods. Neither of these two classes are non-documented in reality. The rest are deprecated methods.

Author(s)

Henrik Bengtsson

Get the architecture of an object or coerce it into another

Description

Get the architecture of an object or coerce it into another

Usage

architecture(x, ...)

as.architecture(
  x,
  ostype = .Platform$OS.type,
  arch = R.version$arch,
  ptrsize = .Machine$sizeof.pointer,
  endian = .Platform$endian,
  ...
)

Arguments

Value

architecture() returns a named list with character element ostype and arch, integer element ptrsize, and character element endian. These elements take a missing values if they could not be inferred.

as.architecture() returns a coerced version of x. If no coercion was needed, then x itself is returned.

Gets a character representation of the product

Description

Gets a character representation of the product.

Usage

## S3 method for class 'DevEvalProduct'
as.character(x, ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see DevEvalProduct.

Check whether current R session supports X11 or not

Description

Check whether current R session supports X11 or not.

Contrary to capabilities("X11") which only checks for X11 support on startup [1], this function checks whether X11 is supported when it is called. This is done by querying a temporary R session.

Usage

capabilitiesX11(reset=FALSE, ...)

Arguments

Value

Returns TRUE if X11 is supported, otherwise FALSE.

Author(s)

Henrik Bengtsson

References

[1] R-devel thread 'capabilities("X11"): Force refresh from within R? (... and minor documentation issue)' on 2015-05-06, https://stat.ethz.ch/pipermail/r-devel/2015-May/071100.html

See Also

capabilities()

Captures a plot such that it can be redrawn later/elsewhere

Description

Captures a plot such that it can be redrawn later/elsewhere.

This feature is only supported in R (>= 3.3.0).

Usage

capturePlot(expr, envir=parent.frame(), type=nulldev, ...)

Arguments

Details

Note that plot dimensions/aspect ratios are not recorded. This means that one does not have to worry about those when recording the plot. Instead, they are specified when setting up the graphics device(s) in which the recorded plot is replayed (see example).

Value

Returns a recordedplot object, which can be replayPlot():ed. If replayed in an interactive session, the plot is displayed in a new window. For conveniency, the object is also replayed when print():ed.

Replaying / replotting on a different architecture

In order to replay a recordedplot object, it has to be replayed on an architecture that is compatible with the one who created the object. If this is not the case, then replayPlot() will generate an Incompatible graphics state error. The as.architecture() function of this package tries to coerce between different architectures, such that one can replay across architectures using replayPlot(as.architectures(g)). For convenience, the recorded plot returned by capturePlot() is automatically coerced when print():ed.

Author(s)

Henrik Bengtsson

References

[1] Paul Murrell et al., Recording and Replaying the Graphics Engine Display List, December 2015. https://www.stat.auckland.ac.nz/~paul/Reports/DisplayList/dl-record.html

See Also

Internally recordPlot() is used.

Examples

if (getRversion() >= "3.3.0") {
oopts <- R.devices::devOptions("*", path=file.path(tempdir(), "figures"))

g <- capturePlot({
  plot(1:10)
})

## Display
print(g)

## Display with a 2/3 height-to-width aspect ratio
toDefault(aspectRatio=2/3, { print(g) })

## Redraw to many output formats using whatever PNG, EPS, and PDF
## device outputs available
devEval(c("{png}", "{eps}", "{pdf}"), aspectRatio=2/3, print(g))

R.devices::devOptions("*", path=oopts$path)
} ## if (getRversion() >= "3.3.0")

Closes zero or more open devices except screen (interactive) devices

Description

Closes zero or more open devices except screen (interactive) devices.

Usage

devDone(which=dev.cur(), ...)

Arguments

Value

Returns (invisibly) dev.cur().

Author(s)

Henrik Bengtsson

See Also

devOff(). dev.interactive.

Opens a new graphics device, evaluate (graphing) code, and closes device

Description

Opens a new graphics device, evaluate (graphing) code, and closes device.

Usage

devEval(type=getOption("device"), expr, initially=NULL, finally=NULL,
  envir=parent.frame(), name=NULL, tags=NULL, sep=getDevOption(type, "sep",
  default = ","), ..., ext=NULL, filename=NULL, path=getDevOption(type, "path",
  default = "figures"), field=getDevOption(type, name = "field"),
  onIncomplete=c("remove", "rename", "keep"), force=getDevOption(type, "force",
  default = TRUE), which=dev.cur(), .exprAsIs=FALSE, .allowUnknownArgs=FALSE)

Arguments

Value

Returns a DevEvalFileProduct if the device generated an image file, otherwise an DevEvalProduct. If argument field is given, then the field of the DevEvalProduct is returned instead. Note that the default return value may be changed in future releases.

Generated image file

If created, the generated image file is saved in the directory specified by argument path with a filename consisting of the name followed by optional comma-separated tags and a filename extension given by argument ext.

By default, the image file is only created if the expr is evaluated completely. If it is, for instance, interrupted by the user or due to an error, then any incomplete/blank image file that was created will be removed. This behavior can be turned of using argument onIncomplete.

Author(s)

Henrik Bengtsson

See Also

To change default device parameters such as the width or the height, devOptions(). devNew().

Examples

# Plot to PNG using one whatever PNG device driver is available
res <- devEval("{png}", name="MyPlot", tags=c("10", "rnd"), aspectRatio=0.7, {
  plot(1:10)
})
print(res$pathname)
# [1] "figures/MyPlot,10,rnd.png"

str(res$dataURI)
# chr "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAeAA..."

## Plot to PDF using grDevices::pdf()
res <- devEval("pdf", name="MyPlot", tags=c("10", "rnd"), aspectRatio=0.7, {
  plot(1:10)
})
print(res$pathname)
# [1] "figures/MyPlot,10,rnd.pdf"


## Plot to EPS using R.devices::eps()
res <- devEval("eps", name="MyPlot", tags=c("10", "rnd"), aspectRatio=0.7, {
  plot(1:10)
})
print(res$pathname)
# [1] "figures/MyPlot,10,rnd.eps"

Gets the labels of zero or more devices

Description

Gets the labels of zero or more devices.

Usage

devGetLabel(which=dev.cur(), ...)

Arguments

Value

Returns a character vector. If a device does not exist, an error is thrown.

Author(s)

Henrik Bengtsson

See Also

devSetLabel() and devList().

Checks whether a device type is interactive or not

Description

Checks whether a device type is interactive or not.

Usage

devIsInteractive(types, ...)

Arguments

Value

Returns a logical vector with TRUE if the device type is interactive, otherwise FALSE.

Author(s)

Henrik Bengtsson

See Also

Internally, deviceIsInteractive is used.

Checks if zero or more devices are open or not

Description

Checks if zero or more devices are open or not.

Usage

devIsOpen(which=dev.cur(), ...)

Arguments

Value

Returns a named logical vector with TRUE if a device is open, otherwise FALSE.

Author(s)

Henrik Bengtsson

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Use devices for conditional processing of code. 
# Close devices to rerun code.
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cat("Currently opened device:\n")
print(devList())

# Alt A: Use device index counter (starting with the 16:th)
fig <- 15
if (!devIsOpen(fig <- fig + 1)) {
  devSet(fig)
  cat("Figure", fig, "\n")
  plot(1:10)
}
cat("Currently opened device:\n")
print(devList())

if (!devIsOpen(fig <- fig + 1)) {
  devSet(fig)
  cat("Figure", fig, "\n")
  plot(1:10)
}
cat("Currently opened device:\n")
print(devList())

# Alt B: Use device labels
if (!devIsOpen(label <- "part 1")) {
  devSet(label)
  cat("Part 1\n")
  plot(1:10)
}
cat("Currently opened device:\n")
print(devList())


if (!devIsOpen(label <- "part 2")) {
  devSet(label)
  cat("Part 2\n")
  plot(1:10)
}
cat("Currently opened device:\n")
print(devList())

Lists the indices of the open devices named by their labels

Description

Lists the indices of the open devices named by their labels.

Usage

devList(interactiveOnly=FALSE, dropNull=TRUE, ...)

Arguments

Value

Returns a named integer vector.

Author(s)

Henrik Bengtsson

See Also

dev.list().

Opens a new device

Description

Opens a new device.

Usage

devNew(type=getOption("device"), ..., scale=1, aspectRatio=1, par=NULL, label=NULL)

Arguments

Value

Returns the device index of the opened device.

Width and heights

The default width and height of the generated image is specific to the type of device used. There is not straightforward programmatic way to infer these defaults; here we use devOptions(), which in most cases returns the correct defaults.

Aspect ratio

The aspect ratio of an image is the height relative to the width. If argument height is not given (or NULL), it is calculated as aspectRatio*width as long as they are given. Likewise, if argument width is not given (or NULL), it is calculated as width/aspectRatio as long as they are given. If neither width nor height is given, then width defaults to devOptions(type)$width. If both width and height are given, then aspectRatio is ignored.

Author(s)

Henrik Bengtsson

See Also

devDone() and devOff(). For simplified generation of image files, see devEval().

Closes zero or more devices

Description

Closes zero or more devices.

Usage

devOff(which=dev.cur(), ...)

Arguments

Value

Returns dev.cur().

Author(s)

Henrik Bengtsson

See Also

devDone(). Internally, dev.off() is used.

Gets the default device options

Description

Gets the default device options as given by predefined devices options adjusted for the default arguments of the device function.

Usage

devOptions(type=NULL, custom=TRUE, special=TRUE, inherits=FALSE, drop=TRUE,
  options=list(), ..., reset=FALSE)

Arguments

Details

If argument special is TRUE, then the 'width' and 'height' options are adjusted according to the rules explained for argument 'paper' in pdf, postscript, and xfig.

Value

If drop=TRUE and a single device is queries, a named list is returned, otherwise a matrix is returned. If a requested device is not implemented/supported on the current system, then "empty" results are returned. If options were set, that is, if named options were specified via ..., then the list is returned invisibly, otherwise not.

Setting new defaults

When setting device options, the getOption("devOptions")[[type]] option is modified. This means that for such options to be effective, any device function needs to query also such options, which for instance is done by devNew().

Also, for certain devices (eps, pdf, postscript, quartz, windows and x11), builtin R device options are set.

Author(s)

Henrik Bengtsson

Examples

# Tabulate some of the default settings for known devices
print(devOptions()[,c("width", "height", "bg", "fg", "pointsize")])

Activates a device

Description

Activates a device.

Usage

devSet(which=dev.next(), ...)

Arguments

Value

Returns what dev.set() returns.

Author(s)

Henrik Bengtsson

See Also

devOff() and devDone(). Internally, dev.set() is used.

Sets the label of a device

Description

Sets the label of a device.

Usage

devSetLabel(which=dev.cur(), label, ...)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

See Also

devGetLabel() and devList().

EPS graphics device

Description

Device driver for Encapsulated Postscript. This driver is the same as the postscript driver where some arguments have different default values.

Usage

eps(file="Rplot%03d.eps", width=7, height=7, horizontal=FALSE, paper="special",
  onefile=FALSE, ...)

Arguments

Value

A plot device is opened; nothing is returned.

Author(s)

Henrik Bengtsson

See Also

This is just a convenient wrapper for postscript with the proper arguments set to generate an EPS file.

It is recommended to use toEPS() instead.

Examples

## Not run: 
  eps("foo.eps", width=7, height=7)

  # is identical to

  postscript("foo.eps", width=7, height=7, onefile=TRUE, horizontal=FALSE)

  # and

  dev.print(eps, "foo.eps", ...)

  # is identical to

  dev.print(postscript, "foo.eps", onefile=TRUE, horizontal=FALSE, paper="special", ...)

## End(Not run)

Favicon graphics device

Description

Device driver for PNG favicons (Favorite icon) also known as shortcut icon, Web site icon, tab icon or bookmark icon. This driver is the same as the png driver where some arguments have different default values.

Usage

favicon(filename="favicon.png", width=32L, height=width, bg="transparent",
  par=list(mar = c(0, 0, 0, 0)), ...)

Arguments

Value

A plot device is opened; nothing is returned.

Author(s)

Henrik Bengtsson

See Also

Internally, png is used.

Examples

## Not run: 
  favicon(width=32L)

  # is identical to

  suppressWarnings({
    png("favicon.png", width=32L, height=32L, bg="transparent",
                       par=list(mar=c(0,0,0,0)))
  })

## End(Not run)

Gets content as a Base64-encoded data URI

Description

Gets content as a Base64-encoded data URI.

Usage

## S3 method for class 'DevEvalFileProduct'
getDataURI(this, mime=getMimeType(this), ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see DevEvalFileProduct.

Gets the full name, name and tags

Description

Gets the full name, name and tags consisting of a name and tags.

Usage

## S3 method for class 'DevEvalProduct'
getFullname(this, ...)
## S3 method for class 'DevEvalFileProduct'
getFullname(this, ...)
## S3 method for class 'DevEvalProduct'
getName(this, ...)
## S3 method for class 'DevEvalProduct'
getTags(this, collapse=",", ...)

Arguments

Value

Returns a character or a character vector.

Author(s)

Henrik Bengtsson

See Also

For more information see DevEvalProduct.

Gets the MIME type

Description

Gets the MIME type.

Usage

## S3 method for class 'DevEvalFileProduct'
getMimeType(this, default="", ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see DevEvalFileProduct.

Gets the (relative) pathname, filename and path

Description

Gets the (relative) pathname, filename and path.

Usage

## S3 method for class 'DevEvalFileProduct'
getPathname(this, relative=TRUE, ...)
## S3 method for class 'DevEvalFileProduct'
getFilename(this, ...)
## S3 method for class 'DevEvalFileProduct'
getPath(this, ...)
## S3 method for class 'DevEvalFileProduct'
getExtension(this, ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

For more information see DevEvalFileProduct.

Gets the type

Description

Gets the type.

Usage

## S3 method for class 'DevEvalProduct'
getType(this, ...)

Arguments

Value

Returns a character string or NULL.

Author(s)

Henrik Bengtsson

See Also

For more information see DevEvalProduct.

A JPEG device for Bitmap Files via GhostScript

Description

A JPEG device for Bitmap Files via GhostScript.

Usage

jpeg2(filename, width=480, height=480, res=144, type="jpeg", ...)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

A \"null\" graphics device voiding all output

Description

A \"null\" graphics device voiding all output.

Usage

nulldev(file=nullfile(), ...)

Arguments

Details

The null graphics device opens a regular pdf device and directs its output to the null file, which is /dev/null unless on Windows where it is NUL.

Value

A plot device is opened; nothing is returned.

Author(s)

Henrik Bengtsson

Examples

## Not run: 
  nulldev()
  plot(1:3)
  dev.off()

## End(Not run)

A PNG device for Bitmap Files via GhostScript

Description

A PNG device for Bitmap Files via GhostScript.

Usage

png2(filename, width=480, height=480, res=144, type="png256", ...)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

Automatically replays a recorded plot

Description

This is identical to the print() method available in grDevices, but if replaying the plot gives an error it will also try to replay it after coercing the data structure to match the architecture of the current machine. This will make it possible to, for instance, replay a plot generated on a 32-bit machine on a 64-bit machine.

Usage

## S3 method for class 'RecordedPlot'
print(x, ...)

Arguments

Value

Returns x invisibly.

See Also

Internally, as.architecture() is used to coerce to the current architecture.

Methods for creating image files of a specific format

Description

Methods for creating image files of a specific format.

Usage

   toBMP(name, ...)
   toPDF(name, ...)
   toPNG(name, ...)
   toSVG(name, ...)
   toTIFF(name, ...)
   toEMF(name, ..., ext="emf")
   toWMF(name, ..., ext="wmf")

   toFavicon(..., name="favicon", ext="png",
             field=getDevOption("favicon", "field", default="htmlscript"))

   
   toDefault(name, ...)
   toQuartz(name, ...)
   toX11(name, ...)
   toWindows(name, ...)

   
   toCairoWin(name, ...)
   toCairoX11(name, ...)
   

   
   toRStudioGD(name, ..., .allowUnknownArgs = TRUE)
 

Arguments

Value

Returns by default the DevEvalProduct. For toFavicon() the default return value is a character string.

Windows Metafile Format

Both toEMF() and toWMF() use the exact same graphics device (win.metafile()) and settings. They only differ by filename extension. The win.metafile() device function exists on Windows only; see the grDevices package for more details.

Author(s)

Henrik Bengtsson

See Also

These functions are wrappers for devEval(). See devOptions() to change the default dimensions for a specific device type.

Evaluate an R expression with graphical parameters set temporarily

Description

Evaluate an R expression with graphical parameters set temporarily.

Usage

withPar(expr, ..., args=list(), envir=parent.frame())

Arguments

Details

Upon exit (also on errors), this function will reset all (modifiable) graphical parameters to the state of options available upon entry. This means any parameters modified from evaluating expr will also be undone upon exit.

Value

Returns the results of the expression evaluated.

Author(s)

Henrik Bengtsson

See Also

Internally, eval() is used to evaluate the expression, and par to set graphical parameters.

Examples

withPar({
  layout(1:4)

  withPar({
    plot(1:10)
    plot(10:1)
  }, pch=4)

  withPar({
    plot(1:10)
    plot(10:1)
  }, pch=0, bg="yellow")
}, mar=c(2,2,1,1))