<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><title>Read an Argo Data File — read.argo • oce</title><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../deps/font-awesome-6.4.2/css/all.min.css" rel="stylesheet"><link href="../deps/font-awesome-6.4.2/css/v4-shims.min.css" rel="stylesheet"><script src="../deps/headroom-0.11.0/headroom.min.js"></script><script src="../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../deps/search-1.0.0/fuse.min.js"></script><script src="../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="Read an Argo Data File — read.argo"><meta name="description" content="read.argo is used to read an Argo file, producing an argo object.
The file must be in the ARGO-style NetCDF format described
in the Argo documentation (see references 2 and 3)."><meta property="og:description" content="read.argo is used to read an Argo file, producing an argo object.
The file must be in the ARGO-style NetCDF format described
in the Argo documentation (see references 2 and 3)."></head><body>
    <a href="#main" class="visually-hidden-focusable">Skip to contents</a>


    <nav class="navbar navbar-expand-lg fixed-top bg-light" data-bs-theme="light" aria-label="Site navigation"><div class="container">

    <a class="navbar-brand me-2" href="../index.html">oce</a>

    <small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">1.8-4</small>


    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>

    <div id="navbar" class="collapse navbar-collapse ms-3">
      <ul class="navbar-nav me-auto"><li class="active nav-item"><a class="nav-link" href="../reference/index.html">Reference</a></li>
<li class="nav-item dropdown">
  <button class="nav-link dropdown-toggle" type="button" id="dropdown-articles" data-bs-toggle="dropdown" aria-expanded="false" aria-haspopup="true">Articles</button>
  <ul class="dropdown-menu" aria-labelledby="dropdown-articles"><li><a class="dropdown-item" href="../articles/A_oce.html">1. Introduction to Oce</a></li>
    <li><a class="dropdown-item" href="../articles/B_ctd.html">2. Analysis of CTD data</a></li>
    <li><a class="dropdown-item" href="../articles/C_adp.html">3. Analysis of acoustic-Doppler data</a></li>
    <li><a class="dropdown-item" href="../articles/D_map_projections.html">4. Using map projections</a></li>
    <li><a class="dropdown-item" href="../articles/E_flags.html">5. Dealing with data-quality flags</a></li>
    <li><a class="dropdown-item" href="../articles/F_subclassing.html">6. Subclassing oce objects</a></li>
    <li><a class="dropdown-item" href="../articles/G_altering_defaults.html">7. Altering oce Defaults</a></li>
    <li><a class="dropdown-item" href="../articles/H_tides.html">8. Tidal Analysis</a></li>
  </ul></li>
<li class="nav-item"><a class="nav-link" href="../news/index.html">Changelog</a></li>
      </ul><ul class="navbar-nav"><li class="nav-item"><form class="form-inline" role="search">
 <input class="form-control" type="search" name="search-input" id="search-input" autocomplete="off" aria-label="Search site" placeholder="Search for" data-search-index="../search.json"></form></li>
<li class="nav-item"><a class="external-link nav-link" href="https://github.com/dankelley/oce/" aria-label="GitHub"><span class="fa fab fa-github fa-lg"></span></a></li>
      </ul></div>


  </div>
</nav><div class="container template-reference-topic">
<div class="row">
  <main id="main" class="col-md-9"><div class="page-header">

      <h1>Read an Argo Data File</h1>
      <small class="dont-index">Source: <a href="https://github.com/dankelley/oce/blob/HEAD/R/argo.R" class="external-link"><code>R/argo.R</code></a></small>
      <div class="d-none name"><code>read.argo.Rd</code></div>
    </div>

    <div class="ref-description section level2">
    <p><code>read.argo</code> is used to read an Argo file, producing an <a href="argo-class.html">argo</a> object.
The file must be in the ARGO-style NetCDF format described
in the Argo documentation (see references 2 and 3).</p>
    </div>

    <div class="section level2">
    <h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">read.argo</span><span class="op">(</span></span>
