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,
remove.outlier = 1.5,
lim = NULL,
xlim = lim,
ylim = lim,
size = 0.3,
cross = NULL,
diag = NULL,
genes = NULL,
highlight = NULL,
label = NULL,
label.repel = 1,
facet = NULL,
color = NULL,
colorpalette = 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

- 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)

- 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

- 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

- 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.