Version:	1.4-0
Date:	2025-08-19
Title:	Annotate Plots
Depends:	R (≥ 4.2.0)
Imports:	stats, graphics, grDevices, grid, conicfit
Description:	Interactively annotate 'base R graphics' plots with freehand drawing, symbols (points, lines, arrows, rectangles, circles, ellipses), and text. This is useful for teaching, for example to visually explain certain plot elements, and creating quick sketches.
License:	GPL-3
Encoding:	UTF-8
URL:	https://github.com/wviechtb/plotannotate https://www.wvbauer.com
BugReports:	https://github.com/wviechtb/plotannotate/issues
NeedsCompilation:	no
Packaged:	2025-08-19 14:23:26 UTC; wviechtb
Author:	Wolfgang Viechtbauer [aut, cre]
Maintainer:	Wolfgang Viechtbauer <wvb@wvbauer.com>
Repository:	CRAN
Date/Publication:	2025-08-22 18:50:02 UTC

plotannotate: Annotate Plots

Description

The plotannotate package allows annotating plots created with ‘base R graphics’. The function for this purpose is called annotate. After creating a plot, for example with plot(), the command annotate() enters a freehand drawing mode where one can draw on the plot with the mouse (or some other input device). Various symbols (points, lines, arrows, rectangles, circles, ellipses) and text can also be added. Pressing ⁠q⁠ or the right mouse button terminates the annotation mode. For further details, see the documentation of the annotate function.

The functionality provided by the package is especially useful when teaching (e.g., to visually explain certain plot elements), but can also be used for creating quick sketches (see also the blank function for creating a blank plot).

Note that the annotate() function makes extensive use of getGraphicsEvent to capture mouse movements and keyboard inputs. Only some graphics devices support this (currently only windows and x11). If you receive the error message ‘The graphics device does not support event handling’, then the graphics device that was opened does not provide this kind of functionality. For example, this will be the case for the RStudioGD graphics device that is used by RStudio. You can then try running x11() before creating the plot.

Also, annotate() does not work for plots based on the grid graphics engine (which includes plots created with the ggplot2 or lattice packages), since such plots are not compatible with getGraphicsEvent.

Author(s)

Wolfgang Viechtbauer (wvb@wvbauer.com)

Annotate Plots

Description

Function to add annotations to a plot.

Usage

annotate(col = c("black", "red", "green", "blue"),
         lwd = c(4, 4, 30),
         cex = c(1, 1),
         info = TRUE)

Arguments

Details

This is the main function of the package. After creating a plot, for example with plot(), the command annotate() enters a freehand drawing mode where one can draw on the plot (by pressing the left mouse button and dragging the pointer across the plot). Use the ⁠q⁠ key (or the right mouse button) to quit the annotate() function.

Various keyboard keys can be used to select colors and to change the drawing mode (when info=TRUE, one can also click on the boxes at the top to select colors and drawing modes):

Various keyboard keys can be used to adjust the settings:

Finally, some additional keyboard keys have the following functions:

When info=TRUE (the default), then visual information about the drawing mode and colors are shown at the top left while annotating a plot. This information may overlap with the plot title or other elements. One can use the info argument to specify a numeric value to rescale the visual information to better match the resolution of the plot. Note that the boxes for the drawing modes and colors are clickable.

Resizing plots while or after the annotate function has been run is not recommended (all annotations and visual elements need to be redrawn, which can take some time, especially when a lot of annotations have been added to the plot).

After annotating a plot, it should be possible to save the plot including the annotations with dev.print, for example using something like dev.print(device=png, filename="plot.png", width=<width>, height=<height>). However, by default, the plot will have a transparent background color, which is typically not what is desired. To avoid this issue, use par(bg="white") before creating the plot (i.e., before running something like plot()) to set a white background color.

Value

No return value (called for side effects).

Author(s)

Wolfgang Viechtbauer (wvb@wvbauer.com).

Examples

dat <- mtcars
plot(dat$hp, dat$mpg, pch=21, bg="gray", cex=1.5, main="Horsepower versus Mileage")
annotate()

Create a Blank Plot

Description

Function to create a blank plot.

Usage

blank(annotate = TRUE, bg = "white", ...)

Arguments

Details

The function creates a blank plot. This is useful if one simply wants to make a quick sketch (and not add annotations to an existing plot).

Value

No return value (called for side effects).

Author(s)

Wolfgang Viechtbauer (wvb@wvbauer.com).

Examples

blank()