Tracers in 3D {OceanView}

Plotting tracer distributions in 3D

Description

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.

Usage

  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.

Value

returns nothing

Author(s)

Karline Soetaert <[e-mail]>

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

# 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)