R: Plotting tracer distributions in 3D

Tracers in 3D {OceanView} | R Documentation

## 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 <karline.soetaert@nioz.nl>

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

[Package OceanView version 1.0.6 Index]