1 Introduction

A common problem in R is labelling scatter plots with large numbers of points and/or labels. We provide a utility for easy labelling of scatter plots and quick plotting of volcano plots and MA plots for gene expression analyses. Using an interactive shiny and plotly interface, users can hover over points to see where specific points are located and click on points to easily label them. Labels can be toggled on/off simply by clicking. An input box and batch input window provides an easy way to label points by name. Labels can be dragged around the plot to place them optimally. Notably we provide an easy way to export directly to PDF for publication.

2 Installation

Install from CRAN

install.packages("easylabel")
library(easylabel)

Install from Github

devtools::install_github("myles-lewis/easylabel")
library(easylabel)

If you wish to use the optional useQ argument with easyVolcano() and easyMAplot(), you will need to install additional package qvalue from Bioconductor:

if (!requireNamespace("BiocManager", quietly = TRUE))
  install.packages("BiocManager")
BiocManager::install("qvalue")

If you wish to use the optional fullGeneNames argument, you will need to install packages AnnotationDbi and org.Hs.eg.db from Bioconductor:

BiocManager::install("AnnotationDbi")
BiocManager::install("org.Hs.eg.db")

3 Scatter plots

Use easylabel() to open a shiny app and plot and label scatter plots. A table of the main data is supplied in the Table tab for easy viewing of data.

data(mtcars)
easylabel(mtcars, x = 'mpg', y = 'wt',
          colScheme = 'royalblue')

3.1 Export plot to PDF

  • Hover over and click on/off genes which you want to label.
  • When you have selected all your chosen genes, then drag gene names to move label positions.
  • Click the save button to export a PDF in base graphics.
  • File type can be changed to export SVG, PNG, JPEG or TIFF.

If dealing with a plot with very large numbers of points (>20k), then it may make sense to rasterize the points by clicking the “Raster points” checkbox and setting a resolution (dpi). This can dramatically reduce file size for plots with millions of points, e.g. Manhattan plots. It also makes these pdf or svg images load much faster. Note that if you use pdf or svg when exporting, the axis lines, ticks, axis labels, label lines, label text etc are all preserved as vectors, only the points are rasterised, which is arguably the best of both worlds, and typically preferred by publications.

3.2 Save state

This button allows users to save the state of the plot including which points are labelled and the position of the labels. An rds file is saved in the working directory. This can be reloaded during another R session using the function loadlabel(). The original data can optionally be embedded in the saved rds file by ticking the “Embed data” checkbox. If the data is not embedded the function will need access to the original data object, so this must be loaded into the global environment before calling loadlabel().

loadlabel() can refer directly to the rds file. Alternatively the rds file can be loaded into the global environment as an object and loadlabel() can be applied to this object.

3.3 Export SVG from plotly

  • Switch to SVG when finalised (only do this at last moment as otherwise editing can very slow, particularly with large numbers of points).
  • Press the camera button in the plotly modebar to save image as SVG.

3.4 Export as plotly object

The output_shiny option enables users to switch between invoking the shiny app or directly outputting a plotly object. For example, to extract a plotly figure with draggable annotations:

data(mtcars)

p1 <- easylabel(mtcars, x = 'mpg', y = 'wt', col = 'cyl', 
                startLabels = rownames(mtcars)[mtcars$gear == 5], 
                output_shiny = FALSE) %>% 
  layout(yaxis = list(zeroline = FALSE))

p2 <- easylabel(mtcars, x = 'mpg', y = 'drat', col = 'vs', 
                colScheme = c("dodgerblue", "orange"), 
                startLabels = rownames(mtcars)[mtcars$gear == 5], 
                output_shiny = FALSE) %>% 
  layout(xaxis = list(zeroline = FALSE))

plotly::subplot(p1, p2, nrows = 2, shareY = TRUE, titleX = TRUE, margin = 0.05)

Note that while the labels and lines can still be dragged and moved in the exported plotly object, clicking on points to add them, exporting to PDF and borders around label text, which are all shiny/ PDF output features, are not available from a pure plotly object.

Plotly objects can also be exported as a return value by pressing the ‘Export plotly & exit’ button in the shiny app. In this case the object retains the labelled points and their edited positions.

3.5 Colour

Similar to ggplot2 and plotly, colour can either be set as a single colour, using colScheme = 'blue' or can be set to change with the level of a factor variable within data by setting col. Transparency can be altered by setting alpha. Currently colour gradients are not supported.

easylabel(mtcars, x = 'mpg', y = 'wt',
          col = 'cyl')

3.6 Shape

Marker shapes can either be set as a single shape using shapeScheme = 21, based on the base graphics pch symbol scheme (see points()), or shapes can be set to change with the level of a factor variable within data by setting shape. Shapes and colours can be combined.

# gapminder data set
if(!require(gapminder)) {install.packages("gapminder")}
library(gapminder)
easylabel(gapminder[gapminder$year == 2007, ], x = 'gdpPercap', y = 'lifeExp',
          col = 'continent', shape = 'continent',
          size = 10,
          labs = 'country', 
          zeroline = FALSE)