plot-argoFloats-method: Plot an argoFloats Object

Description Usage Arguments Details Value Author(s) References Examples

Description

The action depends on the type of the object, and this is set up by the function that created the object; see “Details”. These are basic plot styles, with somewhat limited scope for customization. Since the data with argoFloats objects are easy to extract, users should not find it difficult to create their own plots to meet a particular aesthetic. See “Examples” and Kelley et al. (2021) for more plotting examples.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
## S4 method for signature 'argoFloats'
plot(
  x,
  which = "map",
  bathymetry = TRUE,
  geographical = 0,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL,
  type = NULL,
  cex = NULL,
  col = NULL,
  pch = NULL,
  bg = NULL,
  eos = "gsw",
  mapControl = NULL,
  profileControl = NULL,
  QCControl = NULL,
  summaryControl = NULL,
  TSControl = NULL,
  debug = 0,
  ...
)

Arguments

x

an argoFloats object.

which

a character value indicating the type of plot. The possible choices are "map", "profile", "QC", "summary" and "TS"; see “Details”.

bathymetry

an argument used only if which="map", to control whether (and how) to indicate water depth. See “Details” for details, and Example 4 for a hint on compensating for the margin adjustment done if an image is used to show bathymetry.

geographical

flag indicating the style of axes for the which="map" case, but only if no projection is called for in the mapControl argument. With geographical=0 (which is the default), the axis ticks are labeled with signed longitudes and latitudes, measured in degrees. The signs are dropped with geographical=1. In the geographical=4 case, signs are also dropped, but hemispheres are indicated by writing S, N, W or E after axis tick labels, except at the equator and prime meridian. Note that this scheme mimics that used by oce::plot,coastline-method().

xlim, ylim

numerical values, each a two-element vector, that set the x and y limits of plot axes, as for plot.default() and other conventional plotting functions.

xlab

a character value indicating the name for the horizontal axis, or NULL, which indicates that this function should choose an appropriate name depending on the value of which. Note that xlab is not obeyed if which="TS", because altering that label can be confusing to the user.

ylab

as xlab, but for the vertical axis.

type

a character value that controls the line type, with "p" for unconnected points, "l" for line segments between undrawn points, etc.; see the docs for par(), If type not specified, it defaults to "p".

cex

a character expansion factor for plot symbols, or NULL, to get an value that depends on the value of which.

col

the colour to be used for plot symbols, or NULL, to get an value that depends on the value of which (see “Details”). If which="TS", then the TSControl argument takes precedence over col.

pch

an integer or character value indicating the type of plot symbol, or NULL, to get a value that depends on the value of which. (See par() for more on specifying pch.)

bg

the colour to be used for plot symbol interior, for pch values that distinguish between the interior of the symbol and the border, e.g. for pch=21.

eos

a character value indicating the equation of state to use if which="TS". This must be "gsw" (the default) or "unesco"; see oce::plotTS().

mapControl

a list that permits particular control of the which="map" case. If provided, it may contain elements named bathymetry (which has the same effect as the parameter bathymetry), colLand (which indicates the colour of the land), and projection (which may be FALSE, meaning to plot longitude and latitude on rectilinear axes, TRUE, meaning to plot with oce::mapPlot(), using Mollweide projection that is suitable mainly for world-scale views, or a character value that will be supplied to oce::mapPlot(). If a projection is used, then the positions of the Argo floats are plotted with oce::mapPoints(), rather than with points(), and if the user wishes to locate points with mouse clicks, then oce::mapLocator() must be used instead of locator(). If bathymetry is not contained in mapControl, it defaults to FALSE, and if projection is not supplied, it defaults to FALSE. Note that mapControl takes precedence over the bathymetry argument, if both are provided. Also note that, at present, bathymetry cannot be shown with map projections.

profileControl

a list that permits control of the which="profile" case. If provided, it may contain elements named parameter (a character value naming the quantity to plot on the x axis), ytype (a character value equal to either "pressure" or "sigma0") and connect (a logical value indicating whether to skip across NA values if the type argument is "l", "o", or "b"). If profileControl is not provided, it defaults to list(parameter="temperature", ytype="pressure", connect=FALSE). Alternatively, if profileControl is missing any of the three elements, then they are given defaults as in the previous sentence.

QCControl

a list that permits control of the which="QC" case. If provided, it may contain an element named parameter, a character value naming the quantity for which the quality-control information is to be plotted, and an element named dataStateIndicator, a logical value controlling whether to add a panel showing this quantity (see Reference Table 6 of Carval et al, 2019 to learn more about what is encoded in dataStateIndicator). If not provided, QCControl defaults to list(parameter="temperature",dataStateIndicator=FALSE).

summaryControl

a list that permits control of the which="summary". If provided, it should contain an element named items, a character vector naming the items to be shown. The possible entries in this vector are "dataStateIndicator" (see Reference Table 6 of Carval et al, 2019, for more information on this quantity)), "length" (the number of levels in the profile), "deepest" (the highest pressure recorded), "longitude" and "latitude". If summaryControl is not provided, all of these will be shown. If all the elements of x have the same ID, then the top panel will have ticks on its top axis, indicating the cycle.

TSControl

a list that permits control of the which="TS" case, and is ignored for the other cases. If TSControl is not supplied as an argument, points will be coloured black if their quality-control flags indicate good data, red if flags indicate bad data, and gray if flags are not accessed. Otherwise, if TSControl contains a vector element named colByCycle, then the col argument will be ignored, and instead individual cycles will be coloured as dictated by successive elements in colByCycle.

