Table of Contents for Theme 3: Graphics

points

Command Parameters

x, y	Matrix or vectors of numeric data to plot. The number of rows should match. If only one matrix or vector is given, it is taken as y with x being a simple index based on the number of rows in the given data.
type = "p"	The type of plot to create. The default is "p", producing points. Other options are "l" and "b", producing lines and both lines and points, respectively. Different types can be specified for each column of y.
lty = 1:5	The line type to use for each column of y; defaults to values 1 to 5 and is recycled as necessary.
lwd = 1	The line widths for each column of y.
pch = NULL	The plotting symbols to use for each column of y. The default uses numbers 1–9 and lowercase letters.
col = 1:6	The colors to use for each column of y. Colors are recycled as necessary.
cex = NULL	The character expansion factor for each column of y.
bg = NA	The background colors to use for plotting symbols (if appropriate) for each column of y.
xlab = NULL	A title for the x-axis.
ylab = NULL	A title for the y-axis.
xlim = NULL	The limits of the x-axis. You must specify both starting and ending values.
ylim = NULL	The limits of the y-axis. You must specify both starting and ending values.
...	Additional graphical parameters.
add = FALSE	If add = TRUE, the plot is added to the current plot window; otherwise, a new plot is created.

SEE also par.

Examples

  ## Make some data (matrix for response and matrix for predictor)
> resp = matrix(c(2, 4, 7, 12, 10, 15, 19, 14, 15, 11, 6, 4), ncol = 2)
> pred = matrix(c(2, 3, 5, 8, 12, 15), ncol = 1)

  ## Create matrix plot as lines+points (Figure 3-14)
  ## Use custom symbols, line width, colors and styles
> matplot(pred, resp, type = 'b', pch = c(21,23), lwd = c(1, 2),
 col = 1:2, lty = 1:2)

  ## Add a legend, make sure parameters match original plot
  ## Check pch, lty and so on match
> legend("topright", legend = c("Spp1", "Spp2"), bty = "n", pch = c(21, 23),
 col = 1:2, lty = 1:2, title = "Species")

Figure 3-14: A matrix plot with legend

  ## Create some data (vectors)
> Sp3 = c(15, 9, 5, 2, 3, 8)
> Sp4 = c(3, 5, 8, 12, 13, 9)

  ## Make a blank plot (Figure 3-15)
> plot(0:15, 0:15, type = "n")

  ## matpoints can add to any plot and can also draw lines!
  ## Note that data can be a vector
  ## Specify plotting character, color and so on to help match in legend
> matpoints(pred, Sp3, type = "b", col = "blue", lwd = 3, lty = 3,
  pch = 25)

  # matlines can draw points!
> matlines(pred, Sp4, type = "b", col = "black", pch = 24)

  ## Add a legend
> legend("bottomleft", legend = c("Sp3", "Sp4"),
  col = c("blue", "black"), lty = c(3, 1), pch = 25:24)

Figure 3-15: The matpoints and matlines commands used to add data to an existing plot

Command Name

pairs

This command produces multiple scatter plots within one plot window; that is, it produces a matrix of scatter plots. The command can accept input in two forms:

As a matrix or data frame with numeric columns
As a formula

Common Usage

pairs(formula, data = NULL, ..., subset,
     na.action = stats::na.pass)

pairs(x, labels, panel = points, ...,
     lower.panel = panel, upper.panel = panel,
     diag.panel = NULL, text.panel = textPanel,
     label.pos = 0.5 + has.diag/3,
     cex.labels = NULL, font.labels = 1,
     row1attop = TRUE, gap = 1)

Related Commands

coplot

Command Parameters

formula	A formula with no response variable, only predictors, of the form ~ x + y + z.
data = NULL	A data frame or list containing the variables given in the formula.
subset	A subset of observations to use.
na.action	A function defining what to do if NA items are in the data. The default is to pass missing values on to the panel functions, but na.action = na.omit will cause cases with missing values in any of the variables to be omitted entirely.
x	A data frame or matrix whose columns form the variables to be plotted.
labels	The names for the variables.
panel = points	A function(x, y, ...), used to plot the contents of the panels.
...	Additional graphical parameters.
lower.panel = panel	A function(x, y, ...), used for plotting in the lower triangle of panels.
upper.panel = panel	A function(x, y, ...), used for plotting in the upper triangle of panels.
diag.panel = NULL	A function(x, ...), used to apply to the diagonal.
text.panel = textPanel	A function(x, y, labels, cex, font, ...), which is applied to the diagonals.
label.pos	The y position of the labels in the text panel.
cex.labels = NULL	An expansion factor for the labels in the text panel.
font.labels = 1	The font style to use for the text panel.
row1attop = TRUE	If TRUE, the layout is matrix-like, with row 1 at the top. If FALSE, it is graph-like with row 1 at the bottom.
gap = 1	Sets the distance between sub-plots in margin lines.

Examples

USE mf data in Essential.RData file for these examples.

> names(mf) # as a reminder of variable names
[1] "Length" "Speed"  "Algae"  "NO3"    "BOD"    "site"  

  ## Make pairs plot using some of the variables (Figure 3-16)
> pairs(~ Length + Speed + Algae, data = mf)

Figure 3-16: A default pairs plot using selected data

  ## Make a special function to display best-fit line
> panel.lm = function(x, y, ...) {  # Set-up function and define inputs
    par("new" = TRUE)               # do not wipe a new plot
    plot(x, y)                      # plot the x, y values
    abline(lm(y ~ x), col = "blue") # add a best-fit line in blue
    par("new" = FALSE) } # reset the new parameter and end the function

  ## Make pairs plot (Figure 3-17) and use new function
  ## to place scatter + best-fit in lower panels
> pairs(~Length + Speed + Algae + NO3, data=mf, lower.panel = panel.lm)

Figure 3-17: A pairs plot with a customized function for the lower panels

Command Name

pie

This command produces pie charts.

Common Usage

pie(x, labels = names(x), edges = 200, radius = 0.8,
   clockwise = FALSE, init.angle = if(clockwise) 90 else 0,
   density = NULL, angle = 45, col = NULL, border = NULL,
   lty = NULL, main = NULL, ...)

Related Commands

dotchart

barplot

Command Parameters

x	A vector of numeric values, these will form the pie slices and must be non-negative.
labels = names(x)	Labels for the pie slices. The default is to use the names attribute of x.
edges = 200	A value that controls how smooth the circular outline of the pie is. The greater the value, the more segments of polygon are used, so the smoother the circle.
radius = 0.8	The proportion of the plot area that the pie fills. Smaller size may be necessary to accommodate labels.
clockwise = FALSE	By default, the slices of pie are drawn counter-clockwise.
init.angle	A value specifying the starting angle in degrees. The default is 0 (3 o’clock) unless clockwise = TRUE, in which case it is 90 (12 o’clock).
density = NULL	The density of shading lines in lines per inch. The default is NULL, which suppresses lines.
angle = 45	The angle of shading lines in degrees. This is measured as a counter-clockwise rotation.
col = NULL	Colors used for filling the slices. The default is a set of six pastel colors.
border = NULL	The border color for the slices.
lty = NULL	The line type for the slices.
main = NULL	An overall title for the plot.
...	Additional graphical parameters can be supplied, but the only ones with an effect relate to labels and main title.

Examples

  ## Make data
> rain = c(34, 32, 23, 15, 10, 8, 6, 9, 12, 21, 24, 29) # A vector
> names(rain) = month.abb[1:12] # Make labels
> rain # View the data
Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec 
 34  32  23  15  10   8   6   9  12  21  24  29 

  ## Make a pie chart using all default settings (Figure 3-18)
  ## Labels are shown for slices as names were set
> pie(rain)

Figure 3-18: A pie chart

Command Name

plot

This command is a generic function for plotting R objects. The basic form of the command produces scatter plots. However, many objects have a dedicated plotting routine and variants of the plot command will produce plots according to the class attribute of the object. You have three ways to specify the input to plot:

As separate x and y coordinates
As a formula
As an object that has a plotting structure (that is, it has a dedicated plot command of its own)

Many graphical parameters can be specified and most are shared with other commands that produce a plot window. The par command gives access to all the graphical parameters.

SEE also plot in “Adding Lines.”

Common Usage

plot(x, y, ...)

Related Commands

points

Command Parameters

x, y	The coordinates to plot. These can be separate x and y vectors or a formula. You can also specify an object, which holds a print structure.
frame.plot	If frame.plot = TRUE, the default, a box is drawn around the plot region.
type	The type of plot to produce.The general default is type = "p", which produces points. The main options are "p" for points, "l" for lines, "b" for both, and "n" for nothing.
mainsubxlabylab	Titles.Titles can be specified using a character string (or expression). You can produce titles for the overall plot and a subtitle, as well as for x- and y-axes.
log	Allows plotting of axes on a log scale. Use a character string as follows: "x" for the x-axis to be logarithmic, "y" for the y-axis, and "xy" or "yx" for both.
...	Additional graphical parameters.

Many graphical parameters can be used with the plot command. Additionally, the par command allows you to alter the current settings. Most of the parameters accessible via par can be used directly from the plotting command but some can only be set using the par command.

SEE also par.

Examples

USE mf data in Essential.RData file for this example.

> names(mf) # As a reminder of the variables
[1] "Length" "Speed"  "Algae"  "NO3"    "BOD"    "site"  

  ## A scatter plot in x, y style (Figure 3-19)
  ## Expression used in x-axis label to get superscript
  ## plotting symbol 21 can be colored in ("gray85") and larger
> plot(mf$Speed, mf$Length,
 xlab = expression(Speed~ms^-1), ylab = "Length in mm",
 pch = 21, bg = "gray85", cex = 2)

  ## Add a main title and alter the font to italic
> title(main = "Mayflies", font.main = 3)

Figure 3-19: A scatter plot

  ## Use cars data from R datasets
> data(cars) # make sure data are ready
> names(cars) # A reminder of the variables
[1] "speed" "dist"

  ## Make plot (Figure 3-20), use formula to specify data
  ## Use lines (type = "l") and widen them (lwd = 1.5)
  ## Add titles and ensure axis annotations are horizontal (las = 1)
> plot(dist ~ speed, data = cars, type = "l", lwd = 1.5,
 xlab = "Speed, mph", ylab = "Distance, ft.",
 main = "Stopping Distances (1920s)", las = 1)

Figure 3-20: A plot using lines rather than points

Command Name

qqnorm

This command draws quantile-quantile plots. The command takes a numeric sample and plots it against theoretical quantiles based on a normal distribution. In this way, you can visualize the normality of the data distribution.

SEE also Theme 2: “Math and Statistics: Tests of Distribution.”

Common Usage

qqnorm(y, ylim, main = "Normal Q-Q Plot",
       xlab = "Theoretical Quantiles", ylab = "Sample Quantiles",
       plot.it = TRUE, datax = FALSE, ...)

Related Commands

qqplot

qqline

Command Parameters

y	The data sample to plot, usually a vector.
ylim	The limits of the y-axis; you must specify both starting and ending values.
main	The main title for the plot. The title can be omitted using main = NULL.
xlabylab	Titles for x- and y-axes; the defaults place sensible titles. If you specify NULL, the title is not omitted; "x" and "y" are used for the x- and y-axis, respectively. To suppress an axis, use "", a pair of empty quotes.
plot.it = TRUE	If plot.it = FALSE, the data for the plot is computed but nothing is actually plotted.
datax = FALSE	By default, the sample quantiles are plotted on the y-axis. If datax = TRUE, the theoretical quantiles are plotted on the y-axis and the sample quantiles are plotted on the x-axis.
...	Additional graphical parameters can be used.

