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

View source: R/get.R

getProfilesR Documentation

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

index

an argoFloats object of type "index", as created by getIndex().

destdir

character value indicating the directory in which to store downloaded files. The default value is to compute this using argoDefaultDestdir(), which returns ⁠~/data/argo⁠ by default, although it also provides ways to set other values using options(). 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

Option 1) a numerical value indicating a time interval, in days. If the file to be downloaded from the server already exists locally, and was created is less than age days in the past, it will not be downloaded. The default is one year. Setting age=0 will force a download. Option 2) "latest" meaning the file will only be downloaded if A) the file doesn't exist or B) the file does exist and the time it was created is older than the date_update in the index file

retries

integer telling how many times to retry a download, if the first attempt fails.

skip

A logical value indicating whether to skip over netcdf files that cannot be downloaded from the server. This is FALSE by default, so that getProfiles() will raise an error if it is impossible to re-download an outdated file. This is not unexpected with built-in index files, e.g. data(index), because this package cannot be updated every time the Argo servers change the names of netcdf files. However, users are commonly working with index files they created with getIndex(), so they ought to be up-to-date.

quiet

logical value; use FALSE to show more verbose information when downloading files. (Even if quiet is TRUE, problems will still be reported.)

debug

integer value indicating level of debugging. If this is less than 1, no debugging is done. Otherwise, some functions will print debugging information. If a function call fails, the first step should be to rerun the function with debug=1, to see if the output suggests a problem in the call.

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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3389/fmars.2021.635922")}


dankelley/argoFloats documentation built on April 18, 2024, 5:13 a.m.