R: Read an Argo Data File

read.argo {oce} | R Documentation

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

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

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

### Author(s)

Dan Kelley

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

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

    ## End(Not run)

[Package oce version 1.1-1 Index]