SEE also par.

Examples

USE pw data in Essential.RData file for this example.

  ## Draw the QQ plot (Figure 3-21). Set plotting symbol, color & size.
> qqnorm(pw$height, cex = 2, pch = 21, bg = "gray85")

  ## Add a QQ line to help estimate normality
> qqline(pw$height, lwd = 2, lty = 3)

Figure 3-21: A normal quantile-quantile plot

Command Name

qqplot

This command produces a quantile-quantile plot of two variables.

SEE also Theme 2: “Math and Statistics: Tests of Distribution.”

Common Usage

qqplot(x, y, plot.it = TRUE, xlab = deparse(substitute(x)),
       ylab = deparse(substitute(y)), ...)

Related Commands

qqnorm

abline

Command Parameters

x, y	Numeric samples to plot. They do not need to be the same length because it is the quantiles that are plotted, not the original data.
plot.it = TRUE	If plot.it = FALSE, the data for the plot is computed but nothing is actually plotted.
xlabylab	Titles for x- and y-axes; the defaults place sensible titles. If you specify NULL, the title is not omitted; "sx" and "sy" are used for the x- and y-axis, respectively. To suppress an axis, use "", a pair of empty quotes.

Examples

  ## Make some data
> set.seed(55) # Reset the random number generator

  ## Make random numbers from two distributions
> nd = rnorm(n = 50, mean = 5, sd = 1) # Normal (Gaussian) data
> ud = runif(n = 40, min = 3, max = 7) # Uniform distribution

  ## Make QQ plot to compare samples (Figure 3-22)
> qqplot(nd, ud, cex = 1.5, xlab = "Gaussian", ylab = "Uniform")

  ## If samples matched, the line would "fit"
> abline(0, 1, lwd = 1.5, lty = 4)

Figure 3-22: A QQ plot comparing Gaussian and Uniform distribution

Command Name

stem

This command creates stem-and-leaf plots. The command does not open a graphical window but produces a text-based representation of the data distribution in the console window.

Common Usage

stem(x, scale = 1, width = 80)

Related Commands

hist

density

Command Parameters

x	A numeric vector.
scale = 1	Sets the length of the plot; essentially creates more bins. You can specify values < 1.
width = 80	Sets the width of the plot in the console window. Any truncated values are represented by +n, where n shows the number of missing values.

Examples

  ## Make some data
> set.seed(55) # Set random number generator

  ## Make 50 values from a normal distribution
> nd = rnorm(n = 50, mean = 5, sd = 1)

  ## Stem-leaf plot using defaults
> stem(nd)

  The decimal point is at the |

  2 | 9
  3 | 24
  3 | 5579
  4 | 12334
  4 | 55667788999
  5 | 0012233334
  5 | 5667889
  6 | 0011224
  6 | 56
  7 | 4

  ## Make scale smaller
> stem(nd, scale = 0.5)

  The decimal point is at the |

  2 | 9
  3 | 245579
  4 | 1233455667788999
  5 | 00122333345667889
  6 | 001122456
  7 | 4

Saving Graphs

You can save your graphs to other programs in two ways: using copy and paste or by saving your graph to disk as a graphics file. You can save graphs in various formats; for example, JPEG, PNG, TIFF, BMP, and PDF.

Sometimes you want to create a graphics window ready to accept a plot. Creating a window leaves an old graph intact and readies a new graphics window for subsequent plots. You can also have several graphics windows open at the same time. R provides commands that allow you to manage the various graphics windows.

Command Name

bmp
jpeg
png
tiff
dev.new

These commands open a link to a file on disk and send graphical commands to it. The file remains open and any graphical commands are sent to the file until the command dev.off is used to close the file.

SEE also jpeg, png, tiff, and dev.new in “Saving Graphs.”

Common Usage

bmp(filename = "Rplot%03d.bmp",
   width = 480, height = 480, units = "px",
   pointsize = 12, bg = "white", res = NA)

jpeg(filename = "Rplot%03d.jpeg",
    width = 480, height = 480, units = "px",
    pointsize = 12, quality = 75, bg = "white", res = NA)

png(filename = "Rplot%03d.png",
   width = 480, height = 480, units = "px",
   pointsize = 12, bg = "white",  res = NA)

tiff(filename = "Rplot%03d.tiff",
    width = 480, height = 480, units = "px", pointsize = 12,
    compression = "none", bg = "white", res = NA)

dev.new(...)

Related Commands

Command Parameters

filename	A filename to write the subsequent graphics file. This must be in quotes. The file will be written to the current working directory unless the path is written explicitly.
width = 480	The width of the graphic. The default is 480 (pixels).
height = 480	The height of the graphic. The default is 480 (pixels).
units = "px"	The units for height and width. The default is "px" (pixels). Other options are "in" (inches), "cm" (centimeters), and "mm" (millimeters).
pointsize = 12	The default point-size of plotted text characters. It works out at 1/72 inch at res dpi.
quality = 75	For jpeg this sets the quality of the image as a percentage. Essentially this controls the file size. Smaller values will be smaller files, but greater compression leads to poorer quality.
compression = "none"	For tiff this sets the type of compression to use. The default is "none". Other options are "rle", "lzw", "jpeg", and "zip".
bg	Sets the background color. The default setting is "white".
res = NA	The resolution for the final image in dpi. If you do not specify a value, the image will use 72 dpi but not have a dpi value recorded in the meta data.
...	Any appropriate commands for the device.

Examples

  ## Use cars data from R datasets
> names(cars) # A reminder of the variables
[1] "speed" "dist" 

  ## Draw the plot to screen (not shown)
> plot(dist ~ speed, data = cars, main = "Scatter plot", cex=2, las = 1)
> abline(lm(dist ~ speed, data = cars), lty = 2, lwd = 2)
> text(5, 100, "Correlation = 0.8", pos = 4)

  ## Send to disk as PNG using res = 300
  ## Open the device driver
> png(file = "dpi300.png", height = 2100, width = 2100,
  res = 300, bg = "white")

  ## Use graphical commands
> plot(dist ~ speed, data = cars, main = "Scatter plot", cex=2, las = 1)
> abline(lm(dist ~ speed, data = cars), lty = 2, lwd = 2)
> text(5, 100, "Correlation = 0.8", pos = 4)

  ## Close the device and finish writing the file
> dev.off()

## Compare the screen plot to the disk file

Command Name

dev.copy
dev.print

These commands copy the current graphics device to a new device. The most useful purpose is to copy a graphic from the screen to a disk file (which you can also do via the GUI in Windows). The dev.copy command makes the new device the current one and leaves it open so further graphical commands can be issued (use dev.off to close the file). The dev.print command closes the device immediately.

Common Usage

dev.copy(device, ..., which = dev.next())

dev.print(device, ...)

Related Commands

Command Parameters

device	A device to send the current plot to. This will usually be bmp, png, pdf, jpeg, or tiff.
...	Parameters to pass to the device; e.g., filename, height, width, and res.
which = dev.next()	If a device is already open, it can be specified using which. You cannot specify both device and which parameters.

Examples

  ## Use cars data from R datasets
> data(cars) # make sure data is ready

  ## Plot to screen (not shown)
> plot(dist ~ speed, data = cars, main = "Scatter plot",
  cex = 2, las = 1)

  ## Send graphic to a jpeg file and close device immediately
> dev.print(jpeg, height = 2100, width = 2100, res = 300,
  file = "A_test.jpg")

Command Name

dev.cur
dev.list
dev.next
dev.off
dev.prev
dev.set

These commands manage the graphics device(s). You can see what the current device is, list all active devices, turn off any or all devices (and so complete the writing of a graphics file to disk), and switch between graphics devices (on screen or disk). The commands and their tasks are as follows:

dev.cur shows which is the current device.
dev.list lists all open devices.
dev.next makes the next device current.
dev.off closes a device.
dev.prev makes the previous device current.
dev.set sets a specific device as current.
graphics.off closes all devices.

Common Usage

dev.cur()
dev.list()
dev.next(which = dev.cur())
dev.off(which = dev.cur())
dev.prev(which = dev.cur())
dev.set(which = dev.next())
graphics.off()

Related Commands

Command Parameters

which

The graphics device to use. Usually a simple integer value. The number 1 is always the “null device” and cannot be used.

Examples

> graphics.off() # Turn off all graphics devices
> dev.cur() # What is current? Nothing!
null device 
          1 

  ## Open a new blank window
> windows(height = 7, width = 7, title = "My Graphics Window")
> dev.cur() # Device 2 is current (1 is always null)
windows 
     2 

  ## Open another window
> quartz(height = 7, width = 7, title = "My other Graphics Window")
> dev.list() # Show the list
windows windows 
     2      3 
> dev.cur() # Window 3 is current
windows 
     3 
> dev.prev() # set to previous window
windows 
     2

Command Name

jpeg

Opens a link to a file on disk and sends graphical commands to a JPEG file.

SEE bmp and pdf.

Command Name

pdf

Opens a link to a file on disk and sends graphical commands to a PDF file.

Common Usage

pdf(file = ifelse(onefile, "Rplots.pdf", "Rplot%03d.pdf"),
    width, height, onefile, family, title,
    paper, bg, fg, pointsize, pagecentre, colormodel)

Related Commands

Command Parameters

file	A filename to write the subsequent graphics file. This must be in quotes. The file will be written to the current working directory unless the path is written explicitly. The default filename depends on the onefile setting.
width	The width of the plot in inches. The usual default is 7, but this can be altered.
height	The height of the plot in inches. The usual default is 7, but this can be altered.
onefile	If onefile = TRUE, multiple figures will be sent to a single PDF file.
family	The font family to use. The default is "Helvetica" (or "sans"). Other options are "AvantGarde", "Bookman", "Courier" (or "mono"), "Helvetica-Narrow", "NewCenturySchoolbook", "Palatino", and "Times" (or "serif"). These are standard Adobe PostScript fonts.
title	A title comment embedded in the file. The default is “R Graphics Output”.
paper = "special"	The target paper size. Basic options are "a4", "letter", "legal" (or "us"), and "executive". Also, "a4r" and "USr" can be used for landscape (rotated) orientation. The default, "special", takes the paper size from the height and width.
bg = "transparent"	The background color to use. The default is "transparent".
fg = "black"	The foreground color to use. The default is "black".
pointsize = 12	The default point size to use. This is only approximate and defaults to 12.
pagecentre = TRUE	If paper is not "special", by default the graphic is centered on the page.
colormodel	A character string that specifies the color model to be used; the default is "rgb". Other options are "gray" and "cmyk".

Examples

  ## Create a link to a file and start the PDF device driver
  ## Set the device to create greyscale
> pdf(file = "My_graphic.pdf", height = 7, width = 7,
  colormodel = "gray")

  ## Create a plot
plot(dist ~ speed, data = cars, main = "Scatter plot", cex = 2, las = 1)

  ## Close the device, which writes/finishes the file
dev.off()

Command Name

png

Opens a link to a file on disk and sends graphical commands to a PNG file.

SEE bmp and pdf.

Command Name

quartz
windows
X11
dev.new

These commands open a blank graphics window. Usually this will be on-screen but the quartz command can open a link to a file (which must be closed using dev.off). The different commands operate on different operating systems:

For Macintosh, use quartz and X11
For Windows, use windows and X11
For Linux, use X11 (x11 is an alias)

The dev.new command opens a graphics device appropriate for the operating system.

SEE also x11 in “Saving Graphs.”

Common Usage

