<!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>Introduction to colorist • 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="Introduction to colorist">
<meta property="og:description" content="colorist">
<!-- 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-article">
      <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 toc-ignore">
      <h1 data-toc-skip>Introduction to colorist</h1>
            
      
      <small class="dont-index">Source: <a href="https://github.com/mstrimas/colorist/blob/HEAD/vignettes/introduction.Rmd" class="external-link"><code>vignettes/introduction.Rmd</code></a></small>
      <div class="hidden name"><code>introduction.Rmd</code></div>

    </div>

    
    
<p>Maps play a central role in research aimed at understanding how and
why wildlife distributions shift through space and time. They give form
to complex sets of assumptions, hypotheses, and predictions and, in
doing so, offer the promise of embodying detailed knowledge about
species and individuals. Traditionally, biologists have used range maps,
and home range maps, to describe animal distributions in space and time.
Despite their historical success as representational forms, they are
increasingly incapable of communicating our knowledge of wildlife
distributions.</p>
<p>Technologies for acquiring and modeling wildlife distribution data
have improved dramatically in recent years. As a result, we possess ever
more detailed descriptions of animal occurrence, abundance, and density
in space and time. This glut of high-resolution spatiotemporal
information comes with its own set of visualization challenges, however.
Intuitively, we might try to reveal patterns of spatiotemporal stasis
and change by stacking distributions on top of each other, but this
strategy often results in underlying data being occluded or muddied,
depending on whether and how layers are combined.</p>
<p>We developed the <code>colorist</code> package to provide researchers
with a variety of options for exploring and communicating information
about wildlife distributions in space and time. <code>colorist</code>
emphasizes the use of color to indicate where, when, and how
consistently species, individuals, or groups of animals can be found. In
order to do this effectively, colorist takes information from a stack of
rasters, processes it, and links it to HCL (hue-chroma-luminance) color
palettes in specific ways so that occurrence, abundance, or density
values have nearly equal perceptual weights in resulting maps.</p>
<div class="section level2">
<h2 id="usage">Usage<a class="anchor" aria-label="anchor" href="#usage"></a>
</h2>
<p>Like other visualization tools, we suggest that the
<code>colorist</code> package may be useful to researchers in different
ways throughout the process of building knowledge. Researchers may want
to use <code>colorist</code> to explore preliminary data through
visualizations, with the goal of developing or refining research
questions. Alternatively, researchers may come to <code>colorist</code>
having already discovered something interesting about wildlife
distributions that they would like to communicate in visualizations.
Regardless of where researchers are in the process of discovery, it is
important to remember that <code>colorist</code> functions were built to
handle and display data. People are still in charge of their
interpretation.</p>
<p>The <code>colorist</code> package works on raster data stored as
<code>RasterStack</code> objects. Individual raster layers might
represent an ordered temporal sequence of species distributions or
utilization distributions. Alternatively, raster layers might represent
an unordered set of distributions for multiple species, or individuals,
within a single time period. Whatever temporal or identity relationships
exist within the stack, all raster layers should contain values in the
same units (e.g., abundance, occurrence, or probability density) to
ensure that they can be meaningfully compared.</p>
<p>When preparing raster layers, users should be sure to distinguish
raster cells with 0 values (e.g., cells in which a species is predicted
to occur with probability 0) from cells with NA values (e.g., cells for
which occurrence predictions could not be made). This distinction is
important for identifying areas where knowledge of distributions is
incomplete. In addition, because colorist functions can take time to
process large <code>RasterStack</code> objects, researchers may want to
aggregate their raster data spatially and/or temporally while exploring
alternative visualization strategies.</p>
<p>The basic workflow for colorist is as follows:</p>
<ol style="list-style-type: decimal">
<li>
<strong>Metrics</strong>: Users calculate metrics to describe their
distributions.</li>
<li>
<strong>Color palette</strong>: Users choose a color palette to
enable visualization of metrics.</li>
<li>
<strong>Map</strong>: Users combine metrics and a palette to map
distributions in a series of small multiples or in a single map.</li>
<li>
<strong>Legend</strong>: Users generate a legend to accompany their
map.</li>
</ol>
</div>
<div class="section level2">
<h2 id="examples">Examples<a class="anchor" aria-label="anchor" href="#examples"></a>
</h2>
<p>Here, we describe three use cases to illustrate <code>colorist</code>
functions and how they can be combined to map distributions.</p>
<div class="section level3">
<h3 id="map-a-species-distribution-across-the-annual-cycle">1. Map a species distribution across the annual cycle<a class="anchor" aria-label="anchor" href="#map-a-species-distribution-across-the-annual-cycle"></a>
</h3>
<p>There is growing interest in characterizing wildlife distributions
across the full-annual cycle, as opposed to one or two seasons, so that
we can better understand the places and times at which populations are
vulnerable. Maps play an important role in that process. In the past,
range maps for resident species typically contained a single block of
color along with political boundaries that indicated where a species can
be found throughout the year. In contrast, range maps for migratory
species typically contained several blocks of color indicating where a
species might be found during a particular season, or throughout the
entire year.</p>
<p>Here, we use aggregated <a href="https://ebird.org/science" class="external-link">eBird
Status and Trends</a> data for <a href="https://ebird.org/science/status-and-trends" class="external-link">Field Sparrow</a>
(<em>Spizella pusilla</em>) to illustrate a different strategy for
creating annual cycle maps, one that leverages continuous occurrence
data (rather than categorical presence-absence data) to describe where
and when viewers might be able to find a species. Field Sparrow is a
relatively small bird that is commonly found in open habitats throughout
eastern North America. It is often considered a partial migrant in that
some populations move throughout the year, while others are stationary.
This results in heterogeneity in when, where, and how consistently birds
can be found in space-time.</p>
<p>We start by loading the <code>fiespa_occ</code> data set. It contains
twelve raster layers, one for each month of the year. Cell values in
each layer indicate the modeled probability of Field Sparrow occurrence.
Additional Status and Trends data can be accessed using the <a href="https://ebird.github.io/ebirdst/" class="external-link"><code>ebirdst</code> R
package</a>.</p>
<div class="sourceCode" id="cb1"><pre class="downlit sourceCode r">
<code class="sourceCode R"><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://r-spatial.github.io/sf/" class="external-link">sf</a></span><span class="op">)</span></span>
<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://ggplot2.tidyverse.org" class="external-link">ggplot2</a></span><span class="op">)</span></span>
<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://github.com/mstrimas/colorist" class="external-link">colorist</a></span><span class="op">)</span></span>
<span></span>
<span><span class="co"># load data </span></span>
<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">"fiespa_occ"</span><span class="op">)</span></span>
<span><span class="va">fiespa_occ</span></span>
<span><span class="co">#&gt; class      : RasterStack </span></span>
<span><span class="co">#&gt; dimensions : 100, 121, 12100, 12  (nrow, ncol, ncell, nlayers)</span></span>
<span><span class="co">#&gt; resolution : 26665.26, 26665.28  (x, y)</span></span>
<span><span class="co">#&gt; extent     : -1782551, 1443945, -1160698, 1505830  (xmin, xmax, ymin, ymax)</span></span>
<span><span class="co">#&gt; crs        : +proj=laea +lat_0=37.602 +lon_0=-86.264 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs </span></span>
<span><span class="co">#&gt; names      :       jan,       feb,       mar,       apr,       may,       jun,       jul,       aug,       sep,       oct,       nov,       dec </span></span>
<span><span class="co">#&gt; min values :         0,         0,         0,         0,         0,         0,         0,         0,         0,         0,         0,         0 </span></span>
<span><span class="co">#&gt; max values : 0.5640106, 0.6057996, 0.6536915, 0.7482038, 0.7165731, 0.7626083, 0.7465307, 0.6465662, 0.5210227, 0.5762388, 0.6329718, 0.5829163</span></span></code></pre></div>
<p>After confirming the data have been loaded correctly, we use
<code><a href="../reference/metrics_pull.html">metrics_pull()</a></code> to transform occurrence values from the
stack into intensity values that range from 0 (i.e., cells without Field
Sparrows) to 1 (i.e., the cell[s] with the highest occurrence value
anywhere in the stack). This process of “pulling” metrics from the
<code>RasterStack</code> preserves all of the information in the
original stack while preparing layers for subsequent visualization.</p>
<div class="sourceCode" id="cb2"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># pull information from the stack</span></span>
<span><span class="va">m1</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/metrics_pull.html">metrics_pull</a></span><span class="op">(</span><span class="va">fiespa_occ</span><span class="op">)</span></span>
<span><span class="va">m1</span></span>
<span><span class="co">#&gt; class      : RasterBrick </span></span>
<span><span class="co">#&gt; dimensions : 100, 121, 12100, 12  (nrow, ncol, ncell, nlayers)</span></span>
<span><span class="co">#&gt; resolution : 26665.26, 26665.28  (x, y)</span></span>
<span><span class="co">#&gt; extent     : -1782551, 1443945, -1160698, 1505830  (xmin, xmax, ymin, ymax)</span></span>
<span><span class="co">#&gt; crs        : +proj=laea +lat_0=37.602 +lon_0=-86.264 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs </span></span>
<span><span class="co">#&gt; source     : memory</span></span>
<span><span class="co">#&gt; names      :       jan,       feb,       mar,       apr,       may,       jun,       jul,       aug,       sep,       oct,       nov,       dec </span></span>
<span><span class="co">#&gt; min values :         0,         0,         0,         0,         0,         0,         0,         0,         0,         0,         0,         0 </span></span>
<span><span class="co">#&gt; max values : 0.7395810, 0.7943784, 0.8571786, 0.9811116, 0.9396346, 1.0000000, 0.9789176, 0.8478352, 0.6832114, 0.7556157, 0.8300090, 0.7643719</span></span></code></pre></div>
<p>Next, we want to choose a color palette that helps communicate
temporal information about Field Sparrow occurrence. Among the three
palette functions currently included in <code>colorist</code>, we want
to use <code><a href="../reference/palette_timecycle.html">palette_timecycle()</a></code> because our data layers
represent an ordered sequence of distributions that circles back on
itself (i.e., the distribution of Field Sparrows in December is
temporally adjacent to both November and January distributions).</p>
<div class="sourceCode" id="cb3"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># generate a color palette</span></span>
<span><span class="va">p1</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/palette_timecycle.html">palette_timecycle</a></span><span class="op">(</span><span class="va">fiespa_occ</span><span class="op">)</span></span>
<span><span class="fu"><a href="https://rdrr.io/r/utils/head.html" class="external-link">head</a></span><span class="op">(</span><span class="va">p1</span><span class="op">)</span></span>
<span><span class="co">#&gt;   specificity layer_id   color</span></span>
<span><span class="co">#&gt; 1           0        1 #6A6A6A</span></span>
<span><span class="co">#&gt; 2           0        2 #6A6A6A</span></span>
<span><span class="co">#&gt; 3           0        3 #6A6A6A</span></span>
<span><span class="co">#&gt; 4           0        4 #6A6A6A</span></span>
<span><span class="co">#&gt; 5           0        5 #6A6A6A</span></span>
<span><span class="co">#&gt; 6           0        6 #6A6A6A</span></span></code></pre></div>
<p>The <code><a href="../reference/palette_timecycle.html">palette_timecycle()</a></code> function returns a data frame
with three fields: <code>specificity</code>, <code>layer_id</code>, and
<code>color</code>. The <code>specificity</code> and
<code>layer_id</code> fields will be used to assign colors to specific
raster cells.</p>
<p>To visualize our distributions in individual facets, we provide the
<code><a href="../reference/map_multiples.html">map_multiples()</a></code> function with distribution metrics and
palette information. The structure of the plot and labels for each
distribution within the plot can be specified using the
<code>ncol</code> and <code>labels</code> arguments, respectively.</p>
<div class="sourceCode" id="cb4"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># map each of the layers</span></span>
<span><span class="fu"><a href="../reference/map_multiples.html">map_multiples</a></span><span class="op">(</span><span class="va">m1</span>, <span class="va">p1</span>, ncol <span class="op">=</span> <span class="fl">4</span>, labels <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/names.html" class="external-link">names</a></span><span class="op">(</span><span class="va">fiespa_occ</span><span class="op">)</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/fiespa-mapmult-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>If we want to extract one month of data for closer inspection, we can
use <code><a href="../reference/map_single.html">map_single()</a></code> and specify which month of data we would
like to see using the layer argument.</p>
<div class="sourceCode" id="cb5"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># map one layer</span></span>
<span><span class="fu"><a href="../reference/map_single.html">map_single</a></span><span class="op">(</span><span class="va">m1</span>, <span class="va">p1</span>, layer <span class="op">=</span> <span class="fl">6</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/fiespa-mapsing-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>To generate a single annual cycle map that synthesizes spatiotemporal
information about Field Sparrow occurrence, we need to “distill” the
distributional information in our <code>RasterStack</code> using
<code><a href="../reference/metrics_distill.html">metrics_distill()</a></code>.</p>
<p>The <code><a href="../reference/metrics_distill.html">metrics_distill()</a></code> function calculates distribution
metrics across all layers in every raster cell and returns three metrics
for subsequent visualization:</p>
<ol style="list-style-type: decimal">
<li>Maximum intensity (i.e., the maximum occurrence, abundance, or
density value).</li>
<li>Layer of maximum intensity (i.e., the identity of the layer
containing the maximum intensity value)</li>
<li>Specificity of the maximum intensity value to the layer of maximum
intensity (i.e., the degree to which intensity values are unevenly
distributed across layers).</li>
</ol>
<p>While the maximum intensity and layer of maximum intensity metrics
are relatively easy to grasp, the calculation and meaning of
“specificity” warrants further explanation. We define specificity
according to the following equation:</p>
<p><span class="math display">\[
specificity=50\times \frac{\sum_{l=1}^{n}|y_l-\bar{y}|}{(n-1)\cdot
\bar{y}}
\]</span> where <span class="math inline">\(n\)</span> indicates the
number of layers in the <code>RasterStack</code>, <span class="math inline">\(y_l\)</span> is the intensity value in layer <span class="math inline">\(l\)</span>, and <span class="math inline">\(\bar{y}\)</span> is the mean intensity value
across layers. Specificity values can range from 0 to 100. Values of 0
indicate intensity values are identical in all layers, while values of
100 indicate intensity values are restricted to a single layer.</p>
<p>The interpretation of specificity values depends on the nature of the
data layers being explored. In the case of Field Sparrow, where raster
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).</p>
<p>After providing <code><a href="../reference/metrics_distill.html">metrics_distill()</a></code> with the
<code>fiespa_occ</code> data, the <code><a href="../reference/map_single.html">map_single()</a></code> function
combines the resulting distribution metrics and palette information to
generate a map.</p>
<div class="sourceCode" id="cb6"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># distill distribution information across layers</span></span>
<span><span class="va">m1_distill</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/metrics_distill.html">metrics_distill</a></span><span class="op">(</span><span class="va">fiespa_occ</span><span class="op">)</span></span>
<span></span>
<span><span class="co"># visualize distilled information on a single map</span></span>
<span><span class="fu"><a href="../reference/map_single.html">map_single</a></span><span class="op">(</span><span class="va">m1_distill</span>, <span class="va">p1</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/fiespa-distill-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>Interpreting annual cycle maps becomes straightforward with a little
experience, but a legend is typically required to orient viewers. We can
generate a legend for the Field Sparrow annual cycle map using
<code><a href="../reference/legend_timecycle.html">legend_timecycle()</a></code>, a function that requires a data frame
generated by <code><a href="../reference/palette_timecycle.html">palette_timecycle()</a></code>. Information about when
the time cycle begins (and ends) can also be provided in the
origin_label argument. When interpreting the legend and map, remember
that specificity indicates degree of seasonality in Field Sparrow
occurrence.</p>
<div class="sourceCode" id="cb7"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># generate a legend</span></span>
<span><span class="fu"><a href="../reference/legend_timecycle.html">legend_timecycle</a></span><span class="op">(</span><span class="va">p1</span>, origin_label <span class="op">=</span> <span class="st">"Jan 1"</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/fielsp-legend-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>With an annual cycle map and legend in hand, we can now figure out
where to find Field Sparrows in space and time. Very colorful cells
indicate areas with high occurrence probabilities, but only during
specific times of year. For example, rich blue colors towards the bottom
of the map indicate that birds occur in those cells with high
probability, but almost exclusively in the winter months. In contrast,
dark gray areas indicate consistently high occurrence probabilities in
cells throughout the year.</p>
</div>
<div class="section level3">
<h3 id="map-individual-behavior-over-time">2. Map individual behavior over time<a class="anchor" aria-label="anchor" href="#map-individual-behavior-over-time"></a>
</h3>
<p>Researchers have been placing devices on animals for more than a half
century to record individual movements through space and time. In recent
years, tracking devices have become smaller, lighter, and increasingly
capable of recording data with high spatiotemporal resolution. As a
result, it is now possible to understand and communicate how individual
animals use their environments in much more detail than was feasible
with coarse tracking data and traditional home range maps.</p>
<p>Here, we use <code>colorist</code> to explore how an individual
Fisher (<em>Pekania pennanti</em>) living in upstate New York moved
through its local environment over a period of nine sequential nights in
2011. Fisher are omnivorous mammals in the weasel family that occur in
boreal forests throughout Canada and the United States. They tend to be
solitary throughout most of the year but males and females will
sometimes inhabit overlapping territories.</p>
<p>We start by loading the <code>fisher_ud</code> data set, which
contains utilization distributions calculated for an individual animal
(MP5) on each of nine sequential nights in April 2011. Cell values in
each raster layer indicate the probability density of cell use between
sunset and sunrise.</p>
<div class="sourceCode" id="cb8"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># loda data</span></span>
<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">"fisher_ud"</span><span class="op">)</span></span>
<span><span class="va">fisher_ud</span></span>
<span><span class="co">#&gt; class      : RasterStack </span></span>
<span><span class="co">#&gt; dimensions : 176, 177, 31152, 9  (nrow, ncol, ncell, nlayers)</span></span>
<span><span class="co">#&gt; resolution : 25, 25  (x, y)</span></span>
<span><span class="co">#&gt; extent     : -2282.343, 2142.657, 5100266, 5104666  (xmin, xmax, ymin, ymax)</span></span>
<span><span class="co">#&gt; crs        : +proj=moll +lon_0=-73.4137066015374 +x_0=0 +y_0=0 +ellps=WGS84 +units=m +no_defs </span></span>
<span><span class="co">#&gt; names      :      night1,      night2,      night3,      night4,      night5,      night6,      night7,      night8,      night9 </span></span>
<span><span class="co">#&gt; min values :           0,           0,           0,           0,           0,           0,           0,           0,           0 </span></span>
<span><span class="co">#&gt; max values : 0.004695207, 0.007591029, 0.006749434, 0.002891691, 0.002833876, 0.004711692, 0.002017082, 0.002700729, 0.005282948</span></span></code></pre></div>
<p>After loading the data, let’s begin by visualizing information in
each of the layers. We do this by “pulling” information from the
<code>RasterStack</code> and combining it with a color palette in
<code><a href="../reference/map_multiples.html">map_multiples()</a></code>. The Fisher data differ from the Field
Sparrow data in the previous example in that they describe a linear
sequence of distributions, not a cyclical sequence. So, we need to use
<code><a href="../reference/palette_timeline.html">palette_timeline()</a></code> rather than
<code><a href="../reference/palette_timecycle.html">palette_timecycle()</a></code> to generate our color palette.</p>
<div class="sourceCode" id="cb9"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># pull information from the stack</span></span>
<span><span class="va">m2</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/metrics_pull.html">metrics_pull</a></span><span class="op">(</span><span class="va">fisher_ud</span><span class="op">)</span></span>
<span></span>
<span><span class="co"># generate a color palette</span></span>
<span><span class="va">p2</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/palette_timeline.html">palette_timeline</a></span><span class="op">(</span><span class="va">fisher_ud</span><span class="op">)</span></span>
<span></span>
<span><span class="co"># map each of the layers</span></span>
<span><span class="fu"><a href="../reference/map_multiples.html">map_multiples</a></span><span class="op">(</span><span class="va">m2</span>, <span class="va">p2</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/fisher-map-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>Many of the maps appear relatively washed out because intensity
values in every cell have been scaled relative to the highest intensity
value in the entire <code>RasterStack</code>. It is not uncommon for
distributions to contain highly skewed intensity values because
individual animals spend a vast majority of their time within a
relatively small area or, in the case of species distributions, because
populations are relatively dense during some seasons and relatively
dispersed during others. This can make visualizing distributions a
challenge.</p>
<p>The <code>lambda_i</code> parameter in <code><a href="../reference/map_multiples.html">map_multiples()</a></code>
and <code><a href="../reference/map_single.html">map_single()</a></code> allows users to visually tune the relative
weights of high and low intensity values using a modulus transformation
(see [scales::modulus_trans()]). In this case, we want to reduce the
disparity between the visual weights of high and low intensity values,
so we set <code>lambda_i = -5</code>.</p>
<div class="sourceCode" id="cb10"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># map each of the layers and adjust visual weights</span></span>
<span><span class="fu"><a href="../reference/map_multiples.html">map_multiples</a></span><span class="op">(</span><span class="va">m2</span>, <span class="va">p2</span>, lambda_i <span class="op">=</span> <span class="op">-</span><span class="fl">5</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/fisher-lambda_i-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>This enables us to better see the places where our focal animal spent
at least some time as it moved across the landscape. To further explore
how MP5 moved throughout its territory over the course of nine nights,
we can “distill” distributional information from across all nine layers
and use the resulting metrics to visualize patterns of space use with
<code><a href="../reference/map_single.html">map_single()</a></code>.</p>
<p>It is important to remember that specificity values (and resulting
visualization of specificity values) for Fisher should be interpreted
differently than for Field Sparrow. Here, specificity values indicate
the degree to which MP5 used the same locations within the landscape
across nine nights. Low specificity suggests consistent use through
time. High specificity suggests very inconsistent or ephemeral use.</p>
<div class="sourceCode" id="cb11"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># distill distribution information across layers</span></span>
<span><span class="va">m2_distill</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/metrics_distill.html">metrics_distill</a></span><span class="op">(</span><span class="va">fisher_ud</span><span class="op">)</span></span>
<span></span>
<span><span class="co"># visualize distilled information on a single map</span></span>
<span><span class="fu"><a href="../reference/map_single.html">map_single</a></span><span class="op">(</span><span class="va">m2_distill</span>, <span class="va">p2</span>, lambda_i <span class="op">=</span> <span class="op">-</span><span class="fl">5</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/fisher-distill-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>Output from <code><a href="../reference/legend_timeline.html">legend_timeline()</a></code> will help to orient
viewers and we can use the <code>time_labels</code> argument to indicate
the ends of the timeline. Looking across the nine nights, MP5 spent
relatively little of its time anchored in one area. The bright colors
seen throughout the map are the result of high specificity values, which
indicate that MP5 explored different parts of its territory almost every
night.</p>
<div class="sourceCode" id="cb12"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># generate a legend</span></span>
<span><span class="fu"><a href="../reference/legend_timeline.html">legend_timeline</a></span><span class="op">(</span><span class="va">p2</span>, time_labels <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">"April 7"</span>, <span class="st">"April 15"</span><span class="op">)</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/fisher-legend-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
</div>
<div class="section level3">
<h3 id="map-distributions-of-multiple-individuals-during-the-same-time-period">3. Map distributions of multiple individuals during the same time
period<a class="anchor" aria-label="anchor" href="#map-distributions-of-multiple-individuals-during-the-same-time-period"></a>
</h3>
<p>In the previous examples, we used <code>colorist</code> to explore
the distributions of a single species and a single individual across
multiple time periods. Other conceptualizations and uses of
<code>colorist</code> functions are possible, however. For example,
<code>colorist</code> can also be used to explore the distribution of
multiple species or individuals within a single time period.</p>
<p>Here, we use GPS tracking data collected from African Elephants
(<em>Loxodonta africana</em>) in Etosha National Park, Namibia during
2011 to explore how two individuals used the landscape over the course
of a year. The African Elephant is an iconic species with a complex
social system that remains a target of poachers throughout much of
Africa. Many populations of African Elephants move seasonally along
specific migratory routes, tracking availability of seasonally abundant
resources.</p>
<p>To begin, we load the <code>elephant_ud</code> data set which
contains utilization distributions for two individual elephants (LA11
and LA14) during 2011. Because the utilization distributions form an
unordered set (i.e., they need not be presented in any specific cyclical
or linear sequence), we use the <code><a href="../reference/palette_set.html">palette_set()</a></code> function to
assign them colors. Then, we map the two distributions using
<code><a href="../reference/map_multiples.html">map_multiples()</a></code> while adding visual emphasis to rarely used
areas with the <code>lambda_i</code> argument and adding identifiers to
each map with the labels argument.</p>
<div class="sourceCode" id="cb13"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># load data</span></span>
<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>
<span><span class="co"># pull information from the stack</span></span>
<span><span class="va">m3</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/metrics_pull.html">metrics_pull</a></span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span></span>
<span></span>
<span><span class="co"># assign a color palette</span></span>
<span><span class="va">p3</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/palette_set.html">palette_set</a></span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span></span>
<span></span>
<span><span class="co"># generate maps for each individual</span></span>
<span><span class="fu"><a href="../reference/map_multiples.html">map_multiples</a></span><span class="op">(</span><span class="va">m3</span>, <span class="va">p3</span>, ncol <span class="op">=</span> <span class="fl">2</span>, lambda_i <span class="op">=</span> <span class="op">-</span><span class="fl">5</span>, labels <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/names.html" class="external-link">names</a></span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/elephant-pull-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>The utilization distributions for LA11 and LA14 look remarkably
similar at first glance, which is not surprising given the two elephants
belong to the same herd. However, we can more clearly understand the
similarities and differences in how they used space in 2011 by
“distilling” distributional information from across the two raster
layers with <code><a href="../reference/metrics_distill.html">metrics_distill()</a></code> and visualizing the resulting
metrics with <code><a href="../reference/map_single.html">map_single()</a></code>.</p>
<p>Before generating the map, however, we should recalibrate our
understanding of what specificity values mean based on the nature of the
data we are exploring. In contrast to the Field Sparrow and Fisher
examples, where specificity indicated the degree to which intensity
values were inconsistent (or consistent) through time, here specificity
values can be interpreted as a measure of differential use of the
landscape. Very low specificity values indicate equal use of a cell by
both individuals; very high specificity values indicate exclusive use by
one individual.</p>
<p>Accordingly, if the two utilization distributions were identical, we
would expect <code><a href="../reference/map_single.html">map_single()</a></code> to produce a range of gray values
indicating where the pair spent relatively more or less time. There
would not be any blue or red cells indicating areas were being used
differentially. In contrast, if the two distributions were only
superficially similar then we would expect <code><a href="../reference/map_single.html">map_single()</a></code> to
produce blue and red cells indicating exclusive use of areas by each
individual, and very few gray cells indicating equal use.</p>
<div class="sourceCode" id="cb14"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># distill distribution information across individuals</span></span>
<span><span class="va">m3_distill</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/metrics_distill.html">metrics_distill</a></span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span></span>
<span></span>
<span><span class="co"># visualize distilled information on a single map</span></span>
<span><span class="fu"><a href="../reference/map_single.html">map_single</a></span><span class="op">(</span><span class="va">m3_distill</span>, <span class="va">p3</span>, lambda_i <span class="op">=</span> <span class="op">-</span><span class="fl">5</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/elephant-distill-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<div class="sourceCode" id="cb15"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># generate a legend</span></span>
<span><span class="fu"><a href="../reference/legend_set.html">legend_set</a></span><span class="op">(</span><span class="va">p3</span>, group_labels <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/names.html" class="external-link">names</a></span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span><span class="op">)</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/elephant-distill-2.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>Despite the general similarity of the two utilization distributions,
some places were used almost exclusively by LA11 (i.e., blue cells) and
others were used almost exclusively by LA14 (i.e., red cells). We can
contextualize these patterns by adding information about the locations
of pans, waterholes, roads, and boundaries to the map. These
environmental data layers can be <a href="https://github.com/mstrimas/colorist/raw/master/data-raw/etosha-features.gpkg" class="external-link">downloaded
as a GeoPackage</a> from the package GitHub repository, which we do
below.</p>
<div class="sourceCode" id="cb16"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># download data to a temp directory</span></span>
<span><span class="va">url</span> <span class="op">&lt;-</span> <span class="st">"https://github.com/mstrimas/colorist/raw/master/data-raw/"</span></span>
<span><span class="va">f</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/file.path.html" class="external-link">file.path</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/tempfile.html" class="external-link">tempdir</a></span><span class="op">(</span><span class="op">)</span>, <span class="st">"etosha-features.gpkg"</span><span class="op">)</span></span>
<span><span class="fu"><a href="https://rdrr.io/r/utils/download.file.html" class="external-link">download.file</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/paste.html" class="external-link">paste0</a></span><span class="op">(</span><span class="va">url</span>, <span class="fu"><a href="https://rdrr.io/r/base/basename.html" class="external-link">basename</a></span><span class="op">(</span><span class="va">f</span><span class="op">)</span><span class="op">)</span>, <span class="va">f</span><span class="op">)</span></span></code></pre></div>
<p>We can then read the spatial data from the GeoPackage into R and
ensure that the data are described by the same coordinate reference
system as the elephant data.</p>
<div class="sourceCode" id="cb17"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="va">pans</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_read.html" class="external-link">read_sf</a></span><span class="op">(</span><span class="va">f</span>, layer <span class="op">=</span> <span class="st">"pans"</span><span class="op">)</span> <span class="op"><a href="../reference/pipe.html">%&gt;%</a></span> </span>
<span>  <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_transform.html" class="external-link">st_transform</a></span><span class="op">(</span>crs <span class="op">=</span> <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_crs.html" class="external-link">st_crs</a></span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span><span class="op">)</span></span>
<span></span>
<span><span class="va">waterholes</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_read.html" class="external-link">read_sf</a></span><span class="op">(</span><span class="va">f</span>, layer <span class="op">=</span> <span class="st">"waterholes"</span><span class="op">)</span> <span class="op"><a href="../reference/pipe.html">%&gt;%</a></span> </span>
<span>  <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_transform.html" class="external-link">st_transform</a></span><span class="op">(</span>crs <span class="op">=</span> <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_crs.html" class="external-link">st_crs</a></span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span><span class="op">)</span></span>
<span></span>
<span><span class="va">park</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_read.html" class="external-link">read_sf</a></span><span class="op">(</span><span class="va">f</span>, layer <span class="op">=</span> <span class="st">"etosha"</span><span class="op">)</span> <span class="op"><a href="../reference/pipe.html">%&gt;%</a></span> </span>
<span>  <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_transform.html" class="external-link">st_transform</a></span><span class="op">(</span>crs <span class="op">=</span> <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_crs.html" class="external-link">st_crs</a></span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span><span class="op">)</span></span>
<span></span>
<span><span class="va">roads</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_read.html" class="external-link">read_sf</a></span><span class="op">(</span><span class="va">f</span>, layer <span class="op">=</span> <span class="st">"roads"</span><span class="op">)</span> <span class="op"><a href="../reference/pipe.html">%&gt;%</a></span> </span>
<span>  <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_transform.html" class="external-link">st_transform</a></span><span class="op">(</span>crs <span class="op">=</span> <span class="fu"><a href="https://r-spatial.github.io/sf/reference/st_crs.html" class="external-link">st_crs</a></span><span class="op">(</span><span class="va">elephant_ud</span><span class="op">)</span><span class="op">)</span></span></code></pre></div>
<p>Then we use <code><a href="../reference/map_single.html">map_single()</a></code> to reproduce our map of LA11
and LA14 distributions, but we append <code><a href="https://ggplot2.tidyverse.org/reference/ggsf.html" class="external-link">geom_sf()</a></code> line
objects to our <code><a href="../reference/map_single.html">map_single()</a></code> function. These additional
lines of code allow us to add environmental context to our underlying
elephant map (which is a <code>ggplot</code> object) and communicate
additional information about how elephants LA11 and LA14 navigate Etosha
National Park.</p>
<div class="sourceCode" id="cb18"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># visualize both distributions on a single map and add environmental data </span></span>
<span><span class="va">elephant_map</span> <span class="op">&lt;-</span> <span class="fu"><a href="../reference/map_single.html">map_single</a></span><span class="op">(</span><span class="va">m3_distill</span>, <span class="va">p3</span>, lambda_i <span class="op">=</span> <span class="op">-</span><span class="fl">5</span><span class="op">)</span> <span class="op">+</span></span>
<span>  <span class="fu"><a href="https://ggplot2.tidyverse.org/reference/ggsf.html" class="external-link">geom_sf</a></span><span class="op">(</span>data <span class="op">=</span> <span class="va">pans</span>, alpha <span class="op">=</span> <span class="fl">0.2</span>, size <span class="op">=</span> <span class="fl">0.15</span>, color <span class="op">=</span> <span class="st">"gray40"</span><span class="op">)</span> <span class="op">+</span> </span>
<span>  <span class="fu"><a href="https://ggplot2.tidyverse.org/reference/ggsf.html" class="external-link">geom_sf</a></span><span class="op">(</span>data <span class="op">=</span> <span class="va">waterholes</span>, size <span class="op">=</span> <span class="fl">0.25</span><span class="op">)</span> <span class="op">+</span></span>
<span>  <span class="fu"><a href="https://ggplot2.tidyverse.org/reference/ggsf.html" class="external-link">geom_sf</a></span><span class="op">(</span>data <span class="op">=</span> <span class="va">park</span>, size <span class="op">=</span> <span class="fl">3</span>, fill <span class="op">=</span> <span class="cn">NA</span>, color <span class="op">=</span> <span class="fu"><a href="https://scales.r-lib.org/reference/alpha.html" class="external-link">alpha</a></span><span class="op">(</span><span class="st">"gray60"</span>, <span class="fl">0.2</span><span class="op">)</span><span class="op">)</span> <span class="op">+</span></span>
<span>  <span class="fu"><a href="https://ggplot2.tidyverse.org/reference/ggsf.html" class="external-link">geom_sf</a></span><span class="op">(</span>data <span class="op">=</span> <span class="va">park</span>, size <span class="op">=</span> <span class="fl">0.2</span>, fill <span class="op">=</span> <span class="cn">NA</span>, color <span class="op">=</span> <span class="st">"gray20"</span>, linetype <span class="op">=</span> <span class="fl">6</span><span class="op">)</span> <span class="op">+</span></span>
<span>  <span class="fu"><a href="https://ggplot2.tidyverse.org/reference/labs.html" class="external-link">ggtitle</a></span><span class="op">(</span><span class="st">"Two Elephants in Etosha National Park"</span><span class="op">)</span> </span>
<span></span>
<span><span class="co"># show the map</span></span>
<span><span class="va">elephant_map</span></span></code></pre></div>
<p><img src="introduction_files/figure-html/elephant-pretty-1.png" width="\textwidth" style="display: block; margin: auto;"></p>
<p>The resulting map object (<code>elephant_map</code>) could be saved
using the <code><a href="https://ggplot2.tidyverse.org/reference/ggsave.html" class="external-link">ggsave()</a></code> function.</p>
<div class="sourceCode" id="cb19"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="co"># save the map</span></span>
<span><span class="fu"><a href="https://ggplot2.tidyverse.org/reference/ggsave.html" class="external-link">ggsave</a></span><span class="op">(</span>plot <span class="op">=</span> <span class="va">elephant_map</span>,</span>
<span>       filename <span class="op">=</span> <span class="st">"afrele_map_singles.png"</span>,</span>
<span>       width <span class="op">=</span> <span class="fl">6</span>,</span>
<span>       height <span class="op">=</span> <span class="fl">3.5</span>,</span>
<span>       dpi <span class="op">=</span> <span class="fl">600</span><span class="op">)</span></span></code></pre></div>
</div>
</div>
  </div>

  <div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">

        <nav id="toc" data-toggle="toc"><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>
