Type:	Package
Title:	Analysis of Oceanographic Argo Floats
Version:	1.0.7
Maintainer:	Dan Kelley <dan.kelley@dal.ca>
Depends:	R (≥ 4.1.0)
Suggests:	colourpicker, curl, knitr, lubridate, markdown, ncdf4, ocedata, rmarkdown, shiny, s2, sf, testthat, shinyBS
Imports:	oce (≥ 1.3.0), methods
BugReports:	https://github.com/ArgoCanada/argoFloats/issues
Description:	Supports the analysis of oceanographic data recorded by Argo autonomous drifting profiling floats. Functions are provided to (a) download and cache data files, (b) subset data in various ways, (c) handle quality-control flags and (d) plot the results according to oceanographic conventions. A shiny app is provided for easy exploration of datasets. The package is designed to work well with the 'oce' package, providing a wide range of processing capabilities that are particular to oceanographic analysis. See Kelley, Harbin, and Richards (2021) <doi:10.3389/fmars.2021.635922> for more on the scientific context and applications.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding:	UTF-8
URL:	https://github.com/ArgoCanada/argoFloats
LazyData:	false
RoxygenNote:	7.2.3
BuildVignettes:	true
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2023-10-17 17:33:22 UTC; kelley
Author:	Dan Kelley [aut, cre, cph], Jaimie Harbin [aut], Dewey Dunnington [ctb], Clark Richards [ctb]
Repository:	CRAN
Date/Publication:	2023-10-17 17:50:02 UTC

A Package for Processing Argo Float Profiles

Description

The argoFloats package provides tools for downloading and processing Argo profile data. It allows users to focus on core, biogeochemical ("BGC"), or deep Argo profiles, and also to sift these profiles based on ID, time, geography, variable, institution, and ocean, etc. Once downloaded, such datasets can be analyzed within argoFloats or using other R tools and packages.

Details

The development website is https://github.com/ArgoCanada/argoFloats, and https://argocanada.github.io/argoFloats/index.html provides a simpler view that may be more helpful to most users. For more on the argoFloats package, see Kelley et al. (2021).

The sketch given below illustrates the typical workflow with the package, with descriptions of the steps on the left, and names of the relevant functions on the right.

As illustrated, the central functions are named getIndex(), subset(), getProfiles(), and readProfiles(), and so a good way to get familiar with the package is to read their documentation entries and try the examples provided therein. Some built-in datasets are provided for concreteness of illustration and for testing, but actual work always starts with a call to getIndex() to download a full index of float data.

In addition to these functions, argoFloats also provides specialized versions of R "generic" functions, as follows.

