<!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>Read and zero-fill an eBird data file — auk_zerofill • 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="Read and zero-fill an eBird data file — auk_zerofill"><meta property="og:description" content="Read an eBird Basic Dataset (EBD) file, and associated sampling event data
file, to produce a zero-filled, presence-absence dataset. The EBD contains
bird sightings and the sampling event data is a set of all checklists, they
can be combined to infer absence data by assuming any species not reported on
a checklist was had a count of zero."><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>Read and zero-fill an eBird data file</h1>
    <small class="dont-index">Source: <a href="https://github.com/CornellLabofOrnithology/auk/blob/HEAD/R/auk-zerofill.R" class="external-link"><code>R/auk-zerofill.R</code></a></small>
    <div class="hidden name"><code>auk_zerofill.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>Read an eBird Basic Dataset (EBD) file, and associated sampling event data
file, to produce a zero-filled, presence-absence dataset. The EBD contains
bird sightings and the sampling event data is a set of all checklists, they
can be combined to infer absence data by assuming any species not reported on
a checklist was had a count of zero.</p>
    </div>

    <div id="ref-usage">
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">auk_zerofill</span><span class="op">(</span><span class="va">x</span>, <span class="va">...</span><span class="op">)</span></span>
<span></span>
<span><span class="co"># S3 method for data.frame</span></span>
<span><span class="fu">auk_zerofill</span><span class="op">(</span></span>
<span>  <span class="va">x</span>,</span>
<span>  <span class="va">sampling_events</span>,</span>
<span>  <span class="va">species</span>,</span>
<span>  <span class="va">taxonomy_version</span>,</span>
<span>  collapse <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  unique <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  rollup <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  drop_higher <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  complete <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  <span class="va">...</span></span>
<span><span class="op">)</span></span>
<span></span>
<span><span class="co"># S3 method for character</span></span>
<span><span class="fu">auk_zerofill</span><span class="op">(</span></span>
<span>  <span class="va">x</span>,</span>
<span>  <span class="va">sampling_events</span>,</span>
<span>  <span class="va">species</span>,</span>
<span>  <span class="va">taxonomy_version</span>,</span>
<span>  collapse <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  unique <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  rollup <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  drop_higher <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  complete <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  sep <span class="op">=</span> <span class="st">"\t"</span>,</span>
<span>  <span class="va">...</span></span>
<span><span class="op">)</span></span>
<span></span>
<span><span class="co"># S3 method for auk_ebd</span></span>
<span><span class="fu">auk_zerofill</span><span class="op">(</span></span>
<span>  <span class="va">x</span>,</span>
<span>  <span class="va">species</span>,</span>
<span>  <span class="va">taxonomy_version</span>,</span>
<span>  collapse <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  unique <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  rollup <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  drop_higher <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  complete <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  sep <span class="op">=</span> <span class="st">"\t"</span>,</span>
<span>  <span class="va">...</span></span>
<span><span class="op">)</span></span>
<span></span>
<span><span class="fu">collapse_zerofill</span><span class="op">(</span><span class="va">x</span><span class="op">)</span></span></code></pre></div>
    </div>

    <div id="arguments">
    <h2>Arguments</h2>
    <dl><dt>x</dt>
<dd><p>filename, <code>data.frame</code> of eBird observations, or <code>auk_ebd</code> object
with associated output files as created by <code><a href="auk_filter.html">auk_filter()</a></code>. If a filename is
provided, it must point to the EBD and the <code>sampling_events</code> argument must
point to the sampling event data file. If a <code>data.frame</code> is provided it
should have been imported with <code><a href="read_ebd.html">read_ebd()</a></code>, to ensure the variables names
have been set correctly, and it must have been passed through
<code><a href="auk_unique.html">auk_unique()</a></code> to ensure duplicate group checklists have been removed.</p></dd>


<dt>...</dt>
<dd><p>additional arguments passed to methods.</p></dd>


<dt>sampling_events</dt>
<dd><p>character or <code>data.frame</code>; filename for the sampling
event data or a <code>data.frame</code> of the same data. If a <code>data.frame</code> is
provided it should have been imported with <code><a href="read_ebd.html">read_sampling()</a></code>, to ensure the
variables names have been set correctly, and it must have been passed
through <code><a href="auk_unique.html">auk_unique()</a></code> to ensure duplicate group checklists have been
removed.</p></dd>


