<!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>Distill a raster stack into a set of distribution metrics — metrics_distill • colorist</title><!-- jquery --><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></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="Distill a raster stack into a set of distribution metrics — metrics_distill"><meta property="og:description" content='This function is used to summarize several distributional
features of interest across a series of distributions. Distributional
information in the original raster stack is "distilled" for subsequent
visualization.'><!-- 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">colorist</a>
        <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="">0.1.3</span>
      </span>
    </div>

    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav"><li>
  <a href="../articles/introduction.html">Introduction</a>
</li>
<li>
  <a href="../articles/tuning.html">Tuning Visualizations</a>
</li>
<li>
  <a href="../articles/mapping.html">Customizing Maps</a>
</li>
<li>
  <a href="../reference/index.html">Function Reference</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/mstrimas/colorist/" 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>Distill a raster stack into a set of distribution metrics</h1>
    <small class="dont-index">Source: <a href="https://github.com/mstrimas/colorist/blob/HEAD/R/metrics.R" class="external-link"><code>R/metrics.R</code></a></small>
    <div class="hidden name"><code>metrics_distill.Rd</code></div>
    </div>

    <div class="ref-description">
    <p>This function is used to summarize several distributional
features of interest across a series of distributions. Distributional
information in the original raster stack is "distilled" for subsequent
visualization.</p>
    </div>

    <div id="ref-usage">
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">metrics_distill</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>RasterStack of distributions. Layers typically contain information
about the distribution of a single individual or species at multiple points
in time. Alternatively, layers may contain information about the
distributions of multiple individuals or species within a single time
period. Other conceptualizations are possible.</p></dd>

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

<p>A RasterStack with four layers:</p><ul><li><p><code>intensity</code>: the maximum intensity value across all layers.</p></li>
<li><p><code>layer_id</code>: an integer identifying layer containing the maximum intensity
value.</p></li>
<li><p><code>specificity</code>: the degree to which intensity values are unevenly
distributed across layers (see Details).</p></li>
<li><p><code>n_layers</code>: the number of layers with non-NA values (see Details).</p></li>
</ul><p>The maximum cell value in the stack is stored as the <code>"maximum"</code> attribute.
The link between the <code>layer_id</code> and the layer names from the underlying
raster is stored as a data frame in the <code>layer_names</code> attribute.</p>
    </div>
    <div id="details">
    <h2>Details</h2>
    <p>Specificity values range from 0 to 100. Values of 0 indicate
intensity values are identical in all layers. Values of 100 indicate
intensity values are restricted to a single layer. Interpretation of
specificity values depends on the layers provided. If layers describe the
distribution of a species at different times of the year, specificity can
be interpreted as a measure of seasonality (i.e., 0 = stable year-round
occurrence in a cell, 100 = highly seasonal occurrence). If layers describe
space use by multiple individuals, specificity can be interpreted as a
measure of exclusivity (i.e., 0 = equal use of a cell by all individuals,
100 = exclusive use by one individual).</p>
<p>The number of layers with non-NA values is recorded to aid interpretation
of distributions. Ideally, n_layers values are identical in every cell,
indicating that users have knowledge of distributions over the same area in
every layer of their raster stack. When n_layers values are unequal, it
indicates that users have unequal knowledge of distributions in their
raster stack. Distributions are more likely to be misrepresented and
misinterpreted if cells do not contain intensity values in every layer.</p>
    </div>
    <div id="see-also">
    <h2>See also</h2>
    <div class="dont-index"><p>Other metrics: 
<code><a href="metrics_pull.html">metrics_pull</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"># load elephant data</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="st">"elephant_ud"</span><span class="op">)</span></span></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># distill</span></span></span>
<span class="r-in"><span><span class="va">r</span> <span class="op">&lt;-</span> <span class="fu">metrics_distill</span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/print.html" class="external-link">print</a></span><span class="op">(</span><span class="va">r</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> class      : RasterStack </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> dimensions : 208, 193, 40144, 4  (nrow, ncol, ncell, nlayers)</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> resolution : 500, 500  (x, y)</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> extent     : -58642.18, 37857.82, -2376938, -2272938  (xmin, xmax, ymin, ymax)</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> crs        : +proj=moll +lon_0=15.8231920275931 +x_0=0 +y_0=0 +ellps=WGS84 +units=m +no_defs </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> names      : intensity, layer_id, specificity, n_layers </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> min values :         0,        1,           0,        2 </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> max values :         1,        2,         100,        2 </span>
<span class="r-out co"><span class="r-pr">#&gt;</span> </span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># maximum value across all layers stored as an attribute</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/attr.html" class="external-link">attr</a></span><span class="op">(</span><span class="va">r</span>, <span class="st">"maximum"</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span> [1] 0.002409927</span>
<span class="r-in"><span><span class="co"># link between layer id and name stored as an attribute</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/attr.html" class="external-link">attr</a></span><span class="op">(</span><span class="va">r</span>, <span class="st">"layer_names"</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#&gt;</span>   layer_id layer_name</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 1        1       LA11</span>
<span class="r-out co"><span class="r-pr">#&gt;</span> 2        2       LA14</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://www.justinschuetz.com/" class="external-link">Justin Schuetz</a>, <a href="http://strimas.com" class="external-link">Matthew Strimas-Mackey</a>, <a href="http://twitter.com/tom_auer" class="external-link">Tom Auer</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.7.</p>
</div>

      </footer></div>

  


  

  </body></html>

