Repository files navigation

Package ‘ggpmisc’ (Miscellaneous Extensions to ‘ggplot2’) is a setof extensions to R package ‘ggplot2’ (>= 3.0.0) with emphasis onannotations and plotting related to fitted models. Estimates from modelfit objects can be displayed in ggplots as text, model equations, ANOVAand summary table. Predicted values, residuals, deviations and weightscan be plotted for various model fit functions. Linear models,polynomial regression, quantile regression, major axis regression,non-linear regression and different approaches to robust and resistantregression, as well as user-defined wrapper functions based on them aresupported. In addition, all model fit functions returning objects forwhich accessors are available or supported by package ‘broom’ and itsextensions are also supported but not as automatically. Labelling basedon multiple comparisons supports variousP adjustment methods andcontrast schemes. Annotation of peaks and valleys in time series, andscales for volcano and quadrant plots as used for gene expression dataare also provided. Package ‘ggpmisc’ continues to give access toextensions moved as of version 0.4.0 to package‘ggpp’.

Package ‘ggpmisc’ is consistent with the grammar of graphics, andopens new possibilities retaining the flexibility inherent to thisgrammar. Its aim is not to automate plotting or annotations in a waysuitable for fast data exploration by use of a “fits-all-sizes”predefined design. Package ‘ggpmisc’ together with package‘ggpp’, provide new layer functions, position functions and scales.In fact, these packages follow the tenets of the grammar even morestrictly than ‘ggplot2’ in the distinction between geometries andstatistics. The new statistics in ‘ggpmisc’ focus mainly on modelfitting, including multiple comparisons among groups. The defaultannotations are those most broadly valid and of easiest interpretation.We follow R’s approach of expecting that users know what they need orwant, and will usually want to adjust how results from model fits arepresented both graphically and textually. The approach and mechanics ofplot construction and rendering remain unchanged from those implementedin package‘ggplot2’.

Statistics that help with reporting the results of model fits are:

Notes: (1)weight aesthetic supported; (2) user defined model fitfunctions including wrappers of supported methods are accepted even ifthey modify the modelformula (additional model fitting methods arelikely to work, but have not been tested); (3) unlimited quantilessupported; (4) user defined fit functions that return an object of aclass derived fromrq orrqs are supported even if they override thestatistic’sformula and/orquantiles argument; (5) two and threequantiles supported; (6) user defined fit functions that return anobject of a class derived fromlmodel2 are supported; (7)methodarguments support colon based notation; (8) model fit functions ifmethodresiduals() defined for returned value; (9) model fit functionsif methodfitted() is defined for the returned value.

Statisticsstat_peaks() andstat_valleys() can be used to highlightand/or label global and/or local maxima and minima in a plot.

Scalesscale_x_logFC(),scale_y_logFC(),scale_colour_logFC() andscale_fill_logFC() easy the plotting of log fold change data. Scalesscale_x_Pvalue(),scale_y_Pvalue(),scale_x_FDR() andscale_y_FDR() are suitable for plottingp-values and adjustedp-values or false discovery rate (FDR). Default arguments are suitablefor volcano and quadrant plots as used for transcriptomics, metabolomicsand similar data.

Scalesscale_colour_outcome(),scale_fill_outcome() andscale_shape_outcome() and functionsoutome2factor(),threshold2factor(),xy_outcomes2factor() andxy_thresholds2factor() used together make it easy to map ternarynumeric outputs and logical binary outcomes to color, fill and shapeaesthetics. Default arguments are suitable for volcano, quadrant andother plots as used for genomics, metabolomics and similar data.

Several geoms and other extensions formerly included in package‘ggpmisc’ until version 0.3.9 were migrated to package ‘ggpp’. They arestill available when ‘ggpmisc’ is loaded, but the documentation nowresides in the new package‘ggpp’.

Functions for the manipulation of layers in ggplot objects, togetherwith statistics and geometries useful for debugging extensions topackage ‘ggplot2’, included in package ‘ggpmisc’ until version 0.2.17are now in package‘gginnards’.

library(ggpmisc)library(ggrepel)library(broom)

In the first two examples we plot data such that we map a factor to thex aesthetic and label it with the adjustedP-values for multitlecomparision using “Tukey” contrasts.

ggplot(mpg, aes(factor(cyl),cty))+  geom_boxplot(width=0.33)+  stat_multcomp(label.type="letters")+  expand_limits(y=0)

Using “Dunnet” contrasts and “bars” to annotate individual contrastswith the adjustedP-value, here using Holm’s method.

ggplot(mpg, aes(factor(cyl),cty))+  geom_boxplot(width=0.33)+  stat_multcomp(contrasts="Dunnet",p.adjust.method="holm",size=2.75)+  expand_limits(y=0)

In the third example we add the equation for a linear regression, theadjusted coefficient of determination andP-value to a plot showingthe observations plus the fitted curve, deviations and confidence band.We usestat_poly_eq() together withuse_label() to assemble and mapthe desired annotations.

formula<-y~x+ I(x^2)ggplot(cars, aes(speed,dist))+  geom_point()+  stat_fit_deviations(formula=formula,colour="red")+  stat_poly_line(formula=formula)+  stat_poly_eq(use_label(c("eq","adj.R2","P")),formula=formula)

The same figure as in the third example but this time annotated with theANOVA table for the model fit. We usestat_fit_tb() which can be usedto add ANOVA or summary tables.

