R: Interactive 3D Scatterplots

scatterplot3js {threejs} | R Documentation

## 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, 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)`.
`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.
`pch` | Optional point glyphs, see notes.
`...` | 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.)

### 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:

- "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

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: http://threejs.org. The HTML Widgets project: http://htmlwidgets.org.

### See Also

scatterplot3d, rgl, points3d, lines3d

### 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)

[Package threejs version 0.3.1 Index]