<!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>Set Preference for Adjusted Values — preferAdjusted • 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="Set Preference for Adjusted Values — preferAdjusted"><meta name="description" content='argo data can contain "adjusted" forms of data items,
which may be more trustworthy than the original
data, and preferAdjusted lets the user express a preference
for such adjusted data.  This means that using
[[,argo-method on the results returned by preferAdjusted
will (if possible) return adjusted data, and also use those adjusted
data in computations of derived quantities such as Absolute Salinity.
The preference applies also to units and to data-quality flags,
both of which can be returned by [[,argo-method, as
discussed in &amp;#8220;Details&amp;#8221;.'><meta property="og:description" content='argo data can contain "adjusted" forms of data items,
which may be more trustworthy than the original
data, and preferAdjusted lets the user express a preference
for such adjusted data.  This means that using
[[,argo-method on the results returned by preferAdjusted
will (if possible) return adjusted data, and also use those adjusted
data in computations of derived quantities such as Absolute Salinity.
The preference applies also to units and to data-quality flags,
both of which can be returned by [[,argo-method, as
discussed in &amp;#8220;Details&amp;#8221;.'></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>Set Preference for Adjusted Values</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>preferAdjusted.Rd</code></div>
    </div>

    <div class="ref-description section level2">
    <p><a href="argo-class.html">argo</a> data can contain "adjusted" forms of data items,
which may be more trustworthy than the original
data, and <code>preferAdjusted</code> lets the user express a preference
for such adjusted data.  This means that using
<code><a href="sub-sub-argo-method.html">[[,argo-method</a></code> on the results returned by <code>preferAdjusted</code>
will (if possible) return adjusted data, and also use those adjusted
data in computations of derived quantities such as Absolute Salinity.
The preference applies also to units and to data-quality flags,
both of which can be returned by <code><a href="sub-sub-argo-method.html">[[,argo-method</a></code>, as
discussed in “Details”.</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">preferAdjusted</span><span class="op">(</span><span class="va">argo</span>, which <span class="op">=</span> <span class="st">"all"</span>, fallback <span class="op">=</span> <span class="cn">TRUE</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-argo">argo<a class="anchor" aria-label="anchor" href="#arg-argo"></a></dt>
<dd><p>An <a href="argo-class.html">argo</a> object.</p></dd>


<dt id="arg-which">which<a class="anchor" aria-label="anchor" href="#arg-which"></a></dt>
<dd><p>A character vector naming the items for which
(depending also on the value of <code>fallback</code>) adjusted values
are to be sought by future calls to <code><a href="sub-sub-argo-method.html">[[,argo-method</a></code>.
The short names are used, e.g. <code>which="oxygen"</code> means that
adjusted oxygen is to be returned in future calls
such as <code>argo[["oxygen"]]</code>.  The default,
<code>"all"</code>, means to  use adjusted values for any item in <code>argo</code>
that has adjusted values.</p></dd>


<dt id="arg-fallback">fallback<a class="anchor" aria-label="anchor" href="#arg-fallback"></a></dt>
<dd><p>A logical value indicating whether to fall back
to unadjusted values for any data field in which the
adjusted values are all <code>NA</code>.  The default value, <code>TRUE</code>,
avoids a problem with biogeochemical fields, where adjustment
of any one field may lead to insertion of "adjusted" values for
other fields that consist of nothing more than <code>NA</code>s.</p></dd>

</dl></div>
    <div class="section level2">
    <h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>
    <p>An <a href="argo-class.html">argo</a> object its <code>metadata</code> slot altered
(in its <code>adjustedWhich</code> and <code>adjustedFallback</code> elements)
as a signal for how <code><a href="sub-sub-argo-method.html">[[,argo-method</a></code> should
function on the object.</p>
    </div>
    <div class="section level2">
    <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
    <p><code>preferAdjusted()</code> merely sets two items in the <code>metadata</code> slot of the
returned <a href="argo-class.html">argo</a> object. The real action is carried out by
<code><a href="sub-sub-argo-method.html">[[,argo-method</a></code> but, for convenience, the details are explained here.</p>
<p>Consider salinity, for example.
If <code>which</code> equals <code>"all"</code>, or if it is a character
vector containing <code>"salinity"</code>, then using
<code><a href="sub-sub-argo-method.html">[[,argo-method</a></code> on the returned object
will yield the adjusted forms of the salinity data,
its associated flags, or its units.  Thus, in the salinity
case,</p><ul><li><p><code>argo[["salinity"]]</code> will attempt to return <code>argo@data$salinityAdjusted</code>
instead of returning <code>argo@data$salinity</code>, although if the adjusted values
are all <code>NA</code> then, depending on the value of <code>fallback</code>, the
unadjusted values may be returned; similarly</p></li>
<li><p><code>argo[["salinityFlags"]]</code> will attempt to return
<code>argo@metadata$flags$salinityAdjusted</code>
instead of <code>argo@metadata$flags$salinity</code>, and</p></li>
<li><p><code>argo[["salinityUnits"]]</code> will attempt to return
<code>argo@metadata$units$salinityAdjusted</code>
instead of <code>argo@metadata$units$salinity</code>.</p></li>
</ul><p>The default value, <code>which="all"</code>, indicates that this
preference for adjusted values will apply to all the
elements of the <code>data</code> slot of the returned object, along
with associated flags and units. This can be handy for quick
work, but analysts may also choose to restrict their use of
adjusted values to a subset of variables, based on their own
decisions about data quality or accuracy.</p>
<p>The default value <code>fallback=TRUE</code> indicates that later calls to
<code><a href="sub-sub-argo-method.html">[[,argo-method</a></code> should return unadjusted values for any
data items that have <code>NA</code> for all the adjusted values.  This
condition is rare for core variables (salinity, temperature and
pressure) but is annoyingly common for biogeochemical variables; see
e.g. Section 2.2.5 of Reference 1 for a discussion of
the conditions under which Argo NetCDF files contain
adjusted values. Setting <code>fallback=FALSE</code> means that adjusted
values (if they exist) will always be returned, even if they
are a useless collection of <code>NA</code> values.</p>
<p>Error fields, such as <code>salinityAdjustedError</code>, are returned
as-is by <code><a href="sub-sub-argo-method.html">[[,argo-method</a></code>, regardless of whether
the object was created by <code>preferAdjusted</code>.</p>
<p>It should be noted that, regardless of whether <code>preferAdjusted</code>
has been used, the analyst can always access either unadjusted
or adjusted data directly, using the original variable names stored
in the source NetCDF file.  For example, <code>argo[["PSAL"]]</code>
yields unadjusted salinity values, and
<code>argo[["PSAL_ADJUSTED"]]</code> yields adjusted values (if they exist, or
<code>NULL</code> if they do not).
Similarly, adjusted value can always be obtained by using a form
like <code>argo[["salinityAdjusted"]]</code>.</p>
    </div>
    <div class="section level2">
    <h2 id="references">References<a class="anchor" aria-label="anchor" href="#references"></a></h2>

<ol><li><p>Argo Data Management Team. "Argo User's Manual V3.3." Ifremer,
November 28, 2019.
<a href="https://doi.org/10.13155/29825" class="external-link">doi:10.13155/29825</a></p></li>
</ol></div>
    <div class="section level2">
    <h2 id="author">Author<a class="anchor" aria-label="anchor" href="#author"></a></h2>
    <p>Dan Kelley, based on discussions with Jaimie Harbin (with
respect to the <code><a href="sub-sub-argo-method.html">[[,argo-method</a></code> interface) and Clark Richards
(with respect to storing the preference in the <code>metadata</code> slot).</p>
    </div>

    <div class="section level2">
    <h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-examples"></a></h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><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="r-in"><span><span class="fu"><a href="https://rdrr.io/r/utils/data.html" class="external-link">data</a></span><span class="op">(</span><span class="va">argo</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">argoAdjusted</span> <span class="op">&lt;-</span> <span class="fu">preferAdjusted</span><span class="op">(</span><span class="va">argo</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/all.equal.html" class="external-link">all.equal</a></span><span class="op">(</span><span class="va">argo</span><span class="op">[[</span><span class="st">"salinityAdjusted"</span><span class="op">]</span><span class="op">]</span>, <span class="va">argoAdjusted</span><span class="op">[[</span><span class="st">"salinity"</span><span class="op">]</span><span class="op">]</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] TRUE</span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/all.equal.html" class="external-link">all.equal</a></span><span class="op">(</span><span class="va">argo</span><span class="op">[[</span><span class="st">"salinityFlagsAdjusted"</span><span class="op">]</span><span class="op">]</span>, <span class="va">argoAdjusted</span><span class="op">[[</span><span class="st">"salinityFlags"</span><span class="op">]</span><span class="op">]</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] TRUE</span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/all.equal.html" class="external-link">all.equal</a></span><span class="op">(</span><span class="va">argo</span><span class="op">[[</span><span class="st">"salinityUnitsAdjusted"</span><span class="op">]</span><span class="op">]</span>, <span class="va">argoAdjusted</span><span class="op">[[</span><span class="st">"salinityUnits"</span><span class="op">]</span><span class="op">]</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] TRUE</span>
<span class="r-in"><span></span></span>
</code></pre></div>
    </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>