1. [[ provides a way to extract items from argoFloats objects, without getting lost in the details of storage. See [[,argoFloats-method for details. (Note that ⁠[[<-⁠ is not specialized, since the user is highly discouraged from altering values within argoFloats objects.)

2. plot() provides simple ways to plot aspects of argoFloats objects. See plot,argoFloats-method() for details.

3. summary() displays key features of argoFloats objects. See summary,argoFloats-method() for details.

4. show() provides a one-line sketch of argoFloats objects. See show,argoFloats-method() for details.

5. merge() combines multiple index objects into a new index object.

It should be noted that the profile elements within argoFloats objects are stored as in the form of argo objects as defined by the oce package. This means that argoFloats users can rely on a wide variety of oce functions to analyze their data. The full suite of R tools is also available, and the vastness of that suite explains why argoFloats is written in R.

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

Author(s)

Maintainer: Dan Kelley dan.kelley@dal.ca (ORCID) [copyright holder]

Authors:

• Jaimie Harbin jm810136@dal.ca (ORCID)

Other contributors:

• Dewey Dunnington dewey.dunnington@dfo-mpo.gc.ca (ORCID) [contributor]

• Clark Richards clark.richards@dfo-mpo.gc.ca (ORCID) [contributor]

See Also

Useful links:

• https://github.com/ArgoCanada/argoFloats

• Report bugs at https://github.com/ArgoCanada/argoFloats/issues

Sample Argo File (Delayed Core Data)

Description

This is NetCDF file for delayed-mode data for cycle 48 of Argo float 4900785, downloaded from https://data-argo.ifremer.fr/dac/aoml/4900785/profiles/D4900785_048.nc on 2020 June 24.

See Also

Other raw datasets: R3901602_163.nc, SD5903586_001.nc, SR2902204_131.nc

Examples

library(argoFloats)
a <- readProfiles(system.file("extdata", "D4900785_048.nc", package="argoFloats"))
summary(a)
summary(a[[1]])

Sample Argo File (Real-Time Core Data)

Description

This is NetCDF file for real-time data for cycle 163 of Argo float 3901602, downloaded from https://data-argo.ifremer.fr/dac/coriolis/3901602/profiles/R3901602_163.nc on 2021 March 7.

See Also

Other raw datasets: D4900785_048.nc, SD5903586_001.nc, SR2902204_131.nc

Examples

library(argoFloats)
a <- readProfiles(system.file("extdata", "R3901602_163.nc", package="argoFloats"))
summary(a)
summary(a[[1]])

Sample Argo File (Delayed Synthetic Data)

Description

This is the NetCDF file for cycle 1 of Argo float 5903586, downloaded from ftp://usgodae.org/pub/outgoing/argo/dac/aoml/5903586/profiles/SD5903586_001.nc on 2020 June 24 (this URL appears to be unreliable). As its filename indicates, it holds "synthetic" data in "delayed" mode. The oxygen values are adjusted by 16%, as is shown here, and in the documentation for useAdjusted().

See Also

Other raw datasets: D4900785_048.nc, R3901602_163.nc, SR2902204_131.nc

Examples

library(argoFloats)
a <- readProfiles(system.file("extdata", "SD5903586_001.nc", package="argoFloats"))
a1 <- a[[1]]
# Illustrate oxygen adjustment
p <- a1[["pressure"]]
O <- a1[["oxygen"]]
Oa  <- a1[["oxygenAdjusted"]]
Percent <- 100 * (Oa - O) / O
hist(Percent, main="Oxygen adjustment")

Sample Argo File (Real-Time Synthetic Data)

Description

This is the NetCDF file for cycle 131 of Argo float 2902204, downloaded from ftp://ftp.ifremer.fr/ifremer/argo/dac/incois/2902204/profiles/SR2902204_131.nc on 2020 June 24. As its filename indicates, it holds the "synthetic" version of "real-time" data.

See Also

Other raw datasets: D4900785_048.nc, R3901602_163.nc, SD5903586_001.nc

Examples

library(argoFloats)
a <- readProfiles(system.file("extdata", "SR2902204_131.nc", package="argoFloats"))
summary(a)
summary(a[[1]])

Look up a Value Within an argoFloats Object

Description

This function provides an easy way to look up values within an argoFloats object, without the need to know the exact structure of the data. The action taken by [[ depends on the type element in the metadata slot of the object (which is set by the function that created the object), on the value of i and, in some cases, on the value of j; see “Details”.

Usage

## S4 method for signature 'argoFloats'
x[[i, j, ...]]

Arguments

Details

There are several possibilities, depending on the object type, as listed below. Note that these possibilities are checked in the order listed here.

1. For all object types:

   1. If i is "metadata" then the metadata slot of x is returned.

   2. Otherwise, if i is "data" then the data slot of x is returned.

   3. Otherwise, if i is "cycle" then a character vector of the cycle numbers is returned.

   4. Otherwise, if i is "processingLog" then the processingLog slot of x is returned.

   5. Otherwise, if i is "ID" then a character vector of the ID numbers is returned.

   6. Otherwise, the following steps are taken, depending on type.

2. If type is "index", i.e. if x was created with getIndex() or with subset,argoFloats-method() acting on the result of getIndex(), then:

   1. If i is numeric and j is unspecified, then i is taken to be an index that identifies the row(s) of the data frame that was constructed by getIndex() based on the remote index file downloaded from the Argo server. This has elements file for the remote file name, date for the date of the entry, latitude and longitude for the float position, etc.

   2. If i is the name of an item in the metadata slot, then that item is returned. The choices are: "destdir", "destfileRda", "filename", "ftpRoot", "header", "server", "type", and "url".

   3. Otherwise, if i is the name of an item in the data slot, then that item is returned. The choices are: "date", "date_update", "file", "institution", "latitude", "longitude", "ocean", and "profiler_type". Note that "time" and "time_update" may be used as synonyms for "date" and "date_update".

   4. Otherwise, if i=="index" then that item from the data slot of x is returned. (For the possible names, see the previous item in this sub-list.)

   5. Otherwise, if i is an integer, then the i-th row of the index item in the data slot is returned. This is a good way to learn the longitude and latitude of the profile, the file name on the server, etc.

   6. Otherwise, if i is "ID" then the return value is developed from the index$file item within the data slot of x, in one of three cases:

      1. If j is not supplied, the return value is a vector holding the identifiers (character codes for numbers) for all the data files referred to in the index.

      2. Otherwise, if j is numeric, then the return value is a subset of the ID codes, as indexed by j.

      3. Otherwise, an error is reported.

   7. If i is "length", the number of remote files pointed to by the index is returned.

3. Otherwise, if type is "profiles", i.e. if x was created with getProfiles(), then:

   1. If i is numeric and j is unspecified, then return the local file name(s) that are identified by using i as an index.

   2. If i is the name of an item in the metadata slot, then that item is returned. The choices are: "type" and "destdir".

   3. Otherwise, if i is the name of an item in the data slot, then that item is returned. There is only one choice: "file".

   4. If i is "length", the number of local file names that were downloaded by getProfiles() is returned.

4. Otherwise, if type is "argos", i.e. if x was created with readProfiles(), then:

   1. If i is equal to "argos", and j is unspecified, then a list holding the oce::argo objects stored within x is returned.

   2. If i is equal to "argos", and j is provided, then the associated oce::argo object is returned.

   3. If i is numeric and j is unspecified, then return the argo objects identified by using i as an index.

   4. If i is the name of an item in the metadata slot, then that item is returned. There is only choice, "type".

   5. Otherwise, if i is the name of an item in the data slot, then that item is returned as a named list. (At present, there is only one choice: "argos".)

   6. Otherwise, if i is "length" then the number of oce-type argo objects in x is returned.

   7. Otherwise, if i is a character value then it is taken to be an item within the metadata or data slots of the argo objects stored in x, and the returned value is a list containing that information with one (unnamed) item per profile. If j is provided and equal to "byLevel", then the items from the metadata are repeated (if necessary) and formed into matrix or vector of the same shape as the "pressure" field; this can be convenient for computations involving items that only occur once per profile, such as "longitude", but it should not be used for items that are not level-specific, such as the various "HISTORY_*" elements, which apply to a dataset, not to a level

   8. Otherwise, NULL is reported.

5. Otherwise, an error is reported.

Value

the indicated item, or NULL if it is neither stored within the first argument nor computable from its contents.

Author(s)

Dan Kelley

References

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

data(index)
# Full remote filename for first two item in index
paste0(index[["server"]], "/dac/", index[["cycle", 1:2]])
# File names and geographical locations of first 5 items in index
index5 <- subset(index, 1:5)
data.frame(file=gsub(".*/", "", index5[["file"]][1]),
           lon=index5[["longitude"]],
           lat=index5[["latitude"]])

Apply Quality Control Flags

Description

This function examines the quality-control ("QC") flags within an argoFloats object that was created by readProfiles(). By default, it replaces all suspicious data with NA values, so they will not appear in plots or be considered in calculations. This is an important early step in processing, because suspicious Argo floats commonly report data that are suspicious based on statistical and physical measures, as is illustrated in the “Examples” section. See section 3.3 of Kelley et al. (2021) for more information about this function.

Usage

applyQC(x, flags = NULL, actions = NULL, debug = 0)

Arguments

Details

The work is done by using oce::handleFlags,argo-method() on each of the profiles stored within the object. In most cases, only the object needs to be specified, for the default actions coincide with common conventions for flags in Argo data.

Value

A copy of x but with each of the objects within its data slot having been passed through oce::handleFlags,argo-method().

Author(s)

Dan Kelley

References

1. Argo Data Management. “Argo User’s Manual.” Ifremer, July 5, 2022. https://doi.org/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

# Demonstrate applyQC to a built-in file
library(argoFloats)
f <- system.file("extdata", "SR2902204_131.nc", package="argoFloats")
raw <- readProfiles(f)
clean <- applyQC(raw)
oldpar <- par(no.readonly=TRUE)
par(mar=c(3.3, 3.3, 1, 1), mgp=c(2, 0.7, 0))
plot(raw, col="red", which="TS")
points(clean[[1]][["SA"]], clean[[1]][["CT"]], pch=20)
legend("topleft", pch=20, cex=1,
    col=c("black", "red"), legend=c("OK", "Flagged"), bg="white")
par(oldpar)

Get Default Values

Description

These are helper functions that permit customization of various aspects of functions within the argoFloats package. The idea is that values can be set using options() or by using system 'environment variables', freeing the user from the necessity of altering the parameters provided to various argoFloats functions. See “Details” for more on the individual functions, noting that the entry for argoDefaultServer() is written with the most detail, with other entries relying on the background established there.

Usage

argoDefaultDestdir()

argoDefaultServer()

argoDefaultIndexAge()

argoDefaultProfileAge()

argoDefaultBathymetry()

hasArgoTestCache()

Details

• argoDefaultServer() The getIndex() and getProfiles() functions download data from a remote machine with URL specified by an argument named server. A user may prefer one server over another, perhaps due to speed of downloads to a particular research laboratory. However, that choice might not be best for another user, or even the same user at another time. Code reusability would be enhanced if the user had a way to alter the value of the server argument across all code, thereby eliminating the need to work in a text editor to find all instances of the function call. This is where argoDefaultServer() is useful. It lets the user specify a value for server either in R, using a call like options(argoFloats.server="ifremer-https") within R code (perhaps in the user's .Rprofile file), or by defining an environment variable named R_ARGOFLOATS_SERVER at the operating-system level. If the argoFloats.server option has not been set in R, and R_ARGOFLOATS_SERVER has not been set in the OS, then argoDefaultServer() defaults to c("ifremer-https","usgodae").

• argoDefaultDestdir() returns the name of the local directory into which to store indices and other argo data. The option is named argoFloats.destdir, the environment variable is named R_ARGOFLOATS_DESTDIR, and the default is '"~/data/argo".

• argoDefaultIndexAge() returns the number of days beyond which an index is regarded as stale (and thus in need of a new download). The option is named argoFloats.indexAge, the environment variable is named R_ARGOFLOATS_INDEX_AGE, and the default is 1.0, for 1 day.

• argoDefaultProfileAge() returns the number of days beyond which an individual profile netCDF file is regarded as stale (and thus in need of a new download). The option is named argoFloats.profileAge, the environment variable is named R_ARGOFLOATS_PROFILE_AGE, and the default is 365.0 days. (Note that this is much higher than the value for argoDefaultIndexAge(), on the assumption that users will prefer recent indices, to get new data, but will prefer to update profile-specific datasets infrequently.)

• argoDefaultBathymetry() returns a value for the bathymetry argument used by plot,argoFloats-method(). The option is named argoFloats.bathymetry, the environment variable is named R_ARGOFLOATS_BATHYMETRY, and the default is FALSE.

• hasArgoTestCache() is not a user-facing function. Rather, its purpose is to speed the running of test suites during development, by preventing multiple downloads of data already downloaded.

Value

A value as described above, depending on the particular function in question.

Examples

argoDefaultServer()
argoDefaultDestdir()
argoDefaultIndexAge()
argoDefaultProfileAge()
argoDefaultBathymetry()

Base Class for argoFloats Objects

Description

In the normal situation, users will not create these objects directly. Instead, they are created by functions such as getIndex().

Slots

data

The data slot is a list with contents that vary with the object type. For example, getIndex() creates objects of type "index" that have a single unnamed element in data that is a data frame. This data frame has a column named file that is used in combination with metadata@ftpRoot to form a URL for downloading, along with columns named date, latitude, longitude, ocean, profiler_type, institution and date_update. Other "get" functions create objects with different contents.

metadata

The metadata slot is a list containing information about the data. The contents vary between objects and object types. That type is indicated by elements named type and subtype, which are checked by many functions within the package.

processingLog

The processingLog slot is a list containing time-stamped processing steps that may be stored in the object by argoFloats functions. These are noted in summary() calls.

Examples

str(new("argoFloats"))

Clear the Cache

Description

Clear the cache. This is meant mainly for developers working in interactive sessions to test coding changes.

Usage

argoFloatsClearCache(debug = 0L)

Arguments

Value

integer, returned invisibly, indicating the number of items removed.

Author(s)

Dan Kelley, making a thin copy of code written by Dewey Dunnington

See Also

Other functions relating to cached values: argoFloatsGetFromCache(), argoFloatsIsCached(), argoFloatsListCache(), argoFloatsStoreInCache(), argoFloatsWhenCached()

Print Debugging Information

Description

This function is intended mainly for use within the package, but users may also call it directly in their own code. Within the package, the value of debug is generally reduced by 1 on each nested function call, leading to indented messages. Most functions start and end with a call to argoFloatsDebug() that has style="bold" and unindent=1.

Usage

argoFloatsDebug(
  debug = 0,
  ...,
  style = "plain",
  showTime = FALSE,
  unindent = 0
)

Arguments

Value

None (invisible NULL).

Author(s)

Dan Kelley

Examples

argoFloatsDebug(1, "plain text\n")
argoFloatsDebug(1, "red text\n", style="red")
argoFloatsDebug(1, "blue text\n", style="blue")
argoFloatsDebug(1, "bold text\n", style="bold")
argoFloatsDebug(1, "italic text with time stamp\n", style="italic", showTime=TRUE)

Get an Item From The Cache

Description

Get an Item From The Cache

Usage

argoFloatsGetFromCache(name, debug = 0)

Arguments

Value

The cached value, as stored with argoFloatsStoreInCache().

See Also

Other functions relating to cached values: argoFloatsClearCache(), argoFloatsIsCached(), argoFloatsListCache(), argoFloatsStoreInCache(), argoFloatsWhenCached()

Check Whether an Item is Cached

Description

Check Whether an Item is Cached

Usage

argoFloatsIsCached(name, debug = 0L)

Arguments

Value

A logical value indicating whether a cached value is available.

Author(s)

Dan Kelley, making a thin copy of code written by Dewey Dunnington

See Also

Other functions relating to cached values: argoFloatsClearCache(), argoFloatsGetFromCache(), argoFloatsListCache(), argoFloatsStoreInCache(), argoFloatsWhenCached()

List Items in the Cache

Description

List items in the cache.

Usage

argoFloatsListCache(debug = 0L)

Arguments

Value

character vector of names of items.

Author(s)

Dan Kelley, making a thin copy of code written by Dewey Dunnington

See Also

Other functions relating to cached values: argoFloatsClearCache(), argoFloatsGetFromCache(), argoFloatsIsCached(), argoFloatsStoreInCache(), argoFloatsWhenCached()

Store an Item in the Cache

Description

Store an Item in the Cache

Usage

argoFloatsStoreInCache(name, value, debug = 0)

Arguments

Value

None (invisible NULL).

See Also

Other functions relating to cached values: argoFloatsClearCache(), argoFloatsGetFromCache(), argoFloatsIsCached(), argoFloatsListCache(), argoFloatsWhenCached()

Check When an Item was Cached

Description

Check When an Item was Cached

Usage

argoFloatsWhenCached(name, debug = 0L)

Arguments

Value

A logical value indicating whether a cached value is available.

Author(s)

Dan Kelley, making a thin copy of code written by Dewey Dunnington

See Also

Other functions relating to cached values: argoFloatsClearCache(), argoFloatsGetFromCache(), argoFloatsIsCached(), argoFloatsListCache(), argoFloatsStoreInCache()

Download and Cache a Dataset

Description

General function for downloading and caching a dataset.

Usage

downloadWithRetries(
  url,
  destdir,
  destfile,
  quiet = FALSE,
  age = argoDefaultProfileAge(),
  retries = 3,
  async = FALSE,
  debug = 0
)

Arguments

Value

A character value indicating the full pathname to the downloaded file, or NA, if there was a problem with the download.

Author(s)

Dan Kelley

Get an Index of Available Argo Float Profiles

Description

This function gets an index of available Argo float profiles, typically for later use as the first argument to getProfiles(). The source for the index may be (a) a remote data repository, (b) a local repository (see the keep argument), or (c) a cached RDA file that contains the result of a previous call to getIndex() (see the age parameter).

Usage

getIndex(
  filename = "core",
  server = argoDefaultServer(),
  destdir = argoDefaultDestdir(),
  age = argoDefaultIndexAge(),
  quiet = FALSE,
  keep = FALSE,
  debug = 0L
)

Arguments

Details

Using an index from a remote server

The first step is to construct a URL for downloading, based on the url and file arguments. That URL will be a string ending in .gz, or .txt and from this the name of a local file is constructed by changing the suffix to .rda and prepending the file directory specified by destdir. If an .rda file of that name already exists, and is less than age days old, then no downloading takes place. This caching procedure is a way to save time, because the download can take from a minute to an hour, depending on the bandwidth of the connection to the server.

The resultant .rda file, which is named in the return value of this function, holds a list named index that holds following elements:

• ftpRoot, the FTP root stored in the header of the source file (see next paragraph).

• server, the URL at which the index was found, and from which getProfiles() can construct URLs from which to download the NetCDF files for individual float profiles.

• filename, the argument provided here.

• header, the preliminary lines in the source file that start with the ⁠#⁠ character.

• data, a data frame containing the items in the source file. The names of these items are determined automatically from "core","bgcargo", "synthetic" files.

Some expertise is required in deciding on the value for the file argument to getIndex(). As of March 2023, the FTP sites ⁠ftp://usgodae.org/pub/outgoing/argo⁠ and ⁠ftp://ftp.ifremer.fr/ifremer/argo⁠ contain multiple index files, as listed in the left-hand column of the following table. The middle column lists nicknames for some of the files. These can be provided as the file argument, as alternatives to the full names. The right-hand column describes the file contents. Note that the servers also provide files with names similar to those given in the table, but ending in .txt. These are uncompressed equivalents of the .gz files that offer no advantage and take longer to download, so getIndex() is not designed to work with them.

Using a previously downloaded index

In some situations, it can be desirable to work with local index file that has been copied directly from a remote server. This can be useful if there is a desire to work with the files in R separately from the argoFloats package, or with python, etc. It can also be useful for group work, in which it is important for all participants to use the same source file.

This need can be handled with getIndex(), by specifying filename as the full path name to the previously downloaded file, and at the same time specifying server as NULL. This works for both the raw files as downloaded from the server (which end in .gz, and for the R-data-archive files produced by getIndex(), which end in .rda. Since the .rda files load an order of magnitude faster than the .gz files, this is usually the preferred approach. However, if the .gz files are preferred, perhaps because part of a software chain uses python code that works with such files, then it should be noted that calling getIndex() with keep=TRUE will save the .gz file in the destdir directory.

Value

An object of class argoFloats with type="index", which is suitable as the first argument of getProfiles().

Author(s)

Dan Kelley and Jaimie Harbin

References

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

Get Data for an Argo Float Profile

Description

Get Data for an Argo Float Profile

Usage

getProfileFromUrl(
  url = NULL,
  destdir = argoDefaultDestdir(),
  destfile = NULL,
  age = argoDefaultProfileAge(),
  retries = 3,
  quiet = FALSE,
  debug = 0
)

Arguments

Value

A character value naming the local location of the downloaded file, or NA if the file could not be downloaded.

Author(s)

Dan Kelley

Get "cycles"/"trajectory" Files Named in an argoFloats Index

Description

This takes an index constructed with getIndex(), possibly after focusing with subset,argoFloats-method(), and creates a list of files to download from the server named in the index. Then these files are downloaded to the destdir directory, using filenames inferred from the source filenames. The value returned by getProfiles() is suitable for use by readProfiles().

Usage

getProfiles(
  index,
  destdir = argoDefaultDestdir(),
  age = argoDefaultProfileAge(),
  retries = 3,
  skip = TRUE,
  quiet = TRUE,
  debug = 0
)

Arguments

Details

It should be noted that the constructed server URL follows a different pattern on the USGODAE an Ifremer servers, and so if some other server is used, the URL may be wrong, leading to an error. Similarly, if the patterns on these two servers change, then getProfiles() will fail. Users who encounter such problems are requested to report them to the authors.

If a particular data file cannot be downloaded after multiple trials, then the behaviour depends on the value of the skip argument. If that is TRUE then a NA value is inserted in the corresponding spot in the return value, but if it is FALSE (the default), then an error is reported. Note that readProfiles() skips over any such NA entries, while reporting their positions within index. For more on this function, see Kelley et al. (2021).

Value

An object of class argoFloats with type="profiles", the data slot of which contains two items: url, which holds the URLs from which the NetCDF files were downloaded, and file, which holds the path names of the downloaded files; the latter is used by readProfiles().

Author(s)

Dan Kelley

References

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

Convert Hexadecimal Digit to Integer Vector

Description

hexToBits converts a string holding hexadecimal digits to a sequence of integers 0 or 1, for the bits. This is mainly for for use within showQCTests().

Usage

hexToBits(hex)

Arguments

Value

An integer vector holding the bits as values 0 or 1. The inverse of 'mathematical' order is used, as is the case for the base R function rawToBits(); see the “Examples”.

Author(s)

Jaimie Harbin and Dan Kelley

Examples

library(argoFloats)
hexToBits('3')    # 1 1 0 0
hexToBits('4000') # 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0

A Sample Index of Profiles

Description

This was created by subsetting a global index to the Argo profiles that were within a 200km radius of Marsh Harbour, Abaco Island, Bahamas, using the following code.

indexAll <- getIndex()
index <- subset(indexAll,
    circle=list(longitude=-77.06, latitude=26.54, radius=200))

Caveat about out-of-date index files

Note that the NetCDF files on Argo repositories are changeable, not just in content, but also in file name. For example, the data acquired in a given profile of a given float may initially be provided in real-time mode (with a file name containing an "R" as the first or second character), but later be replaced later with a delayed-mode file (with a "D" in the first or second character). Since index files name data files directly, this means that index files can become out-of-date, containing references to netcdf files that no longer exist on the server. This applies to the sample index files provided with this package, and to user files, and it explains why getProfiles() skips over files that cannot be downloaded.

See Also

Other datasets provided with argoFloats: indexBgc, indexDeep, indexSynthetic

Examples

library(argoFloats)
data(index)
plot(index, bathymetry=FALSE)

A Sample Index of Biogeochemical-Argo Profiles

Description

This was created by subsetting a global index to the BGC Argo profiles that were within a 300km radius of Marsh Harbour, Abaco Island, Bahamas, using the following code.

library(argoFloats)
indexAll <- getIndex("bgc")
indexBgc <- subset(indexAll,
    circle=list(longitude=-77.06, latitude=26.54, radius=300))

Caveat about out-of-date index files

Note that the NetCDF files on Argo repositories are changeable, not just in content, but also in file name. For example, the data acquired in a given profile of a given float may initially be provided in real-time mode (with a file name containing an "R" as the first or second character), but later be replaced later with a delayed-mode file (with a "D" in the first or second character). Since index files name data files directly, this means that index files can become out-of-date, containing references to netcdf files that no longer exist on the server. This applies to the sample index files provided with this package, and to user files, and it explains why getProfiles() skips over files that cannot be downloaded.

See Also

Other datasets provided with argoFloats: indexDeep, indexSynthetic, index

Examples

library(argoFloats)
data(indexBgc)
plot(indexBgc, bathymetry=FALSE)
summary(indexBgc)
unique(indexBgc[["parameters"]])

A Sample Index of Deep Argo

Description

This was created by subsetting a global index to the deep Argo profiles that were within a 800km radius of Antarctica (67S,105E), using the following code.

library(argoFloats)
subset <- subset(getIndex(), deep=TRUE)
sub2 <- subset(subset, circle=list(longitude=105, latitude=-67, radius=800))

Caveat about out-of-date index files

Note that the NetCDF files on Argo repositories are changeable, not just in content, but also in file name. For example, the data acquired in a given profile of a given float may initially be provided in real-time mode (with a file name containing an "R" as the first or second character), but later be replaced later with a delayed-mode file (with a "D" in the first or second character). Since index files name data files directly, this means that index files can become out-of-date, containing references to netcdf files that no longer exist on the server. This applies to the sample index files provided with this package, and to user files, and it explains why getProfiles() skips over files that cannot be downloaded.

See Also

Other datasets provided with argoFloats: indexBgc, indexSynthetic, index

Examples

library(argoFloats)
data(indexDeep)
plot(indexDeep, bathymetry=FALSE)
summary(indexDeep)

A Sample Index of Synthetic Profiles

Description

This was created by subsetting a global index to the BGC Argo profiles that were within a 300km radius of Marsh Harbour, Abaco Island, Bahamas, using the following code.

library(argoFloats)
indexAll <- getIndex("synthetic")
indexSynthetic <- subset(indexAll,
    circle=list(longitude=-77.06, latitude=26.54, radius=300))

This "synthetic" type of index is a replacement for the older "merged" index. See ⁠http://www.argodatamgt.org/Data-Mgt-Team/News/BGC-Argo-synthetic-profiles-distributed-on-GDAC⁠ for more on the data file format, the reasons for the change, and the timetable for the transition from "merged".

Caveat about out-of-date index files

Note that the NetCDF files on Argo repositories are changeable, not just in content, but also in file name. For example, the data acquired in a given profile of a given float may initially be provided in real-time mode (with a file name containing an "R" as the first or second character), but later be replaced later with a delayed-mode file (with a "D" in the first or second character). Since index files name data files directly, this means that index files can become out-of-date, containing references to netcdf files that no longer exist on the server. This applies to the sample index files provided with this package, and to user files, and it explains why getProfiles() skips over files that cannot be downloaded.

See Also

Other datasets provided with argoFloats: indexBgc, indexDeep, index

Examples

library(argoFloats)
data(indexSynthetic)
plot(indexSynthetic, bathymetry=FALSE)
summary(indexSynthetic)
unique(indexSynthetic[["parameters"]])

Interactive App For Viewing Argo Float Positions

Description

mapApp() sets up an interactive "shiny app" session for exploring the spatial-temporal distribution of Argo profiles. The graphical user interface (GUI) is meant to be reasonably self-explanatory, and a button labelled Help yields a pop-up window with more information that might not be evident at first glance. A number of keystrokes exist to assist the user including:
u: undo previous actions
i: zoom in
o: zoom out
n: go north
e: go east
s: go south
w: go west
f: go forward in time
b: go backward in time
r: reset to initial state
h: hold active hover message (press h again to undo)
0: unzoom an area
d: toggle debugging flag
More details are provided in the rest of this documentation page, and in Section 4 of Kelley et al. (2021).

Usage

mapApp(
  age = argoDefaultIndexAge(),
  server = argoDefaultServer(),
  destdir = argoDefaultDestdir(),
  colLand = "lightgray",
  debug = 0
)

Arguments

Details

mapApp() uses getIndex() to download index files from an Argo server the first time it runs. This can be slow, taking a minute or more, depending on the internet connection and load on the server. Once the index files are downloaded, mapApp() categorizes profiles as Core, BGC, or Deep (which may be displayed in any combination, using GUI elements).

The hi-res button will only affect the coastline, not the topography, unless there is a local file named topoWorldFine.rda that contains an alternative topographic information. Here is how to create such a file:

library(oce)
topoFile <- download.topo(west=-180, east=180,
                          south=-90, north=90,
                          resolution=10,
                          format="netcdf", destdir=".")
topoWorldFine <- read.topo(topoFile)
save(topoWorldFine, file="topoWorldFine.rda")
unlink(topoFile) # clean up

Value

mapApp has no return value, since it creates a shiny app by passing control to shiny::runApp(), which never returns.

Author(s)

Dan Kelley and Jaimie Harbin

References

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

if (interactive()) {
    library(argoFloats)
    mapApp()
}

Merge argoFloats Indices

Description

Merge argoFloats Indices

Usage

## S4 method for signature 'argoFloats'
merge(x, y, ...)

Arguments

Value

An argoFloats object of type index.

Author(s)

Dan Kelley

Examples

library(argoFloats)
data(index)

# Index of floats within 50km of Abaca Island
C <- subset(index, circle=list(longitude=-77.5, latitude=27.5, radius=50))

# Index of floats within a rectangle near Abaca Island
lonRect <- c(-76.5, -76)
latRect <- c(26.5, 27.5)
R <- subset(index, rectangle=list(longitude=lonRect, latitude=latRect))

RC <- merge(C, R)

plot(RC, bathymetry=FALSE)

Plot an argoFloats Object

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

## S4 method for signature 'argoFloats'
plot(
  x,
  which = "map",
  bathymetry = argoDefaultBathymetry(),
  geographical = 0,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL,
  type = "p",
  cex = par("cex"),
  col = par("fg"),
  pch = par("pch"),
  bg = par("bg"),
  eos = "gsw",
  mapControl = NULL,
  profileControl = NULL,
  QCControl = NULL,
  summaryControl = NULL,
  TSControl = NULL,
  debug = 0,
  ...
)

Arguments

Details

The various plot types are as follows.

• For which="map", a map of profile locations is created if subtype is equal to cycles, or a rectangle highlighting the trajectory of a float ID is created when subtype is equal to trajectories. This only works if the type is "index" (meaning that x was created by getIndex() or a subset of such an object, created with subset,argoFloats-method()), or argos (meaning that x was created with readProfiles(). The plot range is auto-selected. If the ocedata package is available, then its coastlineWorldFine dataset is used to draw a coastline (which will be visible only if the plot region is large enough); otherwise, if the oce package is available, then its coastlineWorld dataset is used. The bathymetry argument controls whether (and how) to draw a map underlay that shows water depth. There are three possible values for bathymetry:

  1. FALSE (the default, via argoDefaultBathymetry()), meaning not to draw bathymetry;

  2. TRUE, meaning to draw bathymetry as an image, using data downloaded with oce::download.topo(). Example 4 illustrates this, and also shows how to adjust the margins after the plot, in case there is a need to add extra graphical elements using points(), lines(), etc.

  3. A list with items controlling both the bathymetry data and its representation in the plot (see Example 4). Those items are:

     1. source, a mandatory value that is either (a) the string "auto" (the default) to use oce::download.topo() to download the data or (b) a value returned by oce::read.topo().

     2. contour, an optional logical value (with FALSE as the default) indicating whether to represent bathymetry with contours (with depths of 100m, 200m, 500m shown, along with 1km, 2km up to 10km), as opposed to an image;

     3. colormap, ignored if contour is TRUE, an optional value that is either the string "auto" (the default) for a form of GEBCO colors computed with oce::oceColorsGebco(), or a value computed with oce::colormap() applied to the bathymetry data; and

     4. palette, ignored if contour is TRUE, an optional logical value (with TRUE as the default) indicating whether to draw a depth-color palette to the right of the plot. Note that the default value for bathymetry is set by a call to argoDefaultBathymetry(), and that this second function can only handle possibilities 1 and 2 above.

• For which="profile", a profile plot is created, showing the variation of some quantity with pressure or potential density anomaly, as specified by the profileControl argument.

• For which="QC", two time-series panels are shown, with time being that recorded in the individual profile in the dataset. An additional argument named parameter must be given, to name the quantity of interest. The function only works if x is an argoFloats object created with readProfiles(). The top panel shows the percent of data flagged with codes 1 (meaning good data), 2 (probably good), 5 (changed) or 8 (estimated), as a function of time (lower axis) and (if all cycles are from a single Argo float) cycle number (upper axis, with smaller font). Thus, low values on the top panel reveal profiles that are questionable. Note that if all of data at a given time have flag 0, meaning not assessed, then a quality of 0 is plotted at that time. The bottom panel shows the mean value of the parameter in question regardless of the flag value.

• For which="summary", one or more time-series panels are shown in a vertical stack. If there is only one ID in x, then the cycle values are indicated along the top axis of the top panel. The choice of panels is set by the summaryControl argument.

• For which="TS", a TS plot is created, by calling plotArgoTS() with the specified x, xlim, ylim, xlab, ylab, type, cex, col, pch, bg, eos, and TSControl, along with debug-1. See the help for plotArgoTS() for how these parameters are interpreted.

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

# Example 1: map profiles in index
library(argoFloats)
data(index)
plot(index)

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

Plot a TS diagram for an argoFloats object

Description

Plot a TS diagram for an argoFloats object that was created with readProfiles(). This function is called by plot,argoFloats-method(), but may also be called directly.

Usage

plotArgoTS(
  x,
  xlim = NULL,
  ylim = NULL,
  type = "p",
  cex = 1,
  col = NULL,
  pch = 1,
  bg = "white",
  eos = "gsw",
  TSControl = NULL,
  debug = 0,
  ...
)

Arguments

Author(s)

Dan Kelley and Jaimie Harbin

References

1. Argo Data Management. “Argo User’s Manual.” Ifremer, July 5, 2022. https://doi.org/10.13155/29825.

Read Argo Profiles From Local Files

Description

This works with either a vector of NetCDF files, or a argoFloats object of type "profiles", as created by getProfiles(). During the reading, argo profile objects are created with oce::read.argo() or a replacement function provided as the FUN argument.

Usage

readProfiles(
  profiles,
  FUN,
  destdir = argoDefaultDestdir(),
  quiet = FALSE,
  debug = 0
)

Arguments

Details

By default, warnings are issued about any profiles in which 10 percent or more of the measurements are flagged with a quality-control code of 0, 3, 4, 6, 7, or 9 (see the applyQC() documentation for the meanings of these codes). For more on this function, see section 2 of Kelley et al. (2021).

Value

An argoFloats object with type="argos", in which the data slot contains a list named argos that holds objects that are created by oce::read.argo().

Author(s)

Dan Kelley

References

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

# Read from a local file
f <- system.file("extdata", "SR2902204_131.nc", package="argoFloats")
p <- readProfiles(f)

Show Information About argoFloats Object

Description

This produces a one-line explanation of the contents of the object, that typically indicates the type and the number of items referenced by the object. Those items depend on the type of object: URLs if metadata$type is "index", local filenames if "profiles", or oce-created argo objects if "argos". As with other R show() methods, it may be invoked in an interactive session just by typing the object, or by using print(); see the Examples.

Usage

## S4 method for signature 'argoFloats'
show(object)

Arguments

Value

None (invisible NULL).

Author(s)

Jaimie Harbin

Examples

library(argoFloats)
data(index)
show(index)
print(index)
index

Show Real-Time QC Test Results For an Argo Object

Description

showQCTests prints a summary of the quality-control (QC) tests (if any) that were performed on an Argo profile in real-time (Caution: any tests completed and/or failed on delayed mode data are not recorded. This function also assumes tests performed or failed are recorded once, otherwise it produces a warning). It uses hexToBits() to decode the hexadecimal values that may be stored in historyQCTest. From there it pairs the determined test values with the appropriate actions, QC Tests performed or QC Tests failed, found in historyAction within the metadata slot of an individual Argo profile, as read directly with oce::read.argo() or indirectly with readProfiles(), the latter being illustrated in the “Examples” section below. The “Details” section provides an explanation of how showQCTests works at a low level, as an adjunct to the Argo documentation. See section 3.3 of Kelley et al. (2021) for more on this function.

Usage

showQCTests(x, style = "brief")

Arguments

Details

The format used in the historyQCTest and historyAction elements of the metadata slot of an oce::argo object is mentioned in Sections 2.2.7, 2.3.7, 5.1, 5.3 and 5.4 of reference 1, in which they are called HISTORY_QCTEST and HISTORY_ACTION, respectively. Both of these things are vectors of character values, with the entries within historyAction providing names for the entries within historyQCTest.

In the context of showQCTests, the focus is on the element of historyAction that equals "QCP$" (which maps to the element of historyQCTest that specifies the QC tests that were performed) and "QCF$" (which maps to the results of those tests). These mapped elements are character values providing hexadecimal digits that are decoded with hexToBits(), possibly after lengthening the historyQCTest value matching"QCF$" by adding "0" digits on the left to make the length be the same as that of the historyQCTest value matching '"QCP$".

The bits decoded from the relevant elements of historyQCTest correspond to QC tests as indicated in the following table. This is based on Table 11 of reference 1, after correcting the "Number" for test 18 from 261144 to 262144, because the former is not an integral power of 2, suggesting a typo in the manual (since the whole point of the numerical scheme is that the individual bits map to individual tests).

Value

This function returns nothing; its action is in the printing of results.

Author(s)

Jaimie Harbin and Dan Kelley

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)
a <- readProfiles(system.file("extdata", "D4900785_048.nc", package="argoFloats"))
showQCTests(a[[1]])

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

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

Summarize an argoFloats Object

Description

Show some key facts about an argoFloats object.

Usage

## S4 method for signature 'argoFloats'
summary(object, ...)

Arguments

Value

None (invisible NULL).

Author(s)

Dan Kelley

Examples

library(argoFloats)
data(index)
summary(index)

Switch [[ and Plot to Focus on Adjusted Data, if Available

Description

useAdjusted returns a copy of an argoFloats object within which the individual oce::argo objects may have been modified so that future calls to [[,argoFloats-method or plot,argoFloats-method will focus with adjusted versions of the data. (Note that this modification cannot be done for fields that lack adjusted values, so in such cases future calls to [[,argoFloats-method or plot,argoFloats-method work with the unadjusted fields.) The procedure is done profile by profile and parameter by parameter. The fallback argument offers a way to ”fall back” to unadjusted values, depending on the data-mode (real-time, adjusted or delayed) for individual items; see “Details”.

Usage

useAdjusted(argos, fallback = FALSE, debug = 0)

Arguments

Details

There are two cases. First, if fallback is FALSE (which the default) then the focus switches entirely to the adjusted data. This improves the overall reliability of the results, but at the cost of eliminating real-time data. This is because the adjusted fields for real-time data are set to NA as a matter of policy (see section 2.2.5 of reference 1).

Wider data coverage is obtained if fallback is TRUE. In this case, the focus is shifted to adjusted data only if the data-mode for the individual profiles is A or D, indicating either Adjusted or Delayed mode. Any profiles that are of the R (Realtime) data-mode are left unaltered. This blending of adjusted and unadjusted data offers improved spatial and temporal coverage, while reducing the overall data quality, and so this approach should be used with caution. For more on this function see section 3.4 of Kelley et. al (2021).

Value

useAdjusted returns an argoFloats object that is similar to its first argument, but which is set up so that future calls to [[,argoFloats-method or plot,argoFloats-method will focus on the "adjusted" data stream.

Author(s)

Dan Kelley, Jaimie Harbin and Clark Richards

References

1. Argo Data Management Team. "Argo User's Manual V3.4," January 20, 2021. ⁠https://archimer.ifremer.fr/doc/00187/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)
file <- "SD5903586_001.nc"
raw <- readProfiles(system.file("extdata", file, package="argoFloats"))
adj <- useAdjusted(raw)
# Autoscale with adjusted values so frame shows both raw and adjusted.
plot(adj, which="profile", profileControl=list(parameter="oxygen"), pch=2)
points(raw[[1]][["oxygen"]], raw[[1]][["pressure"]], pch=1)
legend("bottomright", pch=c(2,1), legend=c("Raw", "Adjusted"))