sl.plot.vectors: Plot Vectors

In FESOM/spheRlab: Spherical Geometry, Analysis, and Plotting of Geoscientific Data on Arbitrary Grids

Plot Vectors

Description

Plot vectors into a spheRlab plot.

Usage

sl.plot.vectors(pir, lon, lat, u, v, ref=median(sqrt(u^2+v^2)), ref.length.degrees=1, length.by.length=TRUE, lwd.by.length=FALSE, col.by.length=FALSE, col="black", colbar=sl.colbar(cols=c("blue","red"),N=256), colbar.breaks=NA, colbar.breaks.log=FALSE, lwd.ref=1, lty=1, head.line=TRUE, head.fill=FALSE, head.fill.line=TRUE, head.size=1/3, head.width=1, ref.args=NULL, ignore.visibility=FALSE)

Arguments

plot.init.res	a spheRlab plot specifics list as returned by sl.plot.init (or a variant thereof).
lon	a scalar, vector, matrix, or array specifying the longitudes of the points at which the vectors are centered.
lat	a scalar, vector, matrix, or array (same dimensions as lon) specifying the latitudes of the points at which the vectors are centered.
u	a scalar, vector, matrix, or array (same dimensions as lon) specifying the zonal (positive eastward) components of the vectors.
v	a scalar, vector, matrix, or array (same dimensions as lon) specifying the meridional (positive northward) components of the vectors.
ref	a scalar specifying the magnitude ('speed') corresponding to the reference vector; default is median(sqrt(u^2+v^2)).
ref.length.degrees	a scalar specifying the length of the reference vector in degrees.
length.by.length	a logical value specifying whether to scale vector length linearly with its magnitude; if FALSE, all vectors will be ref.length.degrees long. Default is TRUE.
lwd.by.length	a logical value specifying whether to scale vector line width linearly with its magnitude; if FALSE (default), all vectors will be lwd.ref wide.
col.by.length	a logical value specifying whether to vary vector colour with its magnitude; if TRUE, the arguments starting colbar are used to define the colourbar. If FALSE (default), all vectors will be coloured according to col.
col	a colour for the vectors, used if col.by.length=FALSE. Default is "black".
colbar	a spheRlab colourbar (as returned by sl.colbar) with Nc colours for the vectors, used if col.by.length=TRUE. Default is sl.colbar(cols=c("blue","red"),N=256).
colbar.breaks	a numeric vector of length Nc-1 specifying the breaks between colours. Used only if col.by.length=TRUE. If NA, breaks are determined automatically.
colbar.breaks.log	a logical value indicating whether automatic colourbar breaks are to be placed logarithmically. Used only if col.by.length=TRUE and colbar.breaks=NA.
lwd.ref	a scalar specifying the line width of the reference vector; default is 1.
lty	a scalar specifying the line type of the reference vector; default is 1 (solid).
head.line	a logical value specifying whether or not to add the two typical lines bordering the arrow-point triangle; default is TRUE.
head.fill	a logical value specifying whether or not to fill the arrow-point triangle; default is FALSE.
head.fill.line	a logical value specifying whether or not to add all three lines bordering the arrow-point triangle; used only if head.fill=TRUE. Default is TRUE.
head.size	a scalar specifying the size of the arrow-point triangle in terms of length ratio. Default is 1/3.
head.width	a scalar specifying the width of the arrow-point triangle relative to its length. Default is 1.
ref.args	a list to specify where and what type of a reference arrow is drawn. Possible list elements (and their defaults) are: lon (longitude; no default), lat (latitude; no default), rot (rotation in degrees counterclockwise, relative to eastward; default is 0), col (arrow colour; default is NULL, in which case the colour is consistent with the remaining arrows), circbox.bgcol (background colour of the bounding box or circle; default is "white"; if NULL, no background is drawn), circbox.col (line colour of the bounding box or circle; default is "black"; if NULL, no box or circle line is drawn), circbox.lwd (line width of the bounding box or circle; default is 1), circ.ratio (size of the circle relative to the arrow size; default is 1.5), box.ratio (3-element vector specifying the along-direction and left-side and right-side size of the box relative to the arrow size; default is c(1.5,0.5,0.5)). If ref.args=NULL, no reference arrow is drawn.
ignore.visibility	a logical value indicating whether objects shall be attempted to be drawn completely even if classified partly or fully invisible, that is, outside the plot domain.

Details

The vectors are defined on the sphere, meaning that their length and orientation are distorted exactly in the way that any lines and polygons are distorted by the projection used. Accordingly, the vectors are drawn based on sl.plot.lines() and sl.plot.polygon(). The magnitude of the vectors (sqrt(u^2+v^2)) can be coded by any combination of arrow length (linear), line width (linear), and colour (arbitrary colours and breaks).

If ref.args is specified, a reference arrow with an optional circle around it is drawn, likewise on the sphere. This implies that the reference arrow is drawn in the map at a particular lon-lat location.

Author(s)

Helge Goessling

See Also

sl.plot.polygon, sl.plot.lines

Examples

# define a cubed-sphere grid
N.xyz = 20
seq.xyz = seq(-1+1/N.xyz,1-1/N.xyz,2/N.xyz)
face = list(x=rep(-1,N.xyz^2),y=rep(seq.xyz,N.xyz),z=rep(seq.xyz,each=N.xyz))
x = c(face$x,-face$x,face$y,face$y,face$z,face$z)
y = c(face$y,face$y,face$z,face$z,face$x,-face$x)
z = c(face$z,face$z,face$x,-face$x,face$y,face$y)
lonlat = sl.xyz2lonlat(x=x, y=y, z=z)


# define a simple vector field with meridional component a function of longitude and zonal component constant
v = sin(3*lonlat$lon*2*pi/360) * 5
u = rep(2,length(v))

# define a colourbar
colbar = sl.colbar(c("blue","red"),N=8)

# plot vector field in lon-lat projection into the standard graphical device
pir = sl.plot.init(projection = "lonlat", do.init.device = FALSE)
sl.plot.naturalearth(pir, resolution = "coarse")
cb = sl.plot.vectors(pir = pir, lon = lonlat$lon, lat = lonlat$lat, u = u, v = v, ref = max(sqrt(u^2+v^2)), ref.length.degrees = 8, col.by.length = TRUE, colbar = colbar, ref.args = list(lon=-150,lat=0))
sl.plot.end(pir, do.close.device=FALSE)

# plot vector field in north polar projection into a pdf file
pir = sl.plot.init(projection = "polar", device = "pdf", file.name = "~/sl.plot.vectors.pdf")
sl.plot.naturalearth(pir, resolution = "coarse", what = "land", fill.col = "grey", polygon.borders=TRUE)
cb = sl.plot.vectors(pir = pir, lon = lonlat$lon, lat = lonlat$lat, u = u, v = v, ref.length.degrees = 5, col.by.length = TRUE, colbar = colbar, lwd.by.length=TRUE, head.fill = TRUE, ref.args = list(lon=-30,lat=50,circbox.type="circle",circbox.bgcol="grey"))
# if col.by.length=TRUE, you can also plot the colourbar to annotate the plot:
sl.plot.colbar(colbar, breaks = cb$breaks, labels.cex = 0.8, xshift = max(pir$xlim)-0.15, do.init=FALSE)
text("m/s", x = max(pir$xlim)-0.07, y = 0.3, cex = 0.8)
# (you can omit the reference vector by not specifying 'ref.args' in the call to sl.plot.vectors)
sl.plot.end(pir, do.close.device = TRUE)

FESOM/spheRlab documentation built on April 6, 2024, 6:52 p.m.