easylabel {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,
  ...
)

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.

Value

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

See Also

easyVolcano(), easyMAplot()

Examples

# 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')
}