Base Graphics and Devices

The manual An Introduction to R describes the facilities in three groups: high-level plotting functions that create a new plot, low-level plotting functions that add to an existing plot, and interactive functions that read from or add to a plot with a pointing device, together with a list of graphical parameters that customise all of them (An Introduction to R: Graphical procedures). It describes only base graphics and says in its first paragraphs that a separate subsystem in the package grid coexists with base graphics, and that the recommended package lattice builds on it. R Internals explains the reason: the graphics internals were redesigned so that several graphics systems can be installed on top of one graphics engine, and two exist, base graphics (based on the graphics of the S language, with its R code in the package graphics) and grid (R Internals: Graphics). The layers are these.

Source: R Internals: Graphics

The practical consequence is that everything a device can do is available to every system, and that a chart is not tied to a file format: the same call draws on a screen window, into a PNG file or into an SVG file, and only the device changes. A device works in its own units (pixels, big points of 1/72 inch, twips) and the engine hides that from the plotting code. A line of R Internals matters for the rest of this page: some devices keep a display list, a record of the operations that produced the current page, and others do not. Screen devices keep one so they can repaint and resize, file devices normally do not, and dev.copy() and recordPlot() depend on it (see Graphics devices).

The base graphics system is spread over two packages that are always present. The package graphics holds the plotting functions and par(); the package grDevices holds the devices, the colour functions (palette(), colors(), rgb(), hcl.colors()), plotmath, recordPlot() and some helpers that the plotting functions call (boxplot.stats(), nclass.Sturges(), xy.coords(), n2mfrow(), axisTicks()). The split has a historical reason: R Internals says grDevices was created to hold the basic devices and later received functionality that grid also needs, mainly colour handling and the recording and replaying of plots. The generic function plot() is the one exception. R 4.0.0 moved it into base, because it is reasonable to have methods that do not use the graphics package, and the graphics namespace re-exports it so that code importing it from there keeps working (R NEWS: Changes in R 4.0.0). The script asks R where each function lives.

Source: R Internals: Base graphics

find("plot") lists two places because the generic is attached through both packages, while find("hist") and find("png") list one each. environmentName(environment(plot)) is "base", where the generic is defined. The listing of the functions of graphics whose names start with plot shows the generic, its default and function methods, and the three building blocks of the next section: plot.new(), plot.window() and plot.xy(). A fresh session has no device, so the current device is the "null device" with number 1; it accepts no graphics commands. A device is a separate object with its own graphical parameters, a point that returns throughout the page.

Base graphics draws immediately. A call such as points() or text() changes the pixels or the vector page of the current device as it runs and keeps no object that could be edited later, which is the model R inherited from the S language. This differs from lattice and ggplot2, where a plot is an object that can be changed and then printed, and it has three consequences that explain most of the idioms in the rest of the page. First, order matters: the background (a grid, a shaded band) has to be drawn before the marks that sit on it, which is why panel.first exists. Second, the coordinate system has to be fixed before the first mark is drawn: a point outside xlim and ylim is drawn outside the plot region and clipped, and no later call enlarges the page. Third, there is no undo. To change a plot, run the code again from the high-level call.

A high-level function does these things for you in a fixed order. The script builds the same picture from the pieces: plot.new() starts a new page and plot.window() sets the user coordinates, then marks, axes, a box and titles are added. The long vector of names that the script prints is the body of plot.default() itself, read with deparse(): it calls plot.new() and the window, evaluates panel.first, draws the points with plot.xy(), evaluates panel.last, then draws the two axes, the frame and the titles.

Source: R documentation: plot.default

The first par("usr") is c(0.88, 4.12, 1.872, 8.028): the ranges of x (1 to 4) and y (2.1 to 7.8) extended by 4 per cent on each side, the default of the parameters xaxs and yaxs ("r", "regular"). Drawing the same picture with one plot() call gives the same usr. The calls after plot.window() add to the page: the lines() and abline() calls draw on top of what was there and change nothing that was drawn. Calling plot() again starts a new page, which is why a script that wants two charts side by side needs par(mfrow = ...) or layout() (see Several plots on one page).

A single plot is a figure: a plot region surrounded by margins that hold the axes, tick labels and titles. With several figures on a page an outer margin may surround them all (An Introduction to R: Figure margins). Each nesting level has a parameter in lines of text and, usually, a twin in inches or in fractions of the page, and setting one changes the other.

Source: R documentation: par

The script measures them on a 6 by 4 inch device. The inner margins mar are c(5.1, 4.1, 4.1, 2.1) lines of text; one line is par("csi") inches, 0.2 at the default cex and pointsize of 12, so mai is mar times 0.2, which all.equal() confirms. The plot region is the figure minus its margins: 4.76 by 2.16 inches. The default margins were chosen without regard to the size of the device, which is why a short device is mostly margin and why a small PNG fails with figure margins too large (see Errors you will meet).

Source: R documentation: par

