Easily add direct labels to plots using the directlabels package

This package is an attempt to make direct labeling a reality in everyday statistical practice by making available a body of useful functions that make direct labeling of common plots easy to do with high-level plotting systems such as lattice and ggplot2. The main function that the package provides is direct.label(p), which takes a lattice or ggplot2 plot p and adds direct labels: install.packages("directlabels") library(lattice) library(directlabels) direct.label(xyplot(jitter(Sepal.Length)~jitter(Petal.Length),iris,groups=Species)) directlabels website navigation: Positioning Method examples database When are direct labels better than legends? Why not just add direct labels by hand? Several advanced examples Smart label Positioning Methods that avoid label collisions New in directlabels 2.x Direct label positions are re-calculated when the plot window is resized. ggplot2 support for smart Positioning Methods that avoid label collisions. ggplot2 support for fontface, fontfamily, etc. text parameters. See example(dlcompare). ggplot2 support for direct labeling aesthetics other than colour. See example(geom_dl).

Positioning Methods specify the direct label positions

Direct labeling a plot can be decomposed into 2 steps: calculating label positions, then drawing the labels. The directlabels package introduces the concept of the Positioning Method, which is a list of instructions that specifies how to calculate the label positions based on the data points to plot. For example, with the scatterplot above, the default Positioning Method is smart.grid, which places each label close to the center of the corresponding point cloud.

If default label positions are not satisfactory, you can always specify your own Positioning Method, using the method= argument to direct.label. For example, we can label longitudinal data either on the left or right of the lines:

install.packages("ggplot2")
library(ggplot2)
data(BodyWeight,package="nlme")
p <- qplot(Time,weight,data=BodyWeight,colour=Rat,geom="line",facets=.~Diet)
direct.label(p,"first.qp")
direct.label(p,"last.qp")

first.qp and last.qp are the names of Positioning Methods which place the labels respectively near the first or last points, ensuring that the labels do not overlap and so are readable. To find out which built-in Positioning Methods are appropriate for your plot, check out the Positioning Methods example database.

However, the power of the directlabels system is the fact that you can write your own Positioning Methods, and they can be reused for different plots. So once you write a Positioning Method that works, adding direct labels in everyday plots is as simple as calling direct.label, no matter if you are using lattice or ggplot2.

Talks, links, etc.

Adding direct labels to plots, Best Student Poster at useR 2011, attempts to motivate the package and explain how it works. Notably, the "Optimal Labels" section is basically the only documentation of how to implement the qp.labels Positioning Method. The details of the "Modular package design" section have changed in version 2.0. Rather than calling label.positions the first time the plot is printed, we now draw a dlgrob whose drawDetails method calculates label positions every time the plot window is resized/redrawn.

semin-r, 15 oct 2009. "Visualizing multivariate data using lattice and direct labels" with R code examples. Note that the latticedl package used in these slides is obsolete, so please use the directlabels package instead.

Review of directlabels on the learnr blog.

The labcurve function in the Hmisc package provides some similar functionality.

Some notes on extending ggplot2 using custom grid grobs.

More examples of directlabels on the R Graphical Manual.

Return to the project summary page.