easylabel: Interactive scatter plot labels

Description

Interactive labelling of scatter plots using shiny/plotly interface.

Usage

easylabel(
  data,
  x,
  y,
  labs = NULL,
  startLabels = NULL,
  cex.text = 0.72,
  col = NULL,
  colScheme = NULL,
  alpha = 1,
  shape = NULL,
  shapeScheme = 21,
  size = 8,
  sizeRange = c(4, 80),
  xlab = x,
  ylab = y,
  xlim = NULL,
  ylim = NULL,
  xticks = NULL,
  yticks = NULL,
  showOutliers = TRUE,
  outlier_shape = 5,
  outline_col = "white",
  outline_lwd = 0.5,
  plotly_filter = NULL,
  width = 800,
  height = 600,
  showgrid = FALSE,
  zeroline = TRUE,
  hline = NULL,
  vline = NULL,
  mgp = c(1.8, 0.5, 0),
  Ltitle = "",
  Rtitle = "",
  LRtitle_side = 1,
  labelDir = "radial",
  labCentre = NULL,
  lineLength = 75,
  text_col = "black",
  line_col = "black",
  rectangles = FALSE,
  rect_col = "white",
  border_col = "black",
  padding = 3,
  border_radius = 5,
  showLegend = TRUE,
  legendxy = c(1.02, 1),
  filename = NULL,
  panel.last = NULL,
  fullGeneNames = FALSE,
  AnnotationDb = NULL,
  custom_annotation = NULL,
  output_shiny = TRUE,
  ...
)

Value

By default no return value. If output_shiny = FALSE or the shiny button 'Export plotly & exit' is pressed, a plotly figure is returned.

Arguments