plot() is an S3 generic, so what it draws depends on the class of its first argument (S3 Classes and Generics explains the dispatch). The default method draws a scatterplot of two vectors; the other methods draw what is natural for their class. The page of the generic says it is the generic function for the plotting of R objects, and that the default method, formula method and the methods in stats and graphics are documented on their own pages (R documentation: plot).

Source: R documentation: plot.factor

The script checks that each of these methods exists with getS3method(), shows where two of them live, and draws a few. plot(factor(...)) is barplot() of the counts, and the method returns the midpoints that barplot() would return. plot(pages ~ genre_f, data = books) is a box plot because the right-hand side is a factor.

Source: R documentation: plot.formula

The character column is the common stumbling block: plot(pages ~ genre, data = books) does not turn genre into a factor, the method tries to treat it as numbers (NAs introduced by coercion) and fails with need finite 'xlim' values. Convert the column first with factor() or use boxplot(), which does convert it (see Factors). R 4.6.0 added a formula argument to plot.data.frame() so that a data frame can be piped into plot() with a formula: books |> plot(pages ~ year) is plot(books, pages ~ year) (R NEWS: Changes in R 4.6.0).

Most of the arguments of plot.default() are shared by the other high-level functions through .... The help page gives type, xlim, ylim, log, main, sub, xlab, ylab, ann, axes, frame.plot, panel.first, panel.last, asp and, since R 4.6.0, lim2, and passes anything else to par(). The most used graphical parameters are these.

Source: R documentation: points

The pch, col, bg, cex and lwd arguments can be vectors that are recycled, one value for each point, which is how a colour per group is drawn: plot(x, y, col = group) uses the colours of palette() indexed by the integer codes of a factor (see Colours and palettes). The script prints par("usr") after each variation, which is the only place a plot’s geometry is visible. Passing xaxs = "i" removes the 4 per cent margin, xlim and ylim replace the data range, log = "x" puts usr into log10 units (10^usr recovers the data scale), asp = 1 makes the plot region’s aspect match the data’s (the ratio printed is exactly 1), and type = "n" with axes = FALSE and ann = FALSE sets the coordinates and draws nothing at all, the usual start of a hand-built chart. The last example shows the R 4.6.0 argument lim2. By default the limits use every finite x and every finite y, even when the other coordinate of that point is NA and the point cannot be drawn, so one stray large x with a missing y stretches the axis; lim2 = TRUE counts only the points that can be drawn (R NEWS: Changes in R 4.6.0).

Source: R documentation: plot.default

The R FAQ has two entries that matter for plot() arguments. R FAQ 7.13: How can I substitute into a plot label? shows how to put the value of an R object into a label that is an expression (see Mathematical annotation), and R FAQ 7.39: How do I create a plot with two y-axes? says that a plot with two y-axes can be made with par(new = TRUE) but is not recommended.

hist() computes the counts of a numeric vector in cells and draws them as bars; with plot = FALSE it only computes. The result is an object of class histogram with six components, and plot() on it draws the bars, so the computation and the drawing can be separated (hist() calls plot.histogram() with the result). The number of cells comes from breaks: a vector of break points, a single number (a suggestion, because pretty() chooses round numbers), a name ("Sturges", the default, "Scott" or "FD") or a function; nclass.Sturges() is the rule of the default. Cells are right-closed, (a, b], by default, and include.lowest = TRUE closes the first one on the left; right = FALSE makes them left-closed, [a, b). The scale is counts for freq = TRUE (the default when the breaks are equally spaced) and a density for freq = FALSE or probability = TRUE, where the area of the bars is 1.

The script uses the number of days between loan and return of the returned loans (a loan returned before it was lent is a data error in the scenario and is dropped). It prints the six components, shows how the break rules differ, and shows the closed side matters when values fall exactly on a break: four loans lasted exactly 21 days, so with right = TRUE they count in the cell (14, 21] and with right = FALSE in [21, 28).

Source: R documentation: hist

Breaks that do not cover the data are an error (some 'x' not counted; maybe 'breaks' do not span range of 'x'). Two defaults changed in the R 4.x series: the fill colour of hist() and boxplot() is "lightgray" since R 4.0.0 (R NEWS: Changes in R 4.0.0), and the Date and POSIXt methods use the same default since R 4.2.0 (R NEWS: Changes in R 4.2.0); hist(*, log = "x") works without a warning since R 4.5.2 (R NEWS: Changes in R 4.5.2). Histograms of dates are in Dates and Times. The argument panel.first of hist() is new in R 4.6.0 and is the subject of panel.first and panel.last.

barplot() draws bars whose heights are the values of its first argument and, unlike hist(), treats them as categories: it does not count anything, so the input is a table or a vector of counts. A vector gives one bar per element, named by the vector’s names; a matrix gives stacked bars (one bar per column) or, with beside = TRUE, groups of bars side by side. The arguments to know are names.arg, horiz, space (a fraction of the bar width, a pair for grouped bars), legend.text (and args.legend to position it), col, density and angle for shaded bars, ylim, and add. The value is the vector (or, for beside = TRUE, the matrix) of bar midpoints, which is what text(), axis() and segments() need to annotate the bars. For grouped bars colMeans(mp) is the centre of each group.

