Visualize multidimensional data in 3D and/or multiple 2D projections.

TODO

plot3dProj(x, col = NULL, cls = NULL, size = 3, alpha = 1, main = NULL,
    x2 = NULL, col2 = NULL, cls2 = NULL, size2 = 3, alpha2 = 1,
    main2 = NULL, x3 = NULL, col3 = NULL, cls3 = NULL, size3 = 3,
    alpha3 = 1, main3 = NULL, palette = c("black", "red", "green",
        "blue"), scale = TRUE, tx = function(y) y, dimToShow = NULL,
    k = NULL, type = "sawm,fw", widths = 1, heights = 1, devices = rgl.cur(),
    col.axes = "gray", axesExpansion = 1.1, annotateWireFrame = FALSE,
    ellipses = list(list(center = rep(0, ncol(x)), x = diag(rep(1,
        ncol(x))), col = "gray", alpha = 0.2)), boxes = list(list(center = rep(0,
        ncol(x)), scale = rep(0, ncol(x)), col = "gray", alpha = 0.2)),
    wfboxes = list(list(center = rep(0, ncol(x)), scale = rep(0,
        ncol(x)), col = "gray", alpha = 0.2)), planes = list(list(a = 1,
        b = 0, c = 0, d = 0, col = "gray", alpha = 0.2)), texts = list(list(center = rep(0,
        ncol(x)), text = "text", col = "gray", alpha = 0.2)),
    debug = FALSE)

Arguments

x

a data frame or matrix to visualize. Instances in rows, features in columns. It must have at least 3 columns (dimensions).
col

the color of individual instances color of individual instances, recycled if necessary
cls

class membership of individual instances. This serves the only purpose of alternative color specification: if 'col' is NULL ...
size

size of points
alpha

alpha of points
main

title of x
x2

another data frame or matrix to visualize.
col2

the color of data in x2
cls2

class membership of data in x2
size2

size of points in x2
alpha2

alpha of points in x2
main2

title of x2
x3

another data frame or matrix to visualize.
col3

the color of data in x3
cls3

class membership of data in x3
size3

size of points in x3
alpha3

alpha of points in x3
main3

title of x3
palette

color palette to be used for individual classes specified in cls, see the col argument
scale

if TRUE, data get scaled to the range of '[-1, 1]' in all dimensions
tx

Transform function used to transform data from the k-dimensional space of x into 3D space to visualize. The function takes a data matrix to transform, and is expected to return a 3-column transformed version of the input data matrix.
dimToShow

a numeric or character vector of dimensions of x to plot. If numeric, it indexes the dimensions to show. If character, it lists the names of dimensions to show. The default it to plot all dimensions. dimToShow takes precedence over k, another way to specify the dimensions to show.
k

if tx is one of txPca or txSpca, k can specify the number of (most "significant") dimensions to plot. The default is the number of dimensions of x, but smaller values are recommended for high-dimensional data in order to speed up plotting. Internally, the k dimensions selected to be shown are those which contribute the most to the top k components (principal or supervised principal components) of the data. To determine this contribution, the code calls the varExplained stored as a name member of a list attached to the tx argument as the params attribute. This function takes k, the number of top components, and returns the contribution of individual dimensions to these components.
type

a character string defining the type of plots to produce. There general syntax is <row>;<row>;...;<row>, where each <row> stands for <plot>,<plot>,...,<plot>, and each plot is a concatenation of one or more plot types to be combined in the specific plot. The plot types are:

  • a - axes of the feature space

  • b - box(es) as defined by the boxes argument

  • B - wire frame Box(es) as defined by the wfboxes argument

  • d - decoration of a 3D plot (axes and a bounding box, see rgl::decorate3d)

  • e - eellipse(s) as defined by the ellipses argument

  • f - 2D scatter plots on the faces of a parallelepipedon

  • m - main (title) of data

  • p - plane(s) as defined by the planes argument

  • s - 3D scatter plot

  • t - text(s) as defined by the texts argument

  • w - wire frame defining the feature space (the wireframe collides with the edges of the parallelepipedon plotted by f)

Each of t, s, and m can be followed by a number referring to a specific data (i.e. x, x2, or x3). By default, when no number follows the plot type, the x is assumed. For example: tawm,sw defines two subscenes to be plotted in one row next to each other. The first plot type tawm defines a three dimensional scatter plot annotated with axes and enriched with a wire frame and the main (title). The second plot type sw defines a parallelepipedon having scatter plots on its faces, and enriched with a wire frame.
widths