<dt>species</dt>
<dd><p>character; species to include in zero-filled dataset, provided
as scientific or English common names, or a mixture of both. These names
must match the official eBird Taxomony (<a href="ebird_taxonomy.html">ebird_taxonomy</a>). To include all
species, leave this argument blank.</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>collapse</dt>
<dd><p>logical; whether to call <code>collapse_zerofill()</code> to return a
data frame rather than an <code>auk_zerofill</code> object.</p></dd>


<dt>unique</dt>
<dd><p>logical; should <code><a href="auk_unique.html">auk_unique()</a></code> be run on the input data if it
hasn't already.</p></dd>


<dt>rollup</dt>
<dd><p>logical; should <code><a href="auk_rollup.html">auk_rollup()</a></code> be run on the input data if it
hasn't already.</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.". See <code><a href="auk_rollup.html">auk_rollup()</a></code>.</p></dd>


<dt>complete</dt>
<dd><p>logical; if <code>TRUE</code> (the default) all checklists are required
to be complete prior to zero-filling.</p></dd>


<dt>sep</dt>
<dd><p>character; single character used to separate fields within a row.</p></dd>

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

<p>By default, an <code>auk_zerofill</code> object, or a data frame if <code>collapse = TRUE</code>.</p>
    </div>
    <div id="details">
    <h2>Details</h2>
    <p><code>auk_zerofill()</code> generates an <code>auk_zerofill</code> object consisting of a list with
elements <code>observations</code> and <code>sampling_events</code>. <code>observations</code> is a data frame
giving counts and binary presence/absence data for each species.
<code>sampling_events</code> is a data frame with checklist level information. The two
data frames can be connected via the <code>checklist_id</code> field. This format is
efficient for storage since the checklist columns are not duplicated for each
species, however, working with the data often requires joining the two data
frames together.</p>
<p>To return a data frame, set <code>collapse = TRUE</code>. Alternatively,
<code>zerofill_collapse()</code> generates a data frame from an <code>auk_zerofill</code> object,
by joining the two data frames together to produce a single data frame in
which each row provides both checklist and species information for a
sighting.</p>
<p>The list of species is checked against the eBird taxonomy for validity. This
taxonomy 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="methods-by-class-">
    <h2>Methods (by class)</h2>
    
<ul><li><p><code>auk_zerofill(data.frame)</code>: EBD data frame.</p></li>
<li><p><code>auk_zerofill(character)</code>: Filename of EBD.</p></li>
<li><p><code>auk_zerofill(auk_ebd)</code>: <code>auk_ebd</code> object output from <code><a href="auk_filter.html">auk_filter()</a></code>. Must
have had a sampling event data file set in the original call to
<code><a href="auk_ebd.html">auk_ebd()</a></code>.</p></li>
</ul></div>
    <div id="see-also">
    <h2>See also</h2>
    <div class="dont-index"><p>Other import: 
<code><a href="read_ebd.html">read_ebd</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"># read and zero-fill the ebd data</span></span></span>
<span class="r-in"><span><span class="va">f_ebd</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/zerofill-ex_ebd.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="va">f_smpl</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/zerofill-ex_sampling.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="fu">auk_zerofill</span><span class="op">(</span>x <span class="op">=</span> <span class="va">f_ebd</span>, sampling_events <span class="op">=</span> <span class="va">f_smpl</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> Zero-filled EBD: 663 unique checklists, for 3 species.</span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># use the species argument to only include a subset of species</span></span></span>
<span class="r-in"><span><span class="fu">auk_zerofill</span><span class="op">(</span>x <span class="op">=</span> <span class="va">f_ebd</span>, sampling_events <span class="op">=</span> <span class="va">f_smpl</span>,</span></span>
<span class="r-in"><span>             species <span class="op">=</span> <span class="st">"Collared Kingfisher"</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> Zero-filled EBD: 663 unique checklists, for 1 species.</span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># to return a data frame use collapse = TRUE</span></span></span>
<span class="r-in"><span><span class="va">ebd_df</span> <span class="op">&lt;-</span> <span class="fu">auk_zerofill</span><span class="op">(</span>x <span class="op">=</span> <span class="va">f_ebd</span>, sampling_events <span class="op">=</span> <span class="va">f_smpl</span>, collapse <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span></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>