quartz(title, width, height, pointsize, family,
       type, file = NULL, bg, canvas, dpi)

windows(width, height, pointsize, xpinch, ypinch, bg, canvas,
        gamma, title, family)

X11(width, height, pointsize, gamma, bg, canvas, title, type)

dev.new(...)

Related Commands

dev.cur

dev.list

Command Parameters

title	A character string that will appear in the title bar of the graphics window.
width	The width of the graphics window in inches. The default is 7.
height	The height of the graphics window in inches. The default is 7.
pointsize	The point size to use. The default is 12.
dpi	The resolution of the output. For on-screen graphics windows, this defaults to the resolution of the screen. For off-screen graphics, the default is 72.
xpinchypinch	The resolution of the output in the horizontal and vertical directions.
bg	The initial background color to use; defaults to "transparent".
canvas	The canvas color to use for on-screen windows. The default is "white".
type = "native"	The type of display to use. The default, "native", uses the screen. Other options are dependent on the OS and include "png", "jpeg", "tiff", "gif", "psd", and "pdf".
file = NULL	A target for the graphics device. Used when type is set to an off-screen device. Any filename must be in quotes and will go to the current working directory unless the path is specified explicitly.
family	The family name of the font series to be used. The default depends on the operating system.
...	Parameters to pass to selected device. If left blank, the default screen device is used.

Examples

  ## Start a new blank screen 5 inches in size (Windows OS)
> windows(height = 5, width = 5, title = "My graphics")

  ## Start a new window 4 inches is size (on any OS)
> dev.new(height = 4, width = 4, title = "My small graphic")

> graphics.off() # close all graphics

Command Name

tiff

Opens a link to a file on disk and sends graphical commands to a TIFF file.

SEE bmp and pdf.

Command Name

windows

Opens a blank graphics window. The different commands operate on different operating systems.

SEE also windows in “Saving Graphs.”

SEE quartz in “Saving Graphs.”

Command Name

X11
x11

Opens a blank graphics window. The x11 command is an alias for X11.

SEE quartz.

Adding to Graphs

You can add various elements to graphs. You can add data, represented by points or lines. You can also add various sorts of lines to plots, such as lines of best-fit or curves representing mathematical functions. You can also add text to graphs, either in the main plot area or in the margins and along the axes. You can also add legends.

What’s In This Topic:

Adding data

As points
As lines

Adding lines

Straight lines
Curved lines
Mathematical functions

Adding shapes
Adding text

To the plot window
To the axes
Marginal text

Adding legends

Adding Data

Once you have created a graph of some sort you can add data to it in various ways. You can add data as points or as lines. You can also use the lines command to make lines of best-fit.

Command Name

curve

This command plots a mathematical function, either as a new plot or to an existing one.

SEE “Adding Lines.”

Command Name

lines

SEE also lines in “Adding Lines.”

This command adds connected line segments to an existing plot. The data can be specified in two main ways:

As x and y coordinates
As an object that contains a valid plotting structure (that is, x and y coordinates)

You can think of the lines and points commands as equivalent; you can alter the parameters of either to produce the same result.

Common Usage

lines(x, y = NULL, type = "l", ...)

Related Commands

Command Parameters

x, y	Vectors of numeric values that describe the coordinates to plot. If x is an object with a valid plotting structure, y can be missing. This object could be a list with named x and y elements, a two-column matrix or data frame, or a time series object.
type = "l"	The type of line to produce. The default, "l", produces segments of line. Other options include: "p"—Points "b"—Both points and lines "o"—Points and lines overplotted "c"—Unconnected line segments "n"—Nothing
...	Other graphical parameters can be used. Especially noteworthy are: lwd—Line width lty—Line type col—Line color

SEE the par command for a comprehensive list.

Examples

  ## Use cars data from R datasets
> data(cars) # make sure data are ready

  ## Draw scatter plot (Figure 3-23)
> plot(dist ~ speed, data = cars, main = "Scatter plot", cex=2, las = 1)

  ## Make a linear model of relationship
> cars.lm = lm(dist ~ speed, data = cars)

  ## Use fitted model values to add a line (x = speed, y = fitted)
> lines(cars$speed, fitted(cars.lm), lwd = 2)

Figure 3-23: A scatter plot with best-fit line added using lines command

Command Name

locator

The locator command reads the position of the cursor when you click the mouse. The results are returned as x, y coordinates. A common use for the locator command is to allow the user to place a legend or text in a graphic window by clicking with the mouse.

Common Usage

locator(n = 512)

Related Commands

legend

text

Command Parameters

n = 512

The number of points to locate. The coordinates of mouse clicks will be recorded until the default number of clicks is reached (512) or the ESC key is pressed.

Examples

> plot(0:10,0:10) # Make a simple plot

  ## Set one mouse-click and get the coordinates
> locator(1)
$x
[1] 3.357639

$y
[1] 8.821705

  ## Set two clicks and return coordinates
> locator(2)
$x
[1] 2.020833 6.829861

$y
[1] 7.736434 4.538760

Command Name

matlines
matpoints

These commands add data as lines or points to an existing plot (usually one created using matplot).

SEE matplot in “Types of Graphs.”

Command Name

points

This command adds points to an existing plot. The data can be specified in two main ways:

As x and y coordinates
As an object that contains a valid plotting structure (that is, x and y coordinates)

You can think of the points and lines commands as equivalent; you can alter the parameters of either to produce the same result.

Common Usage

points(x, y = NULL, type = "p", ...)

Related Commands

Command Parameters

x, y	Vectors of numeric values that describe the coordinates to plot. If x is an object with a valid plotting structure, y can be missing. This object could be a list with named x and y elements, a two-column matrix or data frame, or a time series object.
type = "p"	The type of line to produce. The default, "p", produces points. Other options include: "l"—Lines "b"—Both points and lines "o"—Points and lines overplotted "c"—Unconnected line segments "n"—Nothing
...	Other graphical parameters can be used. Especially noteworthy are: pch—Plotting symbol cex—Character expansion for plotting symbols col—Color for plotting symbols (and line) bg—Background color for open style plotting symbols (pch = 21:25)

SEE the par command for a comprehensive list.

Examples

  ## make a simple plot (Figure 3-24)
> plot(1:10, 1:10, cex = 2)

  ## Add points to the plot
> points(10:1, 1:10, pch = 23, bg = "gray80", cex = 2)

  ## Some data (as vectors)
> x = c(1, 4, 6, 3, 4, 7)
> y = c(3, 6, 4, 5, 9, 6)

  ## Add the vectors as points
> points(x, y, pch = 21, bg = "black", cex = 2)

Figure 3-24: Scatter plot with extra data added using the points command

Adding Lines

You can add various sorts of lines to existing plots. These include lines of best-fit (straight or curved), sections of straight line, arrows, and curves representing mathematical functions.

Command Name

abline

This command can add one or more straight lines to a plot. Lines can be drawn horizontally, vertically, or with a specified slope and intercept. The command can accept input in two main ways:

Values given explicitly
Values taken from an object, which contains coefficients

Common Usage

abline(a = NULL, b = NULL, h = NULL, v = NULL, reg = NULL,
       coef = NULL, untf = FALSE, ...)

Related Commands

Command Parameters

a = NULL	The intercept for the line as a numeric value.
b = NULL	The slope of the line as a numeric value.
h = NULL	The y value for a horizontal line.
v = NULL	The x value for a vertical line.
reg = NULL	An object that contains coefficients, such as the result of lm.
coef = NULL	A vector containing two values, the intercept and slope.
untf = FALSE	If untf = TRUE, and at least one axis was drawn log-transformed, the line is drawn corresponding to the original coordinates. If untf = FALSE, the line is drawn using the transformed coordinate system. Horizontal and vertical lines always use the original coordinate system.
...	Additional graphics commands can be used. Of particular use are: col—The line color lwd—The line width lty—The line type

SEE the par command for a comprehensive list.

Examples

  ## Use cars data from R datasets
> data(cars) # make sure data is ready

  ## Make the basic scatter plot (Figure 3-25)
> plot(dist ~ speed, data = cars, cex = 2)

  ## Add horizontal lines using a sequence
> abline(h = seq(from = 20, to = 100, by = 20), lty = 3, col = "gray50")

  ## Add a vertical line at the mean speed
> abline(v = mean(cars$speed), lty = "dotted", col = "gray50")

  ## Do a regression
> cars.lm = lm(dist ~ speed, data = cars)

  ## Add line of best-fit using regression result
> abline(cars.lm, lwd = 2.5)

  ## View coefficients of regression (intercept, slope)
> coef(cars.lm)
(Intercept)       speed 
 -17.579095    3.932409 

  ## Add line approximating to intercept, slope
  ## by giving vector of two values
> abline(c(-20, 4), lwd = 2, lty = 2)

  ## add a line by specifying intercept and slope separately
> abline(0, 1)

Figure 3-25: Using the abline command to add to a plot

Command Name

arrows

This command adds arrows to a plot by connecting pairs of coordinates.

Common Usage

arrows(x0, y0, x1 = x0, y1 = y0,
       length = 0.25, angle = 30, code = 2,
       col = par("fg"), lty = par("lty"), lwd = par("lwd"),
       ...)

Related Commands

segments

Command Parameters

x0, y0	The coordinates for the starting point.
x1, y1	The coordinates for the ending point.
length = 0.25	The length of the arrow head, in inches.
angle = 30	The angle of the arrow head to the shaft.
code = 2	The style of arrow to draw. If code = 1, an arrow head is drawn at the starting end. If code = 2 (the default), an arrow head is drawn at the end. If code = 3, arrow heads are drawn at both ends. If code = 0, no heads are drawn.
col	The color for the arrow.
lty	The line type: 1= solid, 2 = dashed, 3 = dotted.
lwd	The line width.
...	Additional graphical commands can be given.

SEE also par in “Using the par Command.”

Examples

  ## Draw an empty plot (Figure 3-26)
> plot(1:10, 1:10, type = "n")

  ## Draw arrows to "join the dots", using defaults
> arrows(1:9, 1:9, 2:10, 2:10)

  ## Set some coordinates
> xc = 2:8
> yc = rep(5, 7)

  ## Use coordinates to add points
> points(xc, yc)

  ## Use arrows to add "error style" bars vertically
> arrows(xc, yc + 0.5, xc, yc - 0.5, code = 3, lwd = 3, angle = 90)

  ## Use arrows to add "error style" bars horizontally
> arrows(xc - 0.3, yc, xc + 0.3, yc, code = 3, length = 0.1,
  lty = 2, angle = 90)

  ## More arrows and annotation
> arrows(2,8, 4, 8, code = 3)
> arrows(2,7, 4, 7, code = 2)
> arrows(2,6, 4, 6, code = 1)
> arrows(2,9, 4, 9, code = 0)
> text(4, 9, "Code 0", pos = 4)
> text(4, 6, "Code 1", pos = 4)
> text(4, 7, "Code 2", pos = 4)
> text(4, 8, "Code 3", pos = 4)

Figure 3-26: Various arrows added to a plot

Command Name

curve
plot

These commands draw curves representing mathematical functions. The plot command is very general and will plot those functions already built in to R. The curve command permits you to specify any function, which is then plotted.

Common Usage

curve(expr, from = NULL, to = NULL, n = 101, add = FALSE,
      type = "l", ylab = NULL, log = NULL, xlim = NULL, ...)

plot(x, y = 0, to = 1, from = y, xlim = NULL, ...)

Related Commands

spline

Command Parameters

