Tracers in 2D {OceanView}

Plots tracer distributions in 2-D.

Description

tracers2D plots a tracer distribution using traditional R graphics. The topography can be defined when calling this function.

tracers2Drgl plots a tracer distribution in open-GL graphics. A suitable topography has to be created before calling this function.

Usage

tracers2D(x, y, colvar = NULL, ..., 
          col = NULL, NAcol = "white", colkey = NULL, 
          mask = NULL, image = FALSE, contour = FALSE, 
          clim = NULL, clab = NULL) 

tracers2Drgl(x, y, colvar = NULL, ...,
          col = NULL, NAcol = "white", breaks = NULL,
          colkey = FALSE, clim = NULL, clab = NULL) 

Arguments

x, y

Vectors with x- and y-coordinates of the 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. Values of NULL, NA, or FALSE will toggle off coloration according to colvar.

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.

contour, image

If TRUE, then a contour2D or image2D plot will be added to the quiver plot. Also allowed is to pass a list with arguments for the contour2D or image2D function.

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.

mask

A list defining the grid cells outside the domain as NA. Use a list with argument NAcol to specify the color that the masked cells (that are NA) should get; the default is "black". The unmasked cells are left "white".

mask should be a list that contains the x, y, and z values (and that are named 'x', 'y', 'z'). A mask cannot be combined with add = TRUE.

...

additional arguments passed to the plotting method scatter2D. The arguments after ... must be matched exactly.

Value

returns nothing

Author(s)

Karline Soetaert <[e-mail]>

See Also

tracers3D for plotting time series of tracer distributions in 3D

Ltrans for the 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.125 * rnorm(100) - pi/2, 0.125 * rnorm(100) - pi/4)
 yi <- 0.25 * rnorm(200) + pi/2

# the species
 species <- c(rep(1, 100), rep(2, 100))   

# set initial conditions 
 xp <- xi; yp <- yi

## =======================================================================
## using a mask and contour
## =======================================================================

 Z <- z; Z[abs(Z) < 0.1] <- NA
 par(mfrow = c(2, 2))

 for (i in 1:4) {
  # update tracer distribution
   xp <- xp + 0.25 * rnorm(200)
   yp <- yp + 0.025 * rnorm(200) 
  
  # plot new tracer distribution
   tracers2D(xp, yp, 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), NAcol = "black", 
     mask = list(x = x, y = y, z = Z), 
     contour = list(x = x, y = y, z = Z) )
 }

## =======================================================================
## using image and contour
## =======================================================================

 for (i in 1:4) {
  # update tracer distribution
   xp <- xp + 0.25 * rnorm(200)
   yp <- yp + 0.025 * rnorm(200) 
  
  # plot new tracer distribution
   tracers2D(xp, yp, 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), NAcol = "black", 
     contour = list(x = x, y = y, z = z),
     image = list(x = x, y = y, z = z, colkey = TRUE))
 }

## =======================================================================
## rgl tracer plot
## =======================================================================

# here the image has to be drawn first
 image2Drgl(x = x, y = y, z = z)

# set initial conditions 
 xp <- xi; yp <- yi
 nstep <- 40
 for (i in 1:nstep) {
  # update tracer distribution
   xp <- xp + 0.25 * rnorm(200)
   yp <- yp + 0.025 * rnorm(200) 
  
  # plot new tracer distribution                                                              n
   tracers2Drgl(xp, yp, colvar = species,  cex = 1,
     main = paste("timestep ", i), col = c("orange", "blue"))

 }

# reset plotting parameters
 par(mfrow = pm)