relative widths of columns in a multi-subscene scene, see rgl::layout3d
heights

relative heights of rows in a multi-subscene scene, see rgl::layout3d
devices

a list of devices to plot at, defaulting to the current active device, if any. If devices is NULL, empty, contains invalid devices, or does not hold enough devices to plot all the scenes requested by the type argument, new scene(s) will be created for such scenes.
col.axes

color of axes in the 3D plot
axesExpansion
annotateWireFrame

if TRUE, the wire frame produced by type='w' will be annotates by a black point at (-1,-1,...,-1) and numbers 1...k at the extremes of the individual k dimensions.
ellipses

a list or a list of lists defining ellipses to be plotted by the 'e' type. TODO
boxes

a list or a list of lists defining boxes to be plotted by the 'b' type. TODO
wfboxes

a list or a list of lists defining wire frame boxes to be plotted by the 'B' type. TODO
planes

a list or a list of lists defining planes to be plotted by the 'p' type. TODO
texts

a list or a list of lists defining texts to be plotted by the 't' type. TODO
debug

if TRUE, debugs will be printed. If numeric of value greater than 1, verbose debugs will be produced.

Value

a list of rgl device IDs holding the scenes plotted

Examples

  if (interactive() && require(rgl)) {
    # Plot a 3D scatter plot and 2D scatter plots as
    # faces of a parallelepipedon:
    plot3dProj(iris[,1:3], cls=iris$Species)

    # Plot 4D data in a 3D scatter plot on a new device,
    # use PCA to go from 4D to 3D, and add a bounding box and 3D axes
    # decoration (\code{type='d'}) on top of the axes of the 4D space
    # (\code{type='a'}).
    plot3dProj(iris[,1:4], cls=iris$Species, tx=txPca(iris[,1:4]), type='sad', devices=NULL)

    # Plot the iris data set with additional decoration: ellipses
    # representing individual species of the flowers, a box and a text
    # in the center, and a plane.
    iris.setosa<-iris[iris$Species=='setosa',1:3]
    iris.versicolor<-iris[iris$Species=='versicolor',1:3]
    iris.virginica<-iris[iris$Species=='virginica',1:3]
    plot3dProj(iris[,1:3], col=c('red','green','blue')[as.numeric(iris$Species)],
      type='sdpbet', # scatter plot with decoration, a plane, a box,
                     # elippses and a text
      ellipse=list(
        list(cov(iris.setosa),center=colMeans(iris.setosa),col='red',alpha=.1),
        list(cov(iris.versicolor),center=colMeans(iris.versicolor),col='green',alpha=.1),
        list(cov(iris.virginica),center=colMeans(iris.virginica),col='blue',alpha=.1)),
      box=list(center=colMeans(iris[,1:3]),scale=c(.3,.3,.3),col='black',alpha=.2),
      planes=list(0,0,1,-2.5,col='yellow',alpha=.2),
      texts=list(colMeans(iris[,1:3]),text='center',col='black'),
      devices=NULL)

    # Plot two data sets: all Iris flowers (on the left side) and
    # Setosa and Versicolor species only (on the right side).
    # In both cases, produce 2D and 3D spatter plots.
    # For the second data set, alter the size and the alpha value
    # of Setosa flowers. Also, plot small axes under the scatter plots.
    plot3dProj(x = iris[, 1:3], cls = iris$Species,
      main = 'Setosa, Versicolor and Virginica',
      x2 = iris[iris$Species != 'virginica', 1:3],
      cls2 = iris$Species[iris$Species != 'virginica'],
      alpha2 = c(1,.3)[1+(iris$Species[iris$Species != 'virginica']=='setosa')],
      size2 = c(3,10)[1+(iris$Species[iris$Species != 'virginica']=='setosa')],
      main2 = 'Setosa and Versicolor',
      ty='fw,swm,s2m2d,f2;,a',heights=c(2,1),
      devices=NULL) # devices=NULL opens a new 'rgl' device
  }

# TODO: unify/propagate scaling done in plot3dProj here ?!
#  p <- prcomp(iris[, 1:4], center = TRUE, scale = TRUE)
#  tx <- function (y,center=TRUE) {
#    if(center) y<-y-matrix(colMeans(iris[, 1:4]),nrow=nrow(y),ncol=4,byrow=TRUE)
#    y<-t(t(p$rotation[,1:3])%*%t(y))
#    return (y)
#  }
#  plot3dProj(iris[,1:4], tx=tx, cls=iris$Species)