Interactive 3D Scatterplots

Description

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

Usage

1
2
3
4
5
6
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 = 1, labels = NULL,
  label.margin = "10px", stroke = "black", flip.y = TRUE, grid = TRUE,
  renderer = c("auto", "canvas", "webgl"), signif = 8, bg = "#ffffff",
  xlim, ylim, zlim, pch, ...)

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 vector with the suggested number of ticks to display per axis. 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). A vector of sizes is only supported by the canvas renderer. The webgl renderer accepts a single size value for all points.

labels

Either NULL (no labels), or a vector of labels as long as the number of data points displayed when the mouse hovers over each point.

label.margin

A CSS-style margin string used to display the point labels.

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', 'canvas', or 'webgl'.

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.

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.

pch

Not yet used but one day will support changing the point glyph.

...

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. The returned object includes a special points3d function for adding points to the plot similar to scatterplot3d. See the note below and examples for details.

Note

Points with missing values are omitted.

Use the renderer option to manually select from the available rendering options. The canvas renderer is the fallback rendering option when webgl is not available. Select auto to automatically choose between the two. The two renderers produce slightly different-looking output and have different available options (see above). Use the webgl renderer for plotting large numbers of points (if available). Use the canvas renderer to excercise finer control of plotting of smaller numbers of points. See the examples.

Use the optional ... argument to explicitly supply axisLabels as a three-element character vector, see the examples below.

The returned object includes a points3d function that can add points to a plot, returning a new htmlwidget plot object. The function signature is a subset of the full scatterplot3js function:

points3d (x, y, z, color="steelblue", size=1, labels="")

It allows you to add points to a plot using the same syntax as scatterplot3js with optionally specified color, size, and labels. New points are plotted in the same scale as the existing plot. See the examples section below for an example.

References

The three.js project http://threejs.org.

See Also

scatterplot3d, rgl

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
# Gumball machine
N <- 100
i <- sample(3, N, replace=TRUE)
x <- matrix(rnorm(N*3),ncol=3)
lab <- c("small", "bigger", "biggest")
scatterplot3js(x, color=rainbow(N), labels=lab[i], size=i, renderer="canvas")

# 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)),
      labels=sprintf("x=%.2f, y=%.2f, z=%.2f", x, y, z))

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

# Pretty 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.25,color=col,bg="black")

# Adding points to a plot with points3d
set.seed(1)
lim <- c(-3,3)
x <- scatterplot3js(rnorm(5),rnorm(5),rnorm(5), xlim=lim, ylim=lim, zlim=lim)
a <- x$points3d(rnorm(3),rnorm(3),rnorm(3)/2, color="red", labels="NEW")
## Not run: 
  # A shiny example
  shiny::runApp(system.file("examples/scatterplot",package="threejs"))

## End(Not run)