GlowMapper: GlowMapper

In glow: Make Plots that Glow

GlowMapper

Description

This class provides a framework for creating scatter plots based on a glow simulation. Points are mapped with a gaussian gradient to a raster with specified dimensions and properties.

Usage

m <- GlowMapper$new(xdim=1000, ydim=800, blend_mode = "screen", contrast_limit = 1e5, nthreads = 1)

m$map(x, y, radius, intensity = 1, distance_exponent = 2, xlimits = c(NA_real_, NA_real_), ylimits = c(NA_real_, NA_real_), append = FALSE)

m$output_raw(saturation = NA_real_)

m$output_dataframe(saturation = NA_real_)

m$aspect()

m$xlim()

m$ylim()

Arguments

xdim

- The first dimension of the output matrix raster.

ydim

- The second dimension of the output matrix raster.

blend_mode

- Either screen or additive blending mode. See details.

contrast_limit

- Determines the distance to search from a point. You shouldn't need to change this unless you have a lot of points in the plot stacked on top of each other.

nthreads

- Number of threads to use.

x

- X coordinate of points.

y

- Y coordinate of points.

radius

- Relative spread of glow intensity. The radius should be proportional to the x and y-ranges of the plot. Values between 1/10 to 1/100 of the range of the plot generally produce good results.

intensity

- Maximum intensity at the center of a point.

distance_exponent

- Exponent of the distance calculation when calculating intensities. A value of 2 corresponds to euclidean distance; a value of 1 corresponds to manhattan distance.

xlimits

- The x-limits of the output plot. If NA, the limits are +/- 5% of the maximum and minimum points.

ylimits

- The y-limits of the output plot. If NA, the limits are +/- 5% of the maximum and minimum points.

append

- Whether to add to the existing output or overwrite.

saturation

- When retrieving the output with $output_raw or $output_dataframe, maximum intensity values are capped at the given value. This is often useful when using additive blend mode to increase contrast.

Details

$new() creates a new GlowMapper object, which holds parameters, plotting data, and the output (a matrix of glow intensities). Creates a canvas to plot point data. With additive blending, the intensities of each point are added arithmetically, which is how light intensities are added in the physical world. This is equivalent to an fast/approximate un-normalized 2D kernel density estimate.

With "screen" blending, two intensities are added according to the formula: I_out = 1 - (1-I_a)*(1-I_b). Both additive blending and screen blending are commutative operations, meaning the order of points in a plot does not affect the output.

Screen blending can often improve contrast in a plot and is the default.

$map() maps points to the canvas.

$output_raw() output raw matrix rasters. Useful for plotting in base R.

$output_dataframe() output the raster as a dataframe with XY coordinates. This is meant to pipe directly into ggplot.

$aspect(), $xlim(), $ylim() return the aspect ratio, x-limits and y-limits of the raster. These functions are intended to be used with plotting functions (e.g. ggplot2::coord_fixed()) so that the output raster is not distorted. See example below.

Examples

# Plot Data: x,y,r
x <- numeric(length=50)
y <- numeric(length=50)
r <- numeric(length=50)
for(t in 1:50) {
  xy <- exp(1i * t/2 - t/12)
  x[t] <- Re(xy)
  y[t] <- Im(xy)
  r[t] <- sqrt(x[t]^2 + y[t]^2)
}

# New class object
m <- GlowMapper$new(xdim=500, ydim = 400, blend_mode = "screen")

# Map data on to raster
m$map(x=x, y=y, intensity = 1, radius = r/4 + 0.1, distance_exponent = 2)

# Output raster data as a dataframe
pd <- m$output_dataframe(saturation = 1)

# Plot with ggplot
ggplot(pd, aes(x = x, y = y, fill = value)) + 
  geom_raster(show.legend = FALSE) +
  scale_fill_gradientn(colors=additive_alpha(c("black", "purple", "white"))) +
  coord_fixed(ratio = m$aspect(), xlim = m$xlim(), ylim = m$ylim(), expand = FALSE) + 
  theme_night(bgcolor = "black")

glow documentation built on April 6, 2023, 1:08 a.m.