data: Dataset (data.frame or data.table) to use for plot.
x: Specifies column of x coordinates in data.
y: Specifies column of y coordinates in data.
labs: Specifies the column in data with label names for points. Label names do not have to be unique. If NULL defaults to rownames(data).
startLabels: Vector of initial labels. With a character vector, labels are identified in the column specified by labs. With a numeric vector, points to be labelled are referred to by row number.
cex.text: Font size for labels. Default 0.72 to match plotly font size. See text().
col: Specifies which column in data affects point colour. Must be categorical. If it is not a factor, it will be coerced to a factor.
colScheme: A single colour or a vector of colours for points.
alpha: Alpha value for transparency of points.
shape: Specifies which column in data controls point shapes. If not a factor, will be coerced to a factor.
shapeScheme: A single symbol for points or a vector of symbols. See pch in points().
size: Either a single value for size of points (default 8), or specifies which column in data affects point size for bubble charts.
sizeRange: Range of size of points for bubble charts.
xlab: x axis title. Accepts expressions when exporting base graphics. Set cex.lab to alter the font size of the axis titles (default 1). Set cex.axis to alter the font size of the axis numbering (default 1).
ylab: y axis title. Accepts expressions when exporting base graphics.
xlim: The x limits (x1, x2) of the plot.
ylim: The y limits of the plot.
xticks: List of custom x axis ticks and labels specified as a list of two named vectors at = ... and labels = .... Another method is to use xaxp as a vector of the form c(x1, x2, n) giving the coordinates of the extreme tick marks and the number of intervals between tick-marks.
yticks: List of custom y axis ticks and labels specified as a list of two named vectors at = ... and labels = .... Another method is to use yaxp as a vector of the form c(y1, y2, n) giving the coordinates of the extreme tick marks and the number of intervals between tick-marks.
showOutliers: Logical whether to show outliers on the margins of the plot.
outlier_shape: Symbol for outliers.
outline_col: Colour of symbol outlines. Set to NA for no outlines.
outline_lwd: Line width of symbol outlines.
plotly_filter: Refers to a column of logical values in data used to filter rows to reduce the number of points shown by plotly. We recommend using this for datasets with >100,000 rows. When saving to pdf, the full original dataset is still plotted. This is useful for plots with millions of points such as Manhattan plots where a subset of points to be labelled is already known.
width: Width of the plot in pixels. Saving to pdf scales 100 pixels to 1 inch.
height: Height of the plot in pixels.
showgrid: Either logical whether to show gridlines, or a character value where "x" means showing x axis gridlines and "y" means showing y axis gridlines.
zeroline: Logical whether to show lines at x = 0 and y = 0.
hline: Adds horizontal lines at values of y.
vline: Adds vertical lines at values of x.
mgp: The margin line for the axis title, axis labels and axis line. See par().
Ltitle: A character or expression (see plotmath) value specifying text for left side title. Size of font can be changed using cex.lab.
Rtitle: A character or expression value specifying text for right side title. Size of font can be changed using cex.lab.
LRtitle_side: On which side of the plot for Ltitle and Rtitle (1 = bottom, 3 = top). See mtext().
labelDir: Initial label line directions. Options include 'radial' (default) for radial lines around the centre of the plot, 'origin' for radial lines around the origin, 'horiz' for horizontal and 'vert' for vertical, 'xellipse' and 'yellipse' for near-horizontal and near-vertical lines arranged in an elliptical way around the centre, 'rect' for rectilinear lines (a mix of horizontal and vertical), 'x' for diagonal lines, 'oct' for lines in 8 directions around the centre.
labCentre: Coordinates in x/y units of the central point towards which radial labels converge. Defaults to the centre of the plot.
lineLength: Initial length of label lines in pixels.
text_col: Colour of label text. If set to "match" label text will match the colour of each point.
line_col: Colour of label lines. If set to "match" label line will match the colour of each point.
rectangles: Logical whether to show rectangles around labels (not supported by plotly).
rect_col: Colour for filling rectangles (not supported by plotly). If set to "match" rectangle fill colour will match the colour of each point.
border_col: Colour of rectangle borders (not supported by plotly). Use border_col = NA to omit borders. If set to "match" rectangle border colour will match the colour of each point.
padding: Amount of padding in pixels around label text.
border_radius: Amount of roundedness in pixels to apply to label rectangles (not supported by plotly).
showLegend: Logical whether to show or hide the legend.
legendxy: Vector of coordinates for the position of the legend. Coordinates are 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.
filename: Filename for saving plots to pdf in a browser. Rstudio opens its own pdf file.
panel.last: An expression to be evaluated after plotting has taken place but before the axes, title and box are added. This can be useful for adding extra titles, legends or trend lines. Currently only works when saving plots using base graphics and does not work with plotly. See plot.default
fullGeneNames: Logical whether to expand gene symbols using Bioconductor AnnotationDbi package. With multiple matches, returns first value only. See AnnotationDbi::mapIds().
AnnotationDb: Annotation database to use when expanding gene symbols. Defaults to human gene database AnnotationDb = org.Hs.eg.db.
custom_annotation: List of annotations to be added via plotly::layout().
output_shiny: Logical whether to output a shiny app. If FALSE a plotly figure will be returned.
...: Further graphical parameters passed to plot() when saving via base graphics. The most useful for most users are likely to be cex.lab which alters axis title font size (default 1, see par()), cex.axis which alters axis numbering font size (default 1), and panel.last which allows additional plotting functions to be called after the main plot has been plotted but before the labels and label lines are drawn, which will allow the addition of trend lines, extra titles or legends for example (see plot.default()).

Details

Instructions:

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.
The Table tab shows a table view of the dataset to help with annotation.

To export an SVG from plotly:

Switch to SVG when finalised (only do this at last moment as otherwise editing is very slow).
Press camera button in modebar to save image as SVG.

Examples

Run this code


# Simple example using mtcars dataset
data(mtcars)
# Launch easylabel Shiny app: only run this example in interactive R sessions
if (interactive()) {
easylabel(mtcars, x = 'mpg', y = 'wt', col = 'cyl')
}