Smooth scatter plot, Jam style

Source: R/jamba-plots.r

Produce smooth scatter plot, a helper function called by plotSmoothScatter().

smoothScatterJam(
  x,
  y = NULL,
  nbin = 256,
  bandwidth,
  colramp = colorRampPalette(c("white", "lightblue", "blue", "orange", "orangered2")),
  nrpoints = 100,
  pch = ".",
  cex = 1,
  col = "black",
  transformation = function(x) x^0.25,
  postPlotHook = box,
  xlab = NULL,
  ylab = NULL,
  xlim,
  ylim,
  add = FALSE,
  xaxs = par("xaxs"),
  yaxs = par("yaxs"),
  xaxt = par("xaxt"),
  yaxt = par("yaxt"),
  useRaster = NULL,
  ...
)

Arguments

x

numeric vector, or data matrix with two or more columns.

y

numeric vector, or if data is supplied via x as a matrix, y is NULL.

nbin

integer number of bins to use when converting the kernel density result (which uses bandwidthN above) into a usable image. For example, nbin=123 is the default used by graphics::smoothScatter(), however the plotSmoothScatter() function default is higher (256).

bandwidth

numeric vector used to define the y- and x-axis bandwidths, respectively, passed to KernSmooth::bkde2D(), which calculates the underlying 2-dimensional kernel density. The plotSmoothScatter() function was motivated by never wanting to define this number directly, instead auto-calculation suitable values.

colramp

function that takes one numeric argument and returns that integer number of colors, by default 256.

nrpoints

integer number of outlier datapoints to display, as defined by graphics::smoothScatter(), however the default here is nrpoints=0 to avoid additional clutter in the output, and because the default argument bandwidthN usually indicates all individual points.

pch

point shape used when nrpoints>0.

cex

numeric point size expansion factor used when nrpoints>0.

col

character R color used when nrpoints>0.

transformation

function which converts point density to a number, typically related to square root or cube root transformation.

postPlotHook

is NULL for no post-plot hook, or a function which is called after producing the image plot. By default it is simply used to draw a box around the image, but could be used to layer additional information atop the image plot, for example contours, labels, etc.

xlab

character x-axis label

ylab

character y-axis label

xlim

numeric x-axis range for the plot

ylim

numeric y-axis range for the plot

add

logical whether to add to an existing active R plot, or create a new plot window.

xaxs

character value compatible with par("xaxs"), mainly useful for suppressing the x-axis, in order to produce a custom x-axis range, most useful to restrict the axis range expansion done by R by default.

yaxs

character value compatible with par("yaxs"), mainly useful for suppressing the y-axis, in order to produce a custom y-axis range, most useful to restrict the axis range expansion done by R by default.

xaxt

character value compatible with par("xaxt"), mainly useful for suppressing the x-axis, in order to produce a custom x-axis by other mechanisms, e.g. log-scaled x-axis tick marks.

yaxt

character value compatible with par("yaxt"), mainly useful for suppressing the y-axis, in order to produce a custom y-axis by other mechanisms, e.g. log-scaled y-axis tick marks.

useRaster

NULL or logical indicating whether to invoke graphics::rasterImage() to produce a raster image. If NULL, it determines whether to produce a raster image within the imageDefault() function, which checks the options using getOption("preferRaster", FALSE) to determine among other things, whether the user prefers raster images, and if the dev.capabilities() supports raster.

...

additional arguments are passed to imageDefault() and optionally to plotPlotHook() when supplied.

Details

For general purposes, use plotSmoothScatter() as a replacement for graphics::smoothScatter(), which produces better default settings for pixel size and density bandwidth.

This function is only necessary in order to override the graphics::smoothScatter() function which calls graphics::image.default(). Instead, this function calls imageDefault() which is required in order to utilize custom raster image scaling, particularly important when the x- and y-axis ranges are not similar, e.g. where the x-axis spans 10 units, but the y-axis spans 10,000 units.