<!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.0"><title>Roll up eBird taxonomy to species — auk_rollup • auk</title><!-- favicons --><link rel="icon" type="image/png" sizes="16x16" href="../favicon-16x16.png"><link rel="icon" type="image/png" sizes="32x32" href="../favicon-32x32.png"><link rel="apple-touch-icon" type="image/png" sizes="180x180" href="../apple-touch-icon.png"><link rel="apple-touch-icon" type="image/png" sizes="120x120" href="../apple-touch-icon-120x120.png"><link rel="apple-touch-icon" type="image/png" sizes="76x76" href="../apple-touch-icon-76x76.png"><link rel="apple-touch-icon" type="image/png" sizes="60x60" href="../apple-touch-icon-60x60.png"><!-- jquery --><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js" integrity="sha512-v2CJ7UaYy4JwqLDIrZUI/4hqeoQieOmAZNXBeQyjo21dadnwR+8ZaIJVT8EE2iyI61OV8e6M8PP2/4hpQINQ/g==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><!-- Bootstrap --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha256-bZLfwXAP04zRMK2BjiO8iu9pf4FbLqX6zitd+tIvLhE=" crossorigin="anonymous"><script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script><!-- bootstrap-toc --><link rel="stylesheet" href="../bootstrap-toc.css"><script src="../bootstrap-toc.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet"><script src="../pkgdown.js"></script><meta property="og:title" content="Roll up eBird taxonomy to species — auk_rollup"><meta property="og:description" content='The eBird Basic Dataset (EBD) includes both true species and every other
field-identifiable taxon that could be relevant for birders to report. This
includes taxa not identifiable to a species (e.g. hybrids) and taxa reported
below the species level (e.g. subspecies). This function produces a list of
observations of true species, by removing the former and rolling the latter
up to the species level. In the resulting EBD data.frame,
category will be "species" for all records and the subspecies fields will
be dropped. By default, read_ebd() calls ebd_rollup() when importing an
eBird data file.'><meta property="og:image" content="/logo.png"><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]--></head><body data-spy="scroll" data-target="#toc">
    

    <div class="container template-reference-topic">
      <header><div class="navbar navbar-default navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <span class="navbar-brand">
        <a class="navbar-link" href="../index.html">auk</a>
        <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="">0.7.1</span>
      </span>
    </div>

    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav"><li>
  <a href="../articles/auk.html">Get started</a>
</li>
<li>
  <a href="../reference/index.html">Reference</a>
</li>
<li class="dropdown">
  <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
    Articles
     
    <span class="caret"></span>
  </a>
  <ul class="dropdown-menu" role="menu"><li>
      <a href="../articles/development.html">auk development</a>
    </li>
  </ul></li>
<li>
  <a href="https://github.com/CornellLabofOrnithology/auk/blob/master/cheatsheet/auk-cheatsheet.pdf" class="external-link">Cheatsheet</a>
</li>
<li>
  <a href="../news/index.html">Changelog</a>
</li>
      </ul><ul class="nav navbar-nav navbar-right"><li>
  <a href="https://github.com/CornellLabofOrnithology/auk/" class="external-link">
    <span class="fab fa-github fa-lg"></span>
     
  </a>
</li>
      </ul></div><!--/.nav-collapse -->
  </div><!--/.container -->
</div><!--/.navbar -->

      

      </header><div class="row">
  <div class="col-md-9 contents">
    <div class="page-header">
    <h1>Roll up eBird taxonomy to species</h1>
    <small class="dont-index">Source: <a href="https://github.com/CornellLabofOrnithology/auk/blob/HEAD/R/auk-rollup.R" class="external-link"><code>R/auk-rollup.R</code></a></small>
    <div class="hidden name"><code>auk_rollup.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>The eBird Basic Dataset (EBD) includes both true species and every other
