Make a scatter plot — PlotScatter • grandR

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

Value

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

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.