R 4.6.0 adds orderH for stacked bars: "incr" or "decr" orders the segments of every stack by size, each stack on its own, in increasing or decreasing order instead of the row order (the default "none"). The argument applies when beside is false, that is, to stacked bars (R NEWS: Changes in R 4.6.0). There is also a formula method, barplot(n ~ genre, data = df), that takes the heights from a data frame; it was added in R 3.6.0 (R NEWS: Changes in R 3.6.0).

Source: R documentation: barplot

The first table is the number of loans per month, the first piece of the figure at the end of the page. A two-way table() of status and genre is the natural stacked input: barplot(tab) has six bars (one per genre) with two segments (out, returned). Passing plot = FALSE returns the midpoints without drawing, useful for computing positions in advance, and legend.text = TRUE uses the row names of the matrix.

boxplot() computes five-number-style summaries per group and draws them with bxp(). It accepts a formula and a data frame (boxplot(pages ~ genre, data = books)), a list of vectors, a matrix (one box per column) or a single vector. The box spans the lower and upper hinges (the median of each half of the data, computed by fivenum()), the thick line is the median, the whiskers reach the most extreme data within range times the hinge spread (the argument range, 1.5 by default, passed to boxplot.stats() as coef), and the points beyond are outliers. range = 0 sends the whiskers to the data extremes. The other arguments are horizontal, notch (a confidence interval for the median, drawn as a notch), varwidth (box width proportional to the square root of the group size), outline (draw the outliers or not), names, at for positions, add and boxwex.

The value is a list with stats (a 5-row matrix, one column per box), n, conf (the notch limits), out and group (the outlying values and the box each belongs to) and names. boxplot.stats() (R documentation: boxplot.stats) computes one such summary for one vector, so it can be used without drawing. Four groups of the shelf have only two books each, so their columns of stats show a box that collapses: with n = 2 the hinges are the two data values, the whiskers end at them and no outlier can exist. The notched version warns when a notch extends past its hinges, which it does here for the small groups; the warning text is some notches went outside hinges ('box'): maybe set notch=FALSE.

Source: R documentation: boxplot

The R NEWS entry for 4.1.0 says boxplot() now accepts labels such as ylab like plot() does; R 4.1.1 made gap.axis an argument of axis() that bxp() passes along, and R 4.6.0 added panel.first and panel.last to bxp() and hence to boxplot() (see panel.first and panel.last).

curve() draws the curve of an expression in x or of a function over an interval and returns the points it computed as a list with the components x and y, so curve() doubles as a sampler: curve(dnorm(x, 21, 8), 0, 42, n = 5) returns five points. The arguments are from, to, n (101 points by default), add, type ("l" by default) and xname (the name of the variable when it is not x). Without from and to (or xlim) the interval is 0 to 1 for a new plot and, for add = TRUE, the x-limits used for the previous plot; the points are equally spaced on the scale of the axis, so on a logarithmic axis they are equally spaced in log scale. plot() on a function calls the same code with the same arguments, as plot.function(). The scripts in the page and in Distributions and Random Numbers use it for densities.

Source: R documentation: curve

The other high-level functions are one-liners that this page does not need to repeat, but a few points are worth knowing. qqnorm() returns the theoretical quantiles with the sample values and qqline() adds the reference line (R documentation: qqnorm); stem() prints a stem-and-leaf display as text; stripchart(), dotchart() and pie() show one value per label; pairs() draws a scatterplot matrix; matplot() plots the columns of one matrix against the columns of another; mosaicplot() shows a contingency table as areas; image(), contour() and persp() take a matrix and draw it as coloured cells, as lines of equal height and as a perspective surface, which returns the 4 by 4 viewing matrix that trans3d() uses to add points to the surface; smoothScatter() replaces thousands of points by a smoothed density (it needs KernSmooth, a recommended package).

The pie chart is on the list because it exists, not because it is recommended: the help page of pie() says that pie charts are a very bad way of displaying information because the eye is good at judging linear measures and bad at judging relative areas, and that a bar chart or a dot chart is a preferable way of displaying this type of data (R documentation: pie). dotchart() and barplot() give the same information with positions on a common scale. The dotchart() call in the script is given as.vector(counts) and names; given a table directly it warns that 'x' is neither a vector nor a matrix: using as.numeric(x).

Source: R documentation: stripchart

points() and lines() add points and connected line segments (the type argument decides which, as for plot()); abline() draws a straight line over the whole plot region: abline(h = y) horizontal, abline(v = x) vertical, abline(a = intercept, b = slope) or abline(coef = c(a, b)), and abline(fit) for a fitted lm with a single predictor, which is how a regression line is added. segments() draws line segments between pairs of points, arrows() the same with arrow heads (length in inches, code = 2 for a head at the end), rect() rectangles, polygon() filled polygons, and symbols() circles, squares or stars whose size comes from data (inches = FALSE scales in user units). grid() draws a background grid aligned with the tick marks, rug() ticks along an axis for the data values, and box() the frame. The script draws all of them on a plot set up with type = "n", shows that withVisible(points(...)) is a NULL that is not printed, and reproduces the error text for a low-level call with no plot underneath.

