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

Metadata items such as `time`, `longitude` and `latitude` are inferred from the data file in a straightforward way, using `ncvar_get` and data-variable names as listed in the Argo documentation [2,3]. The items listed in section 2.2.3 of [3] is read from the file and stored in the `metadata` slot, with the exception of `longitude` and `latitude`, which are stored in the `data` slot.

String data that contain trailing blanks in the argo NetCDF are trimmed using `trimString`. One-dimensional matrices are converted to vectors using `as.vector`. Items listed in section 2.2.3 of [3] are meant to be present in all files, but tests showed that this is not the case, and so `read.argo` sets such items to `NULL` before saving them in returned object.

Items are translated from upper-case Argo names to `oce` names using `decodeDataNamesArgo`.

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.

### 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, http://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 http://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 http://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 http://archimer.ifremer.fr/doc/00187/29825/40575.pdf (link checked 17 Nov 2016 several times in the months before, but failed 18 Nov 2016). Table 2.2.2 of this document lists the codes used in Argo netCDF files.

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 (link checked on 17 Nov 2016). This 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`, `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 <- "http://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 0.9-20 Index]