rasterPlot {dplR}

Add Raster Elements to Plot

Description

This function takes plotting commands and uses a temporary bitmap graphics device to capture their output. The resulting raster image is drawn in the plot or figure region of the active high-level plot. A new plot is started if one does not exist.

Usage

rasterPlot(expr, res = 150, region = c("plot", "figure"), antialias,
           bg = "transparent", interpolate = TRUE, draw = TRUE,
           Cairo = FALSE, ...)

Arguments

expr

Low-level plotting commands (lines, points, text, ...) representing elements to be added to the current plot. A call or an expression.

res

Resolution in points per inch (ppi). A numeric value. Suggested values for different types of display media are given in compactPDF. For example, the default 150 ppi corresponds to “ebook” quality.

region

The function can draw in the "plot" region or the "figure" region which also includes "mar" margins (see par). If the drawing commands in expr contain no material for the margins, the default "plot" is optimal. Plotting in the outer margins ("oma" in par) is not supported.

antialias

Antialiasing argument passed to png. The default (missing argument) is probably good for line plots but "none" is preferred for images in which color signifies value of data. Unused if a Cairo device is used instead of png.

bg

Background color of the raster plot, an argument passed to the bitmap device. If the default "transparent" does not work, try "white" or another color. Note that a non-transparent background will mask any previous content in the figure or plot region, depending on the value of region.

interpolate

Argument passed to rasterImage. A logical flag. The default is TRUE: use linear interpolation. Analogously to antialias, FALSE is preferred when color maps to value.

draw

A logical flag. Draw the results (TRUE, the default) or return an image object (FALSE)?

Cairo

A logical flag. TRUE for preferring a Cairo to png as the bitmap device, FALSE (the default) for the opposite. If the preferred device cannot be used, the other one will be tried.

...

Other arguments to png or Cairo.

Details

The appropriate graphical parameters of the current graphics device are copied to the temporary bitmap device. Therefore the appearance of the raster contents should be almost the same as when directly drawn.

The call or expression expr is evaluated in the environment of the caller.

It is possible that the raster contents will maintain a constant size when the graphics device is resized. If resizing works, however, the image may become distorted. For example, circle symbols will turn into ellipses if the width to height ratio is not maintained (see ‘Examples’). This is in contrast to a standard plot in a display graphics device, e.g. x11, where text and symbols maintain their size when the device is resized.

Value

If draw is TRUE, there is no return value. The function is used for the side effects.

If draw is FALSE, an object of class "nativeRaster" is returned. The object can be used as input for rasterImage or grid.raster. See readPNG. If no bitmap device is available (see ‘Note’), NULL is returned.

Note

• The graphics device used for the output must have support for including raster images. See "rasterImage" in dev.capabilities.

• The R build must have a functional png device, which requires one of the following capabilities: "png", "aqua" or "cairo". Alternatively, a Cairo device from package Cairo must be available with Cairo.capabilities "raster" or "png".

If either of these requirements is not met, at least one message is generated and the function reverts to regular plotting. The bg argument is then handled by drawing a filled rectangle. Also region is honored, but the other settings do not apply.

Author(s)

Mikko Korpela

Examples

library(graphics)
library(stats)

## Picture with various graphical elements
x <- 1:100
y0 <- quote(sin(pi * x / 20) + x / 100 + rnorm(100, 0, 0.2))
y <- eval(y0)
ylab <- deparse(y0)
spl <- smooth.spline(y)
plot(x, y, type = "n", axes = FALSE, ylab = ylab)
usr <- par("usr")
xrange <- usr[2] - usr[1]
xsize <- xrange * 0.4
nsteps <- 8
xmar <- xsize / 20
yrange <- usr[4] - usr[3]
ysize <- yrange / 20
ymar <- 0.5 * ysize
X <- seq(usr[1] + xmar, by = xsize / nsteps, length.out = nsteps + 1)
xleft <- X[-(nsteps + 1)]
xright <- X[-1]
pin <- par("pin")
maxrad <- xsize / 3 * min(1, pin[2] / pin[1])
nrad <- 16
minrad <- maxrad / nrad
Rad <- seq(maxrad, by = (minrad - maxrad) / (nrad - 1), length.out=nrad)
xmar2 <- xmar + maxrad
ymar2 <- (xmar2 / xrange) * pin[1] / pin[2] * yrange
expr <- quote({
    rect(xleft, usr[4] - 1.5 * ysize, xright, usr[4] - ymar,
         col = rainbow(8), border = NA)
    symbols(rep(usr[2] - xmar2, nrad), rep(usr[3] + ymar2, nrad),
            circles = Rad, inches = FALSE, add = TRUE, fg = NA,
            bg = gray.colors(nrad + 1, 1, 0)[-1])
    points(y)
    lines(spl)
})
rasterPlot(expr, res = 50)
box()
axis(1)
axis(2)

## The same picture with higher resolution but no antialiasing
plot(y, type = "n", axes = FALSE, ann = FALSE)
## No content in margin, but region = "figure" and bg = "white"
## paints margin white
rasterPlot(expr, antialias = "none", interpolate = FALSE,
           region = "figure", bg = "white")
## Draw box, axes, labels
parnew <- par(new = TRUE)
plot(x, y, type = "n", ylab = ylab)
par(parnew)

## Draw plot(1:5) with adjusted margins and additional axes.  Some parts
## are drawn with rasterPlot, others normally.  Resize to see stretching.
op <- par(no.readonly = TRUE)
par(mar = c(5.1, 4.1, 2.1, 2.1))
plot(1:5, type = "n", axes = FALSE, ann = FALSE)
expr2 <- quote({
    points(c(2, 4), c(2, 4))
    axis(2)
    axis(3)
})
rasterPlot(expr2, region = "figure", bg = "white")
points(c(1, 3, 5), c(1, 3, 5))
box()
axis(1)
axis(4)
title(xlab = "Index", ylab = "1:5")
par(op)