Source: R documentation: abline

The error plot.new has not been called yet is the typical symptom of a script that draws on a device where the high-level call failed or was skipped: the points() after it is the call that reports the problem. The other errors shown are mismatched lengths ('x' and 'y' lengths differ) and a missing argument (argument "xright" is missing, with no default).

text() writes at user coordinates; pos (1 below, 2 left, 3 above, 4 right) puts the label beside a point, adj justifies it, offset moves it away, and cex, col, font and srt (rotation) style it. mtext() writes in the margins: side is 1 bottom, 2 left, 3 top, 4 right, line counts lines of text outward from the plot region, at and adj place it along the margin, and outer = TRUE uses the outer margin. title() adds titles (the high-level functions call it). axis() draws an axis on one side, with tick marks at chosen positions and labels, las for the orientation of the labels (0 parallel to the axis, 1 horizontal, 2 perpendicular, 3 vertical); it returns the positions of the ticks it drew, and axTicks() and pretty() compute the same default positions. The usual way to draw a custom axis is to suppress the default with xaxt = "n" (or axes = FALSE) in the high-level call and draw it with axis(), as the script does. strwidth() and strheight() measure text in user units, inches or fractions of the figure, so a label or a legend can be sized before it is drawn.

legend() draws a legend. Its position is a keyword ("topright", "bottom", "center" and the others in the error message below) or x and y coordinates, and inset moves a keyword position in from the margin as a fraction of the plot region. The entries are legend (a character vector or, for mathematics, an expression vector), with col, pch, lty, lwd for lines and points, fill for coloured boxes, bty = "n" to remove the box, ncol or horiz for the layout, title for a heading, bg for the background. It returns the rectangle and the text positions invisibly, as list(rect = list(w, h, left, top), text = list(x, y)), so code can place something next to a legend. R 4.2.0 vectorised cex, x.intersp and text.width and added title.cex and title.font (R NEWS: Changes in R 4.2.0). Errors are 'arg' should be one of ... for an unknown keyword, argument "legend" is missing, with no default, and 'at' and 'labels' lengths differ, 3 != 2 for axis().

Source: R documentation: legend

Because the page is drawn with a pen, drawing a grid or a shaded band behind the data needs the call to be made after the coordinates exist and before the marks. The argument panel.first of plot.default() is evaluated after the plot window is set up and before any plotting takes place, panel.last after the plotting but before the axes and the title are added. Both are expressions evaluated lazily by the method, which is why they work as arguments: plot(x, y, panel.first = grid()). The help warns that this works by lazy evaluation and that passing the argument on from another function may well not work, because it may be evaluated too early.

R 4.6.0 extended the idea (R NEWS: Changes in R 4.6.0). Its NEWS lists a new argument panel.first for hist() (through plot.histogram()), barplot() and bxp(), and with it boxplot(), and says that all of them except hist() also gain panel.last. So hist() has panel.first only. Two things differ between the functions, and the script shows both. plot.default(), barplot() and hist() take an expression; bxp() takes a function that it calls without arguments (its help page stresses that it is a function and not an expression), so for a box plot it is boxplot(y, panel.first = \() grid()), with a lambda. Passing an expression there evaluates it too early, on whatever plot is current, and bxp() then warns panel.first ignored, it is not a function. And hist() has no panel.last: the argument travels on to the graphical parameters of axis() and title(), which warn "panel.last" is not a graphical parameter.

Source: R documentation: plot.histogram

Older code reaches the same result with a first call that sets up the plot and type = "n", then grid(), then the marks with points(), which still works and is what to use when the function has no panel.first (such as plot.lm() or most of the other methods).

The interactive functions read from the pointing device of a screen window. locator(n) waits for n clicks (the left mouse button; any other button ends it) and returns a list with the components x and y, which is a quick way to find the position for a legend or a label; identify(x, y, labels) lets the user click near points and returns the indices of the points selected, labelling them as it goes (An Introduction to R: Interacting with graphics). They need a device that has a pointer. On a file device they do not wait: locator() returns NULL and identify() returns integer(0) at once, and dev.capabilities("locator") says whether a device supports it. The script runs them on pdf(NULL) to show that; an interactive session on a screen device is the fragment after it, which is never run here.

Source: R documentation: locator

This fragment is the interactive use from the manual. It is not run here, because the container has no display and locator() would wait for a click that never comes on a screen device.

Source: An Introduction to R: Interacting with graphics

