Add parameter for easier bin specification in hexbinplot

[stefaneng]

create.hexbinplot passes most of its parameters into the function hexbin::panel.hexbinplot

A common requested task with a hexbinplot is to bins based on equal sized counts. The main issue is that there is no easy way to directly pass the number of counts to use for bins. For example, a parameter bnds = c(1, 10, 20, 30, 40, 50) would specific the count boundaries for each of the bins.

Take the first example from the documentation:

library(BoutrosLab.plotting.general);


set.seed(12345);

simple.data <- data.frame(
    x = rnorm(10000),
    y = rnorm(10000)
    );

create.hexbinplot(
    formula = y ~ x,
    data = simple.data
    );

The counts are equal spaced (by 9). There is no direct was to set the sequence of counts used for the bins. The parameters we have access to are:

• mincnt: Cells with fewer counts are ignored
• maxcnt: Cells with more counts are ignored, defaults to auto-generation
• colourcut: Vector of values covering [0, 1] that determine hexagon colour class boundaries and hexagon legend size boundaries. Alternatively, an integer (<= maxcnt) specifying the number of equispaced colourcut values in [0,1].

In hexbin code there is an internal variable bnds that is computed: https://github.com/edzer/hexbin/blob/master/R/hexbinplot.R#L557-L561

sc <- maxcnt - mincnt
bnds <- round(mincnt + sc * colorcut)

with some basic algebra we can compute what colorcut should set to based on what we want bnds to be

colorcut <- (bnds - mincnt) / (maxcnt - mincnt)

Another issue arises because part of the convenience of hexbinplot is that maxcnt is computed automatically. This could be done internally to avoid making a plot twice to see the maxcnt computed.

Here is a full example with "round" bins:

library(BoutrosLab.plotting.general);

set.seed(12345);

simple.data <- data.frame(
    x = rnorm(10000),
    y = rnorm(10000)
    );

mincnt <- 1;
maxcnt <- 90;
bnds <- c(1, 10 * 1:10);
colourcut <- (my.bnds - mincnt) / (maxcnt - mincnt);

create.hexbinplot(
    formula = y ~ x,
    data = simple.data,
    colourcut = colourcut,
    mincnt = mincnt,
    maxcnt = maxcnt
    );

^{Created on 2023-07-07 with reprex v2.0.2}