<!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>Filter observations to repeat visits for hierarchical modeling — filter_repeat_visits • 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="Filter observations to repeat visits for hierarchical modeling — filter_repeat_visits"><meta property="og:description" content="Hierarchical modeling of abundance and occurrence requires repeat visits to
sites to estimate detectability. These visits should be all be within a
period of closure, i.e. when the population can be assumed to be closed.
eBird data, and many other data sources, do not explicitly follow this
protocol; however, subsets of the data can be extracted to produce data
suitable for hierarchical modeling. This function extracts a subset of
observation data that have a desired number of repeat visits within a period
of closure."><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>Filter observations to repeat visits for hierarchical modeling</h1>
    <small class="dont-index">Source: <a href="https://github.com/CornellLabofOrnithology/auk/blob/HEAD/R/filter-repeat-visits.R" class="external-link"><code>R/filter-repeat-visits.R</code></a></small>
    <div class="hidden name"><code>filter_repeat_visits.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>Hierarchical modeling of abundance and occurrence requires repeat visits to
sites to estimate detectability. These visits should be all be within a
period of closure, i.e. when the population can be assumed to be closed.
eBird data, and many other data sources, do not explicitly follow this
protocol; however, subsets of the data can be extracted to produce data
suitable for hierarchical modeling. This function extracts a subset of
observation data that have a desired number of repeat visits within a period
of closure.</p>
    </div>

    <div id="ref-usage">
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">filter_repeat_visits</span><span class="op">(</span></span>
<span>  <span class="va">x</span>,</span>
<span>  min_obs <span class="op">=</span> <span class="fl">2L</span>,</span>
<span>  max_obs <span class="op">=</span> <span class="fl">10L</span>,</span>
<span>  annual_closure <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  n_days <span class="op">=</span> <span class="cn">NULL</span>,</span>
<span>  date_var <span class="op">=</span> <span class="st">"observation_date"</span>,</span>
<span>  site_vars <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">"locality_id"</span>, <span class="st">"observer_id"</span><span class="op">)</span>,</span>
<span>  ll_digits <span class="op">=</span> <span class="fl">6L</span></span>
<span><span class="op">)</span></span></code></pre></div>
    </div>

    <div id="arguments">
    <h2>Arguments</h2>
    <dl><dt>x</dt>
<dd><p><code>data.frame</code>; observation data, e.g. data from the eBird Basic
Dataset (EBD) zero-filled with <code><a href="auk_zerofill.html">auk_zerofill()</a></code>. This function will also
work with an <code>auk_zerofill</code> object, in which case it will be converted to
a data frame with <code><a href="auk_zerofill.html">collapse_zerofill()</a></code>.
<strong>Note that these data must for a single species</strong>.</p></dd>


<dt>min_obs</dt>
<dd><p>integer; minimum number of observations required for each
site.</p></dd>


<dt>max_obs</dt>
<dd><p>integer; maximum number of observations allowed for each site.</p></dd>


<dt>annual_closure</dt>
<dd><p>logical; whether the entire year should be treated as
the period of closure (the default). This can be useful, for example, if
the data have been subset to a period of closure prior to calling
<code>filter_repeat_visits()</code>.</p></dd>


<dt>n_days</dt>
<dd><p>integer; number of days defining the temporal length of
closure. If <code>annual_closure = TRUE</code> closure periods will be split at year
boundaries. If <code>annual_closure = FALSE</code> the closure periods will ignore
year boundaries.</p></dd>


<dt>date_var</dt>
<dd><p>character; column name of the variable in <code>x</code> containing the
date. This column should either be in <code>Date</code> format or convertible to
<code>Date</code> format with <code><a href="https://rdrr.io/r/base/as.Date.html" class="external-link">as.Date()</a></code>.</p></dd>


<dt>site_vars</dt>
<dd><p>character; names of one of more columns in <code>x</code> that define a
site, typically the location (e.g. latitude/longitude) and observer ID.</p></dd>


<dt>ll_digits</dt>
<dd><p>integer; the number of digits to round latitude and longitude
to. If latitude and/or longitude are used as <code>site_vars</code>, it's usually best
to round them prior to identifying sites, otherwise locations that are only
slightly offset (e.g. a few centimeters) will be treated as different. This
argument can also be used to group sites together that are close but not
identical. Note that 1 degree of latitude is approximately 100 km, so the
default value of 6 for <code>ll_digits</code> is equivalent to about 10 cm.</p></dd>

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