locator() and identify() are as far as base graphics goes: R itself has no built-in dynamic or interactive graphics, such as rotating a point cloud or "brushing" (interactively highlighting) points across linked plots (An Introduction to R: Dynamic graphics). The manual points to two add-ons for that. The first is the GGobi system, reached from R through the rggobi package; that route is out of date, because rggobi was archived from CRAN on 2020-07-15 (CRAN: rggobi). The second is the rgl package, which is still maintained and draws interactive 3D plots with OpenGL, such as surfaces that can be rotated with the mouse (CRAN: rgl, package documentation). Interactive charts in a web browser are a different route again: a Shiny app re-draws a base or ggplot2 plot when an input changes, as Shiny, plumber and Web APIs shows.

A single parameter that is queried comes back as a plain vector, several come back as a list named by the parameters, and par() with no arguments returns all of them (72 on R 4.6.1), of which par(no.readonly = TRUE) returns the 66 that can be set. Setting parameters returns their previous values, invisibly, as a list that par() accepts back, and the help page points out the inconsistency: setting one parameter returns a list while querying one returns a vector. This gives the idiom for code that must not leave the device changed: save the old values, change what is needed, restore them, and put the restoring call in on.exit() so that it runs even when the drawing code fails.

Source: R documentation: par

The idiom matters most in functions. A function that calls par(mfrow = c(1, 2)) and does not restore changes the layout of every later plot in the session, and a plot function from a package that does so is a classic surprise. The restoring call is par(op) where op is the list returned by the setting call. The script also shows that parameters belong to the device: a new device starts from its own defaults and dev.off() returns to the earlier device with its parameters as they were.

The table lists the parameters that most scripts touch, with the value each has on a fresh device (the ones printed by the scripts of this section) and the way to set it. The help page lists all of them.

Source: R documentation: par

Some of them can be given as arguments of a single call, with an effect only for the duration of the call (plot(x, y, las = 1, cex.axis = 0.8)), and the others only through par(): mfrow, mfcol, mfg, mar, mai, mex, oma, omd, omi, fig, fin, pin, plt, ps, pty, usr, xlog, ylog, ask, new, lheight and ylbias (the help page lists them). R Internals warns that there is confusion between graphical parameters and the arguments of the same name of graphics functions, and that the arguments bg, cex, col, lty, lwd and pch of plot.default() and points() may be vectors and may mean something different from the parameter (R Internals: Base graphics). For example, the cex argument of points() multiplies par("cex"), and bg of points() is the fill of the symbols pch = 21:25, while par(bg = ) is the background of the device region and, when called through par(), also sets new = FALSE.

Source: R documentation: par

Six parameters can be queried but never set: cin, cra, csi, cxy, din and page. Setting one is a warning, not an error, with the text graphical parameter "cin" cannot be set, and par(no.readonly = TRUE) leaves them out so that restoring a saved list is never a problem. R 4.2.0 added another warning for a misuse that looked reasonable (R NEWS: Changes in R 4.2.0): usr <- par("usr"); par(usr) passes an unnamed value, and par() now warns argument 1 does not name a graphical parameter instead of silently doing something else. Unknown names are the same kind of warning: "nosuch" is not a graphical parameter. A wrong value is an error: graphical parameter "mfrow" has the wrong length, or invalid value specified for graphical parameter "mfrow".

Source: R documentation: par

par(op) with op <- par(no.readonly = TRUE) is allowed but blunt. The Note of the help page says restoring all settable parameters is hard to predict if the device was resized, because several of them set the same things in different ways and the last in alphabetical order wins: mai, mar, pin, plt and pty interact, as do the outer margins, the figure layout and the figure region size. Save and restore only the parameters the function changed.

par(mfrow = c(2, 2)) divides the page into a 2 by 2 grid filled by row (mfcol fills by column), and par("mfg") says which cell the next plot goes to. R-intro adds a detail that surprises people: setting mfrow or mfcol reduces the base size of symbols and text, by a factor of 0.83 with exactly two rows or two columns and by 0.66 with three or more of either (An Introduction to R: Multiple figure environment). The script shows par("cex") become 0.83 and 0.66, which is why labels shrink on a multi-panel figure even though nothing asked for it; set cex again after mfrow if the text should keep its size. Outer margins reserve space around all the plots for a title: mtext(..., outer = TRUE) writes there. The parameter xpd lets drawing leave the plot region (TRUE clips to the figure region, NA to the whole device), which is how text is placed in a margin at data coordinates, and new = TRUE makes the next high-level call draw on the same page instead of a new one, the way to overlay two plots with different scales, for which the R FAQ gives par(new = TRUE) and then says it is not recommended (R FAQ 7.39: How do I create a plot with two y-axes?).

Source: R documentation: par

layout() is the general form of mfrow. It takes a matrix of figure numbers, with 0 for an empty cell and a repeated number for a figure that spans cells, and optional widths and heights (relative numbers, or absolute centimetres with lcm()) and respect to keep a unit of width and height the same physical size. It returns the number of figures, layout.show(n) draws the outlines of the next n figures, and layout(1) returns to a single figure. The matrix must contain every number from 1 to the largest, or R stops with layout matrix must contain at least one reference to each of the values {1 ... 3}. The help page gives a limit of 200 rows and columns and 10007 cells. n2mfrow() proposes a grid for a number of plots (3 by 2 for five), and the older split.screen() divides a device into screens that screen(n) selects. The help page of split.screen() says its functions are totally incompatible with par(mfrow), par(mfcol) and layout(), so choose one mechanism per page. For anything more flexible than a grid of plots, grid viewports (see Grid Graphics and Lattice) are the better tool.