expr	An expression of a function of x or the name of a function to plot.
x	A numeric R function.
from	The starting/lower value for x.
to	The ending/upper value for x.
n = 101	The number of x values to evaluate.
add = FALSE	If add = TRUE, the curve plotted is added to an existing plot window.
type = "l"	The type of plot. The default, "l", plots lines. Other options include "p" for points and "b" for both lines and points.
ylab = NULL	A label for the y-axis.
y	An alias for from. This maintains compatibility with the plot command.
log = NULL	A character string stating which (if any) axes should be on a log scale. The options are "x", "y", and "xy".
xlim = NULL	The limits of the x-axis; two values must be given, the starting and ending values.
...	Additional graphical parameters can be used. The most useful ones are likely to be: col—Color of lines/points lty—Line type lwd—Line width pch—Plotting character

SEE the par command for a comprehensive list.

Examples

  ## Plot a trig function (Figure 3-27)
  ## curve command would give same result
  ## Set x-axis to go from -2*pi to +2*pi and lengthen y-axis for legend
> plot(sin, from = -pi*2, to =  pi*2,
  lty = 2, lwd = 1.5, ylim = c(-1, 1.5), ylab = "y-value")

  ## Plot the cosine, use curve command and set add = TRUE to overlay
> curve(cos, from = -pi*2, to = pi*2, lty = 3, add = TRUE)

  ## Add a legend, be careful to styles from the plot
> legend("topright", legend = c("Sine", "Cosine"),
 lty = c(2, 3), lwd = c(1.5, 1), bty = "n")

  ## Give a main title
> title(main = "Sine and Cosine functions")

Figure 3-27: Plotting mathematical functions

Command Name

lines

This command adds connected line segments to an existing plot.

SEE “Adding Data.”

Command Name

loess

This command carries out local polynomial regression fitting. A common use for this is to produce a locally fitted model that can be added to a scatter plot as a trend line to help visualize the relationship.

SEE Theme 2, “Math and Statistics.”

Command Name

lowess

This command carries out scatter plot smoothing. The algorithm uses a locally weighted polynomial regression. A common use for this is to produce a locally fitted model that can be added to a scatter plot as a trend line to help visualize the relationship. The trend line is not a straight line, but weaves through the scatter of points; thus, lowess is often referred to as a scatter plot smoother.

SEE Theme 2, “Math and Statistics.”

Command Name

matlines
matpoints

These commands add data as lines or points to an existing plot (usually one created using matplot).

SEE matplot in “Types of Graphs.”

Command Name

qqline

This command adds a line to a normal QQ plot, which passes through the first and third quartiles.

SEE also Theme 2, “Tests of Distribution.”

Common Usage

qqline(y, datax = FALSE, ...)

Related Commands

qqnorm

qqplot

Command Parameters

y	The numerical sample from which the QQ plot was derived.
datax = FALSE	By default, the sample quantiles are plotted on the y-axis. If datax = TRUE, the theoretical quantiles are plotted on the y-axis and the sample quantiles are plotted on the x-axis.
...	Additional graphical parameters may be used. The most useful ones are likely to be: col—The color of the line. lty—The line type. lwd—The line width.

SEE the par command for a more comprehensive list.

Examples

  ## make some data
> set.seed(22) # Set random number generator

  ## Random values from Gamma distribution
> dat = rgamma(50, shape = 3)

  ## Make a Normal QQ plot (Figure 3-28)
> qqnorm(dat, cex = 1.5)

  ## Add a line - not a good fit!
> qqline(dat, lty = "dotdash", lwd = 2)

Figure 3-28: Adding a QQ-line to a normal QQ plot

Command Name

segments

This command adds line segments to a plot by connecting pairs of coordinates.

Common Usage

segments(x0, y0, x1 = x0, y1 = y0,
         col = par("fg"), lty = par("lty"), lwd = par("lwd"),
         ...)

Related Commands

arrows

curve

Command Parameters

x0, y0	The coordinates for the starting point.
x1, y1	The coordinates for the ending point.
col	The color for the lines.
lty	The line type: 1= solid, 2 = dashed, 3 = dotted.
lwd	The line width.
...	Additional graphical commands can be given:

SEE also par.

Examples

  ## Use VADeaths data from R datasets
> data(VADeaths) # make sure data is ready

  ## Calculate means for columns
> VADmean = colMeans(VADeaths)

  ## Calculate std. deviation
> VADsd = apply(VADeaths, MARGIN = 2, FUN = sd)

  ## Calculate std. error
> VADerr = VADsd / sqrt(5) # There are 5 rows

  ## Before plotting, set clipping to allow spill-over into margin
  ## as top-hat will reach top of plot area
> opt = par("xpd" = TRUE)

  ## Bar chart of means (Figure 3-29)
  ## Note setting of name for plot object
> bp = barplot(VADmean, ylim = c(0, 50), ylab = "Mean Deaths per 1000")

  ## Use segments to draw error bars (top to bottom)
> segments(bp, VADmean + VADerr, bp, VADmean - VADerr, lwd = 2)

  ## Add top hats (left to right)
> segments(bp - 0.1, VADmean + VADerr, bp + 0.1, VADmean + VADerr, lwd=2)

> par(opt) # Reset clipping back to previous setting

Figure 3-29: Using the segments command to add error bars

Command Name

spline

This command uses spline interpolation on a series of coordinate data. If you use this within a lines command, you can produce a smoothed curve.

Common Usage

spline(x, y = NULL, n = 3*length(x), method = "fmm",
      xmin = min(x), xmax = max(x), xout, ties = mean)

Related Commands

loess

lowess

Command Parameters

x, y = NULL	Vectors giving the coordinates of the points to be interpolated. Alternatively, x can be an object with a plotting structure, such as a list with x and y elements (in which case y can be missing).
n	If xout is unspecified, the interpolation takes place at n equally spaced points between xmin and xmax.
method = "fmm"	The method of interpolation. The default is "fmm"; other options are "natural", "periodic", and "monoH.FC".
xmin = min(x)xmax = max(x)	If xout is unspecified the interpolation takes place at n equally spaced points between xmin and xmax.
xout	A set of values explicitly stating where the interpolation should take place.
ties = mean	Determines how tied values are dealt with. The default is mean. Other functions can be used as long as they require a single value as an argument and return a single value. Alternatively, you can give the string "ordered".

Examples

USE bbel data in Essential.RData file for this example.

> names(bbel) # Check variable names
[1] "abund" "light"

  ## Plot scatter graph of relationship (Figure 3-30)
> plot(abund ~ light, data = bbel, pch = 16)

  ## Looks polynomial - add a title
> title(main = "Polynomial regression")

  ## Carry out polynomial regression
> bbel.lm = lm(abund ~ light + I(light^2), data = bbel)

  ## Add "best-fit" line (y-data from model fit)
> lines(bbel$light, fitted(bbel.lm), lty = 2)

  ## Regular lines look "clunky" so use spline to smooth curve
> lines(spline(bbel$light, fitted(bbel.lm)), lwd = 2)

Figure 3-30: Curved line (using spline) of best-fit for a polynomial regression

Adding Shapes

Various shapes can be added to plots. The commands that deal with these are rect, which adds rectangles, and polygon, which adds polygons. In addition, there is the box command, which adds a bounding box to a plot.

Command Name

box

This command adds a box around the current plot in the given color and line style.

SEE also box in “Altering Axis Parameters.”

Common Usage

box(which = "plot", lty = "solid", ...)

Related Commands

rect

polygon

Command Parameters

which = "plot"	Where the box is to be drawn. The default is "plot", which draws around the plot region (e.g., the extent of the axes and any bars/points). Other options are "inner", "outer", and "figure". Exactly where the box will appear depends on the margin settings.
lty = "solid"	The line type. The default is "solid".
...	Additional graphical commands can be given. The most useful of these are: col—The line color lwd—The line width bty—The box type. The default is "O", producing a complete box. Other options are "L", "C", "U", "7", and "]". The resulting box resembles the character (which can be lowercase). Use bty = "n" (lowercase) for no box.

SEE the par command for a comprehensive list of other options.

Examples

  ## Make some data
> dat = c(23, 15, 6, 9) # A vector
> names(dat) = c("Q1", "Q2", "Q3", "Q4") # Assign names

  ## Draw a pie chart (Figure 3-31)
> pie(dat, clockwise = TRUE, init.angle = 270, radius = 0.9)

  ## Add various boxes
> box(lty = 3, lwd = 1.5, bty = "7") # top and right of plot area
> box(lty = 2, lwd = 2.5, bty = "L") # bottom and left of plot area
> box(lwd = 3, which = "outer")      # around the outer margin

Figure 3-31: A pie chart with various plot boxes added using the box command

Command Name

polygon

Draws shapes into the current plot window by connecting a series of coordinates.

Common Usage

polygon(x, y = NULL, density = NULL, angle = 45,
       border = NULL, col = NA, lty = par("lty"),
       ..., fillOddEven = FALSE)

Related Commands

segments

rect

Command Parameters

x, y	Vectors containing the x and y coordinates to plot. If x contains a plotting structure (e.g., a list with x and y elements, or a two-column matrix or data frame), y can be missing. In any event the polygon is assumed to be closed and the last pair of coordinates are joined to the first.
density = NULL	The density of shading lines in lines per inch. The default is NULL, which suppresses lines.
angle = 45	The angle of shading lines in degrees. This is measured as a counter-clockwise rotation.
border = NULL	The color to draw the border. The default uses the current par("fg") setting. Use border = NA to omit borders.
col = NA	The fill color for the polygon(s). If density is not NULL, the specified color is used for the density lines.
lty	The line type to use.
...	Additional graphical parameters can be given, e.g., lwd.
fillOddEven = FALSE	Controls the way that self-intersecting polygons are colored/filled.

SEE the par command for details.

Examples

  ## Make a plot without data to set a coordinate system (Figure 3-32)
> plot(0:10, 0:10, type = "n")

  ## Make data for shape coordinates and draw
  ## Use vector data
> tri1x = 0:2
> tri1y = c(0, 2, 0)

  ## Draw this shape
> polygon(tri1x, tri1y, lty = 2) # Dotted border

  ## Make more data, matrix
> tri2mat = matrix(c(4, 2, 6, 0, 4, 4), ncol = 2)

  ## Draw this shape with fill color and wide line
> polygon(tri2mat, col = "lightblue", lwd = 2)

  ## More data as a list
> xc = c(6, 8, 6, 10, 4, 5, 6, 9, 8, 10) # vector for x
> yc = c(0, 4, 6, 9, 10, 8, 9, 6, 4, 0) # vector for y
> polyl = list(x = xc, y = yc) # put data into a list

  ## Draw the shape using the list data
> polygon(polyl, col = "pink", border = NA) # Turn off border
> polygon(polyl$y, polyl$x, col = "gray90") # Switch co-ordinates

Figure 3-32: Using the polygon command to draw various shapes

Command Name

rect

This command draws one or more rectangles into an existing plot window. Other plotting commands such as hist and barplot use the command.

Common Usage

rect(xleft, ybottom, xright, ytop, density = NULL, angle = 45,
    col = NA, border = NULL, lty = par("lty"), lwd = par("lwd"),
    ...)

Related Commands

Command Parameters

xleftybottomxrightytop	The coordinates for the rectangle(s). A vector of left x positions. A vector of bottom y positions. A vector of right x positions. A vector of top y positions. You are essentially describing the coordinates for the bottom-left point and the top-right point of each rectangle you want to draw.
density = NULL	The density of shading lines in lines per inch. The default is NULL, which suppresses lines.
angle = 45	The angle of shading lines in degrees. This is measured as a counter-clockwise rotation.
col = NA	The color to fill the rectangles with. The default NA, (also NULL) equates to no fill.
border = NULL	The color to draw the border. The default uses the current par("fg") setting. Use border = NA to omit borders. Use border = TRUE to set the color of the border to the same as the shading lines (if density is used).
lty	The line type.
lwd	The line width.
...	Additional graphical parameters can be used.

