oce (version 1.1-1)

read.argo: Read an Argo Data File

Description

read.argo is used to read an Argo file, producing an object of type argo. The file must be in the ARGO-style NetCDF format described at in the Argo documentation [2,3].

Usage

read.argo(file, debug = getOption("oceDebug"), processingLog, ...)

Arguments

file

a character string giving the name of the file to load.

debug

a flag that turns on debugging. Set to 1 to get a moderate amount of debugging information, or to 2 to get more.

processingLog

if provided, the action item to be stored in the log. (Typically only provided for internal calls; the default that it provides is better for normal calls by a user.)

...

additional arguments, passed to called routines.

Value

An object of argo-class.

Data sources

Argo data are made available at several websites. A bit of detective work can be required to track down the data.

Some servers provide data for floats that surfaced in a given ocean on a given day, the anonymous FTP server ftp://usgodae.org/pub/outgoing/argo/geo/ being an example.

Other servers provide data on a per-float basis. A complicating factor is that these data tend to be categorized by "dac" (data archiving centre), which makes it difficult to find a particular float. For example, https://www.usgodae.org/ftp/outgoing/argo/ is the top level of a such a repository. If the ID of a float is known but not the "dac", then a first step is to download the text file http://www.usgodae.org/ftp/outgoing/argo/ar_index_global_meta.txt and search for the ID. The first few lines of that file are header, and after that the format is simple, with columns separated by slash (/). The dac is in the first such column and the float ID in the second. A simple search will reveal the dac. For example data(argo) is based on float 6900388, and the line containing that token is bodc/6900388/6900388_meta.nc,846,BO,20120225005617, from which the dac is seen to be the British Oceanographic Data Centre (bodc). Armed with that information, visit https://www.usgodae.org/ftp/outgoing/argo/dac/bodc/6900388 and see a directory called `profiles` that contains a NetCDF file for each profile the float made. These can be read with read.argo. It is also possible, and probably more common, to read a NetCDF file containing all the profiles together and for that purpose the file https://www.usgodae.org/ftp/outgoing/argo/dac/bodc/6900388/6900388_prof.nc should be downloaded and provided as the file argument to read.argo. This can be automated as in Example 2, although readers are cautioned that URL structures tend to change over time.

Similar steps can be followed on other servers.

Details

Items are inferred from the data file in a straightforward way, using ncvar_get, converting from one-column matrices to vectors, and trimming leading and trailing blank space in character values, using trimString.

Items are renamed from the argo ('snake case') forms to oce ('camel case') forms with argoNames2oceNames. For example, FIRMWARE_VERSION in the data file is renamed as firmwareVersion in the return value. Note that some files use upper-case for items, while other files use lower-case for the same things; read.argo attempts to ignore this variation.

See the Argo documentation [2,3] for some details on what files contain. Many items listed in section 2.2.3 of [3] are read from the file and stored in the metadata slot, with the exception of longitude and latitude, which are stored in the data slot, alongside hydrographic information.

The following global attributes stored within the netcdf file are stored in the metadata slot: title, institution, source, history, references, userManualVersion, conventions, and featureType. These names are identical to those in the netcdf file, except that userManualVersion is named user_manual_version in the file, and conventions is named Conventions in the file.

It is assumed that the profile data are as listed in the NetCDF variable called STATION_PARAMETERS. Each item can have variants, as described in Sections 2.3.4 of [3]. For example, if "PRES" is found in STATION_PARAMETERS, then PRES (pressure) data are sought in the file, along with PRES_QC, PRES_ADJUSTED, PRES_ADJUSTED_QC, and PRES_ERROR. The same pattern works for other profile data. The variables are stored with different names within the resultant argo-class object, to match with oce conventions. Thus, PRES gets renamed pressure, while PRES_ADJUSTED gets renamed pressureAdjusted, and PRES_ERROR gets renamed pressureError; all of these are stored in the data slot. Meanwhile, the quality-control flags PRES_QC and PRES_ADJUSTED_QC are stored as pressure and pressureAdjusted in the metadata$flags slot.

Once a predefined series of items are inferred and stored in either the metadata or data slot, read.argo then reads all non-empty variables in the file, storing them in the metadata slot, using with the original ('snake case') name that is used in the data file. (Note that the sample dataset accessed with data(argo) lacks metadata items with names starting with HISTORY_, because those are zero-length in the source file.)

References

1. http://www.argo.ucsd.edu/

2. Argo User's Manual Version 3.2, Dec 29th, 2015, available at https://archimer.ifremer.fr/doc/00187/29825/40575.pdf (but note that this is a draft; newer versions may have replaced this by now).

3. User's Manual (ar-um-02-01) 13 July 2010, available at http://www.argodatamgt.org/content/download/4729/34634/file/argo-dm-user-manual-version-2.3.pdf, which is the main document describing argo data.

See Also

The documentation for argo-class explains the structure of argo objects, and also outlines the other functions dealing with them.

Other things related to argo data: [[,argo-method, [[<-,argo-method, argo-class, argoGrid, argoNames2oceNames, argo, as.argo, handleFlags,argo-method, plot,argo-method, subset,argo-method, summary,argo-method

Examples

Run this code
# NOT RUN {
## Example 1: read from a local file
library(oce)
d <- read.argo("/data/OAR/6900388_prof.nc")
summary(d)
plot(d)

## Example 2: construct URL for download (brittle)
id <- "6900388"
url <- "https://www.usgodae.org/ftp/outgoing/argo"
if (!length(list.files(pattern="argo_index.txt")))
    download.file(paste(url, "ar_index_global_meta.txt", sep="/"), "argo_index.txt")
index <- readLines("argo_index.txt")
line <- grep(id, index)
if (0 == length(line)) stop("id ", id, " not found")
if (1 < length(line)) stop("id ", id, " found multiple times")
dac <- strsplit(index[line], "/")[[1]][1]
profile <- paste(id, "_prof.nc", sep="")
float <- paste(url, "dac", dac, id, profile, sep="/")
download.file(float, profile)
argo <- read.argo(profile)
summary(argo)
# }
# NOT RUN {

# }

Run the code above in your browser using DataCamp Workspace