dc.argoIndex: Get an index of available floats
In dankelley/dc: Download and Cache Data

Description Usage Arguments Details Value Author(s) See Also Examples

Downloads a file (or uses a cached file) and then reads it to create a local .rda file that stores information about available float files, as explained in “Details”. The download takes several of order 1 to 60 minutes, so this function has an age argument that lets the user avoid new downloads of data that were downloaded recently.

dc.argoIndex(
  server = "ftp://usgodae.org/pub/outgoing/argo",
  file = "ar_index_global_prof.txt.gz",
  destdir = ".",
  age = 2,
  quiet = FALSE,
  debug = getOption("dcDebug", 0)
)

`server`	character value giving the base name of the server, used in the construction of URL queries. Since servers tend to change over time, this is a good argument to check, when debugging code that once worked but now fails.
`file`	character value indicating the file on the server, also used as a pattern for the name of a constructed `.rda` file that is placed in the `destdir` directory. For the `ftp://usgodae.org/pub/outgoing/argo` server, two of multiple choices for `file` are `ar_index_global_prof.txt.gz` and `argo_bio-profile_index.txt.gz` but examination of the server will reveal other possibilities that might be worth exploring.
`destdir`	character value indicating the directory in which to store downloaded files. The default value of `"."` means to store the downloaded file in the present working directory. Set `destdir=NULL` if `destfile` is a filename with full path information. File clutter is reduced by creating a top-level directory called `data`, with subdirectories for various file types; see “Examples”.
`age`	numeric value indicating how old a downloaded file must be (in days), for it to be considered out-of-date. The default, `age=2`, limits downloads to once per day, as a way to avoid slowing down a workflow with a download that might take a sizeable fraction of an hour. Set `age=0` to force a download at any time.
`quiet`	silence some progress indicators. The default is to show such indicators.
`debug`	an integer specifying whether debugging information is to be printed during processing. The printing is done by a call to `dcDebug()`. Setting `debug=0` turns off this form of debugging, while higher values yield more information. If one `dc` function calls another, it passes the value of `debug` but decreased by 1, which means that the value of `debug` controls not just the breadth of debugging, but also the depth.

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, and from this the name of a local file is constructed by changing the suffix to .rda. If that rda file is less than the age (in days) specified by the age argument, then no downloading takes place, and dc.argoIndex() returns the name of that rda file.

However, if the local rda file is older than age days, a download is started, using curl::curl_download() from the curl package. The data file is downloaded to a local temporary file, and then the contents of that file are analysed, with the results of the analysis being stored in the local rda file.

The resultant .rda file holds a list named argoIndex that holds following elements:

ftpRoot, the FTP root stored in the header of the source file.
server, the argument provided here.
file, 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. As of files downloaded in February 2020, this has columns named file, date, longitude, latitude, ocean, profiler_type, institution, and date_update.

Note that paste0(argoIndex$ftpRoot, argoIndex$data$file) will form a vector of names of files that can be downloaded as local Netcdf files (ending in suffix .nc) that can be read with oce::read.argo() in the oce packag, creating an argo object.

A character value holding the name of the .rda file, which is typically loaded with load(); see “Examples”.

Dan Kelley

Other functions related to argo data: dc.argoById(), dc.argoSearch(), dc.argo()

## Not run: 
# Download whole index
ai <- dc.argoIndex(destdir="~/data/argo")
load(ai) # defines argoIndex
# Plot histograms of 'date' and 'date_update'
par(mfrow=c(2, 1), mar=c(3, 3, 1, 1))
hist(argoIndex$data$date, breaks="years",
     main="", xlab="Time", freq=TRUE)
hist(argoIndex$data$date_update, breaks="years",
     main="", xlab="Last Update Time", freq=TRUE)
# Download and plot the last file in the index
id <- paste0(argoIndex$ftpRoot, "/", tail(argoIndex$data$file, 1))
f <- dc.argoById(id)
library(oce)
a <- read.oce(f)
summary(a)
par(mfrow=c(2, 2))
plot(a, which="map")
mtext(a[["time"]], cex=par("cex"))
plot(a, which="TS")
plot(a, which="temperature profile")
plot(a, which="salinity profile")

## End(Not run)