Examples

 ## Make some data
> dat = c(2, 3, 4, 4, 4, 5, 5, 5, 5, 5, 6, 6, 6, 6, 7)
> table(dat) # Look at the frequencies
dat
2 3 4 5 6 7 
1 1 3 5 4 1

  ## Make your own histogram!
  ## Use hist to determine breakpoints on x-axis
> hist(dat, plot = FALSE)$breaks # computes breakpoints
[1] 2 3 4 5 6 7
> breaks = hist(dat, plot = FALSE)$breaks # make a variable for result

> hist(dat, plot = FALSE)$counts # computes frequencies
[1] 2 3 5 4 1
> counts = hist(dat, plot = FALSE)$counts # make a variable for result

  ## Make a blank plot as a coordinate system (basis for Figure 3-33)
  ## Leave out everything!
> plot(2:7, 0:5, type = "n", axes = FALSE, xlab = NA, ylab = NA)

  ## Add basic axes (adding to Figure 3-33)
> axis(2)          # the y-axis
> axis(1, pos = 0) # the x-axis, shift this up a bit
  ## Create a histogram using rectangles, one for each bar
> for (i in 1:length(counts)) {
  rect(breaks[i], 0, breaks[i+1], counts[i], col = "gray90") }

  ## Add titles (finishing Figure 3-33)
> title(xlab = "Breakpoints", ylab = "Counts")

Figure 3-33: A histogram created using rect command

Adding Text

You can add text to graphs in several ways. You can create titles for plots and axes and you can place text in the plot area or in the margins. R also provides a means to create complicated expressions, for example, containing superscript, subscript, and mathematical symbols.

Command Name

expression
is.expression
as.expression

The expression command allows you to create text strings containing superscript and subscript elements. It also allows the use of math and other symbols. This allows you to create text labels for use as titles and text in graphics windows. An expression object holds a class attribute "expression"; the is.expression and as.expression commands allow you to test for and set this attribute.

SEE also Theme 1, “Data Types.”

Common Usage

expression(...)
is.expression(x)
as.expression(x)

Related Commands

Command Parameters

...	R objects, text, or symbols to create the expression.
x	An R object to test or coerce to an expression.

The following are some of the expressions you can create; use help(plotmath) in R for a comprehensive list. You can also type demo(plotmath) for more details.

Text Elements

~	A space.
*	A connector.
^	Superscript. Text following the caret is superscripted.
[]	Subscript. Text within the brackets is subscripted.
	Newline character.

Font Face

plain()	The text in parentheses is plain text.
italic()	The text in parentheses is italic text.
bold()	The text in parentheses is bold text.
bolditalic()	The text in parentheses is bold and italic text.
underline()	The text in parentheses is underlined.

Math Expressions

x + y	Produces x + y.
x – y	Produces x – y.
x == y	Produces x = y.
x != y	Produces x y.
x %~~% y	Produces x ≈ y.
x %+-% y	Produces x ± y.
x %/% y	Produces x ÷ y.
bar(x)	Produces x with an overbar.
frac(x, y)	Produces a fraction with x over y.
x %up% y	Produces an up arrow, x ↑ y.
x %down%y	Produces a down arrow, x ↓ y.
x %->% y	Produces a right arrow, x → y.
x %<-% y	Produces a left arrow, x ← y.
sum(x, a, b)	Produces a sum (capital sigma) symbol, ∑, with optional sub and superscripts.
sqrt(x)sqrt(x, y)	Produces a square root symbol, √x, with optional root, y√x.
infinity	An infinity symbol, ∞.
alpha – omega	Greek letters in lowercase.
Alpha – Omega	Greek letters in uppercase.
180*degree	Produces a degree symbol, 180˚.
x ~ y	A space, x y.

Examples

  ## Make a blank plot to set a coordinate system (base for Figure 3-34)
> plot(1:10, 1:10, type = 'n')

  ## Set character expansion to a new level
> opt = par(cex = 1.5)

  ## Make some math expressions and draw them on the plot
> text(1, 1, expression(hat(x)))
> text(2, 1, expression(bar(x)))
> text(2, 2, expression(alpha==x))
> text(3, 3, expression(beta==y))
> text(4, 4, expression(frac(x, y)))
> text(5, 5, expression(sum(x)))
> text(6, 6, expression(sum(x^2)))
> text(7, 7, expression(bar(x) == sum(frac(x[i], n), i==1, n)))
> text(8, 8, expression(sqrt(x)))
> text(9, 9, expression(sqrt(x, 3)))

  ## Reset the character expansion to original
> par(opt)

  ## Make some text expressions and draw on the plot
> text(3, 7, expression(Speed ~ ms^-1), cex = 2)
> text(7, 2, expression(Count[per ~ mm]), cex = 2)
> text(4, 9, expression(Mixed^super*" and"[sub]*" script"), cex = 2)

Figure 3-34: Creating math and text using the expression command

Command Name

legend

This command adds a legend to an existing plot window.

SEE also legend in “Adding Legends.”

Command Name

mtext

This command adds text to the marginal area of a plot, that is, outside the coordinate system.

Common Usage

mtext(text, side = 3, line = 0, outer = FALSE, at = NA,
      adj = NA, padj = NA, cex = NA, col = NA, font = NA, ...)

Related Commands

title

expression

text

Command Parameters

text	The text to write. This can be a character string or an expression.
side = 3	The side of the plot to use. The sides are 1 = bottom, 2 = left, 3 = top, 4 = right. The default is the top.
line = 0	The line of the margin to use. The default is 0, which is adjacent to the outside of the plot area. Positive values move outward and negative values inward.
outer = FALSE	If outer = TRUE, the outer margin is used if available.
at = NA	How far along the side to place the text in relation to the axis scale. Text is centered on this point.
adj = NA	How far along the side to place the text as a proportion. The default is effectively 0.5, which places the text halfway along. If text is oriented parallel to the axis, adj = 0 will result in left or bottom placement. Text is centered.
padj = NA	Adjusts the text perpendicular to the reading direction. This permits “tweaking” of the placement. Positive values place text lower; negative values higher.
cex = NA	The character expansion. Values > 1 make text larger; values < 1 make text smaller.
col = NA	The color for the text. The default, NA, means use the current setting par("col").
font = NA	The font to use. The default, NA, means use the current setting par("font"). Use font = 1 for regular text; 2 = bold, 3 = italic, 4 = bold+italic.
...	Additional graphics parameters can be used. Of particular interest is las, which controls the text direction: las = 0—Text parallel to axis (default). las = 1—Text horizontal. las = 2—Text perpendicular to axis. las = 3—Text vertical.

SEE the par command for a more comprehensive list.

Examples

  ## Make a basic plot 
> plot(1:10, 1:10)

  ## Add marginal text, see Figure 3-35 for results
> mtext('mtext(side = 1, line = -1, adj = 1)',
  side = 1, line = -1, adj = 1)

> mtext('mtext(side = 1, line = -1, adj = 0)',
  side = 1, line = -1, adj = 0)

> mtext('mtext(side = 2, line = -1, font = 3)',
  side = 2, line = -1, font = 3)

> mtext('mtext(side = 3, font = 2)', side = 3, font = 2)

> mtext('mtext(side = 3, line = 1, font = 2)',
  line = 1, side = 3, font = 2)

> mtext('mtext(side = 3, line = 2, font = 2, cex = 1.2)',
  cex = 1.2, line = 2, side = 3, font = 2)

> mtext('mtext(side = 3, line = -2, font = 4, cex = 0.8)',
  cex = 0.8, font = 4, line = -2)

> mtext('mtext(side = 4, line = 0)', side = 4, line = 0)

Figure 3-35: Marginal text placed using the mtext command

Command Name

text

This command adds text to a plot. It is a very general command and you can alter the text in many ways. Text can also be described as an expression.

SEE also par.

Common Usage

text(x, y = NULL, labels = seq_along(x), adj = NULL,
    pos = NULL, offset = 0.5,
    cex = 1, col = NULL, font = NULL, ...)

Related Commands

Command Parameters

x, y	The coordinates for positioning of the text. The coordinates can be separate x and y vectors, or y can be missing if x has a plotting structure (a list with x and y elements or a two-column matrix or data frame). You can also use locator(1) to place text with a click of the mouse.
labels	The text labels to place on the plot at the specified coordinates. Can be a character string or an expression. The default attempts to create a numeric index and plots values accordingly; this is not always successful, so it is best to specify labels explicitly!
adj = NULL	An adjustment to the placement coordinates (text is centered on the coordinates). You can specify one or two values (x, y). The default is effectively adj = c(0.5, 0.5), which makes no adjustment. A value of 1 adjusts left (or down). A value of 0 adjusts right (or up). Values > 1 or < 0 are also permitted.
pos = NULL	The positioning of the text relative to the coordinates. This overrides any adj parameter. The default, NULL, results in text centered on the point. Other options are: pos = 1—Below point pos = 2—Left of point pos = 3—Above point pos = 4—Right of point
offset = 0.5	When pos is specified, the offset parameter offsets the position of the text by a fraction of the character width. A value of 1 offsets away from the original coordinate, a value of 0 offsets toward the original coordinate. Values > 1 or < 0 are also permitted.
cex = 1	A character expansion factor. Larger values increase size; smaller values decrease size.
col = NULL	The color to use for the labels.
font = NULL	The font to use. The default, NA, means use the current setting par("font"). Use font = 1 for regular text; 2 = bold, 3 = italic, 4 = bold+italic.
...	Additional graphical parameters may be used. Of particular interest is srt, which sets the rotation of text in degrees. The rotation is counter-clockwise.

SEE the par command for a more comprehensive list.

Examples

  ## Make a basic plot with points
> plot(1:10, 1:10, pch = 3, cex = 1.5)

  ## Add text using various methods of alignment (see Figure 3-36)
> text(4, 4, 'Centered on point')

> text(3, 3, 'Under point (pos = 1)', pos = 1)

> text(5, 5, 'Left of point (pos = 2)', pos = 2)

> text(6, 6, 'Above point (pos = 3)', pos = 3)

> text(7, 7, 'Right of point (pos = 4)', pos = 4)

> text(8, 8, "Upside down! (pos = 4, offset = -0.5)",
  srt = 180, pos = 4, offset = -0.5)

> text(1,1, "Sideways (adj = c(-0.05, 0.5), pos = 4)",
  srt = 90, adj = c(-0.05,0.5))

Figure 3-36: Text positioning in the plot window

Command Name

title

This command places titles on plots. It can add labels to the axes as well as an overall title and subtitle. The titles must be characters, but you can specify an expression, allowing subscripts, symbols, and so on. Most of the commands that produce graphs will accept the same parameters, but it is sometimes useful to specify titles separately.

Common Usage

title(main = NULL, sub = NULL, xlab = NULL, ylab = NULL,
      line = NA, outer = FALSE, ...)

Related Commands

text

mtext

expression

Command Parameters

