jamma

The goal of jamma is to create MA-plots with several useful and powerful capabilities that are intended to provide a more thorough understanding of the data.

The main function provided is jammaplot(). It is distinct from similar MA-plot functions in that it uses smooth scatter by default, and in fact inspired the creation of a custom smooth scatter function provided by jamba::plotSmoothScatter().

Package Reference

A full online function reference is available via the pkgdown documentation:

Full jamma command reference

Example MA-plot

A reasonable example MA-plot can be created using data from the affydata package, if installed.

library(jamma);
library(jamba);
if (suppressPackageStartupMessages(require(affydata))) {
   data(Dilution);
   edata <- log2(1+Biobase::exprs(Dilution));
   jammaplot(edata);
}

What is a smooth scatter plot, and why is it important for MA-plots?

MA-plots are typically created for gene expression data, historically used for microarray data, which contains tens of thousands of rows. Most MA-plot tools combat the number of points either by displaying single pixel points (pch=“.” in R base plotting), or adding transparency.

A secondary issue is that these plots take a while to render when drawing individual points. This effect is amplified when running on a remote server, since each individual point is transmitted over the network for rendering. Also when saving a figure, certain file types save each point as an object, making the file size surprisingly large. If the file is printed to paper (ha!) the printer can take a long time to prepare the image for printing. And the volume of data is not currently getting smaller with new technologies.

First, we show the same MA-plot using single pixel points:

if (exists("edata")) {
   jammaplot(edata[,2:3], ylim=c(-1.5,1.5), titleCexFactor=0.8,
      smoothScatterFunc=function(x, col="navy", ...){plot(x=x, pch=".",col="#000077",...)},
      maintitle="plot(pch='.')");
}

The overall range of points is clearly shown, but the density of points is not clear from that plot. Adding alpha transparency helps somewhat:

if (exists("edata")) {
   jammaplot(edata[,2:3], ylim=c(-1.5,1.5), titleCexFactor=0.8,
      smoothScatterFunc=function(x, col="navy", ...){plot(x=x, pch=".",col="#00007711",...)},
      maintitle="plot(pch='.', alpha=0.07)");
}

The transparency helps visualize the massive number of points in the middle, but now has made all the fun outlier points almost invisible. The typical next step in R is to use smoothScatter(), shown below using its default color ramp:

if (exists("edata")) {
   jammaplot(edata[,2:3],
      xlim=c(6, 14),
      ylim=c(-1.5,1.5),
      titleCexFactor=0.8,
      smoothScatterFunc=function(colramp,...){
         smoothScatter(...,colramp=jamba::getColorRamp(colramp, n=NULL))},
      colramp="Blues",
      maintitle="smoothScatter()");
}

Again, the visualization is improved, but the default “Blues” color ramp (credit Brewer colors from RColorBrewer) could perhaps be improved.

if (exists("edata")) {
   jammaplot(edata[,2:3],
      xlim=c(6, 14),
      ylim=c(-1.5,1.5),
      titleCexFactor=0.8,
      smoothScatterFunc=function(colramp,...){
         smoothScatter(...,colramp=jamba::getColorRamp(colramp, n=NULL))},
      maintitle="smoothScatter()");
}

Now the figure depicts the full range of data, while also conveying the truly massive number of points in the central region. Only two smaller issues remain.

First, not visible here, the underyling data is plotted using tiny rectangles. For the reasons described above, a large number of rectangles can be problematic when saving as a vector image (PDF, SVG), when printing on paper, or when rendering the figure across a remote network connection. The solution is to use a rasterized image, instead of individual rectangles, which can be compressed and resized.

Second, the pixel size used for the point density is flattened horizontally, because the default density function uses the range of data, and not the plot visible range. When the density function is applied to plot coordinates, there is often some distortion. Visually small effect, but when there are 20 panels onscreen, the inconsistency becomes much more obvious.

The plotSmoothScatter function resolves both the issues described, with some enhancements. It uses a density function based upon plot space, but also adds detail, so smaller features are less blurry.

if (exists("edata")) {
   jammaplot(edata[,2:3],
      ylim=c(-1.5,1.5),
      titleCexFactor=0.8,
      maintitle="plotSmoothScatter()");
}

It looks like a small effect here, but the density around single points is now circular. When rendering a density map of plotted data points, it should represent the true density of points as accurately as possible.

To demonstrate some other color effects, the plotSmoothScatter function also fills the complete plot panel with the correct background color, which is not done by smoothScatter().

if (exists("edata")) {
   par("mfrow"=c(2,2));
   jammaplot(edata[,2:3],
      xlim=c(6, 14),
      ylim=c(-2,2),
      titleCexFactor=0.8,
      colramp="viridis",
      doPar=FALSE,
      smoothScatterFunc=function(colramp,...){
         smoothScatter(...,colramp=jamba::getColorRamp(colramp, n=NULL))},
      maintitle="smoothScatter(colramp='viridis')");
   jammaplot(edata[,2:3], ylim=c(-2,2), titleCexFactor=0.8,
      colramp="viridis", doPar=FALSE,
      maintitle="plotSmoothScatter(colramp='viridis')");
}