field-identifiable taxon that could be relevant for birders to report. This
includes taxa not identifiable to a species (e.g. hybrids) and taxa reported
below the species level (e.g. subspecies). This function produces a list of
observations of true species, by removing the former and rolling the latter
up to the species level. In the resulting EBD data.frame,
<code>category</code> will be <code>"species"</code> for all records and the subspecies fields will
be dropped. By default, <code><a href="read_ebd.html">read_ebd()</a></code> calls <code>ebd_rollup()</code> when importing an
eBird data file.</p>
    </div>

    <div id="ref-usage">
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">auk_rollup</span><span class="op">(</span><span class="va">x</span>, <span class="va">taxonomy_version</span>, drop_higher <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span></code></pre></div>
    </div>

    <div id="arguments">
    <h2>Arguments</h2>
    <dl><dt>x</dt>
<dd><p>data.frame; data frame of eBird data, typically as imported by
<code><a href="read_ebd.html">read_ebd()</a></code></p></dd>


<dt>taxonomy_version</dt>
<dd><p>integer; the version (i.e. year) of the taxonomy. In
most cases, this should be left empty to use the version of the taxonomy
included in the package. See <code><a href="get_ebird_taxonomy.html">get_ebird_taxonomy()</a></code>.</p></dd>


<dt>drop_higher</dt>
<dd><p>logical; whether to remove taxa above species during the
rollup process, e.g. "spuhs" like "duck sp.".</p></dd>

</dl></div>
    <div id="value">
    <h2>Value</h2>
    

<p>A data frame of the eBird data with taxonomic rollup applied.</p>
    </div>
    <div id="details">
    <h2>Details</h2>
    <p>When rolling observations up to species level the observed counts
are summed across any taxa that resolve to the same species. However, if
any of these taxa have a count of "X" (i.e. the observer did not enter a
count), then the rolled up record will get an "X" as well. For example, if
an observer saw 3 Myrtle and 2 Audubon's Warblers, this will roll up to 5
Yellow-rumped Warblers. However, if an "X" was entered for Myrtle, this
would roll up to "X" for Yellow-rumped Warbler.</p>
<p>The eBird taxonomy groups taxa into eight different categories. These
categories, and the way they are treated by <code>auk_rollup()</code> are as follows:</p><ul><li><p><strong>Species:</strong> e.g., Mallard. Combined with lower level taxa if present on
the same checklist.</p></li>
<li><p><strong>ISSF or Identifiable Sub-specific Group:</strong> Identifiable subspecies or
group of subspecies, e.g., Mallard (Mexican). Rolled-up to species level.</p></li>
<li><p><strong>Intergrade:</strong> Hybrid between two ISSF (subspecies or subspecies
groups), e.g., Mallard (Mexican intergrade. Rolled-up to species level.</p></li>
<li><p><strong>Form:</strong> Miscellaneous other taxa, including recently-described species
yet to be accepted or distinctive forms that are not universally accepted
(Red-tailed Hawk (Northern), Upland Goose (Bar-breasted)). If the checklist
contains multiple taxa corresponding to the same species, the lower level
taxa are rolled up, otherwise these records are left as is.</p></li>
<li><p><strong>Spuh:</strong>  Genus or identification at broad level -- e.g., duck sp.,
dabbling duck sp.. Dropped by <code>auk_rollup()</code>.</p></li>
<li><p><strong>Slash:</strong> Identification to Species-pair e.g., American Black
Duck/Mallard). Dropped by <code>auk_rollup()</code>.</p></li>
<li><p><strong>Hybrid:</strong> Hybrid between two species, e.g., American Black Duck x
Mallard (hybrid). Dropped by <code>auk_rollup()</code>.</p></li>
<li><p><strong>Domestic:</strong> Distinctly-plumaged domesticated varieties that may be
free-flying (these do not count on personal lists) e.g., Mallard (Domestic
type). Dropped by <code>auk_rollup()</code>.</p></li>
</ul><p>The rollup process is based on the eBird taxonomy, which is updated once a
year in August. The <code>auk</code> package includes a copy of the eBird taxonomy,
current at the time of release; however, if the EBD and <code>auk</code> versions are
not aligned, you may need to explicitly specify which version of the
taxonomy to use, in which case the eBird API will be queried to get the
correct version of the taxonomy.</p>
    </div>
    <div id="references">
    <h2>References</h2>
    <p>Consult the <a href="https://ebird.org/science/use-ebird-data/the-ebird-taxonomy" class="external-link">eBird taxonomy</a>
