subset,argoFloats-method {argoFloats}

Subset an argoFloats Object

Description

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’.

Usage

## S4 method for signature 'argoFloats'
subset(x, subset = NULL, ...)

Arguments

x

an argoFloats object as created by getIndex().

subset

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”.

Details

The possibilities for the ... argument are as follows.

1. An integer vector giving indices to keep.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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".

7. 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.

8. A list named deep that holds a logical value indicating whether argo floats are deep argo (i.e. profiler_type 849, 862, and 864).

9. A list named ID that holds a character value specifying a float identifier.

10. 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.

11. 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.

12. 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.

13. A character value named direction, equal to either "descent" or "ascent", that selects whether to retain data from the ascent or decent phase.

14. 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".

15. An integer value named cycle that selects which cycles to retain.

16. 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".

17. 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).

Value

An argoFloats object, restricted as indicated.

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

library(argoFloats)
data(index)
data(indexSynthetic)

# Subset to the first 3 profiles in the (built-in) index
indexFirst3 <- subset(index, 1:3)

# Subset to a circle near Abaco Island
indexCircle <- subset(index, circle=list(longitude=-77.5, latitude=27.5, radius=50))

# 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))

# 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))

# Subset to year 2019
index2019 <- subset(index, time=list(from="2019-01-01", to="2019-12-31"))

# Subset to Canadian MEDS data
indexMEDS <- subset(index, institution="ME")

# Subset to profiles with oxygen data
indexOxygen <- subset(indexSynthetic, parameter="DOXY")

# Subset to profiles with both salinity and 380-nm downward irradiance data
indexSalinityIrradiance <- subset(indexSynthetic, parameter=c("PSAL", "DOWN_IRRADIANCE380"))