scatterplot3js: Interactive 3D Scatterplots

In bwlewis/rthreejs: Interactive 3D Scatter Plots, Networks and Globes

Interactive 3D Scatterplots

Description

A 3D scatterplot widget using three.js. Many options follow the scatterplot3d package.

Usage

scatterplot3js(
  x,
  y,
  z,
  height = NULL,
  width = NULL,
  axis = TRUE,
  num.ticks = c(6, 6, 6),
  x.ticklabs = NULL,
  y.ticklabs = NULL,
  z.ticklabs = NULL,
  color = "steelblue",
  size = cex.symbols,
  stroke = "black",
  flip.y = TRUE,
  grid = TRUE,
  renderer = c("auto", "canvas"),
  signif = 8,
  bg = "#ffffff",
  cex.symbols = 1,
  xlim,
  ylim,
  zlim,
  axis.scale = c(1, 1, 1),
  pch = "@",
  elementId = NULL,
  ...
)

Arguments

x	Either a vector of x-coordinate values or a three-column data matrix with columns corresponding to the x,y,z coordinate axes. Column labels, if present, are used as axis labels.
y	(Optional) vector of y-coordinate values, not required if x is a matrix.
z	(Optional) vector of z-coordinate values, not required if x is a matrix.
height	The container div height.
width	The container div width.
axis	A logical value that when TRUE indicates that the axes will be displayed.
num.ticks	A three-element or one-element vector with the suggested number of ticks to display per axis. If a one-element vector, this number of ticks will be used for the axis with the smallest axis.scale, and the number of ticks on the remaining axes will be increased proportionally to the axis.scale values. Set to NULL to not display ticks. The number of ticks may be adjusted by the program.
x.ticklabs	A vector of tick labels of length num.ticks[1], or NULL to show numeric labels.
y.ticklabs	A vector of tick labels of length num.ticks[2], or NULL to show numeric labels.
z.ticklabs	A vector of tick labels of length num.ticks[3], or NULL to show numeric labels.
color	Either a single hex or named color name (all points same color), or a vector of hex or named color names as long as the number of data points to plot.
size	The plot point radius, either as a single number or a vector of sizes of length nrow(x).
stroke	A single color stroke value (surrounding each point). Set to null to omit stroke (only available in the canvas renderer).
flip.y	Reverse the direction of the y-axis (the default value of TRUE produces plots similar to those rendered by the R scatterplot3d package).
grid	Set FALSE to disable display of a grid.
renderer	Select from available plot rendering techniques of 'auto' or 'canvas'. Set to 'canvas' to explicitly use non-accelerated Canvas rendering, otherwise WebGL is used if available.
signif	Number of significant digits used to represent point coordinates. Larger numbers increase accuracy but slow plot generation down.
bg	The color to be used for the background of the device region.
cex.symbols	Equivalent to the size parameter.
xlim	Optional two-element vector of x-axis limits. Default auto-scales to data.
ylim	Optional two-element vector of y-axis limits. Default auto-scales to data.
zlim	Optional two-element vector of z-axis limits. Default auto-scales to data.
axis.scale	Three-element vector to scale each axis as displayed on the plot, after first scaling them all to a unit length. Default c(1,1,1) thus results in the axes of equal length. If NA, the displayed axes will be scaled to the ratios determined from c(xlim,ylim,zlim).
pch	Optional point glyphs, see notes.
elementId	Use an explicit element ID for the widget (rather than an automatically generated one). Useful if you have other JavaScript that needs to explicitly discover and interact with a specific widget instance.
...	Additional options (see note).

Value

An htmlwidget object that is displayed using the object's show or print method. (If you don't see your widget plot, try printing it with the print function.)

Scaling the axes

With the default values, the displayed axes are scaled to equal one-unit length. If you instead need to maintain the relative distances between points in the original data, and the same distance between the tick labels, pass num.ticks=6 (or any other single number) and axis.scale=NA

Interacting with the plot

Press and hold the left mouse button (or touch or trackpad equivalent) and move the mouse to rotate the plot. Press and hold the right mouse button (or touch equivalent) to pan. Use the mouse scroll wheel or touch equivalent to zoom. If labels are specified (see below), moving the mouse pointer over a point will display the label.

Detailed plot options

Use the optional ... argument to explicitly supply axisLabels as a three-element character vector, see the examples below. A few additional plot options are also supported:

• "lights" a list of light_ambient and light_directional objects

• "cex.lab" font size scale factor for the axis labels

• "cex.axis" font size scale factor for the axis tick labels

• "font.axis" CSS font string used for all axis labels

• "font.symbols" CSS font string used for plot symbols

• "font.main" CSS font string used for main title text box

• "labels" character vector of length x of point labels displayed when the mouse moves over the points

• "main" Plot title text

• "top" Top location in pixels from top of the plot title text

