% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/type_hexbin.R
\name{type_hexbin}
\alias{type_hexbin}
\title{Hexagonal binning plot type}
\usage{
type_hexbin(
  xbins = 30,
  shape = 1,
  mincnt = 1,
  maxcnt = Inf,
  border = NA,
  fun = NULL
)
}
\arguments{
\item{xbins}{Integer. The number of bins partitioning the range of the
x-axis. Default is \code{30}.}

\item{shape}{Numeric. The aspect ratio (height/width) of the plotting region
used to compute the hexagon geometry. Default is \code{1}.}

\item{mincnt, maxcnt}{Integer. Cells with counts outside the
\verb{[mincnt, maxcnt]} range are omitted. Defaults keep all occupied cells.}

\item{border}{Colour for the hexagon borders, passed to
\code{\link[graphics]{polygon}}. The default \code{NA} omits the border entirely.
Set a colour (e.g. \code{"black"}) for outlined hexagons. Passing the sentinel
string \code{"fill"} matches the border to each cell's fill colour, which
produces perfectly seamless tiling.}

\item{fun}{Function used to summarise a \emph{numeric} \code{by} variable within each
cell (see Details). Defaults to \code{NULL}, which is equivalent to \code{mean}. Has
no effect when \code{by} is absent (count mode) or discrete (modal mode).}
}
\description{
Type function for hexagonal bin plots (a 2D analogue of a
histogram). Point density is aggregated into a regular hexagonal lattice
and each occupied cell is drawn as a hexagon whose fill colour encodes the
number of points it contains. This is a lightweight (vectorized), pure R
implementation of the canonical hexagonal binning algorithm of Carr et al.
(1987).
}
\details{
Hexagonal binning partitions the plotting region into a regular
lattice of hexagons. Following the original Carr et al. (1987) algorithm,
rows are spaced \eqn{\sqrt{3}/2} apart in scaled space, with odd rows
offset by half a cell in the x-direction, while each point is assigned to
its nearest lattice node.

What the fill colour encodes depends on whether a \code{by} variable is supplied
(e.g. \code{y ~ x | z}):
\itemize{
\item \strong{No \code{by} (default).} The fill encodes the \emph{cell count}, mapped to a
continuous colour gradient with an automatic colourbar legend.
\item \strong{Discrete \code{by}.} The fill encodes the \emph{modal} (most frequent) level of
the \code{by} variable within each cell, drawn with a discrete qualitative
palette and legend. Useful for mapping the dominant category across a
dense scatter.
\item \strong{Numeric \code{by}.} The fill encodes a per-cell summary of the \code{by}
variable---by default the mean, or any other function passed via \code{fun}
(e.g. \code{fun = sum}). Like the original no-\code{by} case, the legend is drawn
as a continuous gradient. This is the hexagonal analogue of a binned
heatmap.
}

In all three modes, the \code{mincnt}/\code{maxcnt} filters still apply to the raw
cell \emph{count}, so sparsely populated cells can be excluded regardless of
what the colour encodes.

Because the hexagon size is derived from the data ranges, hexagons will
only appear perfectly regular when the plot region's aspect ratio matches
\code{shape}. Adjust \code{shape} (or the device dimensions) if you need visually
regular hexagons.

The \CRANpkg{tinyplot} implementation presented here is a compact
(vectorised) translation of the original Carr et al. algorithm into base R.
Users requiring the fuller feature set of a dedicated hexbinning package
should consult \CRANpkg{hexbin} as a canonical reference, which is built on
top of compiled Fortran code. Note that we have validated our cell counts
against this package to confirm they match exactly.
}
\examples{
set.seed(1234)
dat = data.frame(x = rnorm(20000), y = rnorm(20000))

# "hexbin" type convenience string
tinyplot(y ~ x, data = dat, type = "hexbin")

# Use type_hexbin() to pass extra arguments
tinyplot(y ~ x, data = dat, type = type_hexbin(xbins = 40))

# tinyplot's default palette logic maps darker colours (the end of the
# spectrum) to higher densities. For hexbin plots it can sometimes be more
# visually pleasing to reverse this, which users can do manually by passing a
# reversed palette.
tinyplot(
  y ~ x, data = dat, type = "hexbin",
  palette = hcl.colors(100, palette = "viridis", rev = TRUE)
)

# Passing a `by` grouping variable will colour cells according to a summary
# of this variable (in each hex cell) instead of density count. The default
# summary function depends on whether `by` is discrete or continuous:

# 1) Discrete grouping variable: each cell is coloured by its mode.
dat$g = cut(dat$x, breaks = c(-Inf, -1, 1, Inf), labels = c("lo", "mid", "hi"))
tinyplot(y ~ x | g, data = dat, type = "hexbin")

# 2) Continuous grouping variable: each cell is coloured by its mean. 
#    Example: Create a long version of the `volcano` dataset, and plot its
#    elevations onto a gridded terrain map.
volc = local({
  v = setNames(stack(as.data.frame(volcano)), c("elevation", "y"))
  v$y = as.numeric(gsub("^V", "", v$y))
  v$x = seq_len(nrow(volcano))
  v
})
tinyplot(
  y ~ x | elevation, data = volc,
  type = "hexbin", xbins = 50,
  palette = terrain.colors(100, rev = TRUE)
)

}
\references{
Carr, D. B., Littlefield, R. J., Nicholson, W. L., and Littlefield, J. S.
(1987). \cite{Scatterplot Matrix Techniques for Large N}. Journal of the
American Statistical Association, 82(398), 424-436. Available:
https://doi.org/10.2307/2289444

Carr, D., Lewin-Koh, N., Maechler, M., and Sarkar, D. (2024).
\cite{hexbin: Hexagonal Binning Routines}. R package version 1.28.5.
Available: https://doi.org/10.32614/CRAN.package.hexbin. The \CRANpkg{hexbin}
package provides the canonical implementation of this algorithm, and was a
valuable reference for validating our cell counts.
}
