Package 'scattermore' reference manual

Title:	Scatterplots with More Points
Description:	C-based conversion of large scatterplot data to rasters plus other operations such as data blurring or data alpha blending. Speeds up plotting of data with millions of points.
Authors:	Tereza Kulichova [aut], Mirek Kratochvil [aut, cre]
Maintainer:	Mirek Kratochvil <[email protected]>
License:	GPL (>= 3)
Version:	1.2
Built:	2024-09-08 04:57:19 UTC
Source:	https://github.com/exaexa/scattermore

apply_kernel_histogram

Description

Apply a kernel to the given histogram.

Usage

apply_kernel_histogram(
  fhistogram,
  filter = "circle",
  mask = default_kernel(filter, radius, sigma),
  radius = 2,
  sigma = radius/2,
  threads = 0
)
apply_kernel_histogram(
  fhistogram,
  filter = "circle",
  mask = default_kernel(filter, radius, sigma),
  radius = 2,
  sigma = radius/2,
  threads = 0
)

Arguments

`fhistogram`	Matrix or array interpreted as histogram of floating-point values.
`filter`	Use the pre-defined filter, either `circle`, `square`, `gauss`. Defaults to `circle`.
`mask`	Custom kernel used for blurring, overrides `filter`. Must be a square matrix of odd size.
`radius`	Radius of the kernel (counted without the "middle" pixel"), defaults to 2. The generated kernel matrix will be a square with (2*radius+1) pixels on each side.
`sigma`	Radius of the Gaussian function selected by `filter`, defaults to `radius/2`.
`threads`	Number of parallel threads (default 0 chooses hardware concurrency).

Value

2D matrix with the histogram processed by the kernel application.

blend_rgba_float

Description

Blend RGBA matrices.

Usage

blend_rgba_float(fRGBA_list)
blend_rgba_float(fRGBA_list)

Arguments

fRGBA_list

List of floating-point RGBA arrays with premultiplied alpha (each of the same size N-by-M-by-4). The "first" matrix in the list is the one that will be rendered on "top".

Value

Blended RGBA matrix.

ggplot2::ggplot() integration. This cooperates with the rest of ggplot (so you can use it to e.g. add rasterized scatterplots to vector output in order to reduce PDF size). Note that the ggplot processing overhead still dominates the plotting time. Use geom_scattermost() to tradeoff some niceness and circumvent ggplot logic to gain speed.

Usage

geom_scattermore(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  interpolate = FALSE,
  pointsize = 0,
  pixels = c(512, 512)
)
geom_scattermore(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  interpolate = FALSE,
  pointsize = 0,
  pixels = c(512, 512)
)

Arguments

`mapping`, `data`, `stat`, `position`, `inherit.aes`, `show.legend`, `...`	passed to `ggplot2::layer()`
`na.rm`	Remove NA values, just as with `ggplot2::geom_point()`.
`interpolate`	Default FALSE, passed to `grid::rasterGrob()`.
`pointsize`	Radius of rasterized point. Use `0` for single pixels (fastest).
`pixels`	Vector with X and Y resolution of the raster, default `c(512,512)`.

Details

Accepts aesthetics x, y, colour and alpha. Point size is fixed for all points. Due to rasterization properties it is often beneficial to try non-integer point sizes, e.g. 3.2 looks much better than 3.

Examples

library(ggplot2)
library(scattermore)
ggplot(data.frame(x = rnorm(1e6), y = rexp(1e6))) +
  geom_scattermore(aes(x, y, color = x),
    pointsize = 3,
    alpha = 0.1,
    pixels = c(1000, 1000),
    interpolate = TRUE
  ) +
  scale_color_viridis_c()
library(ggplot2)
library(scattermore)
ggplot(data.frame(x = rnorm(1e6), y = rexp(1e6))) +
  geom_scattermore(aes(x, y, color = x),
    pointsize = 3,
    alpha = 0.1,
    pixels = c(1000, 1000),
    interpolate = TRUE
  ) +
  scale_color_viridis_c()

geom_scattermost

Description

Totally non-ggplotish version of geom_scattermore(), but faster. It avoids most of the ggplot processing by bypassing the largest portion of data around any ggplot functionality, leaving only enough data to set up axes and limits correctly. If you need to break speed records, use this.

Usage

geom_scattermost(
  xy,
  color = "black",
  interpolate = FALSE,
  pointsize = 0,
  pixels = c(512, 512)
)
geom_scattermost(
  xy,
  color = "black",
  interpolate = FALSE,
  pointsize = 0,
  pixels = c(512, 512)
)

Arguments

`xy`	2-column object with data, as in `scattermore()`.
`color`	Color vector (or a single color).
`interpolate`	Default FALSE, passed to `grid::rasterGrob()`.
`pointsize`	Radius of rasterized point. Use `0` for single pixels (fastest).
`pixels`	Vector with X and Y resolution of the raster, default `c(512,512)`.

Examples

library(ggplot2)
library(scattermore)
d <- data.frame(x = rnorm(1000000), y = rnorm(1000000))
x_rng <- range(d$x)
ggplot() +
  geom_scattermost(cbind(d$x, d$y),
    color = heat.colors(100, alpha = .01)
    [1 + 99 * (d$x - x_rng[1]) / diff(x_rng)],
    pointsize = 2.5,
    pixels = c(1000, 1000),
    interpolate = TRUE
  )
library(ggplot2)
library(scattermore)
d <- data.frame(x = rnorm(1000000), y = rnorm(1000000))
x_rng <- range(d$x)
ggplot() +
  geom_scattermost(cbind(d$x, d$y),
    color = heat.colors(100, alpha = .01)
    [1 + 99 * (d$x - x_rng[1]) / diff(x_rng)],
    pointsize = 2.5,
    pixels = c(1000, 1000),
    interpolate = TRUE
  )

The actual geom for scattermore

Description

The actual geom for scattermore

Usage

GeomScattermore
GeomScattermore

Format

An object of class GeomScattermore (inherits from Geom, ggproto, gg) of length 6.

The actual geom for scattermost

Description

The actual geom for scattermost

Usage

GeomScattermost
GeomScattermost

Format

An object of class GeomScattermost (inherits from Geom, ggproto, gg) of length 4.

histogram_to_rgbwt

Description

Colorize given histogram with input palette.

Usage

histogram_to_rgbwt(
  fhistogram,
  RGBA = grDevices::col2rgb(col, alpha = T),
  col = grDevices::hcl.colors(10),
  zlim = c(min(fhistogram), max(fhistogram))
)
histogram_to_rgbwt(
  fhistogram,
  RGBA = grDevices::col2rgb(col, alpha = T),
  col = grDevices::hcl.colors(10),
  zlim = c(min(fhistogram), max(fhistogram))
)

Arguments

`fhistogram`	Matrix or 2D array with the histogram of values.
`RGBA`	4-by-N matrix floating-point R, G, B and A channels for the palette. Overrides `col`.
`col`	Colors to use for coloring.
`zlim`	Values to use as extreme values of the histogram

Value

RGBWT matrix.

merge_rgbwt

Description

Merge RGBWT matrices.

Usage

merge_rgbwt(fRGBWT_list)
merge_rgbwt(fRGBWT_list)

Arguments

fRGBWT_list

List of RGBWT arrays. The order of the matrices does not matter (except for negligible floating-point rounding and other robustness errors).

Value

Merged RGBWT matrix.

rgba_float_to_rgba_int

Description

Convert a float RGBA bitmap with pre-multiplied alpha to integer RGBA bitmap.

Usage

rgba_float_to_rgba_int(fRGBA)
rgba_float_to_rgba_int(fRGBA)

Arguments

fRGBA

RGBA bitmap in N-by-M-by-4 array.

Value

RGBA matrix. The output is not premultiplied by alpha.

rgba_int_to_raster

Description

Create a raster from the given RGBA matrix.

Usage

rgba_int_to_raster(i32RGBA)
rgba_int_to_raster(i32RGBA)

Arguments

i32RGBA

Integer RGBA matrix (with all values between 0 and 255).

Value

The matrix converted to raster.

rgbwt_to_rgba_float

Description

Convert RGBWT matrix to floating-point RGBA matrix, suitable for alpha-blending.

Usage

rgbwt_to_rgba_float(fRGBWT)
rgbwt_to_rgba_float(fRGBWT)

Arguments

fRGBWT

The RGBWT matrix.

Value

RGBA matrix, output is premultiplied by alpha.

rgbwt_to_rgba_int

Description

Convert a RGBWT matrix to an integer RGBA matrix.

Usage

rgbwt_to_rgba_int(fRGBWT)
rgbwt_to_rgba_int(fRGBWT)

Arguments

fRGBWT

The RGBWT matrix.

Value

A RGBA matrix. The output is not premultiplied by alpha.

scatter_lines_histogram

Description

Render lines into a histogram.

Usage

scatter_lines_histogram(
  xy,
  xlim = c(min(xy[, c(1, 3)]), max(xy[, c(1, 3)])),
  ylim = c(min(xy[, c(2, 4)]), max(xy[, c(2, 4)])),
  out_size = c(512L, 512L),
  skip_start_pixel = FALSE,
  skip_end_pixel = TRUE
)
scatter_lines_histogram(
  xy,
  xlim = c(min(xy[, c(1, 3)]), max(xy[, c(1, 3)])),
  ylim = c(min(xy[, c(2, 4)]), max(xy[, c(2, 4)])),
  out_size = c(512L, 512L),
  skip_start_pixel = FALSE,
  skip_end_pixel = TRUE
)

Arguments

`xy`	4-column matrix with point coordinates. Each row contains X and Y coordinates of line start and X and Y coordinates of line end, in this order.
`xlim`, `ylim`	2-element vector of rendered area limits (position of the first pixel on the left/top, and the last pixel on the right/bottom). You can flip the image coordinate system by flipping the `⁠*lim⁠` vectors.
`out_size`	2-element vector size of the result raster, defaults to `c(512L,512L)`.
`skip_start_pixel`	TRUE if the start pixel of the lines should be omitted, defaults to `FALSE`.
`skip_end_pixel`	TRUE if the end pixel of a line should be omitted, defaults to `TRUE`. (When plotting long ribbons of connected lines, this prevents counting the connecting pixels twice.)

Value

Histogram with the rendered lines.

scatter_lines_rgbwt

Description

Render lines into a RGBWT bitmap.

Usage

scatter_lines_rgbwt(
  xy,
  xlim = c(min(xy[, c(1, 3)]), max(xy[, c(1, 3)])),
  ylim = c(min(xy[, c(2, 4)]), max(xy[, c(2, 4)])),
  out_size = c(512L, 512L),
  RGBA = c(0, 0, 0, 255),
  skip_start_pixel = FALSE,
  skip_end_pixel = TRUE
)
scatter_lines_rgbwt(
  xy,
  xlim = c(min(xy[, c(1, 3)]), max(xy[, c(1, 3)])),
  ylim = c(min(xy[, c(2, 4)]), max(xy[, c(2, 4)])),
  out_size = c(512L, 512L),
  RGBA = c(0, 0, 0, 255),
  skip_start_pixel = FALSE,
  skip_end_pixel = TRUE
)

Arguments

`xy`	4-column matrix with point coordinates. Each row contains X and Y coordinates of line start and X and Y coordinates of line end, in this order.
`xlim`, `ylim`	2-element vector of rendered area limits (position of the first pixel on the left/top, and the last pixel on the right/bottom). You can flip the image coordinate system by flipping the `⁠*lim⁠` vectors.
`out_size`	2-element vector size of the result raster, defaults to `c(512L,512L)`.
`RGBA`	Vector of 4 elements with integral RGBA color for the lines, defaults to `c(0,0,0,255)`.
`skip_start_pixel`	TRUE if the start pixel of the lines should be omitted, defaults to `FALSE`.
`skip_end_pixel`	TRUE if the end pixel of a line should be omitted, defaults to `TRUE`. (When plotting long ribbons of connected lines, this prevents counting the connecting pixels twice.)

Value

Lines plotted in RGBWT bitmap.

scatter_points_histogram

Description

Render a 2D histogram with given points

Usage

scatter_points_histogram(
  xy,
  xlim = c(min(xy[, 1]), max(xy[, 1])),
  ylim = c(min(xy[, 2]), max(xy[, 2])),
  out_size = c(512L, 512L)
)
scatter_points_histogram(
  xy,
  xlim = c(min(xy[, 1]), max(xy[, 1])),
  ylim = c(min(xy[, 2]), max(xy[, 2])),
  out_size = c(512L, 512L)
)

Arguments

`xy`	2-column matrix with point coordinates (X and Y).
`xlim`, `ylim`	2-element vector of rendered area limits (position of the first pixel on the left/top, and the last pixel on the right/bottom). You can flip the image coordinate system by flipping the `⁠*lim⁠` vectors.
`out_size`	2-element vector size of the result raster, defaults to `c(512L,512L)`.

Value

2D histogram with the points "counted" in appropriate pixels.

scatter_points_rgbwt

Description

Render colored points into a RGBWT bitmap

Usage

scatter_points_rgbwt(
  xy,
  xlim = c(min(xy[, 1]), max(xy[, 1])),
  ylim = c(min(xy[, 2]), max(xy[, 2])),
  out_size = c(512, 512),
  RGBA = c(0, 0, 0, 255),
  map = NULL,
  palette = NULL
)
scatter_points_rgbwt(
  xy,
  xlim = c(min(xy[, 1]), max(xy[, 1])),
  ylim = c(min(xy[, 2]), max(xy[, 2])),
  out_size = c(512, 512),
  RGBA = c(0, 0, 0, 255),
  map = NULL,
  palette = NULL
)

Arguments

`xy`	2-column matrix with N point coordinates (X and Y) in rows.
`xlim`, `ylim`	2-element vector of rendered area limits (position of the first pixel on the left/top, and the last pixel on the right/bottom). You can flip the image coordinate system by flipping the `⁠*lim⁠` vectors.
`out_size`	2-element vector size of the result raster, defaults to `c(512L,512L)`.
`RGBA`	Point colors. Either a 4-element vector that specifies the same color for all points, or 4-by-N matrix that specifies color for each of the individual points. Color is specified using integer RGBA; i.e. the default black is `c(0,0,0,255)`.
`map`	Vector with N integer indices to `palette`. Overrides RGBA-based coloring.
`palette`	Matrix 4-by-K matrix of RGBA colors used as a palette lookup for the `map` that gives the point colors. K is at least `max(map)`. Notably, using a palette may be faster than filling and processing the whole RGBA matrix.

Value

A RGBWT array with the rendered points.

scattermore

Description

Convert points to raster scatterplot rather quickly.

Usage

scattermore(
  xy,
  size = c(512, 512),
  xlim = c(min(xy[, 1]), max(xy[, 1])),
  ylim = c(min(xy[, 2]), max(xy[, 2])),
  rgba = c(0L, 0L, 0L, 255L),
  cex = 0,
  output.raster = TRUE
)
scattermore(
  xy,
  size = c(512, 512),
  xlim = c(min(xy[, 1]), max(xy[, 1])),
  ylim = c(min(xy[, 2]), max(xy[, 2])),
  rgba = c(0L, 0L, 0L, 255L),
  cex = 0,
  output.raster = TRUE
)

Arguments

`xy`	2-column float matrix with point coordinates. As usual with rasters in R, X axis grows right, and Y axis grows DOWN. Flipping `ylim` causes the usual mathematical behavior.
`size`	2-element vector integer size of the result raster, defaults to `c(512,512)`.
`xlim`, `ylim`	Float limits as usual (position of the first pixel on the left/top, and the last pixel on the right/bottom). You can easily flip the top/bottom to the "usual" mathematical system by flipping the `ylim` vector.
`rgba`	4-row matrix with color values of 0-255, or just a single 4-item vector for `c(r,g,b,a)`. Best created with `col2rgb(..., alpha=TRUE)`.
`cex`	Additional point radius in pixels, 0=single-pixel dots (fastest)
`output.raster`	Output R-style raster (as.raster)? Default TRUE. Raw array output can be used much faster, e.g. for use with png::writePNG.

Value

Raster with the result.

Examples

library(scattermore)
plot(scattermore(cbind(rnorm(1e6), rnorm(1e6)), rgba = c(64, 128, 192, 10)))
library(scattermore)
plot(scattermore(cbind(rnorm(1e6), rnorm(1e6)), rgba = c(64, 128, 192, 10)))

scattermoreplot

Description

Convenience base-graphics-like layer around scattermore. Currently only works with linear axes!

Usage

scattermoreplot(
  x,
  y,
  xlim,
  ylim,
  size,
  col = grDevices::rgb(0, 0, 0, 1),
  cex = 0,
  pch = NULL,
  xlab,
  ylab,
  ...
)
scattermoreplot(
  x,
  y,
  xlim,
  ylim,
  size,
  col = grDevices::rgb(0, 0, 0, 1),
  cex = 0,
  pch = NULL,
  xlab,
  ylab,
  ...
)

Arguments

`x`, `y`, `xlim`, `ylim`, `xlab`, `ylab`, `...`	used as in `graphics::plot()` or forwarded to `graphics::plot()`
`size`	forwarded to `scattermore()`, or auto-derived from device and plot size if missing (the estimate is not pixel-perfect on most devices, but gets pretty close)
`col`	point color(s)
`cex`	forwarded to `scattermore()`
`pch`	ignored (to improve compatibility with `graphics::plot()`

Examples

# plot an actual rainbow
library(scattermore)
d <- data.frame(s = qlogis(1:1e6 / (1e6 + 1), 6, 0.5), t = rnorm(1e6, pi / 2, 0.5))
scattermoreplot(
  d$s * cos(d$t),
  d$s * sin(d$t),
  col = rainbow(1e6, alpha = .05)[c((9e5 + 1):1e6, 1:9e5)],
  main = "scattermore demo"
)
# plot an actual rainbow
library(scattermore)
d <- data.frame(s = qlogis(1:1e6 / (1e6 + 1), 6, 0.5), t = rnorm(1e6, pi / 2, 0.5))
scattermoreplot(
  d$s * cos(d$t),
  d$s * sin(d$t),
  col = rainbow(1e6, alpha = .05)[c((9e5 + 1):1e6, 1:9e5)],
  main = "scattermore demo"
)

`fRGBWT`	RGBWT array with channels `red`, `green`, `blue`, `weight` and `transparency`. The dimension should be N times M times 5.
`filter`	Use the pre-defined filter, either `circle`, `square`, `gauss`. Defaults to `circle`.
`mask`	Custom kernel used for blurring, overrides `filter`. Must be a square matrix of odd size.
`radius`	Radius of the kernel (counted without the "middle" pixel"), defaults to 2. The generated kernel matrix will be a square with (2*radius+1) pixels on each side.
`sigma`	Radius of the Gaussian function selected by `filter`, defaults to `radius/2`.
`threads`	Number of parallel threads (default 0 chooses hardware concurrency).

Package 'scattermore'

Help Index

apply_kernel_histogram

Description

Usage

Arguments

Value

apply_kernel_rgbwt

Description

Usage

Arguments

Value

blend_rgba_float

Description

Usage

Arguments

Value

geom_scattermore

Description

Usage

Arguments

Details

Examples

geom_scattermost

Description

Usage

Arguments

Examples

The actual geom for scattermore

Description

Usage

Format

The actual geom for scattermost

Description

Usage

Format

histogram_to_rgbwt

Description

Usage

Arguments

Value

merge_rgbwt

Description

Usage

Arguments

Value

rgba_float_to_rgba_int

Description

Usage

Arguments

Value

rgba_int_to_raster

Description

Usage

Arguments

Value

rgbwt_to_rgba_float

Description

Usage

Arguments

Value

rgbwt_to_rgba_int

Description

Usage

Arguments

Value

scatter_lines_histogram

Description

Usage

Arguments

Value

scatter_lines_rgbwt

Description

Usage

Arguments

Value

scatter_points_histogram

Description

Usage

Arguments