page for further details.</p>
    </div>
    <div id="see-also">
    <h2>See also</h2>
    <div class="dont-index"><p>Other pre: 
<code><a href="auk_unique.html">auk_unique</a>()</code></p></div>
    </div>

    <div id="ref-examples">
    <h2>Examples</h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span><span class="co"># get the path to the example data included in the package</span></span></span>
<span class="r-in"><span><span class="co"># in practice, provide path to ebd, e.g. f &lt;- "data/ebd_relFeb-2018.txt</span></span></span>
<span class="r-in"><span><span class="va">f</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/system.file.html" class="external-link">system.file</a></span><span class="op">(</span><span class="st">"extdata/ebd-rollup-ex.txt"</span>, package <span class="op">=</span> <span class="st">"auk"</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="co"># read in data without rolling up</span></span></span>
<span class="r-in"><span><span class="va">ebd</span> <span class="op">&lt;-</span> <span class="fu"><a href="read_ebd.html">read_ebd</a></span><span class="op">(</span><span class="va">f</span>, rollup <span class="op">=</span> <span class="cn">FALSE</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="co"># rollup</span></span></span>
<span class="r-in"><span><span class="va">ebd_ru</span> <span class="op">&lt;-</span> <span class="fu">auk_rollup</span><span class="op">(</span><span class="va">ebd</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="co"># keep higher taxa</span></span></span>
<span class="r-in"><span><span class="va">ebd_higher</span> <span class="op">&lt;-</span> <span class="fu">auk_rollup</span><span class="op">(</span><span class="va">ebd</span>, drop_higher <span class="op">=</span> <span class="cn">FALSE</span><span class="op">)</span></span></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># all taxa not identifiable to species are dropped</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/unique.html" class="external-link">unique</a></span><span class="op">(</span><span class="va">ebd</span><span class="op">$</span><span class="va">category</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] "domestic"   "form"       "hybrid"     "intergrade" "slash"     </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [6] "spuh"       "species"    "issf"      </span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/unique.html" class="external-link">unique</a></span><span class="op">(</span><span class="va">ebd_ru</span><span class="op">$</span><span class="va">category</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] "species"</span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/unique.html" class="external-link">unique</a></span><span class="op">(</span><span class="va">ebd_higher</span><span class="op">$</span><span class="va">category</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] "species" "slash"   "spuh"    "hybrid" </span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># yellow-rump warbler subspecies rollup</span></span></span>
<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://dplyr.tidyverse.org" class="external-link">dplyr</a></span><span class="op">)</span></span></span>
<span class="r-msg co"><span class="r-pr">#&gt;</span> </span>
<span class="r-msg co"><span class="r-pr">#&gt;</span> Attaching package: ‘dplyr’</span>
<span class="r-msg co"><span class="r-pr">#&gt;</span> The following objects are masked from ‘package:stats’:</span>
<span class="r-msg co"><span class="r-pr">#&gt;</span> </span>
<span class="r-msg co"><span class="r-pr">#&gt;</span>     filter, lag</span>
<span class="r-msg co"><span class="r-pr">#&gt;</span> The following objects are masked from ‘package:base’:</span>
<span class="r-msg co"><span class="r-pr">#&gt;</span> </span>
<span class="r-msg co"><span class="r-pr">#&gt;</span>     intersect, setdiff, setequal, union</span>
<span class="r-in"><span><span class="co"># without rollup, there are three observations</span></span></span>
<span class="r-in"><span><span class="va">ebd</span> <span class="op"><a href="https://magrittr.tidyverse.org/reference/pipe.html" class="external-link">%&gt;%</a></span></span></span>
<span class="r-in"><span>  <span class="fu"><a href="https://dplyr.tidyverse.org/reference/filter.html" class="external-link">filter</a></span><span class="op">(</span><span class="va">common_name</span> <span class="op">==</span> <span class="st">"Yellow-rumped Warbler"</span><span class="op">)</span> <span class="op"><a href="https://magrittr.tidyverse.org/reference/pipe.html" class="external-link">%&gt;%</a></span> </span></span>
<span class="r-in"><span>  <span class="fu"><a href="https://dplyr.tidyverse.org/reference/select.html" class="external-link">select</a></span><span class="op">(</span><span class="va">checklist_id</span>, <span class="va">category</span>, <span class="va">common_name</span>, <span class="va">subspecies_common_name</span>, </span></span>
<span class="r-in"><span>         <span class="va">observation_count</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;"># A tibble: 4 × 5</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span>   checklist_id category   common_name   subspecies_common_name observation_count</span>
<span class="r-out co"><span class="r-pr">#&gt;</span>   <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>        <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>      <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>         <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>                  <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>            </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;">1</span> S44943108    intergrade Yellow-rumpe… Yellow-rumped Warbler… 1                </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;">2</span> S129851825   species    Yellow-rumpe… <span style="color: #BB0000;">NA</span>                     1                </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;">3</span> S129851825   issf       Yellow-rumpe… Yellow-rumped Warbler… 1                </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;">4</span> S129851825   issf       Yellow-rumpe… Yellow-rumped Warbler… 2                </span>
<span class="r-in"><span><span class="co"># with rollup, they have been combined</span></span></span>
<span class="r-in"><span><span class="va">ebd_ru</span> <span class="op"><a href="https://magrittr.tidyverse.org/reference/pipe.html" class="external-link">%&gt;%</a></span></span></span>
<span class="r-in"><span>  <span class="fu"><a href="https://dplyr.tidyverse.org/reference/filter.html" class="external-link">filter</a></span><span class="op">(</span><span class="va">common_name</span> <span class="op">==</span> <span class="st">"Yellow-rumped Warbler"</span><span class="op">)</span> <span class="op"><a href="https://magrittr.tidyverse.org/reference/pipe.html" class="external-link">%&gt;%</a></span> </span></span>
<span class="r-in"><span>  <span class="fu"><a href="https://dplyr.tidyverse.org/reference/select.html" class="external-link">select</a></span><span class="op">(</span><span class="va">checklist_id</span>, <span class="va">category</span>, <span class="va">common_name</span>, <span class="va">observation_count</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;"># A tibble: 2 × 4</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span>   checklist_id category common_name           observation_count</span>
<span class="r-out co"><span class="r-pr">#&gt;</span>   <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>        <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>    <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>                 <span style="color: #949494; font-style: italic;">&lt;chr&gt;</span>            </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;">1</span> S129851825   species  Yellow-rumped Warbler 4                </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;">2</span> S44943108    species  Yellow-rumped Warbler 1                </span>
</code></pre></div>
    </div>
  </div>
  <div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
    <nav id="toc" data-toggle="toc" class="sticky-top"><h2 data-toc-skip>Contents</h2>
    </nav></div>
</div>


      <footer><div class="copyright">
  <p></p><p>Developed by <a href="http://strimas.com" class="external-link">Matthew Strimas-Mackey</a>, <a href="http://eliotmiller.weebly.com/" class="external-link">Eliot Miller</a>, <a href="https://www.birds.cornell.edu/hochachka/" class="external-link">Wesley Hochachka</a>.</p>
</div>

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

      </footer></div>

  


  

  </body></html>

