Return a subset of an argoFloats object. This applies
only to objects of type "index", as created with getIndex() or subset()
acting on such a value, or of type "argos", as created with readProfiles().
(It cannot be used on objects of type "profiles", as created with getProfiles().)
There are two ways to use subset(). Method 1. supply
the subset argument. This may be a logical vector indicating
which entries to keep (by analogy to the base-R subset()
function) or it may be an integer vector holding the indices of entries to
be retained. Method 2. do not supply subset. In this
case, the action is determined by the third (...)
argument; see ‘Details’.
# S4 method for argoFloats
subset(x, subset = NULL, ...)an argoFloats object as created by getIndex().
optional numerical or logical vector that indicates which
indices of x@data$index to keep (example 1).
the first entry here must be either (a) a list named circle,
rectangle, polygon, parameter, time, institution,
ID,ocean,dataMode,cycle, direction, profile, or section.
(examples 2 through 8, and 10 through 17),
or (b) a logical value named deep (example 9). Optionally, this entry
may be followed by second entry named silent, which is a logical
value indicating whether to prevent the printing of messages that
indicate the number (and percentage) of data that are kept
during the subsetting operation.
See “Details” and “Examples”.
An argoFloats object, restricted as indicated.
The possibilities for the ... argument are as follows.
An integer vector giving indices to keep.
A list named circle with numeric elements named longitude,
latitude and radius. The first two give the center of
the subset region, and the third gives the radius of
that region, in kilometers.
A list named rectangle that has elements named
longitude and latitude, two-element numeric vectors
giving the western and eastern, and southern and northern
limits of the selection region.
A list named polygon that has elements named longitude and latitude
that are numeric vectors specifying a polygon within which profiles
will be retained. The polygon must not be self-intersecting,
and an error message will be issued if it is. If the polygon is not closed
(i.e. if the first and last points do not coincide) the first point is pasted
onto the end, to close it.
A vector or list named parameter that holds character values that
specify the names of measured parameters to keep. See section 3.3 of
Reference 1 for a list of parameters.
A list named time that has elements from and to that are either
POSIXt times, or character strings that subset() will convert to
POSIXt times using as.POSIXct() with tz="UTC".
A list named institution that holds a single character element that
names the institution. The permitted values are:
"AO" for Atlantic Oceanographic and Meteorological Laboratory;
"BO" for British Oceanographic Data Centre;
"CS" for Commonwealth Scientific and Industrial Research Organization;
"HZ" for China Second Institute of Oceanography;
"IF" for Ifremer, France;
"IN" for India National Centre for Ocean Information Services;
"JA" for Japan Meteorological Agency;
"KM" for Korea Meteorological Agency;
"KO" for Korea Ocean Research and Development Institute;
"ME" for Marine Environment Data Section; and
"NM" for National Marine Data & Information Service.
A list named deep that holds a logical value indicating whether argo floats
are deep argo (i.e. profiler_type 849, 862, and 864).
A list named ID that holds a character value specifying a float identifier.
A list named ocean that holds a single character element that names the
ocean. The permitted values are:
"A" for Atlantic Ocean Area, from 70 W to 20 E,
"P" for Pacific Ocean Area, from 145 E to 70 W, and
"I" for Indian Ocean Area, from 20 E to 145 E.
A character value named dataMode, equal to either realtime or delayed,
that selects whether to retain real-time data or delayed data. There are two
possibilities, depending on the type of the x argument.
Case 1. If x is of type="index", then the subset is done by looking for the letters
R or D in the source filename. Note that a file in the
latter category may contain some profiles that are of delayed mode and also
some profiles that are of realtime or adjusted mode.
Case 2. If x is
of type argos, then the subset operation is done for each profile within
the dataset. Sometimes this will yield data arrays with zero columns.
An integer or character value named cycle that specifies which cycles are to be retained.
This is done by regular-expression matching of the filename, looking between the
underline character ("_") and the suffix (.nc), but note that the expression
is made up of a compulsory component comprising 3 or 4 digits, and an optional
component that is either blank or the character "D" (which designates a
descending profile). Thus, 001 will match both *_001.nc and *_001D.nc.
Note this can be used for both "index" and "argos" types.
A character value named direction, equal to either "descent" or "ascent",
that selects whether to retain data from the ascent or decent phase.
An integer value named profile that selects which profiles
to retain. Note that this type of subset is possible only
for objects of type "argos".
An integer value named cycle that selects which cycles
to retain.
A character value named dataStateIndicator, equal to either "0A", "1A",
"2B", "2B+", "2C", "2C+", "3B", or "3C" that selects which dataStateIndicator
to keep (see table 6 of Reference 1 for details of these codes).
This operation only works for objects of type "argos".
A list named section that has four elements:
longitude,latitude, width, and segments. The first two of these
are numeric vectors that define the spine of the section, in degrees East
and North, respectively. These are both mandatory, while both width and segments
are optional. If given, width is taken as maximal distance between an Argo
and the spine, for that float to be retained. If width is not given, it
defaults to 100km. If given, segments is either NULL or a positive
integer. Setting segments to NULL will cause the float-spine distance
to be computed along a great-circle route. By contrast, if segments is an
integer, then the spine is traced using stats::approx(), creating
segments new points. If segments is not provided, it defaults to 100.
In all cases, the notation is that longitude is positive for degrees East and negative for degrees West, and that latitude is positive for degrees North and negative for degrees South. For more on this function, see Kelley et al. (2021).
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.
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
library(argoFloats)
data(index)
data(indexSynthetic)
# Subset to the first 3 profiles in the (built-in) index
indexFirst3 <- subset(index, 1:3)
#> Kept 3 cycles (0.298%)
# Subset to a circle near Abaco Island
indexCircle <- subset(index, circle=list(longitude=-77.5, latitude=27.5, radius=50))
#> Kept 104 cycles (10.3%)
# Subset to a rectangle near Abaco Island
lonlim <- c(-76.5, -76)
latlim <- c(26.5, 27.5)
indexRectangle <- subset(index, rectangle=list(longitude=lonlim, latitude=latlim))
#> Kept 59 cycles (5.85%)
# Subset to a polygon near Abaco Island
lonp <- c(-77.492, -78.219, -77.904, -77.213, -76.728, -77.492)
latp <- c( 26.244, 25.247, 24.749, 24.987, 25.421, 26.244)
indexPolygon <- subset(index, polygon=list(longitude=lonp, latitude=latp))
#> Kept 173 cycles (17.2%)
# Subset to year 2019
index2019 <- subset(index, time=list(from="2019-01-01", to="2019-12-31"))
#> Kept 9 cycles (0.893%)
# Subset to Canadian MEDS data
indexMEDS <- subset(index, institution="ME")
#> Kept 3 cycles (0.298%)
# Subset to profiles with oxygen data
indexOxygen <- subset(indexSynthetic, parameter="DOXY")
#> Kept 38 cycles (95%)
# Subset to profiles with both salinity and 380-nm downward irradiance data
indexSalinityIrradiance <- subset(indexSynthetic, parameter=c("PSAL", "DOWN_IRRADIANCE380"))
#> Kept 2 cycles (5%)