# Plots velocities as arrows or as trajectory plots. Function `quiver2D` displays velocity vectors as arrows, using ordinary graphics. Function `quiver2Drgl` displays velocity vectors as arrows using rgl. Function `flowpath` displays the flow paths of particles, based on velocity vectors. ```r quiver2D(u, ...) ## S3 method for class 'matrix' quiver2D(u, v, x = NULL, y = NULL, colvar = NULL, ..., scale = 1, arr.max = 0.2, arr.min = 0, speed.max = NULL, by = NULL, type = "triangle", col = NULL, NAcol = "white", breaks = NULL, colkey = NULL, mask = NULL, image = FALSE, contour = FALSE, clim = NULL, clab = NULL, add = FALSE, plot = TRUE) ## S3 method for class 'array' quiver2D(u, v, margin = c(1, 2), subset, ask = NULL, ...) quiver2Drgl (u, v, x = NULL, y = NULL, colvar = NULL, ..., scale = 1, arr.max = 0.2, arr.min = 0, speed.max = NULL, by = NULL, type = "triangle", col = NULL, NAcol = "white", breaks = NULL, mask = NULL, image = FALSE, contour = FALSE, colkey = NULL, clim = NULL, clab = NULL, add = FALSE, plot = TRUE) flowpath(u, v, x = NULL, y = NULL, startx = NULL, starty = NULL, ..., scale = 1, numarr = 0, arr.length = 0.2, maxstep = 1000, add = FALSE, plot = TRUE) ``` ## Arguments - `u`: A matrix (`quiver2D`) or array (`quiver2D.array`) with velocities in x-direction. For `quiver2D` the number of rows should be = Nx or Nx+1 (Nx = length(x), if x given), the number of columns should be = Ny or Ny+1 (Ny = length(y), if y given). - `v`: A matrix (`quiver2D`) or array (`quiver2D.array`) with velocities in y-direction. For `quiver2D` the number of rows should be = Nx or Nx+1, the number of columns should be = Ny or Ny+1. - `x`: Vector with x-coordinates of the velocities. If `NULL`, it is taken to be a sequence between (0, 1), and with length = `nrow(u)`. - `y`: Vector with y-coordinates of the velocities. If `NULL`, it is taken to be a sequence between (0, 1), and with length = `ncol(v)`. - `startx`: Vector with the start position in x-direction of the flow paths. Length > =1. If not specified, then all combinations of `x` and `y` at the outer margins will be used as starting point. - `starty`: Vector with start position in y-direction of flow paths. Length = length of `startx`. - `colvar`: The variable used for coloring. It need not be present, but if specified, it should be a vector of dimension equal to `c(nrow(u), ncol(v))`. Values of `NULL`, `NA`, or `FALSE` will toggle off coloration according to `colvar`. - `col`: Colors to be used for coloring the arrows 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. - `scale`: Scaling factor for the arrows. When `scale = 1`, the longest arrow will fill a grid cell in x- and y- direction. When `scale = 2`, it will be twice as long. - `arr.max`: Maximal size of the arrowhead, in cm (approximately). The arrows are scaled according to the velocity (`sqrt(u^2 + v^2)`). `arr.max` is associated with the maximal velocity. - `arr.min`: Minimal size of the arrowhead, in cm (approximately). Set `arr.min` = `arr.max` for constant size. - `speed.max`: Speed that corresponds to `arr.max`. Everything with speed larger than `speed.max` will be depicted with size equal to `arr.max`. If unspecified (`max(sqrt(u^2 + v^2))`). - `by`: Number increment for plotting the vectors; one value or two (x, y) values. For example, setting `by = 2` will plot every second velocity value in `x` and in `y` direction. Setting `by = c(1, 2)` will plot all vectors in `x` and every second vector in `y`. Useful if the vector density is too high. - `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. - `type`: The type of the arrow head, one of `"triangle"` (the default) or `"simple"`, which uses R-function arrows . - `contour, image`: If present, then a contour2D or image2D plot will be added to the quiver plot. They should be 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. - `margin`: A vector giving the subscripts which the plotting function will be applied over. The plotting function will loop over the index that is not in `margin`. For instance, `c(1, 2)`, indicates to plot rows(x) and columns(y) and to loop over index `3`; `c(2, 1)` will do the same but transposed. `margin` should be a vector with two numbers inbetween `1`, and `3`. - `ask`: A logical; if `TRUE`, the user is asked before each plot, if `NULL` the user is only asked if more than one page of plots is necessary and the current graphics device is set interactive, see par (ask) and dev.interactive . - `add`: If `TRUE`, will add to current plot. Else will start a new plot. Note: to use this in a consistent way, the previous plot should have been done with one of the `plot3D` functions. - `mask`: A `matrix` or `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"`. If `x` and `y` are a vector, then `mask` can be a `matrix` with dimension equal to `length(x), length(y)`. If either `x` or `y` is itself a `matrix`, then `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`. - `plot`: If `FALSE`, will not plot the flow paths, but will return the matrix with path values instead. - `numarr`: The number of arrows added on the flow paths. - `arr.length`: Constant size of the arrowhead, in cm (approximately). - `maxstep`: Maximum number of steps for calculating the flow paths. - ``...``: Additional arguments passed to the plotting methods (arrows2D ), The arguments after `...` must be matched exactly. - `subset`: A logical expression indicating over which elements to loop; missing values are taken as `FALSE`. ## Details S3 function `quiver2D` plots vectors specified by `u, v` at the coordinates `x, y`. `flowpath` uses the velocities `u, v` at the coordinates `x, y` to create trajectories, starting at points `startx, starty`. It can also be used to return the flow path points by setting `plot` equal to `FALSE`. It uses very simple Euler integration and may not be very accurate. ## Returns `flowpath` returns (as `invisible`) a 2-column matrix with the x-y coordinates of the flow paths. Separate flow paths are separated with `NA`. `quiver2D` returns (as `invisible`) a `list` containing the coordinates of the arrows (`x0`, `x1`, `y0`, `y1`), the color of each arrow (`col`), the length of the arrowhead (`length`) and the maximal speed corresponding to `arr.max` (`speed.max`). This output can be used e.g. with function arrows . ## See Also arrows3D for an arrows function from package `plot3D`. vectorplot for plotting velocity vectors as spikes. Arrows for the arrow function from package `shape` on which quiver2D is based. ## Examples ```r ## ======================================================================= ## EXAMPLE 1: ## ======================================================================= pm <- par("mfrow") par(mfrow = c(2, 2)) # generate velocities x <- seq(-1, 1, by = 0.2) y <- seq(-1, 1, by = 0.2) dx <- outer(x, y , function(x, y) -y) dy <- outer(x, y , function(x, y) x) # velocity plot, with legend F <- quiver2D(u = dx, v = dy, x = x, y = y) legend("topright", bg = "white", legend = paste("max = ", format(F$speed.max, digits = 2))) # different color for up/downward pointing arrows quiver2D(u = dx, v = dy, x = x, y = y, colvar = dx > 0, col = c("red", "blue"), colkey = FALSE, arr.max = 0.4, arr.min = 0.1) # different scale quiver2D(u = dx, v = dy, x = x, y = y, by = 2, scale = 2) # three flow paths flowpath(u = dx, v = dy, x = x, y = y, startx = 0.1, starty = 0.1) flowpath(u = dx, v = dy, x = x, y = y, startx = c(0.9, -0.9), starty = c(0.0, 0.0), col = "red", numarr = 2, add = TRUE) ## ======================================================================= ## EXAMPLE 2: note: has changed in version 1.0.3 - uses contour2D! ## ======================================================================= par(mfrow = c(1, 1)) x <- seq(-2, 2, by = 0.2) y <- seq(-1, 1, by = 0.2) z <- outer (x, y, function(x, y) x^3 - 3*x -2*y^2) contour2D(x, y, z = z, col = jet.col(10)) # gradients in x- and y-direction (analytical) dX <- outer(x, y, function(x,y) 3*x^2 - 3) dY <- outer(x, y, function(x,y) -4*y) quiver2D(u = dX, v = dY, x = x, y = y, scale = 1, add = TRUE, by = 1) flowpath(u = dX, v = dY, x = x, y = y, startx = c(-2, 1.1), starty = c(-1, -1), add = TRUE, arr.length = 0.5, col = "darkgreen", lwd = 3, numarr = 1) ## ======================================================================= ## EXAMPLE 3: ## ======================================================================= x <- y <- 1:20 u <- outer (x, y, function (x, y) cos(2*pi*y/10)) v <- outer (x, y, function (x, y) cos(2*pi*x/10)) quiver2D(x = x, y = y, u = u, v = v, col = "grey") # flowpaths using all combinations of x and y at edges flowpath(x = x, y = y, u = u, v = v, add = TRUE, lwd = 2, col = "orange") ## ======================================================================= ## EXAMPLE 4: quiver of an array.. ## ======================================================================= x <- y <- 1:20 u2 <- outer (x, y, function (x, y) sin(2*pi*y/10)) v2 <- outer (x, y, function (x, y) sin(2*pi*x/10)) # merge u, u2 and v, v2 to create an "array" U <- array(dim = c(dim(u2), 2), data = c(u, u2)) V <- array(dim = c(dim(v2), 2), data = c(v, v2)) quiver2D(u = U, v = V, x = x, y = y, main = c("time 1", "time 2")) # quiver over x and time, for a subset of y-values: quiver2D(u = U, v = V, x = x, y = 1:2, margin = c(1, 3), main = paste("y ", y), subset = y <= 4) ## Not run: quiver2D(u = U, v = V, x = x, y = y, ask = TRUE, mfrow = c(1, 1)) quiver2D(u = U, v = V, x = x, y = 1:2, ask = TRUE, margin = c(1, 3), main = paste("y ", y), mfrow = c(1, 1)) ## End(Not run) ## ======================================================================= ## EXAMPLE 5: ## ======================================================================= par(mfrow = c(1, 1)) image2D(x = 1:nrow(volcano), y = 1:ncol(volcano), z = volcano, contour = TRUE) # Assume these are streamfunctions, we calculate the velocity field as: dx <- dy <- 1 v <- (volcano[-1, ] - volcano[-nrow(volcano), ] )/dx u <- - (volcano[, -1] - volcano[ ,-ncol(volcano)] )/dy quiver2D(x = 1:nrow(u), y = 1:ncol(v), u = u, v = v, add = TRUE, by = 3) flowpath(x = 1:nrow(u), y = 1:ncol(v), numarr = 10, u = u, v = v, add = TRUE, lwd = 2, col = "grey", startx = 20, starty = 30) ## ======================================================================= ## EXAMPLE 6: boundary mask, images, contours ## ======================================================================= par (mfrow = c(2, 2)) mask <- volcano; mask[volcano < 120] <- NA quiver2D(by = c(3, 2), u = u, v = v, mask = mask) quiver2D(by = c(3, 2), u = u, v = v, image = list(z = mask, NAcol = "black")) quiver2D(by = c(4, 3), u = u, v = v, contour = list(z = volcano, lwd = 2)) quiver2D(by = c(4, 3), u = u, v = v, contour = list(z = volcano, col = "black"), image = list(z = volcano, NAcol = "black")) ## ======================================================================= ## Same in rgl ## ======================================================================= ## Not run: quiver2Drgl(by = c(3, 2), u = u, v = v, mask = mask, NAcol = "black") quiver2Drgl(by = c(3, 2), u = u, v = v, image = list(z = volcano, NAcol = "black")) quiver2Drgl(by = c(4, 3), u = u, v = v, scale = 2, contour = list(z = volcano, lwd = 2)) quiver2Drgl(by = c(4, 3), u = u, v = v, contour = list(z = volcano, col = "black"), image = list(z = volcano, NAcol = "black")) cutrgl() uncutrgl() ## End(Not run) ## ============================================================================= ## 2-D Data set SyltSurf ## ============================================================================= par(mfrow = c(1, 1)) with (Syltsurf, quiver2D(x = x, y = y, u = u[ , ,2], v = v[ , ,2], xlim = c(5, 20), ylim = c(10, 25), by = 3, main = paste(formatC(time[1]), " hr"), scale = 1.5, image = list(z = depth, x = x, y = y, NAcol = "black", colkey = TRUE), contour = list(z = depth, x = x, y = y, col = "black", drawlabels = FALSE) ) ) ## ============================================================================= ## 2-D Data set SyltSurf, several time points ## ============================================================================= # now for an array (first and 4th time point only) ii <- c(1, 4) with (Syltsurf, quiver2D(x = x, y = y, u = u[ ,,ii], v = v[ ,,ii], xlim = c(5, 20), ylim = c(10, 25), by = 4, mask = list(z = depth, x = x, y = y, NAcol = "blue"), main = paste(formatC(time[ii]), " hr"), scale = 1.5, contour = list(z = depth, x = x, y = y, drawlabels = FALSE) ) ) ## ============================================================================= ## Adding quivers ... ## ============================================================================= x <- 1:2 y <- 1:3 u <- matrix(data = 1:6, nrow = 2, ncol = 3) v <- matrix(data = 6:1, nrow = 2, ncol = 3) par(mfrow = c(1, 1)) A <- quiver2D(x = x, y = y, u = u, v = v) B <- quiver2D(x = x, y = y[-1], u = u[,-1], v = v[,-1], col = 2, add = TRUE) C <- quiver2D(x = x, y = y[-3], u = u[,-3], v = v[,-3], col = 3, add = TRUE) # restore parameter settings par(mfrow = pm) ``` ## Note There was a slight error in the scaling of the arrows in versions previous to 1.0.3, which has been corrected. See last example.

quiver function