Source: R documentation: layout

The palette is the list of colours that col = 1 to col = 8 select, and it is set once for all devices of the session. R 4.0.0 replaced the default palette with colours that are less saturated and have better accessibility properties, and kept the old one under the name "R3" (R NEWS: Changes in R 4.0.0). The old palette (black, red, green3, blue, cyan, magenta, yellow, gray) is made of strongly saturated primaries; the new one starts from black, then "#DF536B", "#61D04F", "#2297E6" and so on. A tutorial that says "colour 2 is red" is describing the R3 palette. The same release added palette.pals(), which lists the built-in palettes, and palette.colors(), which selects colours from any of them without changing the session palette: the default "Okabe-Ito" is a palette of eight colours designed to be distinguishable by readers with colour vision deficiencies, and asking for more colours than a palette has gives a warning and all of them ('n' set to 9, the maximum available for Okabe-Ito palette). R 4.4.0 added an argument that returns named colours; the NEWS calls it name, while the signature and the help page call it names.

Source: R documentation: palette

palette(value) sets the session palette and returns the previous one invisibly, so the same save-and-restore idiom as for par() applies, with on.exit(palette(old)). Changing the palette changes every later plot, in every package, until it is restored, so library code should pass col = vectors to the plot calls rather than set the palette.

hcl.colors(n, palette) (R 3.6.0) makes n colours from one of more than a hundred named palettes defined in the HCL space (hue, chroma, luminance), and hcl.pals(type) lists them by type: "qualitative", "sequential", "diverging" and "divergingx". It was introduced to give a wide range of palettes with much better perceptual properties than the RGB- and HSV-based ones such as rainbow(); R 3.6.0 also based the default colours of image() and filled.contour() on it and gave rainbow() and the other generators a rev argument (R NEWS: Changes in R 3.6.0). The palettes "Rocket" and "Mako" came in R 4.1.0, the handling of alpha in the palette functions was fixed in R 4.3.0, and a bug in hcl.colors(2, ...) was fixed in R 4.3.1 (R NEWS: Changes in R 4.1.0, R NEWS: Changes in R 4.3.0 and R NEWS: Changes in R 4.3.1). The help page makes recommendations that are worth following: "viridis" is a robust default, "Dark 3" works for shading points or lines in up to five groups, "YlGnBu" is a sequential palette similar to viridis but with aligned chroma and luminance, and "Green-Brown" and "Blue-Red 3" are colourblind-safe diverging palettes (R documentation: hcl.colors and palettes). The legacy generators rainbow(), heat.colors(), terrain.colors(), topo.colors() and cm.colors() are defined by hue sweeps in RGB or HSV space; the same help page says the rainbow palette has been widely criticised for its many perceptual problems, is very flashy and unbalanced in chroma and luminance, and recommends a palette from hcl.colors() instead.

The script puts a number on that. It converts the colours to the CIE Lab space and prints the lightness of each: hcl.colors(7, "viridis") steps up from 16 to 90 without a reversal, rainbow(7) jumps between 35 and 89 (yellow, green and cyan are about equally light and the blue-violet is dark), and the Okabe-Ito colours differ in lightness on purpose so that they stay distinguishable in grey. Lightness that rises monotonically survives photocopying or a greyscale print; rainbow() does not.

Source: R documentation: hcl.colors

A short rule follows. For categories up to about eight, use palette.colors(n, "Okabe-Ito") or hcl.colors(n, "Dark 3"); for an ordered quantity, a sequential palette such as hcl.colors(n, "YlGnBu") (rev = TRUE puts the light end where the small values are); for values that diverge from a centre, hcl.colors(n, "Blue-Red 3"); and give col = explicitly in functions that you share, because the session palette is global.

Each call to a device function opens a new device and makes it the current one, to which all drawing goes. The manual lists the functions that manage several devices: dev.list() gives the number and name of every active device (position 1, the null device, is never in the list), dev.cur() the current one, dev.set(which) switches, dev.next() and dev.prev() walk the list, and dev.off(which) closes one and returns the device that becomes current (An Introduction to R: Multiple graphics devices). graphics.off() closes them all. The return value of dev.off() is the one that is visible in a console after every plot: it is null device 1 when it closed the last one.

Source: R documentation: dev.cur and dev.off

Closing is not optional for a file device. The file is written while the device is open and finished when it is closed; an SVG file is empty until dev.off(), a PDF lacks its trailer, and a script that forgets the call leaves a damaged or empty file and a device that the next plot call draws on. The safe pattern is the one in Wrapping a device in a function.