<span>  <span class="va">file</span>,</span>
<span>  encoding <span class="op">=</span> <span class="cn">NA</span>,</span>
<span>  debug <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/options.html" class="external-link">getOption</a></span><span class="op">(</span><span class="st">"oceDebug"</span><span class="op">)</span>,</span>
<span>  <span class="va">processingLog</span>,</span>
<span>  <span class="va">...</span></span>
<span><span class="op">)</span></span></code></pre></div>
    </div>

    <div class="section level2">
    <h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>


<dl><dt id="arg-file">file<a class="anchor" aria-label="anchor" href="#arg-file"></a></dt>
<dd><p>A character string giving the name of the file to load.</p></dd>


<dt id="arg-encoding">encoding<a class="anchor" aria-label="anchor" href="#arg-encoding"></a></dt>
<dd><p>ignored.</p></dd>


<dt id="arg-debug">debug<a class="anchor" aria-label="anchor" href="#arg-debug"></a></dt>
<dd><p>A flag that turns on debugging.  Set to 1 to get a moderate amount
of debugging information, or to 2 to get more.</p></dd>


<dt id="arg-processinglog">processingLog<a class="anchor" aria-label="anchor" href="#arg-processinglog"></a></dt>
<dd><p>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.)</p></dd>


<dt id="arg--">...<a class="anchor" aria-label="anchor" href="#arg--"></a></dt>
<dd><p>additional arguments, passed to called routines.</p></dd>

</dl></div>
    <div class="section level2">
    <h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>
    <p><code>read.argo</code> returns an <a href="argo-class.html">argo</a> object.</p>
    </div>
    <div class="section level2">
    <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
    <p>See the Argo documentation (see references 2 and 3) for some details on what files contain.
