1\HeaderA{scatterplot3d}{3D Scatter Plot}{scatterplot3d}
2\keyword{hplot}{scatterplot3d}
3\begin{Description}\relax
4Plots a three dimensional (3D) point cloud.
5\end{Description}
6\begin{Usage}
7\begin{verbatim}
8scatterplot3d(x, y=NULL, z=NULL, color=par("col"), pch=NULL,
9    main=NULL, sub=NULL, xlim=NULL, ylim=NULL, zlim=NULL,
10    xlab=NULL, ylab=NULL, zlab=NULL, scale.y=1, angle=40,
11    axis=TRUE, tick.marks=TRUE, label.tick.marks=TRUE,
12    x.ticklabs=NULL, y.ticklabs=NULL, z.ticklabs=NULL,
13    y.margin.add=0, grid=TRUE, box=TRUE, lab=par("lab"),
14    lab.z=mean(lab[1:2]), type=par("type"), highlight.3d=FALSE,
15    mar=c(5,3,4,3)+0.1, col.axis=par("col.axis"),
16    col.grid="grey", col.lab=par("col.lab"),
17    cex.symbols=par("cex"), cex.axis=par("cex.axis"),
18    cex.lab=0.8 * par("cex.lab"), font.axis=par("font.axis"),
19    font.lab=par("font.lab"), lty.axis=par("lty"),
20    lty.grid=par("lty"), lty.hide=NULL, log="", ...)
21\end{verbatim}
22\end{Usage}
23\begin{Arguments}
24\begin{ldescription}
25\item[\code{x}] the coordinates of points in the plot.
26\item[\code{y}] the y coordinates of points in the plot, optional if \code{x} is an appropriate structure.
27\item[\code{z}] the z coordinates of points in the plot, optional if \code{x} is an appropriate structure.
28\item[\code{color}] colors of points in the plot, optional if \code{x} is an appropriate structure.
29Will be ignored if \code{highlight.3d = TRUE}.
30\item[\code{pch}] plotting "character", i.e. symbol to use.
31\item[\code{main}] an overall title for the plot.
32\item[\code{sub}] sub-title.
33\item[\code{xlim, ylim, zlim}] the x, y and z limits (min, max) of the plot. Note that setting enlarged limits
34may not work as exactly as expected (a known but unfixed bug).
35\item[\code{xlab, ylab, zlab}] titles for the x, y and z axis.
36\item[\code{scale.y}] scale of y axis related to x- and z axis.
37\item[\code{angle}] angle between x and y axis (Attention: result depends on
38scaling.  For 180 < angle < 360  the returned functions
39\code{xyz.convert} and \code{points3d} will not work properly.).
40\item[\code{axis}] a logical value indicating whether axes should be drawn on the plot.
41\item[\code{tick.marks}] a logical value indicating whether tick marks should
42be drawn on the plot (only if \code{axis = TRUE}).
43\item[\code{label.tick.marks}] a logical value indicating whether tick marks should be labeled on the plot
44(only if \code{axis = TRUE} and \code{tick.marks = TRUE}).
45\item[\code{x.ticklabs, y.ticklabs, z.ticklabs}] vector of tick mark labels.
46\item[\code{y.margin.add}] add additional space between tick mark labels and
47axis label of the y axis
48\item[\code{grid}] a logical value indicating whether a grid should be drawn on the plot.
49\item[\code{box}] a logical value indicating whether a box should be drawn around the plot.
50\item[\code{lab}] a numerical vector of the form c(x, y, len).  The values of
51x and y give the (approximate) number of tickmarks on the x and y axes.
52\item[\code{lab.z}] the same as \code{lab}, but for z axis.
53\item[\code{type}] character indicating the type of plot: "p" for points, "l"
54for lines, "h" for vertical lines to x-y-plane, etc.
55\item[\code{highlight.3d}] points will be drawn in different colors related to y coordinates
56(only if \code{type = "p"} or \code{type = "h"}, else \code{color} will be used).\\
57On some devices not all colors can be displayed. In this case try the
58postscript device or use \code{highlight.3d = FALSE}.
59\item[\code{mar}] A numerical vector of the form c(bottom, left, top, right)
60which gives the lines of margin to be specified on the four sides of the plot.
61\item[\code{col.axis, col.grid, col.lab}] the color to be used for axis / grid / axis labels.
62\item[\code{cex.symbols, cex.axis, cex.lab}] the magnification to be used for
63point symbols, axis annotation, labels relative to the current.
64\item[\code{font.axis, font.lab}] the font to be used for axis annotation / labels.
65\item[\code{lty.axis, lty.grid}] the line type to be used for axis / grid.
66\item[\code{lty.hide}] line style used to plot \sQuote{non-visible} edges (defaults of the \code{lty.axis} style)
67\item[\code{log}] Not yet implemented!  A character string which contains "x"
68(if the x axis is to be logarithmic), "y", "z", "xy", "xz", "yz", "xyz".
69\item[\code{...}] more graphical parameters can be given as arguments,
70\code{pch = 16} or \code{pch = 20} may be nice.
71\end{ldescription}
72\end{Arguments}
73\begin{Value}
74\begin{ldescription}
75\item[\code{xyz.convert}] function which converts coordinates from 3D (x, y, z)
76to 2D-projection (x, y) of \code{scatterplot3d}.
77Useful to plot objects into existing plot.
78\item[\code{points3d}] function which draws points or lines into the existing plot.
79\item[\code{plane3d}] function which draws a plane into the existing plot:
80\code{plane3d(Intercept, x.coef = NULL, y.coef = NULL, lty =
81      "dashed", lty.box = NULL, ...)}.
82Instead of \code{Intercept} a vector containing 3
83elements or an (g)lm object can be specified.
84The argument \code{lty.box} allows to set a different line style for the
85intersecting lines in the box's walls.
86\item[\code{box3d}] function which "refreshes" the box surrounding the plot.
87\end{ldescription}
88\end{Value}
89\begin{Note}\relax
90Some graphical parameters should only be set as arguments in
91\code{scatterplot3d} but not in a previous \code{\LinkA{par}{par}()} call.  One of these is
92\code{mar}, which is also non-standard in another way: Users who
93want to extend an existing \code{scatterplot3d} graphic with another function than
94\code{points3d}, \code{plane3d} or \code{box3d}, should consider to
95set \code{par(mar = c(b, l, t, r))} to the value of \code{mar} used in
96\code{scatterplot3d}, which defaults to \code{c(5, 3, 4, 3) + 0.1}.
97
98Other \code{par} arguments may be split into several arguments in
99\code{scatterplot3d}, e.g., for specifying the line type.  And finally
100some of \code{par} arguments do not apply here, e.g., many of those
101for axis calculation.  So we recommend to try the specification of
102graphical parameters at first as arguments in \code{scatterplot3d} and
103only if needed as arguments in previous \code{par()} call.
104\end{Note}
105\begin{Author}\relax
106Uwe Ligges \email{ligges@statistik.tu-dortmund.de};
107\url{http://www.statistik.tu-dortmund.de/~ligges}.
108\end{Author}
109\begin{References}\relax
110Ligges, U., and Maechler, M. (2003):
111Scatterplot3d -- an R Package for Visualizing Multivariate Data.
112\emph{Journal of Statistical Software} 8(11), 1--20.
113\url{http://www.jstatsoft.org/}
114\end{References}
115\begin{SeeAlso}\relax
116\code{\LinkA{persp}{persp}}, \code{\LinkA{plot}{plot}}, \code{\LinkA{par}{par}}.
117\end{SeeAlso}
118\begin{Examples}
119\begin{ExampleCode}
120  ## On some devices not all colors can be displayed.
121  ## Try the postscript device or use highlight.3d = FALSE.
122  ## example 1
123  z <- seq(-10, 10, 0.01)
124  x <- cos(z)
125  y <- sin(z)
126  scatterplot3d(x, y, z, highlight.3d=TRUE, col.axis="blue",
127      col.grid="lightblue", main="scatterplot3d - 1", pch=20)
128
129  ## example 2
130  temp <- seq(-pi, 0, length = 50)
131  x <- c(rep(1, 50) %*% t(cos(temp)))
132  y <- c(cos(temp) %*% t(sin(temp)))
133  z <- c(sin(temp) %*% t(sin(temp)))
134  scatterplot3d(x, y, z, highlight.3d=TRUE,
135      col.axis="blue", col.grid="lightblue",
136      main="scatterplot3d - 2", pch=20)
137
138  ## example 3
139  temp <- seq(-pi, 0, length = 50)
140  x <- c(rep(1, 50) %*% t(cos(temp)))
141  y <- c(cos(temp) %*% t(sin(temp)))
142  z <- 10 * c(sin(temp) %*% t(sin(temp)))
143  color <- rep("green", length(x))
144  temp <- seq(-10, 10, 0.01)
145  x <- c(x, cos(temp))
146  y <- c(y, sin(temp))
147  z <- c(z, temp)
148  color <- c(color, rep("red", length(temp)))
149  scatterplot3d(x, y, z, color, pch=20, zlim=c(-2, 10),
150      main="scatterplot3d - 3")
151
152  ## example 4
153  my.mat <- matrix(runif(25), nrow=5)
154  dimnames(my.mat) <- list(LETTERS[1:5], letters[11:15])
155  my.mat # the matrix we want to plot ...
156
157  s3d.dat <- data.frame(cols=as.vector(col(my.mat)),
158      rows=as.vector(row(my.mat)),
159      value=as.vector(my.mat))
160  scatterplot3d(s3d.dat, type="h", lwd=5, pch=" ",
161      x.ticklabs=colnames(my.mat), y.ticklabs=rownames(my.mat),
162      color=grey(25:1/40), main="scatterplot3d - 4")
163
164  ## example 5
165  data(trees)
166  s3d <- scatterplot3d(trees, type="h", highlight.3d=TRUE,
167      angle=55, scale.y=0.7, pch=16, main="scatterplot3d - 5")
168  # Now adding some points to the "scatterplot3d"
169  s3d$points3d(seq(10,20,2), seq(85,60,-5), seq(60,10,-10),
170      col="blue", type="h", pch=16)
171  # Now adding a regression plane to the "scatterplot3d"
172  attach(trees)
173  my.lm <- lm(Volume ~ Girth + Height)
174  s3d$plane3d(my.lm, lty.box = "solid")
175
176  ## example 6; by Martin Maechler
177  cubedraw <- function(res3d, min = 0, max = 255, cex = 2,
178    text. = FALSE)
179  {
180    ## Purpose: Draw nice cube with corners
181    cube01 <- rbind(c(0,0,1), 0, c(1,0,0),
182                    c(1,1,0), 1, c(0,1,1), # < 6 outer
183                    c(1,0,1), c(0,1,0))
184                        # <- "inner": fore- & back-ground
185    cub <- min + (max-min)* cube01
186    ## visibile corners + lines:
187    res3d$points3d(cub[c(1:6,1,7,3,7,5) ,],
188        cex = cex, type = 'b', lty = 1)
189    ## hidden corner + lines
190    res3d$points3d(cub[c(2,8,4,8,6),     ],
191        cex = cex, type = 'b', lty = 3)
192    if(text.)## debug
193        text(res3d$xyz.convert(cub), labels=1:nrow(cub),
194            col='tomato', cex=2)
195  }
196  ## 6 a) The named colors in R, i.e. colors()
197  cc <- colors()
198  crgb <- t(col2rgb(cc))
199  par(xpd = TRUE)
200  rr <- scatterplot3d(crgb, color = cc, box = FALSE, angle = 24,
201      xlim = c(-50, 300), ylim = c(-50, 300), zlim = c(-50, 300))
202  cubedraw(rr)
203  ## 6 b) The rainbow colors from rainbow(201)
204  rbc <- rainbow(201)
205  Rrb <- t(col2rgb(rbc))
206  rR <- scatterplot3d(Rrb, color = rbc, box = FALSE, angle = 24,
207      xlim = c(-50, 300), ylim = c(-50, 300), zlim = c(-50, 300))
208  cubedraw(rR)
209  rR$points3d(Rrb, col = rbc, pch = 16)
210\end{ExampleCode}
211\end{Examples}
212
213