• "left" Left location in pixels from center of the plot title text

• "program" User-supplied JavaScript run on plot initialization

The default CSS font string is "48px Arial". Note that the format of this font string differs from, for instance, the usual 'par(font.axis)'.

Use the pch option to specify points styles in WebGL-rendered plots. pch may either be a single character value that applies to all points, or a vector of character values of the same length as x. All character values are used literally ('+', 'x', '*', etc.) except for the following special cases:

• "o" Plotted points appear as 3-d spheres.

• "@" Plotted points appear as stroked disks.

• "." Points appear as tiny squares.

Character strings of more than one character are supported–see the examples. The @ and . option exhibit the best performance, consider using one of those to plot large numbers of points.

Set the optional experimental use.orbitcontrols=TRUE argument to use a more CPU-efficient but somewhat less fluid mouse/touch interface.

Plotting lines

See lines3d for an alternative interface. Lines are optionally drawn between points specified in x, y, z using the following new plot options.

• "from" A numeric vector of indices of line starting vertices corresponding to entries in x.

• "to" A numeric vector exactly as long as from of indices of line ending vertices corresponding to entries in x.

• "lcol" Either a single color value or vector of values as long as from; line colors default to interpolating their vertex point colors.

• "lwd" A single numeric value of line width (for all lines), defaults to 1.

• "linealpha" A single numeric value between 0 and 1 inclusive setting the transparency of all plot lines, defaulting to 1.

Highlighting selected points

Specify the argument brush=TRUE to highlight a clicked point (currently limited to single-point selection). Optionally set the highlight=<color> and lowlight=<color> to manually control the brushing display colors. This feature works with crosstalk.

Crosstalk

The scatterplot3js() and graphjs() functions work with crosstalk selection (but not filtering yet); see https://rstudio.github.io/crosstalk/. Enable crosstalk with the optional agrument crosstalk=df, where df is a crosstalk-SharedData data.frame-like object with the same number of rows as points (scatterplot3js()) or graph vertices (graphjs()) (see the examples).

Note

Points with missing values are omitted from the plot, please try to avoid missing values in x, y, z.

References

The three.js project: https://threejs.org. The HTML Widgets project:

See Also

scatterplot3d, rgl, points3d, lines3d, light_ambient, light_directional

Examples

# Example 1 from the scatterplot3d package (cf.)
z <- seq(-10, 10, 0.1)
x <- cos(z)
y <- sin(z)
scatterplot3js(x, y, z, color=rainbow(length(z)))

# Same example with explicit axis labels
scatterplot3js(x, y, z, color=rainbow(length(z)), axisLabels=c("a", "b", "c"))

# Same example showing multiple point styles with pch
scatterplot3js(x, y, z, color=rainbow(length(z)),
               pch=sample(c(".", "o", letters), length(x), replace=TRUE))

# Point cloud example, should run this with WebGL!
N     <- 20000
theta <- runif (N) * 2 * pi
phi   <- runif (N) * 2 * pi
R     <- 1.5
r     <- 1.0
x <- (R + r * cos(theta)) * cos(phi)
y <- (R + r * cos(theta)) * sin(phi)
z <- r * sin(theta)
d <- 6
h <- 6
t <- 2 * runif (N) - 1
w <- t^2 * sqrt(1 - t^2)
x1 <- d * cos(theta) * sin(phi) * w
y1 <- d * sin(theta) * sin(phi) * w
i <- order(phi)
j <- order(t)
col <- c( rainbow(length(phi))[order(i)],
         rainbow(length(t), start=0, end=2/6)[order(j)])
M <- cbind(x=c(x, x1), y=c(y, y1), z=c(z, h*t))
scatterplot3js(M, size=0.5, color=col, bg="black", pch=".")

# Plot generic text using 'pch' (we label some points in this example)
set.seed(1)
x <- rnorm(5); y <- rnorm(5); z <- rnorm(5)
scatterplot3js(x, y, z, pch="@") %>%
   points3d(x + 0.1, y + 0.1, z, color="red", pch=paste("point", 1:5))

## Not run: 
  # A shiny example
  shiny::runApp(system.file("examples/scatterplot", package="threejs"))

## End(Not run)

## Not run: 
  # A crosstalk example
  library(crosstalk)
  library(d3scatter) # devtools::install_github("jcheng5/d3scatter")
  z <- seq(-10, 10, 0.1)
  x <- cos(z)
  y <- sin(z)
  sd <- SharedData$new(data.frame(x=x, y=y, z=z))
  print(bscols(
    scatterplot3js(x, y, z, color=rainbow(length(z)), brush=TRUE, crosstalk=sd),
    d3scatter(sd, ~x, ~y, width="100%", height=300)
  ))

## End(Not run)

bwlewis/rthreejs documentation built on Aug. 22, 2022, 1:30 p.m.