<p>A <code>data.frame</code> filtered to only retain observations from sites with
the allowed number of observations within the period of closure. The
results will be sorted such that sites are together and in chronological
order. The following variables are added to the data frame:</p><ul><li><p><code>site</code>: a unique identifier for each "site" corresponding to all the
variables in <code>site_vars</code> and <code>closure_id</code> concatenated together with
underscore separators.</p></li>
<li><p><code>closure_id</code>: a unique ID for each closure period. If <code>annual_closure =   TRUE</code> this ID will include the year. If <code>n_days</code> is used an index given the
number of blocks of <code>n_days</code> days since the earliest observation will be
included. Note that in this case, there may be gaps in the IDs.</p></li>
<li><p><code>n_observations</code>: number of observations at each site after all
filtering.</p></li>
</ul></div>
    <div id="details">
    <h2>Details</h2>
    <p>In addition to specifying the minimum and maximum number of
observations per site, users must specify the variables in the dataset that
define a "site". This is typically a combination of IDs defining the
geographic site and the unique observer (repeat visits are meant to be
conducted by the same observer). Finally, the closure period must be
defined, which is a period within which the population of the focal species
can reasonably be assumed to be closed. This can be done using a
combination of the <code>n_days</code> and <code>annual_closure</code> arguments.</p>
    </div>
    <div id="see-also">
    <h2>See also</h2>
    <div class="dont-index"><p>Other modeling: 
<code><a href="format_unmarked_occu.html">format_unmarked_occu</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="co"># data must be for a single species</span></span></span>
<span class="r-in"><span><span class="va">ebd_zf</span> <span class="op">&lt;-</span> <span class="fu"><a href="auk_zerofill.html">auk_zerofill</a></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></span>
<span class="r-in"><span>                       collapse <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu">filter_repeat_visits</span><span class="op">(</span><span class="va">ebd_zf</span>, n_days <span class="op">=</span> <span class="fl">30</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;"># A tibble: 251 × 41</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span>    site          closure_id n_observations checklist_id last_edited_date country</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;int&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> L1055540_obs… 2012-2                  2 S49291608    2023-01-31 19:3… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;"> 2</span> L1055540_obs… 2012-2                  2 S49291611    2022-03-12 04:3… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;"> 3</span> L1361109_obs… 2012-0                 10 S9612576     2021-08-17 17:4… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;"> 4</span> L1361109_obs… 2012-0                 10 S9635686     2022-03-12 04:3… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;"> 5</span> L1361109_obs… 2012-0                 10 S9640246     2012-03-20 03:2… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;"> 6</span> L1361109_obs… 2012-0                 10 S9652466     2012-03-20 03:2… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;"> 7</span> L1361109_obs… 2012-0                 10 S9652476     2022-03-12 04:3… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;"> 8</span> L1361109_obs… 2012-0                 10 S9664006     2022-03-12 04:3… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;"> 9</span> L1361109_obs… 2012-0                 10 S9671189     2021-04-02 03:4… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #BCBCBC;">10</span> L1361109_obs… 2012-0                 10 S9672138     2022-03-12 04:3… Singap…</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;"># ℹ 241 more rows</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;"># ℹ 35 more variables: country_code &lt;chr&gt;, state &lt;chr&gt;, state_code &lt;chr&gt;,</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;">#   county &lt;chr&gt;, county_code &lt;chr&gt;, iba_code &lt;chr&gt;, bcr_code &lt;int&gt;,</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;">#   usfws_code &lt;chr&gt;, atlas_block &lt;chr&gt;, locality &lt;chr&gt;, locality_id &lt;chr&gt;,</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;">#   locality_type &lt;chr&gt;, latitude &lt;dbl&gt;, longitude &lt;dbl&gt;,</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;">#   observation_date &lt;date&gt;, time_observations_started &lt;chr&gt;,</span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> <span style="color: #949494;">#   observer_id &lt;chr&gt;, sampling_event_identifier &lt;chr&gt;, protocol_type &lt;chr&gt;, …</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>

