easylabel
Myles Lewis, Katriona Goldmann
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)
3.7 Size
The size of all markers can be adjusted by setting size
to a single number e.g. size = 6 (default 8). Size can be
assigned to a column of continuous data within data to
produce a bubble chart. The size of points is automatically scaled to
fit within a range of point sizes, determined by
scaleRange.
library(gapminder)
easylabel(gapminder[gapminder$year == 2007, ], x = 'gdpPercap', y = 'lifeExp',
col = 'continent', labs = 'country',
size = 'pop',
alpha = 0.6,
zeroline = FALSE)
3.8 Choosing label names
By default, easylabel() takes the rownames of the main
dataframe as the label names. Any column can be selected for label names
by setting labs to the name of a column within
data, as for example in the Gapminder dataset plots
above.
3.9 Controlling axes
3.9.1 Axis titles
Axis titles can be set using xlab and ylab.
These accept R expressions to allow maths symbols. This is primarily
designed to work when exporting plots to PDF via base graphics, since
plotly does not natively understand expressions.
easylabel(xymatrix, x = 'x', y = 'y', col = 'col',
colScheme = c('darkgrey', 'green3', 'gold3', 'blue'),
xlab = expression("log"[2] ~ " fold change post-Rituximab"),
ylab = expression("log"[2] ~ " fold change post-Tocilizumab"),
showgrid = TRUE)
3.9.2 Axis limits and outliers
xlim and ylim allow control over the range
of each axis. Outlying points are shown as diamonds. Outliers can be
toggled off using showOutliers = FALSE. Outlier symbol,
colour and line width can be set using outlier_shape,
outlier_col and outlier_lwd respectively.
3.9.3 Axis tick marks
Axis tick marks can be controlled by setting xaxp or
yaxp to a vector of form c(x1, x2, n) where
x1 and x2 are the limits of the tick marks and
n is the number of intervals between tick marks.
For full customisation of axis tick coordinates and labels use
xticks or yticks, which are specified as a
list of two named vectors at = ... and
labels = ....
# example axis ticks
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,
xaxp = c(0, 50000, 10),
yaxp = c(40, 85, 9),
showgrid = TRUE)3.10 Gridlines
Gridlines can be shown by setting showgrid = TRUE. If
showgrid is set to "x" or "y"
then gridlines are shown only for that axis. Density of gridlines can be
controlled by setting xaxp or yaxp (see Axis tick marks).
Black lines through the origin can be controlled by setting
zeroline to TRUE or FALSE.
Dashed grey horizontal lines can be added at specific levels by
setting hline with a vector of values. Similarly dashed
grey vertical lines can be added by setting vline with a
vector of values.
3.11 Legends
Setting showLegend to TRUE or
FALSE can be used to show or hide the legend.
Legends can be positioned by setting legendxy. This
gives a vector of coordinates for the position of the legend in plotly
paper reference with c(0, 0) being the bottom left corner
and c(1, 1) being the top right corner of the plot
window.
Plotly has unusual behaviour in that the x coordinate always aligns
the left side of the legend. However, the y coordinate aligns the top,
middle or bottom of the legend dependent on whether it is in the top,
middle or bottom 1/3 of the plot window. So c(1, 0)
positions the legend in the bottom right corner outside the right margin
of the plot, while c(1, 0.5) centre aligns the legend
around the centre of y axis.
3.12 Further control of plotting
Further control of plotting can be achieved by passing other
arguments to plot() via R’s ... argument. For example, a
box around the plot can be added using bty = 'o' (see
par()).
3.13 panel.last
Base graphics’ panel.last argument is a flexible way to
add plotting commands. This provides a way to add trend lines, loess
lines or any additional features such as extra legends to the plot after
the points are plotted, but before labels are drawn. Note that
panel.last only works when saving to PDF, and is not
available in plotly.
# example adding a trend line using panel.last
fit <- lm(xymatrix$y ~ xymatrix$x)
easylabel(xymatrix, x = 'x', y = 'y', col = 'col',
colScheme = c('darkgrey', 'green3', 'gold3', 'blue'),
xlab = expression("log"[2] ~ " fold change post-Rituximab"),
ylab = expression("log"[2] ~ " fold change post-Tocilizumab"),
showgrid = TRUE, fullGeneNames = TRUE,
panel.last = {
abline(fit, col='red')
})3.14 plotly_filter
This argument is used to reduce the number of scatter points
displayed by plotly, to prevent plotly becoming sluggish or unusable,
which happens above about 200,000 points. To plot large datasets such as
genomic data, we recommend adding a logical column to your dataset which
filters out points of interest for inspecting and labelling via plotly.
plotly_filter specifies the name of this column. Saving to
PDF retains the full dataset and all points will be plotted. This
argument is used by the easyManhattan() function (see Manhattan plot).
4 Volcano plots
Use the easyVolcano() function to quickly plot a volcano
plot from DESeq2 or EdgeR objects. The useQ argument will
switch to using q values for FDR.
# Example DESeq2 object
head(volc1)
## baseMean log2FoldChange lfcSE stat pvalue
## 5_8S_rRNA 0.01625099 0.02726923 2.9811510 0.009147217 0.99270168
## 5S_rRNA 3.66321881 0.05989097 0.4115732 0.145517159 0.88430257
## 7SK 12.96667458 -0.46156215 1.3668722 -0.337677614 0.73560615
## A1BG 290.75694559 0.23486554 0.3514587 0.668259368 0.50396804
## A1BG-AS1 170.77906789 0.11800652 0.2001594 0.589562618 0.55548392
## A1CF 4.56855647 -1.23495475 0.4855212 -2.543565265 0.01097276
## padj
## 5_8S_rRNA NA
## 5S_rRNA 0.9823854
## 7SK 0.9528927
## A1BG 0.8956205
## A1BG-AS1 0.9117136
## A1CF 0.4531638
# Example limma object
head(volc2)
## logFC AveExpr t P.Value adj.P.Val B
## A1BG 0.7697662 6.389039 4.692064 0.0011239293 0.008610736 -1.16895727
## A1BG-AS1 0.5298897 3.610850 4.688657 0.0011293516 0.008638889 -0.85241114
## AAAS -0.4162720 5.349529 -5.578986 0.0003398373 0.004148831 0.17585449
## AACS -0.2049703 3.690271 -1.465073 0.1768461859 0.299064278 -5.88763988
## AAGAB 0.2970478 5.538436 5.446618 0.0004033869 0.004553688 -0.02478892
## AAK1 0.1969886 1.861988 1.286456 0.2302992497 0.362402197 -5.74356735# Typical DESeq2 workflow
volc1 <- results(dds)
easyVolcano(volc1, useQ = TRUE)If you want to specify your own columns within the dataset set
x to the column containing log fold change, y
to the column containing raw p values and padj to the
column containing adjusted p values. labs can be used to
specify the column containing label names, otherwise this defaults to
rownames(data).
# Manually specify columns
easyVolcano(volc1, x = 'log2FoldChange', y = 'pvalue', padj = 'padj')
# To use nominal unadjusted p value for significant genes
easyVolcano(volc1, x = 'log2FoldChange', y = 'pvalue')Note that if you specify y for a column of p values but
leave padj blank, the function assumes you are using
nominal unadjusted p values for the cutoff for significance.
4.1 MA plots
Use the easyMAplot() function to quickly plot an MA plot
from DESeq2 or EdgeR objects.
easyMAplot(volc2, useQ = TRUE)
4.2 Expanding full gene names
The fullGeneNames argument will use Bioconductor package
AnnotationDbi and the org.Hs.eg.db human gene
database to expand gene symbols in the Table tab. Both will need to be
installed from Bioconductor.
BiocManager::install("AnnotationDbi")
BiocManager::install("org.Hs.eg.db")
easyVolcano(volc1, useQ = TRUE, fullGeneNames = TRUE)
Full gene names are also shown when hovering over points in the
scatter plot, which can make it easier to label points of interest. For
mouse genes, install org.Mm.eg.db and set
AnnotationDb = org.Mm.eg.db (note the lack of quotes).
BiocManager::install("org.Mm.eg.db")
library(org.Mm.eg.db)
easyVolcano(volc1,
fullGeneNames = TRUE,
AnnotationDb = org.Mm.eg.db)4.3 Colour schemes
For volcano plots a simple colour scheme with downregulated genes in
blue and upregulated genes in red can be rendered by setting
fccut = 0.
easyVolcano(volc2,
useQ = TRUE,
fccut = 0,
main = "Volcano title")
4.4 Titles
A title can be added using main = "Title". The font size
of the title can be modified using cex.main = 2 (default
1.2) if saving to PDF.
4.5 Adding left/right subtitles
You can add left and right sided titles using Ltitle and
Rtitle to explain the direction of effect for
up/downregulation. The use of expression in the example
below shows how to add left/right arrow symbols to the titles. The
symbols only appear in the saved PDF - they are not compatible with
plotly.
LRtitle_side = 1 puts these titles on the bottom while
LRtitle_side = 3 puts them on the top.
cex.lab controls font size for these titles as well as
axis titles. cex.axis controls font size for axis
numbering.
easyVolcano(volc1,
useQ = TRUE, fullGeneNames = TRUE,
Ltitle = expression(symbol("\254") ~ "Non-responder"),
Rtitle = expression("Responder" ~ symbol("\256")),
LRtitle_side = 1,
cex.lab = 0.9, cex.axis = 0.8,
fccut = c(1, 2), fdrcutoff = 0.2,
ylim = c(0, 6), xlim = c(-5, 5),
colScheme = c('darkgrey', 'blue', 'orange', 'red'))
4.6 Setting P value cut-off
The FDR cutoff is set using fdrcutoff (volcano plots
allow a single value, while MA plots allow multiple values). In order to
force significant genes to be shown based on unadjusted P values, this
can be achieved by a workaround setting both y and
padj manually to the unadjusted p value column. Note this
does mean the legend incorrectly states ‘FDR <’ etc.
easyVolcano(volc1, y = 'pvalue', padj = 'pvalue', fdrcutoff = 0.01)4.7 Axis limits and outliers
xlim and ylim allow control over the range
of each axis. Outlying points are shown as diamonds (see example above).
Outliers can be toggled off using showOutliers = FALSE.
Outlier symbol, colour and line width can be set using
outlier_shape, outlier_col and
outlier_lwd respectively.
4.8 Complex colour schemes
The colour scheme system has been expanded to allow multiple fold change cut-offs. In the example above the colours are symmetrical.
In the next 2 plots, the colours range from blue for downregulated
genes, through to red for upregulated genes. Vertical lines can be added
using vline.
colScheme <- c('darkgrey', 'blue', 'lightblue', 'orange', 'red')
easyVolcano(volc1, fccut = 1, fdrcutoff = 0.2,
ylim = c(0, 6), xlim = c(-5, 5),
colScheme = colScheme,
vline = c(-1, 1))
The next example has 6 colours and also shows how to remove the white
outlines around points using outline_col = NA and use
transparency instead via alpha.
library(RColorBrewer)
colScheme <- c('darkgrey', brewer.pal(9, 'RdYlBu')[c(9:7, 3:1)])
easyVolcano(volc1, fccut = c(1, 2), fdrcutoff = 0.2,
ylim = c(0, 6), xlim = c(-5, 5),
colScheme = colScheme,
alpha = 0.75, outline_col = NA)
Similarly 6 colours can be applied to MA plots using 3 levels of cut-off for FDR (note the colour scheme is in a slightly different order).
colScheme <- c('darkgrey', brewer.pal(9, 'RdYlBu')[c(7:9, 3:1)])
easyMAplot(volc2, fdrcutoff = c(0.05, 0.01, 0.001), size = 6, useQ = TRUE,
alpha = 0.75, outline_col = NA,
colScheme = colScheme)
5 Controlling labels
Label lines can be altered using the argument labelDir
or by selecting the Label direction pulldown menu in the shiny app. A
couple of examples are shown below:
easyVolcano(volc1, labelDir = "horiz")
easyMAplot(volc1, labelDir = "vert")
5.1 Label line and text
Label line colour can be set using line_col. Label text
colour can be set using text_col. Each of these can be set
to match the colour of each point by setting each to
"match". Default label line length can be altered by
changing lineLength (default 75 in pixels).
cex.text can be changed to alter the font size of labels
(default 0.72).
5.2 Adding label boxes
Rectangles can be drawn around the label text, using
rectangles = TRUE, and will appear when saving to PDF (they
are not supported in plotly). Rectangle fill colour can be set using
rect_col and rectangle border colour can be set using
border_col. Use border_col = NA to turn off
rectangle borders. The amount of padding in pixels around label text can
be specified by setting padding. The amount of roundedness
in pixels of rectangle corners is specified by
border_radius.
# Simple outlines
easyVolcano(volc2, useQ = TRUE, fccut = 0,
rectangles = TRUE)
# Red outlined labels, rounded ends
easyVolcano(volc2, useQ = TRUE, fullGeneNames = TRUE,
rectangles = TRUE,
padding = 5,
border_radius = 10,
line_col = 'red',
border_col = 'red',
text_col = 'red')
# Transparent grey rectangles, rounded ends
easyMAplot(volc2, fdrcut = c(0.05, 0.01, 0.001), size = 6, useQ = TRUE,
alpha = 0.75, outline_col = NA,
fullGeneNames = TRUE,
colScheme = c('darkgrey', brewer.pal(9, 'RdYlBu')[c(7:9, 3:1)]),
rectangles = TRUE,
border_col = NA,
padding = 5,
rect_col = adjustcolor('grey', alpha.f = 0.6),
border_radius = 20)
# White text on black background, no rounding
easyVolcano(volc2, useQ = TRUE, fullGeneNames = TRUE,
fccut = 0,
rectangles = TRUE,
padding = 4,
border_radius = 0,
rect_col = 'black',
text_col = 'white',
border_col = NA)
5.3 Matching label & point colours
While label text and label lines can be adjusted by setting
text_col and line_col to individual colours,
label text and label lines can also be set to mirror the colour of each
point by setting text_col = "match" and
line_col = "match" respectively. Label box fill colour or
rectangle outline colour can also be set to match each point’s colour by
setting rect_col = "match" or
border_col = "match" (label boxes are not supported in
plotly).
# Label text and label lines match point colours
easylabel(gapminder[gapminder$year == 2007, ], x = 'gdpPercap', y = 'lifeExp',
col = 'continent', labs = 'country',
size = 'pop',
alpha = 0.6,
line_col = "match", text_col = "match",
zeroline = FALSE, showgrid = "y")
# Rectangle fill colour and label line match point colours, rounded rectangles
easylabel(gapminder[gapminder$year == 2007, ], x = 'gdpPercap', y = 'lifeExp',
col = 'continent', labs = 'country',
size = 'pop',
alpha = 0.6,
line_col = "match", text_col = "white",
rectangles = TRUE, border_col = NA,
rect_col = "match", border_radius = 20, padding = 5,
zeroline = FALSE, showgrid = "y")
6 Manhattan plot
Manhattan plots can be labelled using the function
easyManhattan(). Plotly struggles with more than about
100,000 points, so we use a filtering system to reduce the number of
points shown in the plotly interactive plot, while the full plot with
all points is produced when saving to PDF. An example is shown
below:
# Manhattan plot using SLE GWAS data from Bentham et al 2015
# FTP download full summary statistics from
# https://www.ebi.ac.uk/gwas/studies/GCST003156
library(data.table)
SLE_gwas <- fread('../bentham_2015_26502338_sle_efo0002690_1_gwas.sumstats.tsv')
# Simple Manhattan plot
easyManhattan(SLE_gwas)
# 4 colours for chromosomes
easyManhattan(SLE_gwas, chromCols = RColorBrewer::brewer.pal(4, 'Paired'))
By default Manhattan plots display only the top 100,000 points by p
value in the plotly window and plot the top 1 million SNPs when saving
to PDF. These defaults can be altered by setting npoints
and nplotly. Setting npoints to
NA will plot all points when saving to PDF.
# Examples
# 12 colours for chromosomes, no separate colour for significant points
easyManhattan(SLE_gwas, chromCols = RColorBrewer::brewer.pal(12, 'Paired'),
sigCol = NA)
# Label peaks automatically, add horizontal gridlines
easyManhattan(SLE_gwas, npeaks = 20, showgrid = "y")
# Vertical version
easyManhattan(SLE_gwas, transpose = TRUE, height = 1000, width = 600)
# Chr1 only
easyManhattan(SLE_gwas[SLE_gwas$chrom == 1, ])
# Add symbols for the significant SNPs
easyManhattan(SLE_gwas, chromCols = RColorBrewer::brewer.pal(4, 'Paired'),
size = 8,
shape = 'col',
shapeScheme = c(rep(20, 4), 18))6.1 Locus plots
To look in a specific genomic region
# Create a locus plot over one chromosomal region
library(plotly)
p1 = easyManhattan(SLE_gwas[SLE_gwas$chrom == 6 &
SLE_gwas$pos >= 28e6 &
SLE_gwas$pos <= 34e6, ],
output_shiny = FALSE, labs = "rsid",
startLabels=c("rs115466242", "rs2853999"),
npeaks = 3)
# To annotate genes in that region
source("https://raw.githubusercontent.com/KatrionaGoldmann/BioOutputs/master/R/bio_gene_locations.R")
library(ggbio)
library(gginnards)
library(ggrepel)
if (! "EnsDb.Hsapiens.v75" %in% rownames(installed.packages()))
BiocManager::install("EnsDb.Hsapiens.v75")
p2 = bio_gene_locations(6, c(28e6, 34e6),
subset_genes = c('HLA-F', 'HLA-G', 'HLA-A', 'HLA-E',
'HLA-C', 'HLA-B', 'HLA-DRA',
'HLA-DRB5', 'HLA-DRB1', 'HLA-DQA1',
'HLA-DQB1', 'HLA-DQA2', 'HLA-DQB2',
'HLA-DOB', 'HLA-DMB', 'HLA-DMA',
'HLA-DOA', 'HLA-DPA1', 'HLA-DPB1'))
plotly::subplot(p1, p2$plotly_location %>% layout(yaxis=list(range=c(0.25, 2))),
shareY = T, titleX = T, margin=0.05,
nrows=2, heights=c(0.7, 0.3))
7 Known issues
- Plotly’s
scatterglfunction, which uses webGL, seems to have a limit of around 400,000 scatter points per plot. Above this level, the shiny/plotly app becomes sluggish or freezes and becomes unusable. We recommend limiting plots to around 100,000 points using theplotly_filterargument. See plotly_filter.