# Plotting tracer distributions in 3D `tracers3D` plots 3D tracer distributions in traditional graphics. The topography can be defined when calling this function or created before calling this function. `tracers3Drgl` plots 3D tracer distributions in open-GL graphics. A suitable topography has to be created before calling this function. It does not create a movie. `moviepoints3D` creates a movie of tracer distributions in open-GL graphics. It is based on the `plot3Drgl` function points3Drgl . ```r tracers3D (x, y, z, colvar = NULL, ..., col = NULL, NAcol = "white", breaks = NULL, colkey = FALSE, clim = NULL, clab = NULL, surf = NULL) tracers3Drgl (x, y, z, colvar = NULL, ..., col = NULL, NAcol = "white", breaks = NULL, colkey = FALSE, clim = NULL, clab = NULL) moviepoints3D (x, y, z, colvar, t, by = 1, col = jet.col(100), NAcol = "white", breaks = NULL, clim = NULL, wait = NULL, ask = FALSE, add = FALSE, basename = NULL, ...) ``` ## Arguments - `x, y, z`: Vectors with (x, y, z) positions of tracers. Should be of equal length. - `colvar`: The variable used for coloring. It need not be present, but if specified, it should be a vector of dimension equal to `x, y, z`. Values of `NULL`, `NA`, or `FALSE` will toggle off coloration according to `colvar`. - `t`: Vectors with time points of tracers. Should be of length equal to length of `x, y ,z, colvar`. - `by`: Number increment of the time sequence. - `col`: Colors to be used for coloring each individual point (if colvar not specified) or that define the colors as specified by the `colvar` variable. If `col` is `NULL` and `colvar` is specified, then a red-yellow-blue colorscheme (`jet.col`) will be used. If `col` is `NULL` and `colvar` is not specified, then `col` will be "black". - `NAcol`: Colors to be used for `colvar` values that are `NA`. - `breaks`: a set of finite numeric breakpoints for the colors; must have one more breakpoint than color and be in increasing order. Unsorted vectors will be sorted, with a warning. - `colkey`: A logical, `NULL` (default), or a `list` with parameters for the color key (legend). List parameters should be one of `side, plot, length, width, dist, shift, addlines, col.clab, cex.clab,side.clab, line.clab, adj.clab, font.clab` and the axis parameters `at, labels, tick, line, pos, outer, font, lty, lwd, lwd.ticks, col.box,col.axis, col.ticks, hadj, padj, cex.axis, mgp, tck, tcl, las`. The defaults for the parameters are `side = 4, plot = TRUE, length = 1, width = 1, dist = 0, shift = 0,addlines = FALSE, col.clab = NULL, cex.clab = par("cex.lab"), side.clab= NULL, line.clab = NULL, adj.clab = NULL, font.clab = NULL`) See colkey from package `plot3D`. The default is to draw the color key on side = 4, i.e. in the right margin. If `colkey` = `NULL` then a color key will be added only if `col` is a vector. Setting `colkey = list(plot = FALSE)` will create room for the color key without drawing it. if `colkey = FALSE`, no color key legend will be added. - `clim`: Only if `colvar` is specified, the range of the colors, used for the color key. - `clab`: Only if `colkey` is not `NULL` or `FALSE`, the label to be written on top of the color key. The label will be written at the same level as the main title. To lower it, `clab` can be made a vector, with the first values empty strings. - `surf`: If not `NULL`, a list specifying a surface to be added on the scatterplot. They should include at least `x`, `y`, `z`, equal sized matrices, and optional: `colvar, col, NAcol, border, facets, lwd, resfac, clim, ltheta, lphi,shade, lighting`. Note that the default is that `colvar` is not specified. - `add`: Logical. If `TRUE`, then the points will be added to the current plot. If `FALSE` a new plot is started. - `ask`: Logical. If `TRUE`, then new points will only be drawn after a key has been struck. If `FALSE`, redrawing will depend on `wait` - `wait`: The time interval inbetween drawing of a set of new points, in seconds. If `NULL`, the drawing will not be suspended. - `basename`: The base name of a `png` file to be produced for each movieframe. - ``...``: additional arguments passed to scatter3D from package `plot3D`. Typical arguments are `cex, main` (both functions), and `pch, ...` for `tracers3D`. ## Returns returns nothing ## Author(s) Karline Soetaert ## See Also tracers2D for plotting time series of tracer distributions in 2D movieslice3D for plotting slices in 3D Ltrans for 3-D output of a particle tracking model ## Examples ```r # save plotting parameters pm <- par("mfrow") ## ======================================================================= ## Create topography, data ## ======================================================================= # The topographic surface x <- seq(-pi, pi, by = 0.2) y <- seq(0, pi, by = 0.1) M <- mesh(x, y) z <- with(M, sin(x)*sin(y)) # Initial condition xi <- c(0.25 * rnorm(100) - pi/2, 0.25 * rnorm(100) - pi/4) yi <- 0.25 * rnorm(200) + pi/2 zi <- 0.005*rnorm(200) + 0.5 # the species species <- c(rep(1, 100), rep(2, 100)) # set initial conditions xp <- xi; yp <- yi; zp <- zi ## ======================================================================= ## Traditional graphics ## ======================================================================= par(mfrow = c(2, 2)) # Topography is defined by argument surf for (i in 1:4) { # update tracer distribution xp <- xp + 0.25 * rnorm(200) yp <- yp + 0.025 * rnorm(200) zp <- zp + 0.25 *rnorm(200) # plot new tracer distribution tracers3D(xp, yp, zp, colvar = species, pch = ".", cex = 5, main = paste("timestep ", i), col = c("orange", "blue"), surf = list(x, y, z = z, theta = 0, facets = FALSE), colkey = list(side = 1, length = 0.5, labels = c("sp1","sp2"), at = c(1.25, 1.75), dist = 0.075)) } # same, but creating topography first ## Not run: # create the topography on which to add points persp3D(x, y, z = z, theta = 0, facets = FALSE, plot = FALSE) for (i in 1:4) { # update tracer distribution xp <- xp + 0.25 * rnorm(200) yp <- yp + 0.025 * rnorm(200) zp <- zp + 0.25 *rnorm(200) # plot new tracer distribution tracers3D(xp, yp, zp, colvar = species, pch = ".", cex = 5, main = paste("timestep ", i), col = c("orange", "blue"), colkey = list(side = 1, length = 0.5, labels = c("sp1","sp2"), at = c(1.25, 1.75), dist = 0.075)) } ## End(Not run) ## ======================================================================= ## rgl graphics ## ======================================================================= # pause <- 0.05 # create a suitable topography persp3D(x, y, z = z, theta = 0, facets = NA, plot = FALSE) plotrgl( ) xp <- xi; yp <- yi; zp <- zi nstep <- 10 for (i in 1:nstep) { xp <- xp + 0.05 * rnorm(200) + 0.05 yp <- yp + 0.0025 * (rnorm(200) + 0.0025) zp <- zp + 0.05 *rnorm(200) # tracers3Drgl(xp, yp, zp, col = c(rep("orange", 100), rep("blue", 100)), # main = paste("timestep ", i)) # or: tracers3Drgl(xp, yp, zp, colvar = species, col = c("orange", "blue"), main = paste("timestep ", i)) # Sys.sleep(pause) # or: readline("hit enter for next") } # using function moviepoints3D ## Not run: # first create the data in matrices xp <- matrix(nrow = 200, ncol = nstep, data = rep(xi, times=nstep)) yp <- matrix(nrow = 200, ncol = nstep, data = rep(yi, times=nstep)) zp <- matrix(nrow = 200, ncol = nstep, data = rep(zi, times=nstep)) tp <- matrix(nrow = 200, ncol = nstep, data = 0) cv <- matrix(nrow = 200, ncol = nstep, data = rep(species, times=nstep)) nstep <- 10 for (i in 2:nstep) { xp[,i] <- xp[,i-1] + 0.05 * rnorm(200) + 0.05 yp[,i] <- yp[,i-1] + 0.0025 * (rnorm(200) + 0.0025) zp[,i] <- zp[,i-1] + 0.05 *rnorm(200) tp[,i] <- i } # create the topography persp3Drgl(x, y, z = z, theta = 0, lighting = TRUE, smooth = TRUE) # add moviepoints: moviepoints3D (xp, yp, zp, colvar = cv, t = tp, wait = 0.05, cex = 10, col = c("red", "orange")) ## End(Not run) # reset plotting parameters par(mfrow = pm) ```

tracers3D function