Skip to contents

3D scatter plot with a categorical legend

Source: R/fpoints3d.R
fpoints3d.Rd

A generic function that, by default, draws a 3D scatter plot (rgl::plot3d()) with points colored according to the levels of a factor f, and (optionally) adds a categorical legend (via fplot3d()).

Usage

fpoints3d(x, ...)

# Default S3 method
fpoints3d(
  x,
  y = NULL,
  z = NULL,
  f,
  col = hcld.colors(nlevels(f)),
  xlab = NULL,
  ylab = NULL,
  zlab = NULL,
  type = "p",
  legend = TRUE,
  legend.type = c("s", "c", "p", "l"),
  legend.zoom = 0.6,
  legend.width = 0.2,
  legend.size = 4,
  legend.dim = 0.2,
  legend.lab = NULL,
  lab.dist = 2.5,
  lab.rev = FALSE,
  add = FALSE,
  ...
)

Arguments

x

object used to select a method. In the default method, it provides the x coordinates for the plot (and optionally the y and z coordinates; any reasonable way of defining the coordinates is acceptable, see the function xyz.coords() for details).

...

additional arguments passed to rgl::plot3d() for the main scatter plot (e.g. size).

y, z

y and z point coordinates. Alternatively, a single argument x can be provided.

f

(factor, or vector coercible to factor), used to color the points.

col

vector of colors associated with each level of f (defaults to hcld.colors(nlevels(f))).

xlab, ylab, zlab

labels for the coordinates.

type

character indicating the type of item to plot (see rgl::plot3d(): "p" for points, "s" for spheres, "l" for lines, "h" for line segments from z = 0, and "n" for nothing).

legend

logical; if TRUE (default), the active rgl device is splitted into two subscenes, drawing the main plot in one and the categorical legend in the other (see fplot3d()). if FALSE only the (coloured) main plot is drawn and the arguments related to the legend are ignored (fplot3d() is not called).

legend.type

character; symbol/object used to represent each level in the legend (see type in fplot3d()): "s" for spheres (default), "c" for cubes, "p" for points, or "l" for (horizontal) line segments.

legend.zoom

zoom factor applied to the legend subscene/panel.

legend.width

relative size of the legend symbols (spheres, cubes or line segments), as a fraction of the corresponding dimension of the legend subscene.

legend.size

point size, if type = "p", or line width, if type = "l" (in pixels; see size and lwd graphical parameters in rgl::par3d(); ignored in all other cases).

legend.dim

relative dimension of the legend panel, as a fraction of the full width (or height) of the device.

legend.lab

label for the axis of the color legend, defaults to a description of f.

lab.dist

distance between the legend symbols and their text labels, as a multiple of the symbol size (legend.width).

lab.rev

logical; if TRUE the order of the levels in the legend is reversed (by default they are shown from top to bottom).

add

logical; if TRUE the scatter plot is just added to the existing plot (including the legend if legend = TRUE).

Value

Called for its side effect (draws the 3D scatter plot and, unless legend = FALSE, the legend on the active rgl device).

See also

spoints3d(), fplot3d(), fcolor(), fshade3d(), rgl::plot3d().

Examples

library(rgl)
open3d() # Alternatively, use `new3d()` to clear the current device or open a new one
with(mtcars, fpoints3d(hp, qsec, mpg, f = cyl, type = "s"))