ggpmisc follows the grammar of graphics implemented in ggplot2, based on the idea that many different data visualizations can be built by combining the same components: a data set, a coordinate system, and geoms—visual marks that represent data or summaries derived from data. These elements are complemented by stats that compute data summaries to be passed to geoms and scales that describe the mapping of data into graphical elements.
There are multiple variations of each element of the grammar, providing a vocabulary. Thus, the grammar allows us to ‘speak/write’ a graph from composable elements, instead of being limited to a predefined set of charts. ‘ggpmisc’ adds new stats and scales, expanding the vocabulary while remaining consistent with the grammar. ‘ggpmisc’ relies on geoms from packages ‘ggpmisc’ and ‘ggplot2’ for its defaults, while also compatible with geoms from other R packages including ‘ggtext’, ‘marquee’, ‘xdvir’, ‘ggrepel’ and ‘gganimate’.
If you are not already familiar with the grammar of graphics and ggplot2 you should visit the ggplot2 Cheat Sheet first, and afterwards come back to this Cheat Sheet.
Differently to ggplot2, no geometries with the new
stats as their default are provided. The plot layers described here are
always added with a stat, and when necessary, their default
geom argument can be overridden.
Most of the layer functions in ggpmisc aim at making
it easier to add to plots information derived from model fitting, tests
of significance or statistical summaries. All the stats
from ‘ggpmisc’ do computations by data group except for
stat_fit_tb() and stat_multcomp() that do
computations by plot panel.
The statistics that return predicted values for regressions return
x and y where one of the variables is a
sequence of numbers for the explanatory variables and the other contains
the predictions based on them; depending on the orientation
or formula, ymin and ymax, or
xmin and xmax, give the lower and upper
confidence limits for the fitted line or curve.
The statistics returning fitted or residual values return these
values as variables y.fitted or x.fitted,
y.resid or x.resid, weights and
robustness.weights. Variables x and
y contain the observed values. When present,
weights are the prior weights, and
robustness.weights are posterior weights, those actually
used by the model fit function, possibly computed by it.
The statistics that return text labels for annotating plots, return
in x and y the label coordinates, the values
passed as arguments to parameters label.x and
label.y, or values computed based on them. The character
strings are returned as variables with names ending in
.label. These variables can be used in mappings created
with aes() or with use_label(). The difference
is that use_label() accepts short names for the labels,
recognizes them as computed by the stats from package ‘ggpmisc’ and
pastes them into a single character string (e.g.,
use_label("eq", "R2", "n", sep = ", ") is equivalent to
aes(paste(after_stat("eq.label"), after_stat("rr.label"), after_stat("n.label), sep = ", "),
saving some typing. In most cases numeric values for the parameter
estimates are also returned, making possible assembly of labels by user
code.
stat_correlation() computes parametric \(r\) or non-parametric correlation
coefficients, \(\tau\) and \(\rho\), and optionally their confidence
intervals, \(P\), and \(n\), the number of observations, flexibly
adding an annotation to the plot.The statistics for fitted models come in matched pairs, one that adds
a plot layer with one or more curves and confidence band(s), and one
that annotates the plot with the fitted model equation and/or other
parameter estimates. These depend on the type of fitted model and
include \(R^2\), \(F\), \(P\), \(AIC\), \(BIC\), \(n\), and in most cases also the
fitted-model equation. The curve plotting stats fulfil a similar role to
ggplot2::stat_smooth() while the ones for textual
annotations have no equivalent in ‘ggplot2’.
stat_poly_line() and stat_poly_eq()
support a broad set of model fit functions: e.g., linear models
(OLS, resistant and robust), general linear model (gls), linear splines,
cubic splines, additive models (gam), major axis (MA) and standardised
major axis (SMA) regression, etc. The fitted model equation is
automatically generated for polynomials, but can be assembled manually
for other model formulas.
stat_quant_line(), stat_quant_band()
and stat_quant_eq() support quantile regression
based on both polynomials and smoothing splines (using
‘quantreg’).
stat_ma_line() and stat_ma_eq() support
major axis (MA), standardised major axis (SMA) and ranged major axis
(RMA) regression (using ‘lmodel2’).
stat_distrmix_line() and
stat_distrmix_eq() support fitting of univariate
Normal-distribution mixture models or a of a single Normal
distribution.
stat_fit_fitted() and
stat_fit_deviations() can be used to highlight the fitted
values and their distance to the observations in a scatter plot
supporting a wide range of model fit functions.
stat_fit_residuals() can be used to create
consistent plots of residuals for many different model fit functions
supporting a wide range of model fit functions.
stat_fit_augment() works with model fit functions
supported by broom::augment() methods including non-linear
models. Provides an alternative to stat_poly_line() for an
even broader range of model fit functions.
stat_fit_tidy() works with model fit functions
supported by broom::tidy() methods including non-linear
models. Provides numeric values from which equation labels can be
created for an even broader range of model fit functions than those
supported by stat_poly_eq(). broom::tidy() is
similar to R’s summary() for fitted models.
stat_fit_glance() works with model fit functions
supported by broom::glance() methods including non-linear
models. Provides an alternative to stat_poly_eq() for an
even broader range of model fit functions. broom::glance()
is similar to R’s anova() applied to a single fitted model
object.
stat_fit_tb() fits any model supported by a
broom::tidy() method. Adds an ANOVA or Summary table. Which
columns are included and their naming can be set by the user.stat_multcomp() fits a model, computes ANOVA and
subsequently calls functions from package ‘multcomp’ to test the
significance of Tukey, Dunnet or arbitrary sets of pairwise contrasts,
with a choice of the adjustment method for the P-values.
Significance of differences can be indicated with letters, asterisks or
P-values. Sizes of differences are also computed and available
for user-assembled labels.use_label() pastes together the labels
automatically generated by the stats and maps the combined string to the
label aesthetic.stat_peaks() finds and labels peaks (= global or
local maxima).
stat_valleys() finds and labels valleys (= global or
local minima).
These plots are frequently used with gene expression data, and each
of the many genes labelled based on the ternary outcome from a
statistical test. Data are usually, in addition transformed. ‘ggpmisc’
provides several variations on continuous, colour, fill and shape
scales, with defaults set as needed. Scales support log fold-change
(logFC) on multiple logarithm bases both for input and for
output, false discovery ratio (FDR), P-value
(Pvalue) and binary or ternary test outcomes
(outcome).
Discrete manual scales: scale_colour_outcome(),
scale_fill_outcome(),
scale_shape_outcome().
Continuous scales: scale_x_logFC(),
scale_y_logFC(), scale_colour_logFC(),
scale_fill_logFC().
Continuous scales: scale_x_Pvalue(),
scale_y_Pvalue(), scale_x_FDR(),
scale_y_FDR().
Most of the functions used to generate formatted labels in layers and scales are also exported.
Learn more at docs.r4photobiology.info/ggpmisc/.