main = NULL	The main title at the top of the plot window.
sub = NULL	A subtitle.
xlab = NULL	A title for the x-axis.
ylab = NULL	A title for the y-axis.
line = NULL	Allows for offsetting of titles (in marginal lines). A value of 0 places the title just outside the axis. Larger values move the title outward, and smaller values move the title inward.
outer = FALSE	If outer = TRUE, the title is added to the outer margin.
...	Additional graphical parameters can be used. To differentiate between titles, add .main, .sub, or .lab to the parameter required. For example: font.main, font.sub, font.lab for font col.main, col.sub, col.lab for color cex.main, cex.sub, cex.lab for character expansion

SEE the par command for additional parameters.

Examples

  ## Set wider margins for plots (save original settings in opt)
> opt = par("mar" = c(7, 5, 5, 3))

  ## Make a simple plot (Figure 3-37). Alter most of the settings!
  ## Include x-axis and y-axis titles here
> plot(1, col.axis = "darkgreen", cex.axis = 1.5, font.axis = 3,
 col.lab = "brown", cex.lab = 2, font.lab = 3,
 xlab = "X-axis", ylab = "Y-axis")

  ## Add main and sub-titles. Alter most of the settings!
> title(main = "Main title", font.main = 4, col.main = "blue",
 cex.main = 2, sub = "Sub-title", font.sub = 1,
 col.sub = "red", cex.sub = "0.75")

  ## Reset margin settings to previous
> par(opt)

Figure 3-37: Customizing titles

Adding Legends

Some plot types have a legend parameter (for example, barplot), which allows the placement of a legend. The legend command enables a legend to be created and placed on any plot. The placement of the legend can be achieved in three ways: by coordinate, by keyword, or interactively. See the following command parameters for details.

Command Name

legend

Creates and adds a legend to an existing plot. You have many options and the parameter list is long!

Common Usage

legend(x, y = NULL, legend, fill = NULL, col = par("col"),
      border="black", lty, lwd, pch,
      angle = 45, density = NULL, bty = "o", bg = par("bg"),
      box.lwd = par("lwd"), box.lty = par("lty"), box.col = par("fg"),
      pt.bg = NA, cex = 1, pt.cex = cex, pt.lwd = lwd,
      xjust = 0, yjust = 1, x.intersp = 1, y.intersp = 1,
      adj = c(0, 0.5), text.width = NULL, text.col = par("col"),
      merge = do.lines && has.pch,
      ncol = 1, horiz = FALSE, title = NULL,
      inset = 0, title.col = text.col, title.adj = 0.5, seg.len = 2)

Related Commands

Command Parameters

x, y = NULL	The coordinates where the legend should be placed. You can specify x and y coordinates explicitly or using a text string. The options are "bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right", and "center". Abbreviations can be used. You can also place the legend interactively using locator(1) instead of x. The top-left corner of the legend will be placed where you click with the mouse.
legend	The text of the legend. Usually this will be a character or expression vector.
fill = NULL	The fill colors for boxes to appear beside the legend text. If density is given, fill gives the colors for the shading lines. The default, NULL, omits boxes.
col = par("col")	The colors to use for the lines and/or points that appear in the legend. The default uses the current setting in par("col").
border = "black"	The color for the boxes of the legend. Only used if fill is not NULL.
lty	The line types used in the legend. Usually these will match those used in the plot.
lwd	The line widths used in the legend. Usually these will match those used in the plot.
pch	The plotting symbols used in the legend. Usually these will match those used in the plot.
density = NULL	The density of shading lines in lines per inch. The default is NULL, which suppresses lines.
angle = 45	The angle of shading lines in degrees. This is measured as a counter-clockwise rotation.
bty = "o"	The type of box to place around the legend. The default, "o", produces a box. Use bty = "n" to omit the box.
bg = par("bg")	The background color to use for the legend box; only used if bty = "o". The default uses the current setting from par("bg").
box.ltybox.lwdbox.col	Settings specific to the box around the legend (assuming bty = "o"); they set line type, line width, and color.
pt.bg	The background color for the points that appear in the legend (for open type symbols, pch = 21:25). This will usually match those from the original plot.
cex	The character expansion factor. This operates relative to the current setting in par("cex"). Specifying a value also sets the expansion for pt.cex and title.cex (which can also be set independently).
pt.cexpt.lwd	Settings for the points that appear in the legend. Sets their expansion factor and line width.
xjust = 0yjust = 1	Adjust the justification of the legend relative to the placement coordinates: 0 = left (or bottom), 0.5 = centered, 1 = right (or top).
x.intersp = 1y.intersp = 1	Sets the character interspaces for the horizontal or vertical line distances. Larger values allow you to “spread out” the legend over a greater area.
adj = c(0, 0.5)	Adjusts the text in the legend box. You can specify one or two values corresponding to the x- and y-axis directions. Increasing the defaults results in text being adjusted to the left (or down). Decreasing the defaults results in text being adjusted right (or up).
text.width = NULL	Sets the text width (and so the extent of the legend box), which is usually computed automatically. The value is not in characters; you can determine the value for your text using strwidth(text), where text is your character string or expression.
text.col = par("col")	The color of the text in the legend. The default uses the current setting from par("col"); usually this is "black".
merge = TRUE	If merge = FALSE, the points appear at the end of the lines in the legend, rather than in the middle.
ncol = 1	The number of columns for the legend. The default is 1.
horiz = FALSE	If TRUE, the legend is set out horizontally instead of vertically. This has the same effect as increasing the number of columns, but note that you cannot have horiz = TRUE and ncol > 1.
title = NULL	A title for the legend, usually as a character string or expression.
inset = 0	If the legend is placed using a keyword (rather than x, y coordinates), inset specifies the distance to the margin(s). The value is a fraction of the plot region.
title.col	The color to use for the title.
title.adj = 0.5	Sets the horizontal adjustment for the title (as a proportion of the legend width). The default, 0.5, centers the title. Smaller values shift the title to the right. Larger values shift the title to the left.
seg.len = 2	The length of the lines drawn in the legend. Larger values mean longer lines (the units are character widths).

Examples

  ## Make an empty plot to create a coordinate system
> plot(0:10, 0:10, type = "n")

  ## Add some points/lines (see Figure 3-38 for final result)
> points(3:5, 4:6, type = "b", lwd=2, lty = 1, pch = 21, col = "black")
> points(2:4, 2:4, type = "b", lwd=2, lty = 2, pch = 24, col = "blue")
> points(5:7, 5:7, type = "b", lwd=2, lty = 3, pch = 25, col = "red")

  ## Make a list of names as labels for each set of lines/points
> mydata = c("Line1", "Line2", "Line3")

  ## Add a legend, take care to match up line/point parameters
> legend("topright", legend = mydata, lty = c(1, 2, 3), lwd = 2,
 col = c("black", "red", "blue"), pch = c(21, 24, 25))

  ## It is often easier to make named objects for colors
  ## and plot characters
> plcols = c("black", "red", "blue")
> plchr = c(21, 24, 25)

  ## Add more legends: note the various options