debug

an integer specifying the level of debugging.

...

extra arguments passed to the plot calls that are made within this function.

Details

The various plot types are as follows.

Value

None (invisible NULL).

Author(s)

Dan Kelley and Jaimie Harbin

References

  1. Carval, Thierry, Bob Keeley, Yasushi Takatsuki, Takashi Yoshida, Stephen Loch, Claudia Schmid, and Roger Goldsmith. Argo User's Manual V3.3. Ifremer, 2019. doi:10.13155/29825

  2. Kelley, D. E., Harbin, J., & Richards, C. (2021). argoFloats: An R package for analyzing Argo data. Frontiers in Marine Science, (8), 636922. doi: 10.3389/fmars.2021.635922

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
# Example 1: map profiles in index
library(argoFloats)
data(index)
plot(index, bathymetry=FALSE)

# Example 2: as Example 1, but narrow the margins and highlight floats
# within a circular region of diameter 100 km.
oldpar <- par(no.readonly=TRUE)
par(mar=c(2, 2, 1, 1), mgp=c(2, 0.7, 0))
plot(index, bathymetry=FALSE)
lon <- index[["longitude"]]
lat <- index[["latitude"]]
near <- oce::geodDist(lon, lat, -77.06, 26.54) < 100
R <- subset(index, near)
points(R[["longitude"]], R[["latitude"]],
    cex=0.6, pch=20, col="red")
par(oldpar)

# Example 3: TS of a built-in data file.
f <- system.file("extdata", "SR2902204_131.nc", package="argoFloats")
a <- readProfiles(f)
oldpar <- par(no.readonly=TRUE)
par(mar=c(3.3, 3.3, 1, 1), mgp=c(2, 0.7, 0)) # wide margins for axis names
plot(a, which="TS")
par(oldpar)

# Example 4: map with bathymetry. Note that par(mar) is adjusted
# for the bathymetry palette, so it must be adjusted again after
# the plot(), in order to add new plot elements.
# This example specifies a coarse bathymetry dataset that is provided
# by the 'oce' package.  In typical applications, the user will use
# a finer-scale dataset, either by using bathymetry=TRUE (which
# downloads a file appropriate for the plot view), or by using
# an already-downloaded file.
data(topoWorld, package="oce")
oldpar <- par(no.readonly=TRUE)
par(mar=c(2, 2, 1, 2), mgp=c(2, 0.7, 0)) # narrow margins for a map
plot(index, bathymetry=list(source=topoWorld))
# For bathymetry plots that use images, plot() temporarily
# adds 2.75 to par("mar")[4] so the same must be done, in order
# to correctly position additional points (shown as black rings).
par(mar=par("mar") + c(0, 0, 0, 2.75))
points(index[["longitude"]], index[["latitude"]],
    cex=0.6, pch=20, col="red")
par(oldpar)

# Example 5. Simple contour version, using coarse dataset (ok on basin-scale).
# Hint: use oce::download.topo() to download high-resolution datasets to
# use instead of topoWorld.
oldpar <- par(no.readonly=TRUE)
par(mar=c(2, 2, 1, 1))
data(topoWorld, package="oce")
plot(index, bathymetry=list(source=topoWorld, contour=TRUE))
par(oldpar)

# Example 6. Customized map, sidestepping plot,argoFloats-method().
lon <- topoWorld[["longitude"]]
lat <- topoWorld[["latitude"]]
asp <- 1/cos(pi/180*mean(lat))
# Limit plot region to float region.
xlim <- range(index[["longitude"]])
ylim <- range(index[["latitude"]])
# Colourize 1km, 2km, etc, isobaths.
contour(x=lon, y=lat, z=topoWorld[["z"]], xlab="", ylab="",
        xlim=xlim, ylim=ylim, asp=asp,
        col=1:6, lwd=2, levels=-1000*1:6, drawlabels=FALSE)
# Show land
data(coastlineWorldFine, package="ocedata")
polygon(coastlineWorldFine[["longitude"]],
        coastlineWorldFine[["latitude"]], col="lightgray")
# Indicate float positions.
points(index[["longitude"]], index[["latitude"]], pch=20)


# Example 7: Temperature profile of the 131st cycle of float with ID 2902204
a <- readProfiles(system.file("extdata", "SR2902204_131.nc", package="argoFloats"))
oldpar <- par(no.readonly=TRUE)
par(mfrow=c(1, 1))
par(mgp=c(2, 0.7, 0))                  # mimic the oce::plotProfile() default
par(mar=c(1,3.5,3.5,2))                # mimic the oce::plotProfile() default
plot(a, which="profile")
par(oldpar)

# Example 8: As Example 7, but showing temperature dependence on potential density anomaly.
a <- readProfiles(system.file("extdata", "SR2902204_131.nc", package="argoFloats"))
oldpar <- par(no.readonly=TRUE)
par(mgp=c(2, 0.7, 0))                  # mimic the oce::plotProfile() default
par(mar=c(1,3.5,3.5,2))                # mimic the oce::plotProfile() default
plot(a, which="profile", profileControl=list(parameter="temperature", ytype="sigma0"))
par(oldpar)

dankelley/argoFloats documentation built on Oct. 19, 2021, 1:17 p.m.