<!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>Format a Confidence Interval — formatCI • 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="Format a Confidence Interval — formatCI"><meta name="description" content="This formats a confidence interval in either the +/- notation or
the parenthetic notation.  For example, if a quantity has mean 1
with uncertainty 0.05, which means a CI of 0.95 to 1.05,
the &quot;+-&quot; style yields &quot;1+/-0.05&quot;, and the &quot;parentheses&quot;
style yields `&quot;&quot;'."><meta property="og:description" content="This formats a confidence interval in either the +/- notation or
the parenthetic notation.  For example, if a quantity has mean 1
with uncertainty 0.05, which means a CI of 0.95 to 1.05,
the &quot;+-&quot; style yields &quot;1+/-0.05&quot;, and the &quot;parentheses&quot;
style yields `&quot;&quot;'."></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>Format a Confidence Interval</h1>
      <small class="dont-index">Source: <a href="https://github.com/dankelley/oce/blob/HEAD/R/misc.R" class="external-link"><code>R/misc.R</code></a></small>
      <div class="d-none name"><code>formatCI.Rd</code></div>
    </div>

    <div class="ref-description section level2">
    <p>This formats a confidence interval in either the +/- notation or
the parenthetic notation.  For example, if a quantity has mean 1
with uncertainty 0.05, which means a CI of 0.95 to 1.05,
the <code>"+-"</code> style yields <code>"1+/-0.05"</code>, and the <code>"parentheses"</code>
style yields `""'.</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">formatCI</span><span class="op">(</span></span>
<span>  <span class="va">ci</span>,</span>
<span>  style <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="st">"+/-"</span>, <span class="st">"parentheses"</span><span class="op">)</span>,</span>
<span>  <span class="va">model</span>,</span>
<span>  digits <span class="op">=</span> <span class="fl">2</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="fl">0</span><span class="op">)</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-ci">ci<a class="anchor" aria-label="anchor" href="#arg-ci"></a></dt>
<dd><p>optional vector of length 2 or 3.</p></dd>


<dt id="arg-style">style<a class="anchor" aria-label="anchor" href="#arg-style"></a></dt>
<dd><p>string indicating notation to be used.</p></dd>


<dt id="arg-model">model<a class="anchor" aria-label="anchor" href="#arg-model"></a></dt>
<dd><p>optional regression model, e.g. returned by <code><a href="https://rdrr.io/r/stats/lm.html" class="external-link">lm()</a></code> or
<code><a href="https://rdrr.io/r/stats/nls.html" class="external-link">nls()</a></code>.</p></dd>


<dt id="arg-digits">digits<a class="anchor" aria-label="anchor" href="#arg-digits"></a></dt>
<dd><p>optional number of digits to use.  This is ignored
if <code>style</code> is <code>"parentheses"</code>.</p></dd>


<dt id="arg-debug">debug<a class="anchor" aria-label="anchor" href="#arg-debug"></a></dt>
<dd><p>integer value indicating debugging level. If 0, then
<code>formatCI()</code> works silently.  If greater than 0, then some debugging
messages are printed during processing.</p></dd>

</dl></div>
    <div class="section level2">
    <h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>
    <p>If <code>ci</code> is given, the result is a character string with the
estimate and its uncertainty, in plus/minus or parenthetic notation.  If
<code>model</code> is given, the result is a 1-column matrix holding character
strings, with row names corresponding to the parameters of the model.</p>
    </div>
    <div class="section level2">
    <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
    <p>If a <code>model</code> is given, then <code>ci</code> is ignored, and a confidence
interval is calculated using <code><a href="https://rdrr.io/r/stats/confint.html" class="external-link">confint()</a></code> with <code>level</code> set to
0.6914619.  This <code>level</code> corresponds to a range of plus or minus one
standard deviation, for the t distribution and a large number of degrees of
freedom (since <code>qt(0.6914619, 100000)</code> is 0.5).</p>
<p>If <code>model</code> is missing, <code>ci</code> must be provided.  If it contains 3
elements, then first and third elements are taken as the range of the
confidence interval (which by convention should use the <code>level</code> stated
in the previous paragraph), and the second element is taken as the central
value.  Alternatively, if <code>ci</code> has 2 elements, they are taken to be
bounds of the confidence interval and their mean is taken to be the central
value.</p>
<p>In the <code>+/-</code> notation, e.g. \(a \pm b\) indicates that the true
value lies between \(a-b\) and \(a+b\) with a high degree of
certainty.  Mills et al. (1993, section 4.1 on page 83) suggest that
\(b\) should be set equal to 2 times the standard uncertainty or
standard deviation.  JCGM (2008, section 7.2.2 on pages 25 and 26), however,
suggest that \(b\) should be set to the standard uncertainty, while
also recommending that the \(\pm\) notation (and presumably
the parentheses notation also) be avoided altogether, in favour of
writing sentences that explains uncertainties in clear terms.</p>
<p>The <code>parentheses</code> notation is often called the compact notation.  In
it, the digits in parentheses indicate the uncertainty in the corresponding
digits to their left, e.g. 12.34(3) means that the last digit (4) has an
uncertainty of 3.  However, as with the \(\pm\) notation, different
authorities offer different advice on defining this uncertainty; Mills et
al. (1993) provide an example in which the
parenthetic value is half the \(\pm\) value, whereas
JCM (2008) suggest using the same values.</p>
<p>The JCM(2008) convention is used by <code>formatCI()</code> for the parentheses
notation, as illustrated in Examples 1 and 2.  Note, however, that
if the confidence range exceeds the value, then
a request for <code>parentheses</code> format reverts to <code>+/-</code> format.</p>
    </div>
    <div class="section level2">
    <h2 id="references">References<a class="anchor" aria-label="anchor" href="#references"></a></h2>

<ol><li><p>JCGM, 2008. <em>Evaluation of measurement data - Guide to the
expression of uncertainty in measurement (JCGM 100:2008)</em>, published by the
Joint Committee for Guides in Metrology, available (as of November 2023)
at https://www.bipm.org/documents/20126/2071204/JCGM_100_2008_E.pdf.
See section 7.2.2 on Page 25, for a summary of notation, including
an illustration of the use of equal values for both the <code>+-</code> and the
parentheses notations.</p></li>
<li><p>Mills, I., T. Cvitas, K. Homann, N. Kallay, and K. Kuchitsu, 1993.
<em>Quantities, Units and Symbols in Physical Chemistry</em>, published
Blackwell Science for the International Union of Pure and Applied Chemistry.
(See section 4.1, page 83, for a summary of notation, which shows that a
value to the right of a <code>+-</code> sign is to be halved if put in
in parentheses, which is not done in the present function, because
of a choice to follow the recommendation of reference 1.</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</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></span>
<span class="r-in"><span><span class="co"># Example 1: mean=1, uncertainty=0.05, in +/- notation.</span></span></span>
<span class="r-in"><span><span class="fu">formatCI</span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="fl">0.95</span>, <span class="fl">1.05</span><span class="op">)</span><span class="op">)</span> <span class="co"># "1+/-0.05"</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] "1+/-0.05"</span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># Example 2: save mean and uncertainty, but in parentheses notation.</span></span></span>
<span class="r-in"><span><span class="fu">formatCI</span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="fl">0.95</span>, <span class="fl">1.05</span><span class="op">)</span>, style <span class="op">=</span> <span class="st">"parentheses"</span><span class="op">)</span> <span class="co"># "1.00(5)"</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] "1.00(5)"</span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># example 3: using t.test to find a CI.</span></span></span>
<span class="r-in"><span><span class="va">a</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/stats/Normal.html" class="external-link">rnorm</a></span><span class="op">(</span><span class="fl">100</span>, mean <span class="op">=</span> <span class="fl">10</span>, sd <span class="op">=</span> <span class="fl">1</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">CI</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/stats/t.test.html" class="external-link">t.test</a></span><span class="op">(</span><span class="va">a</span><span class="op">)</span><span class="op">$</span><span class="va">conf.int</span></span></span>
<span class="r-in"><span><span class="fu">formatCI</span><span class="op">(</span><span class="va">CI</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] "9.9+/-0.19"</span>
<span class="r-in"><span><span class="fu">formatCI</span><span class="op">(</span><span class="va">CI</span>, style <span class="op">=</span> <span class="st">"parentheses"</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] "9.9(1.87)"</span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># example 4: specifying a model</span></span></span>
<span class="r-in"><span><span class="va">x</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/seq.html" class="external-link">seq</a></span><span class="op">(</span><span class="fl">0</span>, <span class="fl">10</span>, <span class="fl">0.1</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">y</span> <span class="op">&lt;-</span> <span class="fl">2</span> <span class="op">+</span> <span class="fl">3</span> <span class="op">*</span> <span class="va">x</span> <span class="op">+</span> <span class="fu"><a href="https://rdrr.io/r/stats/Normal.html" class="external-link">rnorm</a></span><span class="op">(</span><span class="va">x</span>, sd <span class="op">=</span> <span class="fl">0.1</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">m</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/stats/lm.html" class="external-link">lm</a></span><span class="op">(</span><span class="va">y</span> <span class="op">~</span> <span class="va">x</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu">formatCI</span><span class="op">(</span>model <span class="op">=</span> <span class="va">m</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span>             value       </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> (Intercept) "2+/-0.021" </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> x           "3+/-0.0036"</span>
<span class="r-in"><span><span class="fu">formatCI</span><span class="op">(</span>model <span class="op">=</span> <span class="va">m</span>, style <span class="op">=</span> <span class="st">"parentheses"</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span>             value        </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> (Intercept) "1.97(2.11)" </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> x           "3.005(3.64)"</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>