> legend("bottomleft", legend = mydata, lty = 1:3, col = plcols,
 pch = plchr, bty = "n", title = "Sample
Legend Title")

> legend("top", legend = mydata, lty = 1:3, col = plcols,
 pch = plchr, horiz = TRUE, inset = 0.01)

> legend(8.5, 1.5, legend = mydata, lty = 1:3, col = plcols,
 pch = plchr, bg = "gray90")

> legend("right", legend = mydata, lty = 1:3, col = plcols,
 pch = plchr, ncol = 2, inset = 0.01, title = "Two-column Layout")

  ## This time go for simple colored boxes
> legend(0, 8, legend = mydata, fill = plcols)

Figure 3-38: A variety of legends

  ## Add a legend using the mouse to set the location
  ## This adds to the previous example
  ## Top left of legend appears where you click with the mouse
> legend(locator(1), legend = mydata, lty = 1:3, col = plcols)

Graphical Parameters

R provides a mechanism to view current graphical settings and alter them via the par command. The parameters are common to most of the commands that produce graphics. Most settings can be altered (temporarily) by the plotting commands, but a few can only be set via the par command.

In addition to the par command, a few other commands have relevance to graphical parameters; for example, the commands that deal with partitioning the plot window and the palette command for creating colors.

What’s In This Topic:

Using the par command
Altering color

Setting color palettes
Color parameters

Altering axis parameters
Altering text parameters

Text parameters
Plotting characters/symbols

Altering line (and box) parameters
Altering plot margins
Altering the graph window

Splitting the window into parts
Controlling split windows

Using the par Command

The par command is the management tool for most of the graphical parameters used in R.

Command Name

par

This command queries or sets the graphical parameters. Some of the parameters are read-only and cannot be set by the user. Many of the remaining parameters can be altered by the separate commands that draw plots, at least for the duration of the plotting. Some parameters can only be set via the par command.

To make it easy to return to previous settings, you can save the current parameters to a named object (a list) as the new settings are applied. See the following examples.

SEE additional entries for the par command listed under the following headings:

“Altering Color”
“Altering Axis Parameters”
“Altering Text Parameters”
“Altering Line (and Box) Parameters”
“Altering Plot Margins”
“Altering the Graph Window”

Common Usage

par(..., no.readonly = FALSE)

Related Commands

Command Parameters

...	A list of parameters to be queried or set. Generally, the form is tag = value, where tag is a character string corresponding to the required parameter. If no tag is given, the values of all are reported.
no.readonly = FALSE	If TRUE, only the parameters that can be set by the user are shown.

Examples

  ## List all parameters that you can change (result not shown here)
> par(no.readonly = TRUE)

  ## List some parameters
  ## Character expansion, color, background, plot margin size
> par(list("cex", "col", "bg", "mar"))

$cex
[1] 1

$col
[1] "black"

$bg
[1] "white"

$mar
[1] 5.1 4.1 4.1 2.1

  ## Alter the margin sizes
  ## Note that you make an object; the current setting is saved there
> opt = par("mar" = c(7, 4, 4, 2))

  ## Check the new setting
> par("mar")
[1] 7 4 4 2

  ## See how previous setting was saved
> opt
$mar
[1] 5.1 4.1 4.1 2.1

  ## Restore setting and check it
> par(opt)
> par("mar")
[1] 5.1 4.1 4.1 2.1

Altering Color

Color can be managed in several ways. Various commands deal with color palettes and creation of colors (for example, the RGB specification). Other color parameters are set via the par command.

Command Name

colors
colours

These commands display the built-in color names. The color names can be used wherever a color is required. Colors are often referred to by a simple integer value. This refers to the position of the color in the current palette.

SEE the par command to set various default colors.

Common Usage

colors()
colours()

Related Commands

palette

col2rgb

Command Parameters

()	No parameters are required.

Examples

  ## Get colors and save result as an object
> cl = colors()

  ## How many colors are available?
> length(cl)
[1] 657

  ## Display the first 20 color names
  ## Color numbers do not correspond to their position in this list
  ## but to their position in the current palette

> cl[1:20]
 [1] "white"         "aliceblue"     "antiquewhite"  "antiquewhite1"
 [5] "antiquewhite2" "antiquewhite3" "antiquewhite4" "aquamarine"   
 [9] "aquamarine1"   "aquamarine2"   "aquamarine3"   "aquamarine4"  
[13] "azure"         "azure1"        "azure2"        "azure3"       
[17] "azure4"        "beige"         "bisque"        "bisque1"

Command Name

col2rgb
hcl
hsv
rgb
rgb2hsv

These commands deal with the creation of colors and the translation of specification:

col2rgb converts a named color to its RGB specification.
hcl creates a color from hue, chroma, and luminance.
hsv creates a color from hue, saturation, and value.
rbg creates a color from red, green, and blue settings.
rgb2hsv converts RGB values into HSV equivalents.

Common Usage

col2rgb(col, alpha = FALSE)

hcl(h = 0, c = 35, l = 85, alpha, fixup = TRUE)

hsv(h = 1, s = 1, v = 1, gamma = 1, alpha)

rgb(red, green, blue, alpha, names = NULL, maxColorValue = 1)

rgb2hsv(r, g = NULL, b = NULL, gamma = 1, maxColorValue = 255)

Related Commands

palette

colors

Command Parameters

col	A named color. This can be a character string giving the name or a hexadecimal string "#rrggbb". You can also give a single integer value, which will return the appropriate value from the current palette.
alpha	The transparency value. Values are: col2rgb, set to TRUE or FALSE to display (or not) the result hcl, set between 0 and 1 (1 is opaque) rgb, set between 0 and maxColorValue
h	A value for “hue.” Values are: hcl, set between 0 and 360 (0 = red, 120 = green) hsv, set between 0 and 1
c	A value for “chroma.” The upper limit for this depends on h, “hue” and l, “luminance.”
l	A value for “luminance,” generally between 0 and 100, but for any combination of h and c only a subset is possible.
fixup = TRUE	If this is TRUE, the resulting color is adjusted so that it is a real color. If fixup = FALSE, an “unreal” color will result in NA.
s, v	Numeric levels for “saturation” and “value.” These should be between 0 and 1.
gamma	A gamma correction component.
r, g, b	Integer values for red, green, and blue components of the color. The range of values should be 0 to maxColorValue.
names = NULL	A character vector giving names for the resulting color(s).
maxColorValue	Sets the maximum value for r, g, and b. Values 1 or 255 are most useful.

Examples

  ## View current palette colors
> palette()

[1] "black"   "red"     "green3"  "blue"    "cyan"    "magenta" "yellow"  "gray"


  ## View current palette colors as RGB
> col2rgb(1:8)
      [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8]
red      0  255    0    0    0  255  255  190
green    0    0  205    0  255    0  255  190
blue     0    0    0  255  255  255    0  190

Command Name

palette
rainbow
heat.colors
terrain.colors
topo.colors
cm.colors
gray
grey

These commands create and manage color “sets.” The palette command manages the “set” of colors (the palette); you can see the current palette or create a customized range of colors as a palette.

The other commands create custom “sets” of colors that can be assigned to the palette (the commands gray and grey are the same). In plotting commands the parameter col = palette() will use the current color “set.” Specifying a color simply by an integer value takes the color from its position in the current palette. Using palette("default") returns to base settings and restores the default “set.”

Common Usage

palette(value)
rainbow(n, s = 1, v = 1, start = 0, end = max(1,n - 1)/n, gamma = 1, alpha = 1)
heat.colors(n, alpha = 1)
terrain.colors(n, alpha = 1)
topo.colors(n, alpha = 1)
cm.colors(n, alpha = 1)
gray(level)
grey(level)

Related Commands

colors

col2rgb

hsv

Command Parameters

value	The palette to set; you have several options: Leave empty, view current palette. "default", restores original default palette. Names of colors as character strings, sets new palette to these colors. Color commands, e.g., rainbow(n), to set new palette.
n	The number of colors to be in the palette.
s, v	The “saturation” and “value” to be used in the HSV color descriptions.
start = 0	The starting value for “hue” in the rainbow (between 0 and 1).
end	The ending value for “hue” in the rainbow (between 0 and 1).
gamma	The gamma correction.
alpha	The transparency, between 0 and 1 (1 is opaque).
level	A vector of gray levels, between 0 and 1 (0 is black, 1 is white).

Examples

  ## Set plot window into 6 (2 rows, 3 columns)
> opt = par(mfrow = c(2, 3))

  ## Produce color wheels as pie charts (final result in Figure 3-39)
> pie(rep(1,12), col = rainbow(12), radius = 0.95,
 main = "Rainbow Colors")
> box(which = "figure") # a box around the sub-window

> pie(rep(1,12), col = heat.colors(12), radius = 0.95,
 main = "Heat colors")
> box(which = "figure")

> pie(rep(1,12), col = terrain.colors(12), radius = 0.95,
 main = "Terrain Colors")
> box(which = "figure")

> pie(rep(1,12), col = topo.colors(12), radius = 0.95,
 main = "Topo Colors")
> box(which = "figure")

> pie(rep(1,12), col = cm.colors(12), radius = 0.95, main = "CM Colors")
> box(which = "figure")

> pie(rep(1,12), col = gray(seq(0, 1, len = 12)), radius = 0.95,
 main = "Gray Colors")
> box(which = "figure")

  ## Reset the plot window to previous setting
> par(opt)

Figure 3-39: Color wheels for standard palettes

  ## Set new palette (6 rainbow colors)
> palette(rainbow(6))
> palette()
[1] "red"     "yellow"  "green"   "cyan"    "blue"    "magenta"

  ## Set palette to 6 topo colors
> palette(topo.colors(6))
> palette()
[1] "#4C00FF" "#00E5FF" "#00FF4D" "#E6FF00" "yellow"  "#FFE0B3"

  ## View palette colors as RGB
> col2rgb(1:length(palette()))
      [,1] [,2] [,3] [,4] [,5] [,6]
red     76    0    0  230  255  255
green    0  229  255  255  255  224
blue   255  255   77    0    0  179

  ## Reset palette to default
> palette("default")
> palette()

[1] "black"   "red"     "green3"  "blue"    "cyan"    "magenta" "yellow"  "gray"

Command Name

par

This command queries or sets the various graphical parameters.

SEE also “Using the par Command.”

Common Usage

par(tag = value)

par(list(tag1 = value, tag2 = value, ...))

Related Commands

palette

col2rgb

colors

Command Parameters

bg	Sets the background color for the plot. If set via par("bg"), "new" is also set to FALSE (see “Altering the Graph Window”). Note that some graphical commands have a bg parameter, which is different than the par setting.
col	The overall default plotting color, usually "black". Several variants control colors on plot elements: col.axis—Axis annotation col.lab—Axis labels (titles) col.main—Plot title col.sub—Plot subtitle
fg	The foreground color for plots. Controls axis color, for example. When set via par("fg"), the "col" parameter is also set to the same color. If you want different values, set "fg" first, then "col" (which you will have to do with a separate par command).

Examples

  ## Check current setting of some parameters
> par(list("bg", "col", "fg"))
$bg
[1] "white"

$col
[1] "black"

$fg
[1] "black"

  ## You can make a list of parameters and set them anytime
  ## Use the list for custom settings or as a "default" for restore
> parcols = list(col = "black", fg = "black", bg = "white",
 col.main = "black", col.sub = "black",
 col.lab = "black", col.axis = "black")

## If you assign a name to the par command you can restore later
> opt = par(list(bg = "gray95", fg = "blue", col.main = "red",
 col.sub = "brown"))

  ## The list you made contains the settings that were current
  ## when you made it
> opt
$bg
[1] "white"

$fg
[1] "black"

$col.main
[1] "black"

$col.sub
[1] "black"

  ## Use your list to restore previous settings
> par(opt)

  ## Or you can use the earlier list
> par(parcols)

Altering Axis Parameters

Most axis parameters can be set directly as part of a plotting command, but some can only be altered via the par command. Several separate commands also exist relating to axes.

Command Name

axis

This command adds an axis to a current plot. It allows you to specify a completely customized axis.

Common Usage

axis(side, at = NULL, labels = TRUE, tick = TRUE, line = NA,
    pos = NA, outer = FALSE, font = NA, lty = "solid",
    lwd = 1, lwd.ticks = lwd, col = NULL, col.ticks = NULL,
    hadj = NA, padj = NA, ...)

Related Commands

Command Parameters

side	An integer value giving the side for the axis: 1 = bottom, 2 = left, 3= top, 4 = right.
at = NULL	The points along the axis where the tick marks are to be placed. If NULL, the default, the tick marks are calculated automatically. Otherwise, you must specify values explicitly.
labels = TRUE	The labels to use for the tick marks. If TRUE, numerical labels are used. You can specify labels as a character string or an expression.
tick = TRUE	If FALSE, the axis line and tick marks are not drawn in.
line = NA	The margin line where the axis will be drawn. Effectively, the default = 0. Positive values move the axis outward, negative values inward.
pos = NA	The coordinate where the axis line is to be drawn. This will be a y-value for sides 1 and 3 and an x-value for sides 2 and 4.
outer = FALSE	If TRUE, the axis is drawn in the outer margin of the plot.
font = NA	The font for the text. The default is effectively par("font").
lty = "solid"	The line type to use. The default is "solid". See “Altering Line (and Box) Parameters.”
lwd = 1lwd.ticks = lwd	The line width for the axis and tick marks. The tick marks default to the same as the lwd setting.
col = NULLcol.ticks = NULL	The colors for the axis line and tick marks. If col = NULL, the setting in par("fg") is used. If col.ticks = NULL, the setting is whatever col is set to.
hadj = NA	An adjustment value for all labels parallel to the reading direction. The default is effectively 0.5. Smaller values place labels to the right, larger values to the left.
padj = NA	An adjustment value for all labels perpendicular to the reading direction. The default is effectively 0. Positive values place labels lower, negative values higher.
...	Additional graphical parameters can be used. For example: cex.axis, col.axis and font.axis

SEE the par command for more details.

Examples

  ## Make some data
> rain = c(34, 32, 23, 15, 10, 8, 6, 9, 12, 21, 24, 29) # Vector
> names(rain) = month.abb[1:12] # Make labels
> rain # View the data
Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec 
 34  32  23  15  10   8   6   9  12  21  24  29 

  ## Because x-data are categorical a regular plot will show index
  ##  rather than categories we want, so
  ##  draw plot without axes (forms basis for Figure 3-40)
  ## Note that axis labels omitted using NA
> plot(rain, type = "b", lty = "dashed", lwd = 2.5, axes = FALSE,
 main = "Rainfall", xlab = NA, ylab = NA)

  ## Axis 2 (y-axis) is numeric so default is fine but
  ## use las to rotate annotation
> axis(side = 2, las = 1)

  ## New x-axis, at = axis ticks, specify number required
  ## Also give labels
> axis(side = 1, at = 1:length(rain), labels = names(rain))

  ## Add axis labels (final result is Figure 3-40)
> title(xlab = "Month", ylab = "Rainfall in mm")

Figure 3-40: Specifying a custom axis

Command Name

axTicks

This command computes sensible (pretty) locations for tick marks. The locations are the same as calculated using the axis or pretty commands, but axTicks is able to deal with log coordinates.

Common Usage

axTicks(side, axp = NULL, usr = NULL, log = NULL)

Related Commands

pretty

Command Parameters

side	An integer value giving the side for the axis: 1 = bottom, 2 = left, 3= top, 4 = right.
axp = NULL	A numeric vector with three values. You supply the start, end, and number of ticks required. The default values are taken from par("xaxp") or par("yaxp") according to the value of side.
usr = NULL	A numeric vector with four values. You supply the limits of the coordinate system for x and y directions. The default takes values as in par("usr").
log = NULL	A logical value indicating is log coordinates are active. The defaults take values from par("xlog") or par("ylog”).

SEE also “Altering the Graph Window.”

SEE also par.

Examples

  ## Set x-axis to a log scale
> par(xlog = TRUE)

  ## Determine tick marks locations using 3 algorithms
> axTicks(side = 1, axp = c(1,1000, 2))
[1]    1    5   10   50  100  500 1000

> axTicks(side = 1, axp = c(1,1000, 1))
[1]    1   10  100 1000

> axTicks(side = 1, axp = c(1,1000, 3))
 [1]    1    2    5   10   20   50  100  200  500 1000

  ## Set x-axis back to regular scale
> par(xlog = FALSE)

  ## Make a plot with one axis log, the other not (not shown)
> plot(1:1000, 1:1000, log = "x")

  ## Look at tick mark locations
> axTicks(1)
[1]    1    5   10   50  100  500 1000
> axTicks(2)
[1]    0  200  400  600  800 1000

Command Name

box

This command adds a bounding box around the plot.

SEE “Adding Shapes.”

Command Name

par

This command queries or sets the various graphical parameters.

SEE also “Using the par Command.”

Common Usage

par(tag = value)

par(list(tag1 = value, tag2 = value, ...))

Related Commands

Command Parameters

adj	Adjusts how text strings are justified. See the text, mtext, and title commands. Generally, 0.5 means centered, 0 means left justified, and 1 means right justified.
bty	The type of box to draw around the plot region. The default is "O", producing a complete box. Other options are "L", "C", "U", "7", and "]". The resulting box resembles the character (which can be lowercase). Use bty = "n" (lowercase) for no box.
cex.axiscex.lab	The character expansion to use for axis annotation and axis labels, respectively. The values are relative to the current setting in par("cex"). See “Altering Text Parameters.”
col.axiscol.lab	The color to use for axis annotation and axis labels, respectively.
font.axisfont.lab	The font to use for axis annotation and axis labels, respectively. Generally, 1 = plain, 2 = bold, 3 = italic, 4 = bold+italic.
lab	This controls approximately how many tick marks and annotations will be used for the axes. You specify three values (x, y, len), which correspond to the two axes and the length of the labels (len is unused and provides compatibility with the S language). The default is c(5, 5, 7).
las	Controls how axis labels are oriented relative to the axes. Specify a numeric value as follows: 0—Always parallel to the axis (default) 1—Always horizontal 2—Always perpendicular to the axis 3—Always vertical
tck = NA	Controls the length of the tick marks as a fraction of the smallest axis. The default is to use tcl = -0.5. Values >= 0.5 are interpreted as a fraction of the axis. Use tck = 1 to draw gridlines. Positive values place tick inside the axis, negative values outside.
tcl = -0.5	Controls the length of the tick marks as a fraction of the height of a line of text. Using tcl = NA sets the value to –0.01 (the default for the S language).
xaxpyaxp	Controls the number of tick marks and their intervals. For a regular scale (not log), you supply three values: c(x, y, n). These correspond to the extremes of the axis and the required number of tick marks.If the axis is a log scale, the three values have a different meaning. Values for x and y correspond to the powers of 10 and n is a code 1, 2, or 3. It is hard to visualize the result and experimentation is encouraged! Generally, you get more tick marks as the code increases. You can also use negative values, which ignore the log values and give tick marks in the 0–10 range.
xaxsyaxs	Controls the style of interval calculation for tick marks: "r"—Regular (the default) intervals; axis is extended by 4% then subdivided. "i"—Internal intervals; axis is subdivided without extension. Use this to get x- and y-axes to “meet” at the origin.
xaxtyaxt	Sets the axis type. Values of "s", "l", or "t" will produce a regular axis, and a value of "n" will omit the axis. All other values will give an error.
xlogylog	A logical value determining if a log scale is to be used for the axis in question; the default is FALSE. These parameters can only be set using par.

Examples

  ## Set up plot window for 2 rows and 1 column
  ## par Figure 3-41
> par(mfrow = c(2, 1))

  ## Alter some axis parameters: las = annotation orientation,
  ## adj = justification, xaxs/yaxs = do not extend axis
  ## tcl = tick marks inside
> parax = par(las = 1, adj = 1, xaxs = "i", yaxs = "i", tcl = 0.5)

  ## Draw the plot (Figure 3-41, top)
> plot(0:10, 0:10, main = "Title")

  ## Reset values to previous
> par(parax)

  ## Draw plot again (Figure 3-41, bottom)
> plot(0:10, 0:10, main = "Title")

  ## Reset plot window to single plot
> par(mfrow = c(1, 1))

Figure 3-41: Customization of axis parameters

Command Name

pretty

This command calculates breakpoints for an axis. Essentially, the command creates equally spaced intervals spanning the range you specify.

Common Usage

pretty(x, n = 5, min.n = n %/% 3)

Related Commands

axTicks

Command Parameters

x	A numeric vector or object that can be coerced into one.
n = 5	The desired number of intervals. Generally, the result will be n or n+1 intervals.
min.n	The minimum number of intervals to calculate.

Examples

  ## Calculate default axis intervals
> pretty(1:1000)
[1]    0  200  400  600  800 1000

  ## This gives same result
> pretty(100:1000)
[1]    0  200  400  600  800 1000

  ## If you specify min value it must be > n (default n = 5)
> pretty(1:1000, n = 10, min = 9)
 [1]    0  100  200  300  400  500  600  700  800  900 1000

Altering Text Parameters

The par command provides a mechanism to alter many default text parameters. Many of these parameters can also be used from within the various plotting commands.

Command Name

par

This command queries or sets the various graphical parameters.

SEE also “Using the par Command.”

Common Usage

par(tag = value)

par(list(tag1 = value, tag2 = value, ...))

Related Commands

Command Parameters

adj	Adjusts how text strings are justified. See the text, mtext, and title commands. Generally, 0.5 means centered, 0 means left justified, and 1 means right justified. Note that the adj parameter in the text command will allow adjustment in x and y directions.
cexcex.axiscex.labcex.maincex.sub	The parameter cex sets the magnification factor for text. Note that some commands have cex as a parameter with different interpretation. The other parameters affect the expansion of text for axis, labels, and titles and operate relative to the setting of cex.
colcol.maincol.subcol.axiscol.lab	The col parameter sets the colors of the plot and text. The other parameters set colors for main and subtitles and axis annotations and labels.
crt	Controls the rotation of characters in degrees. This is generally not a helpful parameter and srt is more useful for rotating strings.
family	The name of the font family to use for drawing text. The default is "", which uses the defaults for the device. Other options include "serif", "sans", and "mono".
fontfont.mainfont.subfont.axisfont.lab	An integer value determines the style of text: 1 = plain (the default), 2 = bold, 3 = italic, 4 = bold+italic. The parameters set the font for plotting text, titles, axis annotation, and axis labels.
las	Controls how axis labels are oriented relative to the axes. Specify a numeric value as follows: 0—Always parallel to the axis (default) 1—Always horizontal 2—Always perpendicular to the axis 3—Always vertical
lheight	Specifies the line height multiplier. The default is 1. Larger values create more space between lines of text. This parameter can only be set using par.
pch	The plotting symbols to use. Generally, an integer value between 0 and 25. Values 32–127 give ASCII characters; negative values (< –31) use Unicode characters (if available). Alternatively, a character can be given as a string. Useful symbols include: 19—Solid circle 20—Bullet 21—Filled circle 22—Filled square 23—Filled diamond 24—Filled triangle, point up 25—Filled triangle, point down Characters 21 to 25 have a border, which can be colored separately; col affects the border and bg fills the character.In addition, pch = 46 (or pch = ".") is represented as a special character, a rectangle 0.01 inch in size (if cex = 1). Other symbols are scaled according to the font size.
ps	Sets the point size of text (but not symbols). This parameter can only be set using par.
srt	Sets the string rotation in degrees. The setting only operates for the text command. Text is rotated in a counter-clockwise direction.

Examples

  ## A blank plot to set up a coordinate system
  ## Final result will be Figure 3-42
> plot(0:10, 0:10, type = "n")

  ## Some regular text as a baseline
> text(2,10, "Regular text", pos = 4)

  ## Set text larger and use serif family
> par(list(cex = 2, family = "serif"))

  ## Add some text
> text(2,8, "Serif Family", pos = 4)

  ## Alter rotation and set sans serif family
> par(list(srt = 180, family = "sans"))

  ## Add some text note pos is opposite to previous
> text(2,6, "Sans Family", pos = 2)

  ## Alter rotation and set monospace family
> par(list(srt = 90, family = "mono"))

 ## Add some text
> text(8,6, "Monospace Family")

  ## Reset parameters
> par(list(cex = 1, srt = 0, family = ""))

  ## Create multi-line text
> text(2,4, "Multi-line
text with
default spacing", pos = 4)

  ## Alter line height
> par(lheight = 2)

## More multi-line text
> text(4, 2, "Multi-line
text with
custom spacing", pos = 4)

  ## Reset line height
> par(lheight = 1)

Figure 3-42: Altering text parameters

Altering Line (and Box) Parameters

Most graphical commands use lines of one sort or another. Various parameters can be set via the par command. Many of these can also be used directly by the plotting commands that utilize the settings.

Command Name

par

This command queries or sets the various graphical parameters.

SEE also “Using the par Command.”

Common Usage

par(tag = value)

par(list(tag1 = value, tag2 = value, ...))

Related Commands

Command Parameters

bty	The type of box to draw around the plot region. The default is "O", producing a complete box. Other options are "L", "C", "U", "7", and "]". The resulting box resembles the character (which can be lowercase). Use bty = "n" (lowercase) for no box.
col	Sets colors for the plot. This generally includes any lines drawn.
lend	The style of the ends of lines. You can specify an integer or a character string as follows: 0 or "round"—Rounded line caps (the default) 1 or "butt"—Butt line caps 2 or "square"—Square line caps
ljoin	This controls how lines are joined. Specify an integer value or a character string as follows: 0 or "round"—Rounded joins (the default) 1 or "miter"—Mitered line joins 2 or "bevel"—Beveled line joins
lmitre	Sets the line mitre limit and so controls when mitered line joins are converted to beveled joins. The default is 10; you must set a value > 1.
lty	The line type. This can be an integer or a character string as follows: 0 or "blank" 1 or "solid" 2 or "dashed" 3 or "dotted" 4 or "dotdash" 5 or "longdash" 6 or "twodash" Alternatively, you can specify your own pattern using a string of hexadecimal characters. The string defines the length of “on” and “off” segments and must be 2, 4, 6, or 8 characters in length.
lwd	The line width; the default is 1. This is similar to an expansion factor and larger values result in thicker lines.

Examples

  ## Set plot window to 2 rows and 2 columns
> par(mfrow = c(2, 2))

  ## Set box type and line type/width
> par(list(bty = "L", lty = 2, lwd = 1.5))

  ## Use bbel data from download as basis for plot
  ## (Figure 3-43, top left)
> plot(abund ~ light, data = bbel, type = "b")

  ## Alter parameters again
> par(list(bty = "7", lty = "dashed", lwd = 2))

  ## Redraw plot using new settings (Figure 3-43, top right)
> plot(abund ~ light, data = bbel, type = "b")

  ## Alter parameters again
> par(list(bty = "n", lty = 4, lwd = 2.5))

  ## Redraw (Figure 3-43, bottom left)
> plot(abund ~ light, data = bbel, type = "b")

  ## Alter settings again (these are the usual defaults)
> par(list(bty = "O", lty = 1, lwd = 1))

  ## Plot again (Figure 3-43, bottom right)
> plot(abund ~ light, data = bbel, type = "b")

  ## reset plot window
> par(mfrow = c(1, 1))

Figure 3-43: Altering line and box parameters

Altering Plot Margins

You have various ways to control the margins of your plots. These parameters can only be set via the par command.

SEE also “Altering the Graph Window.”

Command Name

par

This command queries or sets the various graphical parameters.

SEE also “Using the par Command.”

Common Usage

par(tag = value)

par(list(tag1 = value, tag2 = value, ...))

Related Commands

title

mtext