Many items listed in section 2.2.3 of reference 3 are read from the
file and stored in the <code>metadata</code> slot, with the exception of
<code>longitude</code> and <code>latitude</code>, which are stored in the
<code>data</code> slot, alongside hydrographic information.  The details of storage
in the return value are somewhat complex, although the following notes
might be helpful to readers seeking to learn more.</p>
<p><em>1. Variable renaming.</em></p>
<p>The names of several data parameters stored within the NetCDF file
are altered to fit the oce context. For example, <code>PRES</code> becomes <code>pressure</code>,
matching the name of this variable in other oce data types.
The original names are reported by <code>summary,argo-method</code>, and
data may be extracted with <code>[[,argo-method</code> using those names, so
the renaming should not be too inconvenient to Argo experts who
are new to oce.</p>
<p>Argo NetCDF files employ a <code>"SNAKE_CASE"</code> naming scheme (sometimes
using lower case) that is inconsistent with the <code>"camelCase"</code> scheme
used in oce. Since argo objects are just a small part of oce, a decision
was made to rename argo items. For example, <code>"CYCLE_NUMBER"</code> in the NetCDF file
becomes <code>"cycleNumber"</code> in the oce object returned by <code>read.argo</code>.
(Note that <code>[[,argo-method</code> also accepts <code>"cycle"</code> for this item.)
The conversion for objects in the <code>data</code> slot often also involves
expanding on argo abbreviations, e.g. <code>"PSAL"</code> becomes <code>"salinity"</code>.
The renaming work is carried out with <code><a href="argoNames2oceNames.html">argoNames2oceNames()</a></code> for
handles both name expansion for several dozen special cases,
and with <code><a href="snakeToCamel.html">snakeToCamel()</a></code> with the <code>specialCase</code> argument
set to <code>"QC"</code>. While this results in variable names that should make
sense in the general oce context (where, for example, salinity is expected
to be stored in a variable named <code>"salinity"</code>), it may be confusing
to argo experts who are just starting to use oce.  Such people might
find it helpful to use e.g. <code>sort(names(x[["metadata"]]))</code> to get a list
of all items in the <code>metadata</code> slot (or similar with <code>"data"</code>), since working
in reverse may be easier than simply guessing at what names oce has chosen.
(Note that prior to 2020 June 24, some metadata items were stored in
<code>"SNAKE_CASE"</code>.)</p>
<p><em>2. Metadata.</em></p>
<p>Several of the NetCDF global attributes are also renamed before
placement in the <code>metadata</code> slot of the return value.  These include
<code>conventions</code>, <code>featureType</code>, <code>history</code>, <code>institution</code>,
<code>nParameters</code>, <code>nProfiles</code>,  <code>references</code>, <code>source</code>, <code>title</code>,
and <code>userManualVersion</code>.
These names are derived from those in the NetCDF
file, and mainly follow the pattern explained in the
“Variable renaming convention” section.</p>
<p>For profile data (as indicated by the NetCDF global attribute
named <code>"featureType"</code> being equal to <code>"trajectoryProfile"</code>),
the NetCDF item named <code>"STATION_PARAMETERS"</code> controls
whether variables in the source file will be stored in the
<code>metadata</code> or <code>data</code> slot of the returned object.
If <code>STATION_PARAMETERS</code> is not present, as is the case for
trajectory files (which are detected by <code>featureType</code> being
<code>"trajectory"</code>), some guesses are made as to what goes in
<code>data</code> and <code>metadata</code> slots.</p>
<p><em>3. Data variants.</em></p>
<p>Each data item can have variants, as
described in Sections 2.3.4 of reference 3.
For example, if <code>"PRES"</code> is found in <code>STATION_PARAMETERS</code>,
then <code>PRES</code> (pressure) data are sought in the file, along with
<code>PRES_QC</code>, <code>PRES_ADJUSTED</code>, <code>PRES_ADJUSTED_QC</code>, and
<code>PRES_ERROR</code>. The same pattern works for other profile data. The variables
are stored with names created as explained in the
“Variable renaming convention” section below. Note that
flags, which are stored variables ending in <code>"_QC"</code> in the NetCDF
file, are stored in the <code>flags</code> item within the <code>metadata</code> slot
of the returned object; thus, for example,
<code>PRES_QC</code> is stored as <code>pressure</code> in <code>flags</code>.</p>
<p><em>4. How time is handled.</em></p>
<p>The NetCDF files for profile data store time in an item named <code>juld</code>,
which holds the overall profile time, in what the Argo documentation
calls Julian days, with respect to a reference time that is also stored
in the file.  Based on this information, a <a href="https://rdrr.io/r/base/DateTimeClasses.html" class="external-link">POSIXct</a> value named <code>time</code>
is stored in the <code>metadata</code> slot of the returned value, and this
may be found with e.g. <code>a[["time"]]</code>, where <code>a</code> is that returned value.
Importantly, this value matches the time listed in profile index files.
In addition, some profile data files contain a field called <code>MTIME</code>,
which holds the offset (in days) between the time of individual measurements and the
overall profile time. For such files, the measurement times may be
computed with <code>a[["time"]]+86400*a[["mtime"]]</code>. (This formula is used by
<code><a href="as.ctd.html">as.ctd()</a></code>, if its first argument is an <a href="argo-class.html">argo</a> object created
by supplying <code>read.argo()</code> with such a data file.)</p>
<p><em>5. Data sources.</em></p>
<p>Argo data are made available at several websites. A bit of detective
work can be required to track down the data.</p>
<p>Some servers provide data for floats that surfaced in a given ocean
on a given day, the anonymous FTP server
<code>usgodae.org/pub/outgoing/argo/geo/</code> being an example.</p>
<p>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,
<code>https://www.usgodae.org/ftp/outgoing/argo/</code> 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
<code>https://www.usgodae.org/ftp/outgoing/argo/ar_index_global_meta.txt</code>
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
(<code>/</code>). The dac is in the first such column and the float ID in the
second. A simple search will reveal the dac.
For example <code>data(argo)</code> is based on float 6900388, and the line
containing that token is
<code>bodc/6900388/6900388_meta.nc,846,BO,20120225005617</code>, from
which the dac is seen to be the British Oceanographic Data Centre
(<code>bodc</code>). Armed with that information, visit
<code>https://www.usgodae.org/ftp/outgoing/argo/dac/bodc/6900388</code>
and see a directory called <code>profiles</code> that contains a NetCDF
file for each profile the float made. These can be read with
<code>read.argo</code>. It is also possible, and probably more common,
to read a NetCDF file containing all the profiles together and for
that purpose the file
<code>https://www.usgodae.org/ftp/outgoing/argo/dac/bodc/6900388/6900388_prof.nc</code>
should be downloaded and provided as the <code>file</code> argument to
<code>read.argo</code>.  This can be automated as in Example 2,
although readers are cautioned that URL structures tend to change
over time.</p>
<p>Similar steps can be followed on other servers.</p>
    </div>
    <div class="section level2">
    <h2 id="sample-of-usage">Sample of Usage<a class="anchor" aria-label="anchor" href="#sample-of-usage"></a></h2>


<div class="sourceCode"><pre><code><span></span>
<span><span class="co"># Example 1: read from a local file</span></span>
<span><span class="kw"><a href="https://rdrr.io/r/base/library.html" class="external-link">library</a></span><span class="op">(</span><span class="va"><a href="https://dankelley.github.io/oce/">oce</a></span><span class="op">)</span></span>
<span><span class="va">d</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/read.argo.html">read.argo</a></span><span class="op">(</span><span class="st">"~/data/OAR/6900388_prof.nc"</span><span class="op">)</span></span>
<span><span class="fu"><a href="https://rdrr.io/r/base/summary.html" class="external-link">summary</a></span><span class="op">(</span><span class="va">d</span><span class="op">)</span></span>
<span><span class="fu"><a href="https://rdrr.io/r/graphics/plot.default.html" class="external-link">plot</a></span><span class="op">(</span><span class="va">d</span><span class="op">)</span></span>
<span></span>
<span><span class="co"># Example 2: construct URL for download (brittle)</span></span>
<span><span class="va">id</span> <span class="op">&lt;-</span> <span class="st">"6900388"</span></span>
<span><span class="va">url</span> <span class="op">&lt;-</span> <span class="st">"https://www.usgodae.org/ftp/outgoing/argo"</span></span>
<span><span class="kw">if</span> <span class="op">(</span><span class="op">!</span><span class="fu"><a href="https://rdrr.io/r/base/length.html" class="external-link">length</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/list.files.html" class="external-link">list.files</a></span><span class="op">(</span>pattern<span class="op">=</span><span class="st">"argo_index.txt"</span><span class="op">)</span><span class="op">)</span><span class="op">)</span></span>
<span>    <span class="fu"><a href="https://rdrr.io/r/utils/download.file.html" class="external-link">download.file</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/paste.html" class="external-link">paste</a></span><span class="op">(</span><span class="va">url</span>, <span class="st">"ar_index_global_meta.txt"</span>, sep<span class="op">=</span><span class="st">"/"</span><span class="op">)</span>, <span class="st">"argo_index.txt"</span><span class="op">)</span></span>
<span><span class="va">index</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/readLines.html" class="external-link">readLines</a></span><span class="op">(</span><span class="st">"argo_index.txt"</span><span class="op">)</span></span>
<span><span class="va">line</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/grep.html" class="external-link">grep</a></span><span class="op">(</span><span class="va">id</span>, <span class="va">index</span><span class="op">)</span></span>
<span><span class="kw">if</span> <span class="op">(</span><span class="fl">0</span> <span class="op">==</span> <span class="fu"><a href="https://rdrr.io/r/base/length.html" class="external-link">length</a></span><span class="op">(</span><span class="va">line</span><span class="op">)</span><span class="op">)</span></span>
<span>    <span class="kw"><a href="https://rdrr.io/r/base/stop.html" class="external-link">stop</a></span><span class="op">(</span><span class="st">"id "</span>, <span class="va">id</span>, <span class="st">" not found"</span><span class="op">)</span></span>
<span><span class="kw">if</span> <span class="op">(</span><span class="fl">1</span> <span class="op">&lt;</span> <span class="fu"><a href="https://rdrr.io/r/base/length.html" class="external-link">length</a></span><span class="op">(</span><span class="va">line</span><span class="op">)</span><span class="op">)</span></span>
<span>    <span class="kw"><a href="https://rdrr.io/r/base/stop.html" class="external-link">stop</a></span><span class="op">(</span><span class="st">"id "</span>, <span class="va">id</span>, <span class="st">" found multiple times"</span><span class="op">)</span></span>
<span><span class="va">dac</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/strsplit.html" class="external-link">strsplit</a></span><span class="op">(</span><span class="va">index</span><span class="op">[</span><span class="va">line</span><span class="op">]</span>, <span class="st">"/"</span><span class="op">)</span><span class="op">[[</span><span class="fl">1</span><span class="op">]</span><span class="op">]</span><span class="op">[</span><span class="fl">1</span><span class="op">]</span></span>
<span><span class="va">profile</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/paste.html" class="external-link">paste</a></span><span class="op">(</span><span class="va">id</span>, <span class="st">"_prof.nc"</span>, sep<span class="op">=</span><span class="st">""</span><span class="op">)</span></span>
<span><span class="va">float</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/paste.html" class="external-link">paste</a></span><span class="op">(</span><span class="va">url</span>, <span class="st">"dac"</span>, <span class="va">dac</span>, <span class="va">id</span>, <span class="va">profile</span>, sep<span class="op">=</span><span class="st">"/"</span><span class="op">)</span></span>
<span><span class="fu"><a href="https://rdrr.io/r/utils/download.file.html" class="external-link">download.file</a></span><span class="op">(</span><span class="va">float</span>, <span class="va">profile</span><span class="op">)</span></span>
<span><span class="va">argo</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/read.argo.html">read.argo</a></span><span class="op">(</span><span class="va">profile</span><span class="op">)</span></span>
<span><span class="fu"><a href="https://rdrr.io/r/base/summary.html" class="external-link">summary</a></span><span class="op">(</span><span class="va">argo</span><span class="op">)</span></span></code></pre></div>

    </div>
    <div class="section level2">
    <h2 id="references">References<a class="anchor" aria-label="anchor" href="#references"></a></h2>

<ol><li><p><code>https://argo.ucsd.edu</code></p></li>
<li><p>Argo User's Manual Version 3.2, Dec 29th, 2015, available at
<code>https://archimer.ifremer.fr/doc/00187/29825/</code> online.</p></li>
<li><p>User's Manual (ar-um-02-01) 13 July 2010, available at
<code>http://www.argodatamgt.org/content/download/4729/34634/file/argo-dm-user-manual-version-2.3.pdf</code>,
which is the main document describing argo data.</p></li>
</ol></div>
    <div class="section level2">
    <h2 id="see-also">See also<a class="anchor" aria-label="anchor" href="#see-also"></a></h2>
    <div class="dont-index"><p>The documentation for the <a href="argo-class.html">argo</a> class explains the structure of argo
objects, and also outlines the other functions dealing with them.</p>
<p>Other things related to argo data:
<code><a href="sub-sub-argo-method.html">[[,argo-method</a></code>,
<code>[[&lt;-,argo-method</code>,
<code><a href="argo.html">argo</a></code>,
<code><a href="argo-class.html">argo-class</a></code>,
<code><a href="argoGrid.html">argoGrid</a>()</code>,
<code><a href="argoNames2oceNames.html">argoNames2oceNames</a>()</code>,
<code><a href="as.argo.html">as.argo</a>()</code>,
<code><a href="handleFlags-argo-method.html">handleFlags,argo-method</a></code>,
<code><a href="plot-argo-method.html">plot,argo-method</a></code>,
<code><a href="read.argo.copernicus.html">read.argo.copernicus</a>()</code>,
<code><a href="subset-argo-method.html">subset,argo-method</a></code>,
<code><a href="summary-argo-method.html">summary,argo-method</a></code></p></div>
    </div>
    <div class="section level2">
    <h2 id="author">Author<a class="anchor" aria-label="anchor" href="#author"></a></h2>
    <p>Dan Kelley</p>
    </div>

  </main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
    </nav></aside></div>


    <footer><div class="pkgdown-footer-left">
  <p>Developed by Dan Kelley, Clark Richards.</p>
</div>

<div class="pkgdown-footer-right">
  <p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.1.0.9000.</p>
</div>

    </footer></div>





  </body></html>