formula<-y~x+ I(x^2)ggplot(cars, aes(speed,dist))+  geom_point()+  geom_smooth(method="lm",formula=formula)+  stat_fit_tb(method="lm",method.args=list(formula=formula),tb.type="fit.anova",tb.vars= c(Effect="term","df","M.S."="meansq","italic(F)"="statistic","italic(P)"="p.value"),tb.params= c(x=1,"x^2"=2),label.y="top",label.x="left",size=2.5,parse=TRUE)#> Dropping params/terms (rows) from table!

The same figure as in the third example but this time using quantileregression, median in this example.

formula<-y~x+ I(x^2)ggplot(cars, aes(speed,dist))+  geom_point()+  stat_quant_line(formula=formula,quantiles=0.5)+  stat_quant_eq(formula=formula,quantiles=0.5)

Band highlighting the region between both quartile regressions and aline for the median regression.

formula<-y~x+ I(x^2)ggplot(cars, aes(speed,dist))+  geom_point()+  stat_quant_band(formula=formula)

A quadrant plot with counts and labels, usinggeom_text_repel() frompackage ‘ggrepel’.

ggplot(quadrant_example.df, aes(logFC.x,logFC.y))+  geom_point(alpha=0.3)+  geom_quadrant_lines()+  stat_quadrant_counts()+  stat_dens2d_filter(color="red",keep.fraction=0.02)+  stat_dens2d_labels(aes(label=gene),keep.fraction=0.02,geom="text_repel",size=2,colour="red")+  scale_x_logFC(name="Transcript abundance after A%unit")+  scale_y_logFC(name="Transcript abundance after B%unit",expand= expansion(mult=0.2))#> Warning: ggrepel: 1 unlabeled data points (too many overlaps). Consider#> increasing max.overlaps

A time series using the specialized version ofggplot() that convertsthe time series into a tibble and maps thex andy aestheticsautomatically. We also highlight and label the peaks usingstat_peaks().

ggplot(lynx,as.numeric=FALSE)+ geom_line()+  stat_peaks(colour="red")+  stat_peaks(geom="text",colour="red",angle=66,hjust=-0.1,x.label.fmt="%Y")+  stat_peaks(geom="rug",colour="red",sides="b")+  expand_limits(y=8000)

Installation of the most recent stable version from CRAN (sources, Macand Win binaries):

install.packages("ggpmisc")

Installation of the current unstable version from R-Universe CRAN-likerepository (binaries for Mac, Win, Webassembly, and Linux, as well assources available):

install.packages("ggpmisc",repos= c("https://aphalo.r-universe.dev","https://cloud.r-project.org"))

Installation of the current unstable version from GitHub (from sources):

# install.packages("remotes") # nolint: commented_code_linter.remotes::install_github("aphalo/ggpmisc")

HTML documentation for the package, including help pages and theUserGuide, is available athttps://docs.r4photobiology.info/ggpmisc/.

News about updates are regularly posted athttps://www.r4photobiology.info/.

Chapter 7 in Aphalo (2020) and Chapter 9 in Aphalo (2024) explain basicconcepts of the grammar of graphics as implemented in ‘ggplot2’ as wellas extensions to this grammar including several of those made availableby packages ‘ggpp’ and ‘ggpmisc’. Information related to the book isavailable athttps://www.learnr-book.info/.

Please report bugs and request new features athttps://github.com/aphalo/ggpmisc/issues. Pull requests are welcome athttps://github.com/aphalo/ggpmisc.

If you use this package to produce scientific or commercialpublications, please cite according to:

citation("ggpmisc")#> To cite package 'ggpmisc' in publications use:#>#>   Aphalo P (2025). _ggpmisc: Miscellaneous Extensions to 'ggplot2'_. R#>   package version 0.6.3.9000,#>   <https://docs.r4photobiology.info/ggpmisc/>.#>#> A BibTeX entry for LaTeX users is#>#>   @Manual{,#>     title = {ggpmisc: Miscellaneous Extensions to 'ggplot2'},#>     author = {Pedro J. Aphalo},#>     year = {2025},#>     note = {R package version 0.6.3.9000},#>     url = {https://docs.r4photobiology.info/ggpmisc/},#>   }

Being an extension to package ‘ggplot2’, some of the code in package‘ggpmisc’ has been created by using as a template that from layerfunctions and scales in ‘ggplot2’. The user interface of ‘ggpmisc’ aimsat being as consistent as possible with ‘ggplot2’ and the layeredgrammar of graphics (Wickham 2010). New features added in ‘ggplot2’ areadded when relevant to ‘ggpmisc’, such as support fororientation forflipping of layers. This package does consequently indirectly includesignificant contributions from several of the authors and maintainers of‘ggplot2’, listed at (https://ggplot2.tidyverse.org/).

Aphalo, Pedro J. (2024)Learn R: As a Language. 2ed. The R Series.Boca Raton and London: Chapman and Hall/CRC Press. ISBN: 9781032516998.466 pp. 

Aphalo, Pedro J. (2020)Learn R: As a Language. 1ed. The R Series.Boca Raton and London: Chapman and Hall/CRC Press. ISBN: 9780367182533.350 pp. 

Wickham, Hadley. 2010. “A Layered Grammar of Graphics.” Journal ofComputational and Graphical Statistics 19 (1): 3–28.https://doi.org/10.1198/jcgs.2009.07098.

© 2016-2025 Pedro J. Aphalo (pedro.aphalo@helsinki.fi). Released underthe GPL, version 2 or greater. This software carries no warranty of anykind.