If no device is open, any high-level graphics function opens one. Which one is the value of the option device: a screen device for most interactive use, and pdf(), or the setting of the environment variable R_DEFAULT_DEVICE, otherwise (R documentation: Devices). With Rscript that is pdf() with its default file name, Rplots.pdf, in the working directory. This is the most common way to find a stray file in a project directory, and anything that calls a plotting function or par() triggers it, including a package function that plots as a side effect. The script shows the file appearing and removes it; the getOption("device") value is a function in this setting, not a name. options(device = ) replaces the default with any function that opens a device, such as one that writes no file, and dev.new() opens a device of the default kind; if Rplots.pdf is taken it picks Rplots1.pdf and says so in a message.

Source: R documentation: Devices

The environment variable changes the default without editing a script. This is a shell fragment, not one of the scripts above; it ran once in the same container to confirm that the file name is Rplot001.png and not Rplots.pdf.

Source: R documentation: Devices

The R FAQ’s entry 7.19 on PNG graphics in batch mode says that where the installation supports the type = "cairo" option to png() there should be no problem, and the default settings should just work (R FAQ 7.19: How do I produce PNG graphics in batch mode?). Older tutorials told batch users to start an X virtual framebuffer, or to use bitmap() with Ghostscript, which this entry also mentions as alternatives; neither is needed on a build with cairo.

The four bitmap devices take the same arguments: filename (with a C integer format for the page number, Rplot%03d.png by default), width and height, units, pointsize, bg, res and type. The units are the trap. The default is pixels, 480 by 480, which at the nominal 72 ppi is a 6.7 inch square; units = "in" (or "cm", "mm") needs res, the resolution in pixels per inch, and without it png() stops with 'res' must be specified unless 'units = "px"'. The script reads the dimensions back from the PNG header, so the pixel size is checked and not assumed: 6 by 4 inches at 300 ppi is 1800 by 1200 pixels.

Text is sized in points, and a point is 1/72 inch at the resolution of the device, so the same pixel size at a different res is a different page in inches while 12 point text stays 0.2 inch tall. A 1800 by 1200 pixel device at 300 ppi is a 6 by 4 inch page, a good size for a figure; at 72 ppi it is a 25 by 16.7 inch page on which the same text is small. When a figure comes out with tiny text, res is the first thing to set. The opposite problem is a device too small for the default margins: a 200 by 100 pixel PNG at 72 ppi is 2.8 by 1.4 inches, the default vertical margins alone take 1.8 inches, and plot() stops with figure margins too large. Set mar smaller or make the device larger. Every bitmap device writes a new file for every new page, and the file name should contain %03d or later pages are lost: with a fixed name the file contains the last page plotted (R documentation: png).

Source: R documentation: png, jpeg, tiff and bmp

capabilities() reports what the build supports: in the container cairo, png, jpeg and tiff are TRUE and X11 is FALSE, which is why no screen device can open there. type = "cairo" is the default where cairo is available (getOption("bitmapType") says which), and it is the variant that works without a display, allows semi-transparent colours and gives anti-aliased text and lines. The help page lists others, "Xlib" (needs an X11 display) and "quartz" (macOS), and "cairo-png", which uses cairographics' own PNG writer, never uses a palette and normally gives a larger 32-bit file. On Windows the bitmap devices are drawn with the operating system’s GDI calls and their usage differs; the page of png() documents the platform differences, and this page was run on Linux. bg = "transparent" makes a PNG with a transparent background; JPEG supports only opaque ones. PNG is the right format for charts, lines and blocks of colour, JPEG is lossy and suits photographs and image plots, tiff() writes uncompressed lossless files by default, with compression choices, and bmp() is a standard Windows format. By default no resolution is recorded in the file (except for BMP), and viewers often assume 72 ppi, so set res when the file will be placed in a document at a known size.

pdf() is the default file device and a multi-page one: with onefile = TRUE every new plot is a new page of the same file, and with onefile = FALSE it writes one file per page, using a C integer format in the name. The script counts three pages in a three-plot file and shows page01.pdf and page02.pdf for the other mode. Notable arguments are width and height in inches (7 by 7 by default), paper ("special" by default, a page size such as "a4" centres the device region on it), family (a PDF font family, Helvetica by default), pointsize, bg, title, compress, and, since R 4.5.0, author, timestamp and producer, where timestamp = FALSE omits the creation and modification dates and producer = FALSE the producer field, which helps to produce identical files. Since R 4.0.0 the default of useDingbats is FALSE, so no symbol font is used for the plotting symbols (R NEWS: Changes in R 4.0.0). The device does not embed fonts in the file, so only the standard families (Helvetica, Times, Courier and their aliases "sans", "serif" and "mono") are safe everywhere, and the 8-bit encoding of the font limits the characters: a character outside it is a warning, and R 4.4.0 made the warning show the UTF-8 character and one dot per character instead of per byte (R NEWS: Changes in R 4.4.0). For text with accents beyond Latin-1, Greek or symbols, cairo_pdf() supports a much wider range of UTF-8 glyphs and embeds the fonts it uses; the price is that it may record bitmaps instead of vector graphics in some cases, and it needs cairo (capabilities("cairo")). cairo_pdf() and cairo_ps() default to onefile = TRUE since R 4.4.0, to match pdf() and postscript().

