PlotScatter {grandR}

Make a scatter plot

Description

Convenience method to compare two variables (slot data or analyses results).

Usage

PlotScatter(
  data,
  x = NULL,
  y = NULL,
  analysis = NULL,
  xcol = NULL,
  ycol = NULL,
  xlab = NULL,
  ylab = NULL,
  log = FALSE,
  log.x = log,
  log.y = log,
  axis = TRUE,
  axis.x = axis,
  axis.y = axis,
  remove.outlier = 1.5,
  show.outlier = TRUE,
  lim = NULL,
  xlim = lim,
  ylim = lim,
  size = 0.3,
  cross = NULL,
  diag = NULL,
  filter = NULL,
  genes = NULL,
  highlight = NULL,
  label = NULL,
  label.repel = 1,
  facet = NULL,
  color = NULL,
  colorpalette = NULL,
  color.label = NULL,
  density.margin = "n",
  density.n = 100,
  rasterize = NULL,
  correlation = NULL,
  correlation.x = -Inf,
  correlation.y = Inf,
  correlation.hjust = 0.5,
  correlation.vjust = 0.5,
  layers.below = NULL
)

Arguments

data

the grandR object (can also be a plain data frame)

x

an expression to compute the x value or a character corresponding to a sample (or cell) name or a fully qualified analysis result name (see details)

y

an expression to compute the y value or a character corresponding to a sample (or cell) name or a fully qualified analysis result name (see details)

analysis

the name of an analysis table (can be NULL; see details)

xcol

a character corresponding to a sample (or cell) name or a fully qualified analysis result name (see details)

ycol

a character corresponding to a sample (or cell) name or a fully qualified analysis result name (see details)

xlab

the label for x (can be NULL, then the x parameter is used)

ylab

the label for y (can be NULL, then the y parameter is used)

log

if TRUE, use log scales for x and y axis

log.x

if TRUE, use log scale for the x axis

log.y

if TRUE, use log scale for the y axis

axis

if FALSE, don't show x and y axes

axis.x

if FALSE, don't show the x axis

axis.y

if FALSE, don't show the y axis

remove.outlier

configure how outliers are selected (is the coef parameter to boxplot.stats); can be FALSE, in which case no points are considered outliers (see details)

show.outlier

if TRUE, show outlier as gray points at the border of the plotting plane

lim

define the both x and y axis limits (vector of length 2 defining the lower and upper bound, respectively)

xlim

define the x axis limits (vector of length 2 defining the lower and upper bound, respectively)

ylim

define the y axis limits (vector of length 2 defining the lower and upper bound, respectively)

size

the point size to use

cross

add horizontal and vertical lines through the origin?

diag

if TRUE, add main diagonal; if numeric vector, add these diagonals

filter

restrict to these rows; is evaluated for the data frame, and should result in a logical vector

genes

restrict to these genes; can be either numeric indices, gene names, gene symbols or a logical vector

highlight

highlight these genes; can be either numeric indices, gene names, gene symbols or a logical vector (see details)

label

label these genes; can be either numeric indices, gene names, gene symbols or a logical vector (see details)

label.repel

force to repel labels from points and each other (increase if labels overlap)

facet

an expression (evaluated in the same environment as x and y); for each unique value a panel (facet) is created; can be NULL

color

either NULL (use point density colors), or a name of the GeneInfo table (use scale_color_xxx to define colors), or a color for all points

colorpalette

either NULL (use default colors), or a palette name from color brewer or viridis

color.label

the label for the color legend

density.margin

for density colors, one of 'n','x' or 'y'; should the density be computed along both axes ('n'), or along 'x' or 'y' axis only

density.n

how many bins to use for density calculation (see kde2d)

rasterize

use ggrastr to rasterize points? (can be NULL, see details)

correlation

a function to format correlation statistics to be annotated (see details)

correlation.x

x coordinate to put the correlation annotation in the plot (see details)

correlation.y

y coordinate to put the correlation annotation in the plot (see details)

correlation.hjust

x adjustment to put the correlation annotation in the plot (see details)

correlation.vjust

y adjustment to put the correlation annotation in the plot (see details)

layers.below

list of ggplot geoms to add before adding the layer containing the points

Details

Both the x and y parameter are either expressions or names. Names are either sample (or cell, in case of single cell experiments) names or fully qualified analysis results (analysis name followed by a dot and the analysis result table column). If the analysis parameter is given, the analysis name must be omitted from x and y. These names can be used within expressions using non-standard evaluation. Defining by names only works with character literals like "kinetics.Synthesis", but if you give an expression (e.g. a variable name that contains a character), the situation is more complicated, since PlotScatter will try to evaluate this for defining the values, not the name of the column. If the expression evaluates into a single character string that is equal to a name (see above!), PlotScatter knows what to do. For more complicated situations that cannot be resolved by this, you can use the xcol and ycol parameters instead of the x and y parameters!

By default the limits of x and y axis are chosen after removing outliers (using the same algorithm used for boxplot). Thus, larger numbers filter less stringently. remove.outlier can also be set to FALSE (no outlier filtering). If xlim or ylim are set, this overrides outlier filtering. Points outside of the limits (i.e. outliers or points outside of xlim or ylim) are set to infinity (such that they are shown at the border of the plot in gray)

By default, all genes are shown. This can be restricted using the genes parameter (see ToIndex). It is also possible to highlight a subset of the genes using highlight. This parameter either describes a subset of the genes (either numeric indices, gene names, gene symbols or a logical vector), in which case these genes are plotted in red and with larger points size, or it can be a list of such vectors. The names of this list must be valid colors. Genes can also be labeled (make sure that this is really only a small subset of the genes).

When rendering to vector based devices (such as svg or pds), a genome-wide scatterplot often is painfully big (and rendering therefore slow). The rasterize parameter can be used to automatically rasterize the points only (via the ggrastr package). If this parameter is NULL, ggrastr is used if more than 1000 points are plotted!

Often scatter plots show that x and y coordinates are correlated. Correlations can be annotated using the FormatCorrelation function. Most often you will use PlotScatter(data,x,y,correlation=FormatCorrelation()). To use a different correlation measure, other formats for correlation coefficient and P values or omit one of these statistics, parametrize FormatCorrelation. Use correlation.x and correlation.y to place the annotation in the plot, and correlation.hjust/correlation.vjust to align the annotation at the given x,y coordinates. Infinite values for correlation.x/correlation.y will put the annotation at the border of the plot.

Value

a ggplot object with the data frame used as the df attribute