Skip to contents

n \(\times\) n Unmixed Biplot Triangle

Source: R/plot_unmixed_nxn.R
unmixed.nxn.plot.Rd

Produces a lower-triangular grid of scatter biplots for every pair of channels in an unmixed dataset, with 1-D histograms on the diagonal, and saves the result as a single large-format PDF.

For \(n\) channels the grid is \(n \times n\) panels. The upper triangle and all cells above the diagonal are left blank, giving \(n(n-1)/2\) scatter panels and \(n\) histogram panels. Panel \((i, j)\) (row \(i\), column \(j\)) shows column \(j\) on the x-axis and row \(i\) on the y-axis, consistent with the convention used by unmixed.mxn.plot(): the named fluorophore always appears on x.

Data are downsampled once to max.points events before any panel is drawn so all panels share an identical cell population. Axis minima are auto-scaled per channel from the 1st percentile of the data, floored at the user-supplied x.min / y.min.

Usage

unmixed.nxn.plot(
  unmixed.data,
  asp,
  channels = NULL,
  gate.boundary = NULL,
  scatter.param = asp$default.scatter.parameter,
  max.points = 50000,
  title = "nxn_biplot",
  biplot.size = 3,
  x.min = -1000,
  y.min = -1000,
  x.width.basis = -1000,
  y.width.basis = -1000,
  use.hex = TRUE,
  hex.bins = 64,
  color.palette = "viridis",
  hist.fill = "steelblue",
  file.type = "jpg",
  dpi = 150,
  max.canvas.px = 20000,
  output.dir = "."
)

Arguments

unmixed.data

Either a character string giving the path to an unmixed FCS file, or a numeric matrix / data.frame whose columns are fluorophore channels and whose rows are cells.

asp

The AutoSpectral parameter list, created by get.autospectral.param().

channels

Optional character vector. Subset of columns to include. When NULL (default) all columns are used. Large panels sets (\(n > 20\)) will produce very large PDFs; consider subsetting.

gate.boundary

Optional gate boundary, as returned by define.gate.landmarks(), define.gate.density(), or do.gate() — a list containing at least numeric x and y components describing the polygon vertices. When supplied and scatter.param columns are present in the data, events are gated with apply.gate() before downsampling to max.points. When scatter.param columns are absent, gating is skipped with a warning. Default NULL (no gating).

scatter.param

Character vector of length 2 giving the names of the two scatter columns to gate on when gate.boundary is supplied. Default asp$default.scatter.parameter. Ignored if gate.boundary is NULL.

max.points

Integer. Total number of events retained after a single random downsample applied before any panel is drawn. Default 5e4.

title

Character string used as the PDF filename stem. Default "nxn_biplot".

biplot.size

Numeric. Edge length in inches of each individual panel (both scatter and histogram panels). The saved PDF will be n * biplot.size \(\times\) n * biplot.size inches. Default 3.

x.min

Numeric. Floor for the auto-scaled x-axis minimum (data units). The actual minimum used is min(auto, x.min). Default -1000.

y.min

Numeric. Floor for the auto-scaled y-axis minimum (data units). Default -1000.

x.width.basis

Numeric. Width basis for the biexponential x-axis transform. Default -1000.

y.width.basis

Numeric. Width basis for the biexponential y-axis transform. Default -1000.

use.hex

Logical. When TRUE (default), scatter panels are rendered with ggplot2::geom_hex() for speed. When FALSE, reverts to scattermore::geom_scattermore() + ggplot2::stat_density_2d().

hex.bins

Integer. Number of bins for geom_hex in each dimension. Ignored when use.hex = FALSE. Default 64.

color.palette

Character string. Viridis palette name ("viridis", "magma", "inferno", "plasma", "cividis", "rocket", "mako", "turbo") or "rainbow" to use the package default gradient. Applies to scatter panels. Default "viridis".

hist.fill

Character string. Fill color for the diagonal histogram bars. Default "steelblue".

file.type

Character string specifying the output file format. One of "jpg" (default), "tiff", "png", or "pdf". Raster formats are strongly recommended here: for large channel counts the triangle holds hundreds to thousands of panels, and a vector "pdf" records every hexagon/point as a separate drawn object, making it extremely slow to render and write.

dpi

Numeric. Resolution in dots per inch for raster file.type values. Ignored for "pdf". Default 150.

max.canvas.px

Numeric. Safety cap on the predicted raster width/ height in pixels (n * biplot.size * dpi). If the requested combination would exceed this, dpi is automatically reduced (with a warning) rather than attempting to allocate an oversized raster. Ignored for "pdf". Default 20000.

output.dir

Character string. Directory for the output file. Created automatically if absent. Default ".".

Value

The combined cowplot::plot_grid() object is returned invisibly. The figure is always written to output.dir.

See also

unmixed.mxn.plot(), create.biplot()