pdf(NULL) is the device of this page. With file = NULL no file is created and, effectively, nothing is drawn, but the device can still be asked for text widths, which is why scripts and tests that need a device without a file, and the examples of this page, use it; par() and strwidth() work on it as on any other device. postscript() is the older vector format: with onefile = FALSE it writes Encapsulated PostScript (the first line of the file says EPSF). Since R 4.3.3, passing filename = NA to svg(), cairo_pdf(), cairo_ps() or the cairo bitmap devices is an error and no longer opens a file called NA, and postscript(NULL), which some people expected to work as pdf(NULL) does, is an error too (R NEWS: Changes in R 4.3.3).

Source: R documentation: pdf

svg() is a cairo device and writes SVG 1.1 (the multi-page form is SVG 1.2, which never passed the draft stage and which few viewers can display, so keep onefile = FALSE). Its arguments are filename (Rplot%03d.svg by default, one file per page), width and height in inches, pointsize, family, bg and antialias. A file name without a %03d format overwrites the file on every page, so the file contains the last page plotted. The text of an SVG written by cairo is not text: it is a set of glyph outlines, each character defined once as a path in a defs section and then placed with a use element. The script counts them: for a small plot there is no <text element, tens of <path elements and a glyph definition per distinct character. The consequence is that the picture looks the same on every machine, with no font dependency and no substitution, but the text cannot be searched, selected or edited in a vector editor, and the file is larger than the equivalent with real text. This is why the SVG at the end of this page has no <text> element.

Source: svglite package documentation: svglite

svglite is an add-on package that writes SVG with real <text> elements: the script shows 11 of them and no <path> for the same plot, because it keeps the text as text and leaves the choice of font to the viewer. That gives searchable, editable text, and a figure whose text uses whatever font the viewer finds for the family named, so it can look different on a machine without the font. Which is better depends on where the file goes: a web page that styles the text with its own fonts wants svglite, a figure that must look exactly the same everywhere wants the cairo glyph paths. Both are valid answers to the same task.

dev.copy(device, ...) replays the current plot on a new device, which is how a plot that was drawn on the screen is saved to a file afterwards, and dev.print() and dev.copy2pdf() do the same and return to the original device. They copy the display list, not the pixels, so they need a device that keeps one: screen devices do by default, and print devices do not, so on a file device the first step is dev.control("enable"), which the help page says is safe only at the beginning of a plot. dev.copy() copies the device region and not just the plot, including the background colour, which on a screen device is transparent by default and probably not wanted on a PNG; dev.print() produces a PostScript print by default, and when it is given a device it sets the width and height in inches, which is wrong for the bitmap devices (png, jpeg, tiff, bmp) unless their units are set to inches. recordPlot() snapshots the display list into an object of class recordedplot and replayPlot() draws it again, on another device or at another size (dev.size() reports the device size in inches, pixels or centimetres). The help page of recordPlot() (R documentation: recordPlot) warns that recorded plots must not be used as a permanent storage format, because the format may change between R versions, and that replay of a plot drawn with ggplot2 may fail unless the package is loaded.

dev.capabilities() (new in R 4.2.0) reports what a device supports, as a named list: semi-transparency, transparent backgrounds, raster images, locator(), and the features of the graphics engine that arrived with R 4.1.0 and later for the grid system: gradients and patterns, clipping paths, masks, compositing, affine transformations, paths and glyphs, supported so far on Cairo-based devices and pdf() (R NEWS: Changes in R 4.1.0 and R NEWS: Changes in R 4.3.0). Base graphics does not use them; they are mentioned here because they explain why some devices report more than others, and the graphics engine version, R_GE_version, went from 14 in R 4.1.0 to 17 in R 4.6.0, each bump requiring packages that provide devices to be reinstalled.

Source: R documentation: dev.copy and dev.print

The screen devices are x11() on Unix-alikes, quartz() on macOS and windows() on Windows, and dev.new() opens the right one for the platform; an interactive session starts one when the first plot is made. They keep a display list, can be resized and redrawn, and are the only ones where locator() and identify() have a pointer. The container used for the examples has no display, so none of these is run here; this fragment is what an interactive session does.

Source: R documentation: dev.new

The pattern for scripts is to open the device, draw and close, with on.exit() closing it when the drawing code fails. Without it, a function that errors leaves the device open and the file half-written, and the next call draws on the same device, which is a hard mistake to find in a long script. dev.list() in the script confirms that no device is left, including after the error. The same pattern with par() in two_panels() keeps the graphical parameters of the caller intact.

Source: R documentation: on.exit

The messages below were produced by the script in the container, caught with tryCatch() so that the script ends normally. The first three are the ones that come up most often in practice.

Source: R documentation: par

Source: R documentation: dev.off