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