<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" ><generator uri="https://jekyllrb.com/" version="3.10.0">Jekyll</generator><link href="https://jessecambon.github.io/feed.xml" rel="self" type="application/atom+xml" /><link href="https://jessecambon.github.io/" rel="alternate" type="text/html" /><updated>2025-11-21T15:04:45+00:00</updated><id>https://jessecambon.github.io/feed.xml</id><title type="html">Jesse Cambon</title><subtitle>Musings on data and open source software</subtitle><author><name>Jesse Cambon</name><email>jesse.cambon@gmail.com</email></author><entry><title type="html">Tidygeocoder 1.0.4</title><link href="https://jessecambon.github.io/2021/10/17/tidygeocoder-1-0-4.html" rel="alternate" type="text/html" title="Tidygeocoder 1.0.4" /><published>2021-10-17T00:00:00+00:00</published><updated>2021-10-17T00:00:00+00:00</updated><id>https://jessecambon.github.io/2021/10/17/tidygeocoder-1-0-4</id><content type="html" xml:base="https://jessecambon.github.io/2021/10/17/tidygeocoder-1-0-4.html"><![CDATA[<p><a href="https://jessecambon.github.io/tidygeocoder/">Tidygeocoder v1.0.4</a> is released! 🍾 This release adds support for the <a href="https://www.geoapify.com/geocoding-api">Geoapify geocoding service</a> (thanks <a href="https://github.com/dpprdan">Daniel Possenriede</a>!), a progress bar, more helpful console output, and new functions for combining the results of multiple geocoding queries. A more detailed overview of the changes in this release is available in the <a href="https://jessecambon.github.io/tidygeocoder/news/index.html">changelog</a>.</p>

<h3 id="progress-bars-and-console-output">Progress Bars and Console Output</h3>

<p>Progress bars are now displayed for single input geocoding queries (ie. not batch queries). Additionally, console messages now by default show which geocoding service was used, how many addresses or coordinates were given to it, and how long the query took to execute.</p>

<p><img src="/../images/tidygeocoder_progress_bar_v104.gif" width="70%" style="display: block; margin: auto;" /></p>

<p>The <code class="language-plaintext highlighter-rouge">progress_bar</code> parameter can be used to toggle the use of the progress bar while the <code class="language-plaintext highlighter-rouge">quiet</code> parameter can be used to silence console messages that are displayed by default. See the documentation for <a href="https://jessecambon.github.io/tidygeocoder/reference/geo.html">geo()</a> or <a href="https://jessecambon.github.io/tidygeocoder/reference/reverse_geo.html">reverse_geo()</a> for details.</p>

<p>Additionally, the <code class="language-plaintext highlighter-rouge">quiet</code>, <code class="language-plaintext highlighter-rouge">progress_bar</code>, and <code class="language-plaintext highlighter-rouge">verbose</code> parameters can now be set permanently via <code class="language-plaintext highlighter-rouge">options()</code>. For example, <code class="language-plaintext highlighter-rouge">options(tidygeocoder.progress_bar = FALSE)</code> will disable progress bars for all queries.</p>

<h3 id="combining-multiple-queries">Combining Multiple Queries</h3>

<p>In past releases of the package, <code class="language-plaintext highlighter-rouge">method = "cascade"</code> could be used in the <code class="language-plaintext highlighter-rouge">geo()</code> and <code class="language-plaintext highlighter-rouge">geocode()</code> functions to combine the results of geocoding queries from two different services. The “cascade” method is now deprecated in favor of two new and more flexible functions: <code class="language-plaintext highlighter-rouge">geocode_combine()</code> and <code class="language-plaintext highlighter-rouge">geo_combine()</code>. These functions allow for executing and combining the results of more than two queries and they allow the queries to be fully customized.</p>

<p>To demonstrate the utility of these new functions, below I’ve assembled a dataset of addresses to be geocoded. The first 5 are street level addresses in the United States that can be geocoded with the US Census geocoding service. However, three of these addresses will not return results with the US Census <em>batch</em> service (see <a href="https://github.com/jessecambon/tidygeocoder/issues/87">issue #87</a> for more information) and must instead be geocoded with the US Census single address geocoder. Also, the last three addresses are cities outside the United States and require a different geocoding service entirely (the US Census service is limited to the United States).</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">tidyverse</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">tidygeocoder</span><span class="p">)</span><span class="w">

</span><span class="n">mixed_addresses</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">tribble</span><span class="p">(</span><span class="w">
  </span><span class="o">~</span><span class="n">street_address</span><span class="p">,</span><span class="w"> </span><span class="o">~</span><span class="n">city</span><span class="p">,</span><span class="w"> </span><span class="o">~</span><span class="n">state_cd</span><span class="p">,</span><span class="w"> </span><span class="o">~</span><span class="n">zip_cd</span><span class="p">,</span><span class="w">
  </span><span class="s2">"624 W DAVIS ST #1D"</span><span class="p">,</span><span class="w">   </span><span class="s2">"BURLINGTON"</span><span class="p">,</span><span class="w"> </span><span class="s2">"NC"</span><span class="p">,</span><span class="w">  </span><span class="m">27215</span><span class="p">,</span><span class="w">
  </span><span class="s2">"201 E CENTER ST #268"</span><span class="p">,</span><span class="w"> </span><span class="s2">"MEBANE"</span><span class="p">,</span><span class="w">     </span><span class="s2">"NC"</span><span class="p">,</span><span class="w">  </span><span class="m">27302</span><span class="p">,</span><span class="w">
  </span><span class="s2">"7833  WOLFE LN"</span><span class="p">,</span><span class="w">       </span><span class="s2">"SNOW CAMP"</span><span class="p">,</span><span class="w">  </span><span class="s2">"NC"</span><span class="p">,</span><span class="w">  </span><span class="m">27349</span><span class="p">,</span><span class="w">
  </span><span class="s2">"202 C St"</span><span class="p">,</span><span class="w">             </span><span class="s2">"San Diego"</span><span class="p">,</span><span class="w">  </span><span class="s2">"CA"</span><span class="p">,</span><span class="w">  </span><span class="m">92101</span><span class="p">,</span><span class="w">
  </span><span class="s2">"121 N Rouse Ave"</span><span class="p">,</span><span class="w">      </span><span class="s2">"Bozeman"</span><span class="p">,</span><span class="w">    </span><span class="s2">"MT"</span><span class="p">,</span><span class="w">  </span><span class="m">59715</span><span class="w">
</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">bind_rows</span><span class="p">(</span><span class="w">
    </span><span class="n">tibble</span><span class="p">(</span><span class="n">city</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="s1">'Taipei'</span><span class="p">,</span><span class="w"> </span><span class="s1">'Moscow'</span><span class="p">,</span><span class="w"> </span><span class="s1">'Buenos Aires'</span><span class="p">))</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p>If we wanted to geocode a large dataset with addresses such as these, we might first try to geocode as many as possible via the US Census batch service, then attempt the remaining addresses with the US Census single address geocoder, and then finally send any remaining unfound addresses to another service. We’ll accomplish this workflow in the code below.</p>

<p>The <code class="language-plaintext highlighter-rouge">geocode_combine()</code> function accepts a dataframe input and a list of queries provided as lists (ie. a list of lists). Each list in the <code class="language-plaintext highlighter-rouge">queries</code> argument contains parameters that are passed to the <code class="language-plaintext highlighter-rouge">geocode()</code> function. Optionally, the <code class="language-plaintext highlighter-rouge">query_names</code> argument can be used to specify a label to be used for each query’s results.</p>

<p>Below, the <code class="language-plaintext highlighter-rouge">street</code>, <code class="language-plaintext highlighter-rouge">city</code>, <code class="language-plaintext highlighter-rouge">state</code>, and <code class="language-plaintext highlighter-rouge">postalcode</code> arguments are specified for the first two queries while the <code class="language-plaintext highlighter-rouge">address</code> argument (ie. single line address) is pointed at the <code class="language-plaintext highlighter-rouge">city</code> column for the third query (the ArcGIS service only accepts a single line address argument and doesn’t use address component arguments like <code class="language-plaintext highlighter-rouge">city</code> and <code class="language-plaintext highlighter-rouge">state</code>).</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">results</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mixed_addresses</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">geocode_combine</span><span class="p">(</span><span class="w">
    </span><span class="n">queries</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">list</span><span class="p">(</span><span class="w">
      </span><span class="nf">list</span><span class="p">(</span><span class="n">method</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'census'</span><span class="p">,</span><span class="w"> </span><span class="n">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'batch'</span><span class="p">,</span><span class="w"> 
        </span><span class="n">street</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'street_address'</span><span class="p">,</span><span class="w"> </span><span class="n">city</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'city'</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'state_cd'</span><span class="p">,</span><span class="w"> </span><span class="n">postalcode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'zip_cd'</span><span class="p">),</span><span class="w">
      </span><span class="nf">list</span><span class="p">(</span><span class="n">method</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'census'</span><span class="p">,</span><span class="w"> </span><span class="n">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'single'</span><span class="p">,</span><span class="w">
           </span><span class="n">street</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'street_address'</span><span class="p">,</span><span class="w"> </span><span class="n">city</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'city'</span><span class="p">,</span><span class="w"> </span><span class="n">state</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'state_cd'</span><span class="p">,</span><span class="w"> </span><span class="n">postalcode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'zip_cd'</span><span class="p">),</span><span class="w">
      </span><span class="nf">list</span><span class="p">(</span><span class="n">method</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'arcgis'</span><span class="p">,</span><span class="w"> </span><span class="n">address</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'city'</span><span class="p">)</span><span class="w">
    </span><span class="p">),</span><span class="w">
    </span><span class="n">query_names</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="s1">'census - batch'</span><span class="p">,</span><span class="w"> </span><span class="s1">'census - single'</span><span class="p">,</span><span class="w"> </span><span class="s1">'arcgis'</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>## 

## Passing 8 addresses to the US Census batch geocoder

## Query completed in: 1.9 seconds

## Passing 6 addresses to the US Census single address geocoder

## Query completed in: 3.6 seconds

## Passing 3 addresses to the ArcGIS single address geocoder

## Query completed in: 1.4 seconds
</code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">street_address</th>
      <th style="text-align: left">city</th>
      <th style="text-align: left">state_cd</th>
      <th style="text-align: right">zip_cd</th>
      <th style="text-align: right">lat</th>
      <th style="text-align: right">long</th>
      <th style="text-align: left">query</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">624 W DAVIS ST #1D</td>
      <td style="text-align: left">BURLINGTON</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: right">27215</td>
      <td style="text-align: right">36.09598</td>
      <td style="text-align: right">-79.44453</td>
      <td style="text-align: left">census - single</td>
    </tr>
    <tr>
      <td style="text-align: left">201 E CENTER ST #268</td>
      <td style="text-align: left">MEBANE</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: right">27302</td>
      <td style="text-align: right">36.09683</td>
      <td style="text-align: right">-79.26977</td>
      <td style="text-align: left">census - single</td>
    </tr>
    <tr>
      <td style="text-align: left">7833 WOLFE LN</td>
      <td style="text-align: left">SNOW CAMP</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: right">27349</td>
      <td style="text-align: right">35.89866</td>
      <td style="text-align: right">-79.43713</td>
      <td style="text-align: left">census - single</td>
    </tr>
    <tr>
      <td style="text-align: left">202 C St</td>
      <td style="text-align: left">San Diego</td>
      <td style="text-align: left">CA</td>
      <td style="text-align: right">92101</td>
      <td style="text-align: right">32.71676</td>
      <td style="text-align: right">-117.16283</td>
      <td style="text-align: left">census - batch</td>
    </tr>
    <tr>
      <td style="text-align: left">121 N Rouse Ave</td>
      <td style="text-align: left">Bozeman</td>
      <td style="text-align: left">MT</td>
      <td style="text-align: right">59715</td>
      <td style="text-align: right">45.68066</td>
      <td style="text-align: right">-111.03203</td>
      <td style="text-align: left">census - batch</td>
    </tr>
    <tr>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">Taipei</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: right">NA</td>
      <td style="text-align: right">25.03737</td>
      <td style="text-align: right">121.56355</td>
      <td style="text-align: left">arcgis</td>
    </tr>
    <tr>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">Moscow</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: right">NA</td>
      <td style="text-align: right">55.75696</td>
      <td style="text-align: right">37.61502</td>
      <td style="text-align: left">arcgis</td>
    </tr>
    <tr>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">Buenos Aires</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: right">NA</td>
      <td style="text-align: right">-34.60849</td>
      <td style="text-align: right">-58.37344</td>
      <td style="text-align: left">arcgis</td>
    </tr>
  </tbody>
</table>

<p>By default the results of the queries are combined into a single dataframe as shown above and the <code class="language-plaintext highlighter-rouge">query</code> column shows which query produced each result. Alternatively, the results of each query can be returned as separate dataframes in a list by using <code class="language-plaintext highlighter-rouge">return_list = TRUE</code>.</p>

<p>By default, only addresses that are not found in a query are passed to the subsequent query. However, setting <code class="language-plaintext highlighter-rouge">cascade = FALSE</code> will pass all addresses to all queries. See <a href="https://jessecambon.github.io/tidygeocoder/reference/geocode_combine.html">the documentation for the geocode_combine() function</a> for more usage details.</p>

<h3 id="package-housekeeping">Package Housekeeping</h3>

<p>The <code class="language-plaintext highlighter-rouge">return_type</code>, <code class="language-plaintext highlighter-rouge">geocodio_v</code>, <code class="language-plaintext highlighter-rouge">mapbox_permanent</code>, <code class="language-plaintext highlighter-rouge">mapquest_open</code>, <code class="language-plaintext highlighter-rouge">iq_region</code>, and <code class="language-plaintext highlighter-rouge">here_request_id</code> parameters are now <em>deprecated</em> in favor of the new <code class="language-plaintext highlighter-rouge">api_options</code> parameter. For instance, instead of using <code class="language-plaintext highlighter-rouge">return_type = "geographies"</code> you should now instead use <code class="language-plaintext highlighter-rouge">api_options = list(census_return_type = "geographies")</code>.</p>

<p>Also, the <code class="language-plaintext highlighter-rouge">cascade_order</code>, <code class="language-plaintext highlighter-rouge">param_error</code>, and <code class="language-plaintext highlighter-rouge">batch_limit_error</code> parameters in <code class="language-plaintext highlighter-rouge">geo()</code> are now deprecated as they were only required because of the deprecated “cascade” method. Refer to the documentation for <a href="https://jessecambon.github.io/tidygeocoder/reference/geo.html">geo()</a> or <a href="https://jessecambon.github.io/tidygeocoder/reference/reverse_geo.html">reverse_geo()</a> for details.</p>]]></content><author><name>Jesse Cambon</name></author><category term="r" /><category term="tidygeocoder" /><summary type="html"><![CDATA[Tidygeocoder v1.0.4 is released! 🍾 This release adds support for the Geoapify geocoding service (thanks Daniel Possenriede!), a progress bar, more helpful console output, and new functions for combining the results of multiple geocoding queries. A more detailed overview of the changes in this release is available in the changelog.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="https://jessecambon.github.io/images/tidygeocoder_hex_dark2021.png" /><media:content medium="image" url="https://jessecambon.github.io/images/tidygeocoder_hex_dark2021.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry><entry><title type="html">Tidygeocoder 1.0.3</title><link href="https://jessecambon.github.io/2021/04/19/tidygeocoder-1-0-3.html" rel="alternate" type="text/html" title="Tidygeocoder 1.0.3" /><published>2021-04-19T00:00:00+00:00</published><updated>2021-04-19T00:00:00+00:00</updated><id>https://jessecambon.github.io/2021/04/19/tidygeocoder-1-0-3</id><content type="html" xml:base="https://jessecambon.github.io/2021/04/19/tidygeocoder-1-0-3.html"><![CDATA[<p><a href="https://jessecambon.github.io/tidygeocoder/">Tidygeocoder v1.0.3</a> is released on <a href="https://cran.r-project.org/package=tidygeocoder">CRAN</a>! This release adds support for reverse geocoding (geocoding geographic coordinates) and 7 new geocoder services: <a href="https://opencagedata.com/">OpenCage</a>, <a href="https://developer.here.com/products/geocoding-and-search">HERE</a>, <a href="https://docs.mapbox.com/api/search/">Mapbox</a>, <a href="https://developer.mapquest.com/documentation/geocoding-api/">MapQuest</a>, <a href="https://developer.tomtom.com/search-api/search-api-documentation/geocoding">TomTom</a>, <a href="https://docs.microsoft.com/en-us/bingmaps/rest-services/locations/">Bing</a>, and <a href="https://developers.arcgis.com/rest/geocode/api-reference/overview-world-geocoding-service.htm">ArcGIS</a>. Refer to the <a href="https://jessecambon.github.io/tidygeocoder/articles/geocoder_services.html">geocoder services page</a> for information on all the supported geocoder services.</p>

<p>Big thanks go to <a href="https://github.com/dieghernan">Diego Hernangómez</a> and <a href="https://github.com/dpprdan">Daniel Possenriede</a> for their work on this release. You can refer to the <a href="https://jessecambon.github.io/tidygeocoder/news/index.html">changelog</a> for the details on the changes in the release.</p>

<h2 id="reverse-geocoding">Reverse Geocoding</h2>

<p>In this example we’ll randomly sample coordinates in Madrid and label them on a map. The coordinates are placed in a dataframe and reverse geocoded with the <code class="language-plaintext highlighter-rouge">reverse_geocode()</code> function. The Nominatim (“osm”) geocoder service is used and several API parameters are passed via the <code class="language-plaintext highlighter-rouge">custom_query</code> argument to request additional columns of data from Nominatim. Refer to <a href="https://nominatim.org/release-docs/latest/api/Reverse/">Nominatim’s API documentation</a> for more information on these parameters.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">tidyverse</span><span class="p">,</span><span class="w"> </span><span class="n">warn.conflicts</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">FALSE</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">tidygeocoder</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">knitr</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">leaflet</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">glue</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">htmltools</span><span class="p">)</span><span class="w">

</span><span class="n">num_coords</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="m">25</span><span class="w"> </span><span class="c1"># number of coordinates</span><span class="w">
</span><span class="n">set.seed</span><span class="p">(</span><span class="m">103</span><span class="p">)</span><span class="w"> </span><span class="c1"># for reproducibility</span><span class="w">

</span><span class="c1"># latitude and longitude bounds</span><span class="w">
</span><span class="n">lat_limits</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="m">40.40857</span><span class="p">,</span><span class="w"> </span><span class="m">40.42585</span><span class="p">)</span><span class="w">
</span><span class="n">long_limits</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="m">-3.72472</span><span class="p">,</span><span class="w"> </span><span class="m">-3.66983</span><span class="p">)</span><span class="w">

</span><span class="c1"># randomly sample latitudes and longitude values</span><span class="w">
</span><span class="n">random_lats</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">runif</span><span class="p">(</span><span class="w">
  </span><span class="n">num_coords</span><span class="p">,</span><span class="w"> 
  </span><span class="n">min</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">lat_limits</span><span class="p">[</span><span class="m">1</span><span class="p">],</span><span class="w"> 
  </span><span class="n">max</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">lat_limits</span><span class="p">[</span><span class="m">2</span><span class="p">]</span><span class="w">
  </span><span class="p">)</span><span class="w">

</span><span class="n">random_longs</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">runif</span><span class="p">(</span><span class="w">
  </span><span class="n">num_coords</span><span class="p">,</span><span class="w"> 
  </span><span class="n">min</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">long_limits</span><span class="p">[</span><span class="m">1</span><span class="p">],</span><span class="w"> 
  </span><span class="n">max</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">long_limits</span><span class="p">[</span><span class="m">2</span><span class="p">]</span><span class="w">
  </span><span class="p">)</span><span class="w">

</span><span class="c1"># Reverse geocode the coordinates</span><span class="w">
</span><span class="c1"># the speed of the query is limited to 1 coordinate per second to comply</span><span class="w">
</span><span class="c1"># with Nominatim's usage policies</span><span class="w">
</span><span class="n">madrid</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">reverse_geo</span><span class="p">(</span><span class="w">
              </span><span class="n">lat</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">random_lats</span><span class="p">,</span><span class="w"> </span><span class="n">random_longs</span><span class="p">,</span><span class="w"> 
              </span><span class="n">method</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'osm'</span><span class="p">,</span><span class="w"> </span><span class="n">full_results</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">TRUE</span><span class="p">,</span><span class="w">
              </span><span class="n">custom_query</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">list</span><span class="p">(</span><span class="n">extratags</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span><span class="p">,</span><span class="w"> </span><span class="n">addressdetails</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span><span class="p">,</span><span class="w"> </span><span class="n">namedetails</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span><span class="p">)</span><span class="w">
          </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p>After geocoding our coordinates, we can construct HTML labels with the data returned from Nominatim and display these locations on a <a href="http://rstudio.github.io/leaflet/">leaflet</a> map.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Create html labels</span><span class="w">
</span><span class="c1"># https://rstudio.github.io/leaflet/popups.html</span><span class="w">
</span><span class="n">madrid_labelled</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">madrid</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">transmute</span><span class="p">(</span><span class="w">
    </span><span class="n">lat</span><span class="p">,</span><span class="w"> 
    </span><span class="n">long</span><span class="p">,</span><span class="w"> 
    </span><span class="n">label</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">str_c</span><span class="p">(</span><span class="w">
        </span><span class="n">ifelse</span><span class="p">(</span><span class="nf">is.na</span><span class="p">(</span><span class="n">name</span><span class="p">),</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w"> </span><span class="n">glue</span><span class="p">(</span><span class="s2">"&lt;b&gt;Name&lt;/b&gt;: {name}&lt;/br&gt;"</span><span class="p">)),</span><span class="w">
        </span><span class="n">ifelse</span><span class="p">(</span><span class="nf">is.na</span><span class="p">(</span><span class="n">suburb</span><span class="p">),</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w"> </span><span class="n">glue</span><span class="p">(</span><span class="s2">"&lt;b&gt;Suburb&lt;/b&gt;: {suburb}&lt;/br&gt;"</span><span class="p">)),</span><span class="w">
        </span><span class="n">ifelse</span><span class="p">(</span><span class="nf">is.na</span><span class="p">(</span><span class="n">quarter</span><span class="p">),</span><span class="w"> </span><span class="s2">""</span><span class="p">,</span><span class="w"> </span><span class="n">glue</span><span class="p">(</span><span class="s2">"&lt;b&gt;Quarter&lt;/b&gt;: {quarter}"</span><span class="p">)),</span><span class="w">
        </span><span class="n">sep</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">''</span><span class="w">
    </span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> </span><span class="n">lapply</span><span class="p">(</span><span class="n">htmltools</span><span class="o">::</span><span class="n">HTML</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w">

</span><span class="c1"># Make the leaflet map</span><span class="w">
</span><span class="n">madrid_labelled</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> 
  </span><span class="n">leaflet</span><span class="p">(</span><span class="n">width</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"100%"</span><span class="p">,</span><span class="w"> </span><span class="n">options</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">leafletOptions</span><span class="p">(</span><span class="n">attributionControl</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">FALSE</span><span class="p">))</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">setView</span><span class="p">(</span><span class="n">lng</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">mean</span><span class="p">(</span><span class="n">madrid</span><span class="o">$</span><span class="n">long</span><span class="p">),</span><span class="w"> </span><span class="n">lat</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">mean</span><span class="p">(</span><span class="n">madrid</span><span class="o">$</span><span class="n">lat</span><span class="p">),</span><span class="w"> </span><span class="n">zoom</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">14</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="c1"># Map Backgrounds</span><span class="w">
  </span><span class="c1"># https://leaflet-extras.github.io/leaflet-providers/preview/</span><span class="w">
  </span><span class="n">addProviderTiles</span><span class="p">(</span><span class="n">providers</span><span class="o">$</span><span class="n">Stamen.Terrain</span><span class="p">,</span><span class="w"> </span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"Terrain"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">addProviderTiles</span><span class="p">(</span><span class="n">providers</span><span class="o">$</span><span class="n">OpenRailwayMap</span><span class="p">,</span><span class="w"> </span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"Rail"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">addProviderTiles</span><span class="p">(</span><span class="n">providers</span><span class="o">$</span><span class="n">Esri.WorldImagery</span><span class="p">,</span><span class="w"> </span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"Satellite"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">addTiles</span><span class="p">(</span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"OSM"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="c1"># Add Markers</span><span class="w">
  </span><span class="n">addMarkers</span><span class="p">(</span><span class="w">
    </span><span class="n">labelOptions</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">labelOptions</span><span class="p">(</span><span class="n">noHide</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">F</span><span class="p">),</span><span class="w"> </span><span class="n">lng</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">~</span><span class="n">long</span><span class="p">,</span><span class="w"> </span><span class="n">lat</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">~</span><span class="n">lat</span><span class="p">,</span><span class="w">
    </span><span class="n">label</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">~</span><span class="n">label</span><span class="p">,</span><span class="w">
    </span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"Random Locations"</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="c1"># Map Control Options</span><span class="w">
  </span><span class="n">addLayersControl</span><span class="p">(</span><span class="w">
    </span><span class="n">baseGroups</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="s2">"OSM"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Terrain"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Satellite"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Rail"</span><span class="p">),</span><span class="w">
    </span><span class="n">overlayGroups</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="s2">"Random Locations"</span><span class="p">),</span><span class="w">
    </span><span class="n">options</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">layersControlOptions</span><span class="p">(</span><span class="n">collapsed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">TRUE</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<div id="htmlwidget-562547e6d92361b7b630" style="width:100%;height:480px;" class="leaflet html-widget"></div>
<script type="application/json" data-for="htmlwidget-562547e6d92361b7b630">{"x":{"options":{"crs":{"crsClass":"L.CRS.EPSG3857","code":null,"proj4def":null,"projectedBounds":null,"options":{}},"attributionControl":false},"setView":[[40.415021103152,-3.69357282582785],14,[]],"calls":[{"method":"addProviderTiles","args":["Stamen.Terrain",null,"Terrain",{"errorTileUrl":"","noWrap":false,"detectRetina":false}]},{"method":"addProviderTiles","args":["OpenRailwayMap",null,"Rail",{"errorTileUrl":"","noWrap":false,"detectRetina":false}]},{"method":"addProviderTiles","args":["Esri.WorldImagery",null,"Satellite",{"errorTileUrl":"","noWrap":false,"detectRetina":false}]},{"method":"addTiles","args":["//{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",null,"OSM",{"minZoom":0,"maxZoom":18,"tileSize":256,"subdomains":"abc","errorTileUrl":"","tms":false,"noWrap":false,"zoomOffset":0,"zoomReverse":false,"opacity":1,"zIndex":1,"detectRetina":false,"attribution":"&copy; <a href=\"http://openstreetmap.org\">OpenStreetMap<\/a> contributors, <a href=\"http://creativecommons.org/licenses/by-sa/2.0/\">CC-BY-SA<\/a>"}]},{"method":"addMarkers","args":[[40.4123014709814,40.4096615445682,40.4175871664274,40.417272506227,40.4106519994937,40.4100781149822,40.4160619508378,40.411906436556,40.4091072090676,40.413993361209,40.4163817212981,40.4135176730348,40.4223178283641,40.4228223820305,40.423828380907,40.410822169486,40.4109466401929,40.4134973449898,40.4146834641808,40.4143576724255,40.4116045660791,40.4180861643726,40.4174389485912,40.4185510909274,40.4180497715706],[-3.67578744418699,-3.67010136934424,-3.67335474251329,-3.70310583343772,-3.67488869123186,-3.71444517586805,-3.67663930623259,-3.68756156697234,-3.72200196854039,-3.69475406050333,-3.67205522449481,-3.70229658222932,-3.6763332644197,-3.68158102478245,-3.72233264530065,-3.6795209595742,-3.68922342991826,-3.69160540612346,-3.6707955976882,-3.70259709061521,-3.7173106429264,-3.72088573588971,-3.69363431777976,-3.71829686008829,-3.70821170503502],null,null,"Random Locations",{"interactive":true,"draggable":false,"keyboard":true,"title":"","alt":"","zIndexOffset":0,"opacity":1,"riseOnHover":false,"riseOffset":250},null,null,null,null,["<b>Name<\/b>: Torre del Retiro<\/br><b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Niño Jesús","<b>Name<\/b>: Alimentación Bazar<\/br><b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Niño Jesús","<b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Ibiza","<b>Name<\/b>: Casa de Empeño<\/br><b>Suburb<\/b>: Sol<\/br><b>Quarter<\/b>: Sol","<b>Name<\/b>: Real Escuela Superior de Arte Dramático (RESAD)<\/br><b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Niño Jesús","<b>Name<\/b>: Dalieda de San Francisco<\/br><b>Suburb<\/b>: Palacio<\/br>","<b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Ibiza","<b>Name<\/b>: Bosque del Recuerdo<\/br><b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Jerónimos","<b>Suburb<\/b>: Latina<\/br>","<b>Suburb<\/b>: Cortes<\/br><b>Quarter<\/b>: Cortes","<b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Ibiza","<b>Suburb<\/b>: Embajadores<\/br>","<b>Suburb<\/b>: Salamanca<\/br><b>Quarter<\/b>: Goya","<b>Suburb<\/b>: Salamanca<\/br><b>Quarter<\/b>: Recoletos","<b>Suburb<\/b>: Moncloa-Aravaca<\/br>","<b>Name<\/b>: La Rosaleda<\/br><b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Jerónimos","<b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Jerónimos","<b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Jerónimos","<b>Name<\/b>: Citröen España<\/br><b>Suburb<\/b>: Retiro<\/br><b>Quarter<\/b>: Niño Jesús","<b>Name<\/b>: España Cañi<\/br><b>Suburb<\/b>: Cortes<\/br>","<b>Suburb<\/b>: Palacio<\/br><b>Quarter<\/b>: Palacio","<b>Name<\/b>: Paseo de la Virgen del Puerto<\/br><b>Suburb<\/b>: Palacio<\/br><b>Quarter<\/b>: Palacio","<b>Suburb<\/b>: Cortes<\/br><b>Quarter<\/b>: Cortes","<b>Suburb<\/b>: Moncloa-Aravaca<\/br><b>Quarter<\/b>: Argüelles","<b>Name<\/b>: Oratorio Santo Niño del Remedio<\/br><b>Suburb<\/b>: Centro<\/br>"],{"interactive":false,"permanent":false,"direction":"auto","opacity":1,"offset":[0,0],"textsize":"10px","textOnly":false,"className":"","sticky":true},null]},{"method":"addLayersControl","args":[["OSM","Terrain","Satellite","Rail"],"Random Locations",{"collapsed":true,"autoZIndex":true,"position":"topright"}]}],"limits":{"lat":[40.4091072090676,40.423828380907],"lng":[-3.72233264530065,-3.67010136934424]}},"evals":[],"jsHooks":[]}</script>

<h2 id="limits">Limits</h2>

<p>This release also improves support for returning multiple results per input with the <code class="language-plaintext highlighter-rouge">limit</code> argument. Consider this batch query with the US Census geocoder:</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">tie_addresses</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">tibble</span><span class="o">::</span><span class="n">tribble</span><span class="p">(</span><span class="w">
  </span><span class="o">~</span><span class="n">res_street_address</span><span class="p">,</span><span class="w"> </span><span class="o">~</span><span class="n">res_city_desc</span><span class="p">,</span><span class="w"> </span><span class="o">~</span><span class="n">state_cd</span><span class="p">,</span><span class="w"> </span><span class="o">~</span><span class="n">zip_code</span><span class="p">,</span><span class="w">
  </span><span class="s2">"624 W DAVIS ST   #1D"</span><span class="p">,</span><span class="w">   </span><span class="s2">"BURLINGTON"</span><span class="p">,</span><span class="w"> </span><span class="s2">"NC"</span><span class="p">,</span><span class="w">  </span><span class="m">27215</span><span class="p">,</span><span class="w">
  </span><span class="s2">"201 E CENTER ST   #268"</span><span class="p">,</span><span class="w"> </span><span class="s2">"MEBANE"</span><span class="p">,</span><span class="w">     </span><span class="s2">"NC"</span><span class="p">,</span><span class="w">  </span><span class="m">27302</span><span class="p">,</span><span class="w">
  </span><span class="s2">"7833  WOLFE LN"</span><span class="p">,</span><span class="w">         </span><span class="s2">"SNOW CAMP"</span><span class="p">,</span><span class="w">  </span><span class="s2">"NC"</span><span class="p">,</span><span class="w">  </span><span class="m">27349</span><span class="p">,</span><span class="w">
</span><span class="p">)</span><span class="w">

</span><span class="n">tg_batch</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">tie_addresses</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">geocode</span><span class="p">(</span><span class="w">
    </span><span class="n">street</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">res_street_address</span><span class="p">,</span><span class="w">
    </span><span class="n">city</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">res_city_desc</span><span class="p">,</span><span class="w">
    </span><span class="n">state</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">state_cd</span><span class="p">,</span><span class="w">
    </span><span class="n">postalcode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">zip_code</span><span class="p">,</span><span class="w">
    </span><span class="n">method</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'census'</span><span class="p">,</span><span class="w"> 
    </span><span class="n">full_results</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">TRUE</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">res_street_address</th>
      <th style="text-align: left">res_city_desc</th>
      <th style="text-align: left">state_cd</th>
      <th style="text-align: right">zip_code</th>
      <th style="text-align: right">lat</th>
      <th style="text-align: right">long</th>
      <th style="text-align: right">id</th>
      <th style="text-align: left">input_address</th>
      <th style="text-align: left">match_indicator</th>
      <th style="text-align: left">match_type</th>
      <th style="text-align: left">matched_address</th>
      <th style="text-align: left">tiger_line_id</th>
      <th style="text-align: left">tiger_side</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">624 W DAVIS ST #1D</td>
      <td style="text-align: left">BURLINGTON</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: right">27215</td>
      <td style="text-align: right">NA</td>
      <td style="text-align: right">NA</td>
      <td style="text-align: right">1</td>
      <td style="text-align: left">624 W DAVIS ST #1D, BURLINGTON, NC, 27215</td>
      <td style="text-align: left">Tie</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
    </tr>
    <tr>
      <td style="text-align: left">201 E CENTER ST #268</td>
      <td style="text-align: left">MEBANE</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: right">27302</td>
      <td style="text-align: right">NA</td>
      <td style="text-align: right">NA</td>
      <td style="text-align: right">2</td>
      <td style="text-align: left">201 E CENTER ST #268, MEBANE, NC, 27302</td>
      <td style="text-align: left">Tie</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
    </tr>
    <tr>
      <td style="text-align: left">7833 WOLFE LN</td>
      <td style="text-align: left">SNOW CAMP</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: right">27349</td>
      <td style="text-align: right">NA</td>
      <td style="text-align: right">NA</td>
      <td style="text-align: right">3</td>
      <td style="text-align: left">7833 WOLFE LN, SNOW CAMP, NC, 27349</td>
      <td style="text-align: left">Tie</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
    </tr>
  </tbody>
</table>

<p>You can see NA results are returned and the <code class="language-plaintext highlighter-rouge">match_indicator</code> column indicates a “Tie”. This is what the US Census batch geocoder returns when multiple results are available for each input address (see <a href="https://github.com/jessecambon/tidygeocoder/issues/87">issue #87</a> for more details).</p>

<p>To see all available results for these addresses, you will need to use <code class="language-plaintext highlighter-rouge">mode</code> to force single address (not batch) geocoding and <code class="language-plaintext highlighter-rouge">limit &gt; 1</code>. The <code class="language-plaintext highlighter-rouge">return_input</code> argument (new in this release) has to be set to <code class="language-plaintext highlighter-rouge">FALSE</code> to allow <code class="language-plaintext highlighter-rouge">limit</code> to be set to a value other than 1. See the <a href="https://jessecambon.github.io/tidygeocoder/reference/geocode.html">geocode() function documentation</a> for details.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">tg_single</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">tie_addresses</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">geocode</span><span class="p">(</span><span class="w">
    </span><span class="n">street</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">res_street_address</span><span class="p">,</span><span class="w">
    </span><span class="n">city</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">res_city_desc</span><span class="p">,</span><span class="w">
    </span><span class="n">state</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">state_cd</span><span class="p">,</span><span class="w">
    </span><span class="n">postalcode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">zip_code</span><span class="p">,</span><span class="w">
    </span><span class="n">limit</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">100</span><span class="p">,</span><span class="w">
    </span><span class="n">return_input</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">FALSE</span><span class="p">,</span><span class="w">
    </span><span class="n">method</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'census'</span><span class="p">,</span><span class="w"> 
    </span><span class="n">mode</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'single'</span><span class="p">,</span><span class="w">
    </span><span class="n">full_results</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">TRUE</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">street</th>
      <th style="text-align: left">city</th>
      <th style="text-align: left">state</th>
      <th style="text-align: left">postalcode</th>
      <th style="text-align: right">lat</th>
      <th style="text-align: right">long</th>
      <th style="text-align: left">matchedAddress</th>
      <th style="text-align: left">tigerLine.tigerLineId</th>
      <th style="text-align: left">tigerLine.side</th>
      <th style="text-align: left">addressComponents.fromAddress</th>
      <th style="text-align: left">addressComponents.toAddress</th>
      <th style="text-align: left">addressComponents.preQualifier</th>
      <th style="text-align: left">addressComponents.preDirection</th>
      <th style="text-align: left">addressComponents.preType</th>
      <th style="text-align: left">addressComponents.streetName</th>
      <th style="text-align: left">addressComponents.suffixType</th>
      <th style="text-align: left">addressComponents.suffixDirection</th>
      <th style="text-align: left">addressComponents.suffixQualifier</th>
      <th style="text-align: left">addressComponents.city</th>
      <th style="text-align: left">addressComponents.state</th>
      <th style="text-align: left">addressComponents.zip</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">624 W DAVIS ST #1D</td>
      <td style="text-align: left">BURLINGTON</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27215</td>
      <td style="text-align: right">36.09598</td>
      <td style="text-align: right">-79.44453</td>
      <td style="text-align: left">624 W DAVIS ST, BURLINGTON, NC, 27215</td>
      <td style="text-align: left">71662708</td>
      <td style="text-align: left">L</td>
      <td style="text-align: left">618</td>
      <td style="text-align: left">628</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">W</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">DAVIS</td>
      <td style="text-align: left">ST</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">BURLINGTON</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27215</td>
    </tr>
    <tr>
      <td style="text-align: left">624 W DAVIS ST #1D</td>
      <td style="text-align: left">BURLINGTON</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27215</td>
      <td style="text-align: right">36.08821</td>
      <td style="text-align: right">-79.43201</td>
      <td style="text-align: left">624 E DAVIS ST, BURLINGTON, NC, 27215</td>
      <td style="text-align: left">71664000</td>
      <td style="text-align: left">L</td>
      <td style="text-align: left">600</td>
      <td style="text-align: left">698</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">E</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">DAVIS</td>
      <td style="text-align: left">ST</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">BURLINGTON</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27215</td>
    </tr>
    <tr>
      <td style="text-align: left">201 E CENTER ST #268</td>
      <td style="text-align: left">MEBANE</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27302</td>
      <td style="text-align: right">36.09683</td>
      <td style="text-align: right">-79.26977</td>
      <td style="text-align: left">201 W CENTER ST, MEBANE, NC, 27302</td>
      <td style="text-align: left">71655977</td>
      <td style="text-align: left">R</td>
      <td style="text-align: left">201</td>
      <td style="text-align: left">299</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">W</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">CENTER</td>
      <td style="text-align: left">ST</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">MEBANE</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27302</td>
    </tr>
    <tr>
      <td style="text-align: left">201 E CENTER ST #268</td>
      <td style="text-align: left">MEBANE</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27302</td>
      <td style="text-align: right">36.09582</td>
      <td style="text-align: right">-79.26624</td>
      <td style="text-align: left">201 E CENTER ST, MEBANE, NC, 27302</td>
      <td style="text-align: left">71656021</td>
      <td style="text-align: left">R</td>
      <td style="text-align: left">299</td>
      <td style="text-align: left">201</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">E</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">CENTER</td>
      <td style="text-align: left">ST</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">MEBANE</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27302</td>
    </tr>
    <tr>
      <td style="text-align: left">7833 WOLFE LN</td>
      <td style="text-align: left">SNOW CAMP</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27349</td>
      <td style="text-align: right">35.89866</td>
      <td style="text-align: right">-79.43713</td>
      <td style="text-align: left">7833 WOLFE LN, SNOW CAMP, NC, 27349</td>
      <td style="text-align: left">71682243</td>
      <td style="text-align: left">L</td>
      <td style="text-align: left">7999</td>
      <td style="text-align: left">7801</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">WOLFE</td>
      <td style="text-align: left">LN</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">SNOW CAMP</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27349</td>
    </tr>
    <tr>
      <td style="text-align: left">7833 WOLFE LN</td>
      <td style="text-align: left">SNOW CAMP</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27349</td>
      <td style="text-align: right">35.89693</td>
      <td style="text-align: right">-79.43707</td>
      <td style="text-align: left">7833 WOLF LN, SNOW CAMP, NC, 27349</td>
      <td style="text-align: left">71685327</td>
      <td style="text-align: left">L</td>
      <td style="text-align: left">7801</td>
      <td style="text-align: left">7911</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">WOLF</td>
      <td style="text-align: left">LN</td>
      <td style="text-align: left"> </td>
      <td style="text-align: left"> </td>
      <td style="text-align: left">SNOW CAMP</td>
      <td style="text-align: left">NC</td>
      <td style="text-align: left">27349</td>
    </tr>
  </tbody>
</table>

<p>We can now see there are two available results for each address. Note that this particular issue with “Tie” batch results is specific to the US Census geocoder service. Refer to the <a href="https://jessecambon.github.io/tidygeocoder/reference/api_parameter_reference.html">api_parameter_reference</a> documentation for more details on the <code class="language-plaintext highlighter-rouge">limit</code> parameter.</p>

<p>The <code class="language-plaintext highlighter-rouge">limit</code> parameter can also be used to return all matches for a more general query:</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">paris</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">geo</span><span class="p">(</span><span class="s1">'Paris'</span><span class="p">,</span><span class="w"> </span><span class="n">method</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'opencage'</span><span class="p">,</span><span class="w"> </span><span class="n">full_results</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">TRUE</span><span class="p">,</span><span class="w"> </span><span class="n">limit</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">10</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">address</th>
      <th style="text-align: right">lat</th>
      <th style="text-align: right">long</th>
      <th style="text-align: left">formatted</th>
      <th style="text-align: left">annotations.currency.name</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">Paris</td>
      <td style="text-align: right">48.85670</td>
      <td style="text-align: right">2.351462</td>
      <td style="text-align: left">Paris, France</td>
      <td style="text-align: left">Euro</td>
    </tr>
    <tr>
      <td style="text-align: left">Paris</td>
      <td style="text-align: right">33.66180</td>
      <td style="text-align: right">-95.555513</td>
      <td style="text-align: left">Paris, TX 75460, United States of America</td>
      <td style="text-align: left">United States Dollar</td>
    </tr>
    <tr>
      <td style="text-align: left">Paris</td>
      <td style="text-align: right">38.20980</td>
      <td style="text-align: right">-84.252987</td>
      <td style="text-align: left">Paris, Kentucky, United States of America</td>
      <td style="text-align: left">United States Dollar</td>
    </tr>
    <tr>
      <td style="text-align: left">Paris</td>
      <td style="text-align: right">36.30195</td>
      <td style="text-align: right">-88.325858</td>
      <td style="text-align: left">Paris, TN 38242, United States of America</td>
      <td style="text-align: left">United States Dollar</td>
    </tr>
    <tr>
      <td style="text-align: left">Paris</td>
      <td style="text-align: right">39.61115</td>
      <td style="text-align: right">-87.696137</td>
      <td style="text-align: left">Paris, IL 61944, United States of America</td>
      <td style="text-align: left">United States Dollar</td>
    </tr>
    <tr>
      <td style="text-align: left">Paris</td>
      <td style="text-align: right">44.25995</td>
      <td style="text-align: right">-70.500641</td>
      <td style="text-align: left">Paris, Maine, United States of America</td>
      <td style="text-align: left">United States Dollar</td>
    </tr>
    <tr>
      <td style="text-align: left">Paris</td>
      <td style="text-align: right">35.29203</td>
      <td style="text-align: right">-93.729917</td>
      <td style="text-align: left">Paris, AR 72855, United States of America</td>
      <td style="text-align: left">United States Dollar</td>
    </tr>
    <tr>
      <td style="text-align: left">Paris</td>
      <td style="text-align: right">39.48087</td>
      <td style="text-align: right">-92.001281</td>
      <td style="text-align: left">Paris, MO 65275, United States of America</td>
      <td style="text-align: left">United States Dollar</td>
    </tr>
  </tbody>
</table>

<p>The R Markdown file that generated this post is available <a href="https://github.com/jessecambon/jessecambon.github.io/blob/main/_posts/2021-04-19-tidygeocoder-1-0-3.Rmd">here</a>.</p>]]></content><author><name>Jesse Cambon</name></author><category term="r" /><category term="tidygeocoder" /><summary type="html"><![CDATA[Tidygeocoder v1.0.3 is released on CRAN! This release adds support for reverse geocoding (geocoding geographic coordinates) and 7 new geocoder services: OpenCage, HERE, Mapbox, MapQuest, TomTom, Bing, and ArcGIS. Refer to the geocoder services page for information on all the supported geocoder services.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="https://jessecambon.github.io/images/tidygeocoder_hex.png" /><media:content medium="image" url="https://jessecambon.github.io/images/tidygeocoder_hex.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry><entry><title type="html">Tidygeocoder 1.0.2</title><link href="https://jessecambon.github.io/2021/01/18/tidygeocoder-1-0-2.html" rel="alternate" type="text/html" title="Tidygeocoder 1.0.2" /><published>2021-01-18T00:00:00+00:00</published><updated>2021-01-18T00:00:00+00:00</updated><id>https://jessecambon.github.io/2021/01/18/tidygeocoder-1-0-2</id><content type="html" xml:base="https://jessecambon.github.io/2021/01/18/tidygeocoder-1-0-2.html"><![CDATA[<p><a href="https://jessecambon.github.io/tidygeocoder/index.html">Tidygeocoder v1.0.2</a> <em>“Yodeling Yak”</em> is now on <a href="https://cran.r-project.org/package=tidygeocoder">CRAN</a>. This release adds support for the popular <a href="https://developers.google.com/maps/documentation/javascript/geocoding">Google geocoder service</a> (thanks <a href="https://github.com/chris31415926535">@chris31415926535</a>) and also includes several bugfixes and enhancements. Refer to the <a href="https://jessecambon.github.io/tidygeocoder/news/index.html">changelog</a> for details on the release and to the <a href="https://jessecambon.github.io/tidygeocoder/#geocoder-services">tidygeocoder homepage</a> for a comparison of all supported geocoder services.</p>

<p><img src="/../images/google_map_pin.png" width="25%" style="display: block; margin: auto;" /></p>

<p>You can make use of the Google geocoder service by passing <code class="language-plaintext highlighter-rouge">method = 'google'</code> to the <a href="https://jessecambon.github.io/tidygeocoder/reference/geo.html"><code class="language-plaintext highlighter-rouge">geo()</code></a> and <a href="https://jessecambon.github.io/tidygeocoder/reference/geocode.html"><code class="language-plaintext highlighter-rouge">geocode()</code></a> functions. Note that the Google geocoder service requires registering for an API key and <a href="https://developers.google.com/maps/documentation/geocoding/usage-and-billing">charges per query</a>. The Google API key needs to be stored in the <code class="language-plaintext highlighter-rouge">GOOGLEGEOCODE_API_KEY</code> environmental variable for use with tidygeocoder.</p>

<p>Also new in this release, US Census batch geocoding results will now return geographic FIPs codes in character format (instead of numeric) to preserve leading zeros (<a href="https://github.com/jessecambon/tidygeocoder/issues/47">#47</a>). The <code class="language-plaintext highlighter-rouge">return_type = 'geographies'</code> query in the <a href="https://jessecambon.github.io/tidygeocoder/index.html#usage">usage example</a> shows the new data format.</p>

<p>Additionally, arguments passed to the <a href="https://jessecambon.github.io/tidygeocoder/reference/geo.html"><code class="language-plaintext highlighter-rouge">geo()</code></a> and <a href="https://jessecambon.github.io/tidygeocoder/reference/geocode.html"><code class="language-plaintext highlighter-rouge">geocode()</code></a> functions that aren’t valid for the selected geocoder service (ie. the Census geocoder doesn’t have a <code class="language-plaintext highlighter-rouge">country</code> argument) will now throw errors:</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">tidygeocoder</span><span class="p">)</span><span class="w">

</span><span class="n">geo</span><span class="p">(</span><span class="n">city</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'Auckland'</span><span class="p">,</span><span class="w"> </span><span class="n">country</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'New Zealand'</span><span class="p">,</span><span class="w"> </span><span class="n">method</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'census'</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>## Error in geo(city = "Auckland", country = "New Zealand", method = "census"): The following parameter(s) are not supported for the "census" method:
## 
## country
## 
## See ?api_parameter_reference for more details.
</code></pre></div></div>

<p>If you’re interested in contributing to the package and would like to add support for other geocoder services, updated instructions on how to go about this are <a href="https://github.com/jessecambon/tidygeocoder/issues/62#issue-777707424">located here</a>.</p>]]></content><author><name>Jesse Cambon</name></author><category term="r" /><category term="tidygeocoder" /><summary type="html"><![CDATA[Tidygeocoder v1.0.2 “Yodeling Yak” is now on CRAN. This release adds support for the popular Google geocoder service (thanks @chris31415926535) and also includes several bugfixes and enhancements. Refer to the changelog for details on the release and to the tidygeocoder homepage for a comparison of all supported geocoder services.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="https://jessecambon.github.io/images/google_map_pin.png" /><media:content medium="image" url="https://jessecambon.github.io/images/google_map_pin.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry><entry><title type="html">Introducing Tidygeocoder 1.0.0</title><link href="https://jessecambon.github.io/2020/07/15/tidygeocoder-1-0-0.html" rel="alternate" type="text/html" title="Introducing Tidygeocoder 1.0.0" /><published>2020-07-15T00:00:00+00:00</published><updated>2020-07-15T00:00:00+00:00</updated><id>https://jessecambon.github.io/2020/07/15/tidygeocoder-1-0-0</id><content type="html" xml:base="https://jessecambon.github.io/2020/07/15/tidygeocoder-1-0-0.html"><![CDATA[<p><a href="https://jessecambon.github.io/tidygeocoder/index.html">Tidygeocoder v1.0.0</a> is now live on CRAN. There are numerous new features and improvements such as batch geocoding (submitting multiple addresses per query), returning full results from geocoder services (not just latitude and longitude), address component arguments (city, country, etc.), query customization, and reduced package dependencies.</p>

<p>For a full list of new features and improvements refer to the <a href="https://github.com/jessecambon/tidygeocoder/releases/tag/v1.0.0">release page on Github</a>. For usage examples you can reference the <a href="https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html">Getting Started vignette</a>.</p>

<p><img src="/../images/tidygeocoder_hex.png" width="200" style="display: block; margin: auto;" /></p>

<p>To demonstrate a few of the new capabilities of this package, I decided to make a map of the stadiums for the <a href="https://www.uefa.com/uefachampionsleague/draws/2020/2001141/">UEFA Champions League Round of 16 clubs</a>. To start, I looked up the addresses for the stadiums and put them in a dataframe.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">dplyr</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">tidygeocoder</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">ggplot2</span><span class="p">)</span><span class="w">
</span><span class="n">require</span><span class="p">(</span><span class="n">maps</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">ggrepel</span><span class="p">)</span><span class="w">

</span><span class="c1"># https://www.uefa.com/uefachampionsleague/clubs/</span><span class="w">
</span><span class="n">stadiums</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">tibble</span><span class="o">::</span><span class="n">tribble</span><span class="p">(</span><span class="w">
</span><span class="o">~</span><span class="n">Club</span><span class="p">,</span><span class="w">                </span><span class="o">~</span><span class="n">Street</span><span class="p">,</span><span class="w">   </span><span class="o">~</span><span class="n">City</span><span class="p">,</span><span class="w">   </span><span class="o">~</span><span class="n">Country</span><span class="p">,</span><span class="w">
</span><span class="s2">"Barcelona"</span><span class="p">,</span><span class="w">          </span><span class="s2">"Camp Nou"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Barcelona"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Spain"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Bayern Munich"</span><span class="p">,</span><span class="w">      </span><span class="s2">"Allianz Arena"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Munich"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Germany"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Chelsea"</span><span class="p">,</span><span class="w">            </span><span class="s2">"Stamford Bridge"</span><span class="p">,</span><span class="w"> </span><span class="s2">"London"</span><span class="p">,</span><span class="w"> </span><span class="s2">"UK"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Borussia Dortmund"</span><span class="p">,</span><span class="w">  </span><span class="s2">"Signal Iduna Park"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Dortmund"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Germany"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Juventus"</span><span class="p">,</span><span class="w">           </span><span class="s2">"Allianz Stadium"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Turin"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Italy"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Liverpool"</span><span class="p">,</span><span class="w">          </span><span class="s2">"Anfield"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Liverpool"</span><span class="p">,</span><span class="w"> </span><span class="s2">"UK"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Olympique Lyonnais"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Groupama Stadium"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Lyon"</span><span class="p">,</span><span class="w"> </span><span class="s2">"France"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Man. City"</span><span class="p">,</span><span class="w">          </span><span class="s2">"Etihad Stadium"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Manchester"</span><span class="p">,</span><span class="w"> </span><span class="s2">"UK"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Napoli"</span><span class="p">,</span><span class="w">             </span><span class="s2">"San Paolo Stadium"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Naples"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Italy"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Real Madrid"</span><span class="p">,</span><span class="w">        </span><span class="s2">"Santiago Bernabéu Stadium"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Madrid"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Spain"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Tottenham"</span><span class="p">,</span><span class="w">          </span><span class="s2">"Tottenham Hotspur Stadium"</span><span class="p">,</span><span class="w"> </span><span class="s2">"London"</span><span class="p">,</span><span class="w"> </span><span class="s2">"UK"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Valencia"</span><span class="p">,</span><span class="w">           </span><span class="s2">"Av. de Suècia, s/n, 46010"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Valencia"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Spain"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Atalanta"</span><span class="p">,</span><span class="w">           </span><span class="s2">"Gewiss Stadium"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Bergamo"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Italy"</span><span class="p">,</span><span class="w">
</span><span class="s2">"Atlético Madrid"</span><span class="p">,</span><span class="w">    </span><span class="s2">"Estadio Metropolitano"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Madrid"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Spain"</span><span class="p">,</span><span class="w">
</span><span class="s2">"RB Leipzig"</span><span class="p">,</span><span class="w">         </span><span class="s2">"Red Bull Arena"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Leipzig"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Germany"</span><span class="p">,</span><span class="w">
</span><span class="s2">"PSG"</span><span class="p">,</span><span class="w">                </span><span class="s2">"Le Parc des Princes"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Paris"</span><span class="p">,</span><span class="w"> </span><span class="s2">"France"</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p>To geocode these addresses, you can use the <a href="https://jessecambon.github.io/tidygeocoder/reference/geocode.html">geocode</a> function as shown below. New in v1.0.0, the <code class="language-plaintext highlighter-rouge">street</code>, <code class="language-plaintext highlighter-rouge">city</code>, and <code class="language-plaintext highlighter-rouge">country</code> arguments specify the address. The Nominatim (OSM) geocoder is selected with the <code class="language-plaintext highlighter-rouge">method</code> argument. Additionally, the <code class="language-plaintext highlighter-rouge">full_results</code> and <code class="language-plaintext highlighter-rouge">custom_query</code> arguments (also new in v1.0.0) are used to return the full geocoder results and set <a href="https://nominatim.org/release-docs/develop/api/Search/#parameters">Nominatim’s “extratags” parameter</a> which returns extra columns.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">stadium_locations</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">stadiums</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">geocode</span><span class="p">(</span><span class="n">street</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Street</span><span class="p">,</span><span class="w"> </span><span class="n">city</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">City</span><span class="p">,</span><span class="w"> </span><span class="n">country</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Country</span><span class="p">,</span><span class="w"> </span><span class="n">method</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'osm'</span><span class="p">,</span><span class="w"> 
          </span><span class="n">full_results</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">TRUE</span><span class="p">,</span><span class="w"> </span><span class="n">custom_query</span><span class="o">=</span><span class="w"> </span><span class="nf">list</span><span class="p">(</span><span class="n">extratags</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span><span class="p">))</span><span class="w">
</span></code></pre></div></div>

<p>This returns 40 columns including the longitude and latitude. A few of the columns returned due to the <code class="language-plaintext highlighter-rouge">extratags</code> argument are shown below.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">stadium_locations</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">select</span><span class="p">(</span><span class="n">Club</span><span class="p">,</span><span class="w"> </span><span class="n">City</span><span class="p">,</span><span class="w"> </span><span class="n">Country</span><span class="p">,</span><span class="w"> </span><span class="n">extratags.sport</span><span class="p">,</span><span class="w"> </span><span class="n">extratags.capacity</span><span class="p">,</span><span class="w"> </span><span class="n">extratags.operator</span><span class="p">,</span><span class="w"> </span><span class="n">extratags.wikipedia</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">rename_with</span><span class="p">(</span><span class="o">~</span><span class="n">gsub</span><span class="p">(</span><span class="s1">'extratags.'</span><span class="p">,</span><span class="w"> </span><span class="s1">''</span><span class="p">,</span><span class="w"> </span><span class="n">.</span><span class="p">))</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">knitr</span><span class="o">::</span><span class="n">kable</span><span class="p">()</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">Club</th>
      <th style="text-align: left">City</th>
      <th style="text-align: left">Country</th>
      <th style="text-align: left">sport</th>
      <th style="text-align: left">capacity</th>
      <th style="text-align: left">operator</th>
      <th style="text-align: left">wikipedia</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">Barcelona</td>
      <td style="text-align: left">Barcelona</td>
      <td style="text-align: left">Spain</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">en:Camp Nou</td>
    </tr>
    <tr>
      <td style="text-align: left">Bayern Munich</td>
      <td style="text-align: left">Munich</td>
      <td style="text-align: left">Germany</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">75021</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">de:Allianz Arena</td>
    </tr>
    <tr>
      <td style="text-align: left">Chelsea</td>
      <td style="text-align: left">London</td>
      <td style="text-align: left">UK</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">41837</td>
      <td style="text-align: left">Chelsea Football Club</td>
      <td style="text-align: left">en:Stamford Bridge (stadium)</td>
    </tr>
    <tr>
      <td style="text-align: left">Borussia Dortmund</td>
      <td style="text-align: left">Dortmund</td>
      <td style="text-align: left">Germany</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">de:Signal Iduna Park</td>
    </tr>
    <tr>
      <td style="text-align: left">Juventus</td>
      <td style="text-align: left">Turin</td>
      <td style="text-align: left">Italy</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">it:Allianz Stadium (Torino)</td>
    </tr>
    <tr>
      <td style="text-align: left">Liverpool</td>
      <td style="text-align: left">Liverpool</td>
      <td style="text-align: left">UK</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">54074</td>
      <td style="text-align: left">Liverpool Football Club</td>
      <td style="text-align: left">en:Anfield</td>
    </tr>
    <tr>
      <td style="text-align: left">Olympique Lyonnais</td>
      <td style="text-align: left">Lyon</td>
      <td style="text-align: left">France</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">58000</td>
      <td style="text-align: left">Olympique Lyonnais</td>
      <td style="text-align: left">fr:Parc Olympique lyonnais</td>
    </tr>
    <tr>
      <td style="text-align: left">Man. City</td>
      <td style="text-align: left">Manchester</td>
      <td style="text-align: left">UK</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">Manchester City Football Club</td>
      <td style="text-align: left">en:City of Manchester Stadium</td>
    </tr>
    <tr>
      <td style="text-align: left">Napoli</td>
      <td style="text-align: left">Naples</td>
      <td style="text-align: left">Italy</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">en:Stadio San Paolo</td>
    </tr>
    <tr>
      <td style="text-align: left">Real Madrid</td>
      <td style="text-align: left">Madrid</td>
      <td style="text-align: left">Spain</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">85454</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">es:Estadio Santiago Bernabéu</td>
    </tr>
    <tr>
      <td style="text-align: left">Tottenham</td>
      <td style="text-align: left">London</td>
      <td style="text-align: left">UK</td>
      <td style="text-align: left">soccer;american_football</td>
      <td style="text-align: left">62062</td>
      <td style="text-align: left">Tottenham Hotspur</td>
      <td style="text-align: left">en:Tottenham Hotspur Stadium</td>
    </tr>
    <tr>
      <td style="text-align: left">Valencia</td>
      <td style="text-align: left">Valencia</td>
      <td style="text-align: left">Spain</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
    </tr>
    <tr>
      <td style="text-align: left">Atalanta</td>
      <td style="text-align: left">Bergamo</td>
      <td style="text-align: left">Italy</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
    </tr>
    <tr>
      <td style="text-align: left">Atlético Madrid</td>
      <td style="text-align: left">Madrid</td>
      <td style="text-align: left">Spain</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">es:Estadio Metropolitano (Madrid)</td>
    </tr>
    <tr>
      <td style="text-align: left">RB Leipzig</td>
      <td style="text-align: left">Leipzig</td>
      <td style="text-align: left">Germany</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">NA</td>
      <td style="text-align: left">de:Red Bull Arena (Leipzig)</td>
    </tr>
    <tr>
      <td style="text-align: left">PSG</td>
      <td style="text-align: left">Paris</td>
      <td style="text-align: left">France</td>
      <td style="text-align: left">soccer</td>
      <td style="text-align: left">48527</td>
      <td style="text-align: left">Paris Saint-Germain</td>
      <td style="text-align: left">fr:Parc des Princes</td>
    </tr>
  </tbody>
</table>

<p>Below, the stadium locations are plotted on a map of Europe using the longitude and latitude coordinates and ggplot.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ggplot</span><span class="p">(</span><span class="n">stadium_locations</span><span class="p">,</span><span class="w"> </span><span class="n">aes</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">long</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">lat</span><span class="p">))</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">borders</span><span class="p">(</span><span class="s2">"world"</span><span class="p">,</span><span class="w"> </span><span class="n">xlim</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="m">-10</span><span class="p">,</span><span class="w"> </span><span class="m">10</span><span class="p">),</span><span class="w"> </span><span class="n">ylim</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="m">40</span><span class="p">,</span><span class="w"> </span><span class="m">55</span><span class="p">))</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_label_repel</span><span class="p">(</span><span class="n">aes</span><span class="p">(</span><span class="n">label</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Club</span><span class="p">),</span><span class="w"> </span><span class="n">force</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">2</span><span class="p">,</span><span class="w"> </span><span class="n">segment.alpha</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">0</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_point</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme_void</span><span class="p">()</span><span class="w">
</span></code></pre></div></div>

<p><img src="/rmd_images/2020-07-15-tidygeocoder-1-0-0/unnamed-chunk-5-1.png" style="display: block; margin: auto;" /></p>

<p>Alternatively, an interactive map can be created with the <a href="https://rstudio.github.io/leaflet/">leaflet</a> library:</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">leaflet</span><span class="p">)</span><span class="w">

</span><span class="n">stadium_locations</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> </span><span class="c1"># Our dataset</span><span class="w">
  </span><span class="n">leaflet</span><span class="p">(</span><span class="n">width</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"100%"</span><span class="p">,</span><span class="w"> </span><span class="n">options</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">leafletOptions</span><span class="p">(</span><span class="n">attributionControl</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">FALSE</span><span class="p">))</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">setView</span><span class="p">(</span><span class="n">lng</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">mean</span><span class="p">(</span><span class="n">stadium_locations</span><span class="o">$</span><span class="n">long</span><span class="p">),</span><span class="w"> </span><span class="n">lat</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">mean</span><span class="p">(</span><span class="n">stadium_locations</span><span class="o">$</span><span class="n">lat</span><span class="p">),</span><span class="w"> </span><span class="n">zoom</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">5</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="c1"># Map Backgrounds</span><span class="w">
  </span><span class="n">addProviderTiles</span><span class="p">(</span><span class="n">providers</span><span class="o">$</span><span class="n">Stamen.Terrain</span><span class="p">,</span><span class="w"> </span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"Terrain"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">addProviderTiles</span><span class="p">(</span><span class="n">providers</span><span class="o">$</span><span class="n">NASAGIBS.ViirsEarthAtNight2012</span><span class="p">,</span><span class="w"> </span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"Night"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">addProviderTiles</span><span class="p">(</span><span class="n">providers</span><span class="o">$</span><span class="n">Stamen.Toner</span><span class="p">,</span><span class="w"> </span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"Stamen"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">addTiles</span><span class="p">(</span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"OSM"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="c1"># Add Markers</span><span class="w">
  </span><span class="n">addMarkers</span><span class="p">(</span><span class="w">
    </span><span class="n">labelOptions</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">labelOptions</span><span class="p">(</span><span class="n">noHide</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">F</span><span class="p">),</span><span class="w"> </span><span class="n">lng</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">~</span><span class="n">long</span><span class="p">,</span><span class="w"> </span><span class="n">lat</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">~</span><span class="n">lat</span><span class="p">,</span><span class="w">
    </span><span class="n">clusterOptions</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">markerClusterOptions</span><span class="p">(</span><span class="n">maxClusterRadius</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">10</span><span class="p">),</span><span class="w"> </span><span class="n">label</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">~</span><span class="n">Club</span><span class="p">,</span><span class="w">
    </span><span class="n">group</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"Stadiums"</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="c1"># Map Control Options</span><span class="w">
  </span><span class="n">addLayersControl</span><span class="p">(</span><span class="w">
    </span><span class="n">baseGroups</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="s2">"OSM"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Stamen"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Terrain"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Night"</span><span class="p">),</span><span class="w">
    </span><span class="n">overlayGroups</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="s2">"Stadiums"</span><span class="p">),</span><span class="w">
    </span><span class="n">options</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">layersControlOptions</span><span class="p">(</span><span class="n">collapsed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">TRUE</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<div id="htmlwidget-e070e6d717a54d5f5327" style="width:100%;height:480px;" class="leaflet html-widget"></div>
<script type="application/json" data-for="htmlwidget-e070e6d717a54d5f5327">{"x":{"options":{"crs":{"crsClass":"L.CRS.EPSG3857","code":null,"proj4def":null,"projectedBounds":null,"options":{}},"attributionControl":false},"setView":[[46.816030234375,3.70195179384455],5,[]],"calls":[{"method":"addProviderTiles","args":["Stamen.Terrain",null,"Terrain",{"errorTileUrl":"","noWrap":false,"detectRetina":false}]},{"method":"addProviderTiles","args":["NASAGIBS.ViirsEarthAtNight2012",null,"Night",{"errorTileUrl":"","noWrap":false,"detectRetina":false}]},{"method":"addProviderTiles","args":["Stamen.Toner",null,"Stamen",{"errorTileUrl":"","noWrap":false,"detectRetina":false}]},{"method":"addTiles","args":["//{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",null,"OSM",{"minZoom":0,"maxZoom":18,"tileSize":256,"subdomains":"abc","errorTileUrl":"","tms":false,"noWrap":false,"zoomOffset":0,"zoomReverse":false,"opacity":1,"zIndex":1,"detectRetina":false,"attribution":"&copy; <a href=\"http://openstreetmap.org\">OpenStreetMap<\/a> contributors, <a href=\"http://creativecommons.org/licenses/by-sa/2.0/\">CC-BY-SA<\/a>"}]},{"method":"addMarkers","args":[[41.38089905,48.21880845,51.4816865,51.4928359,45.10965935,53.4308358,45.7653624,53.48309105,40.82797725,40.4530512,51.6041916,39.4756558,45.709222,40.43605295,51.34579105,48.8413634],[2.12292250075175,11.6246641517999,-0.191963664421104,7.45074465483453,7.64122132434347,-2.96090954141653,4.98205431107367,-2.20025200234333,14.1928889639353,-3.68754628942801,-0.0662349052591809,-0.3587826,9.68081336849461,-3.59971580972644,12.3482549226364,2.25306931623782],null,null,"Stadiums",{"interactive":true,"draggable":false,"keyboard":true,"title":"","alt":"","zIndexOffset":0,"opacity":1,"riseOnHover":false,"riseOffset":250},null,null,{"showCoverageOnHover":true,"zoomToBoundsOnClick":true,"spiderfyOnMaxZoom":true,"removeOutsideVisibleBounds":true,"spiderLegPolylineOptions":{"weight":1.5,"color":"#222","opacity":0.5},"freezeAtZoom":false,"maxClusterRadius":10},null,["Barcelona","Bayern Munich","Chelsea","Borussia Dortmund","Juventus","Liverpool","Olympique Lyonnais","Man. City","Napoli","Real Madrid","Tottenham","Valencia","Atalanta","Atlético Madrid","RB Leipzig","PSG"],{"interactive":false,"permanent":false,"direction":"auto","opacity":1,"offset":[0,0],"textsize":"10px","textOnly":false,"className":"","sticky":true},null]},{"method":"addLayersControl","args":[["OSM","Stamen","Terrain","Night"],"Stadiums",{"collapsed":true,"autoZIndex":true,"position":"topright"}]}],"limits":{"lat":[39.4756558,53.48309105],"lng":[-3.68754628942801,14.1928889639353]}},"evals":[],"jsHooks":[]}</script>

<p><br /></p>

<p>If you find any issues with the package or have ideas on how to improve it, feel free to <a href="https://github.com/jessecambon/tidygeocoder/issues">file an issue on Github</a>. For reference, the R Markdown file that generated this blog post can be found <a href="https://github.com/jessecambon/jessecambon.github.io/tree/main/_posts/2020-07-15-tidygeocoder-1-0-0.Rmd">here</a>.</p>]]></content><author><name>Jesse Cambon</name></author><category term="r" /><category term="tidygeocoder" /><summary type="html"><![CDATA[Tidygeocoder v1.0.0 is now live on CRAN. There are numerous new features and improvements such as batch geocoding (submitting multiple addresses per query), returning full results from geocoder services (not just latitude and longitude), address component arguments (city, country, etc.), query customization, and reduced package dependencies.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="https://jessecambon.github.io/images/tidygeocoder_hex.png" /><media:content medium="image" url="https://jessecambon.github.io/images/tidygeocoder_hex.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry><entry><title type="html">Deploying R Markdown Online</title><link href="https://jessecambon.github.io/2020/03/22/deploying-rmarkdown-online.html" rel="alternate" type="text/html" title="Deploying R Markdown Online" /><published>2020-03-22T00:00:00+00:00</published><updated>2020-03-22T00:00:00+00:00</updated><id>https://jessecambon.github.io/2020/03/22/deploying-rmarkdown-online</id><content type="html" xml:base="https://jessecambon.github.io/2020/03/22/deploying-rmarkdown-online.html"><![CDATA[<p><a href="https://rmarkdown.rstudio.com/">R Markdown</a> is a great tool for creating a variety of documents with R code and it’s a natural choice for producing blog posts such as this one. However, depending on which blog software you use, you may run into some problems related to the file paths for figure images (such as <a href="https://ggplot2.tidyverse.org/">ggplot</a> charts) which will require tweaks in your R Markdown workflow.</p>

<p>This blog post demonstrates a simple solution to this problem that will also give you central control over R Markdown knit settings across your site. I use this solution for this blog and <a href="https://github.com/jessecambon/Data-Science-Codex">a GitHub repository of data science resources</a>. You can also find the R Markdown file that generated this blog post <a href="https://github.com/jessecambon/jessecambon.github.io/blob/master/_posts/2020-03-22-deploying-rmarkdown-online.Rmd">here</a>.</p>

<p><img src="/../images/hex-rmarkdown.png" style="display: block; margin: auto;" /></p>

<p>Note that in this post I will be talking about implementing a solution for a <a href="https://jekyllrb.com/">Jekyll</a> blog that is hosted via <a href="https://pages.github.com/">GitHub pages</a>. Some modifications may be required if you are using another blog or website platform. However, this solution should be adaptable to all blogs or websites that use Markdown.</p>

<p>For Jekyll there are two steps to building web content (HTML) from an R Markdown file. The first is to knit the R Markdown (.Rmd) file which creates the Markdown (.md) file. The second step is to use the <a href="https://jekyllrb.com/docs/usage/">jekyll build</a> command to create HTML content which is what will be displayed online.</p>

<pre>
1. <b>Knit:</b>          R Markdown (.Rmd) ----&gt;  Markdown (.md) 
2. <b>Jekyll Build:</b>  Markdown (.md)   ----&gt;  HTML (.html)
</pre>

<h2 id="the-problem">The Problem</h2>

<p>When I first used R Markdown to create a post for this blog, none of my figures showed up in the post. The issue was that <a href="https://jekyllrb.com/">Jekyll</a> creates the HTML file for a blog post in a different location than the R Markdown (.Rmd) and Markdown (.md) files and this breaks figure file paths. <a href="http://www.randigriffin.com/2017/04/25/how-to-knit-for-mysite.html">This blog post</a> describes the problem in more detail.</p>

<p>Also, by default R Markdown stores files for figures two folder levels deep using the R Markdown file location as its root (ie. <code class="language-plaintext highlighter-rouge">&lt;rmarkdown-filename&gt;_files/figure-gfm/image.png</code>). I find it more convenient to organize figure files in a separate root directory from my R Markdown files and store the images only one folder level deep (ie. <code class="language-plaintext highlighter-rouge">/rmd_images/&lt;rmarkdown-filename&gt;/image.png</code>). You can see this folder structure in action <a href="https://github.com/jessecambon/jessecambon.github.io">here</a> (posts are in the <code class="language-plaintext highlighter-rouge">_posts</code> folder and figures are in the <code class="language-plaintext highlighter-rouge">rmd_images</code> folder).</p>

<h2 id="the-solution">The Solution</h2>

<p>This solution uses a single R script file (.R) which contains knit settings adjustments and is referenced by all R Markdown (.Rmd) files. This allows you to edit knit settings in one central location and use these settings whenever you knit an R Markdown file. Modifications are made to the knit process so that figure image files are saved in a well organized folder structure and the HTML files display figures properly.</p>

<p>The contents of this central R script which I have named <a href="https://github.com/jessecambon/jessecambon.github.io/blob/master/rmd_config.R">rmd_config.R</a> is below. It lives in the root directory of my Github repository and the contents of this file will be run (via <a href="https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/source">source</a>) when each R Markdown file is knit.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># get name of file during knitting and strip file extension</span><span class="w">
</span><span class="n">rmd_filename</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">stringr</span><span class="o">::</span><span class="n">str_remove</span><span class="p">(</span><span class="n">knitr</span><span class="o">::</span><span class="n">current_input</span><span class="p">(),</span><span class="w"> </span><span class="s2">"\\.Rmd"</span><span class="p">)</span><span class="w">

</span><span class="c1"># Figure path on disk = base.dir + fig.path</span><span class="w">
</span><span class="c1"># Figure URL online = base.url + fig.path</span><span class="w">
</span><span class="n">knitr</span><span class="o">::</span><span class="n">opts_knit</span><span class="o">$</span><span class="n">set</span><span class="p">(</span><span class="n">base.dir</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">stringr</span><span class="o">::</span><span class="n">str_c</span><span class="p">(</span><span class="n">here</span><span class="o">::</span><span class="n">here</span><span class="p">(),</span><span class="w"> </span><span class="s2">"/"</span><span class="p">),</span><span class="w"> </span><span class="n">base.url</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"/"</span><span class="p">)</span><span class="w"> </span><span class="c1"># project root folder</span><span class="w">
</span><span class="n">knitr</span><span class="o">::</span><span class="n">opts_chunk</span><span class="o">$</span><span class="n">set</span><span class="p">(</span><span class="n">fig.path</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">stringr</span><span class="o">::</span><span class="n">str_c</span><span class="p">(</span><span class="n">file.path</span><span class="p">(</span><span class="s2">"rmd_images"</span><span class="p">,</span><span class="w"> </span><span class="n">rmd_filename</span><span class="p">),</span><span class="w"> </span><span class="s2">"/"</span><span class="p">))</span><span class="w">
</span></code></pre></div></div>

<p>Here is what is going on in the above script:</p>

<ul>
  <li>The filename of our R Markdown file is extracted using <code class="language-plaintext highlighter-rouge">knitr::current_input()</code> and stored in the variable <code class="language-plaintext highlighter-rouge">rmd_filename</code> (<code class="language-plaintext highlighter-rouge">str_remove</code> is used to remove the .Rmd file extension).</li>
  <li>The <a href="https://here.r-lib.org/">here package</a> establishes our ‘base’ directory (the root folder of our GitHub repository). The base directory path could change based on which computer we use and where we put our GitHub repository files so the here package allows us to automatically find this path.</li>
  <li>The <code class="language-plaintext highlighter-rouge">fig.path</code>, which is where our figures will be stored, is set to a folder named after the R Markdown file being run that resides in the ‘/rmd_images’ root directory.</li>
</ul>

<p>To utilize the above script in an R Markdown file, we simply insert the code below as a chunk into the R Markdown file. This will <a href="https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/source">source</a> the script to apply all the necessary knit settings when an R Markdown file is knit.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">source</span><span class="p">(</span><span class="n">here</span><span class="o">::</span><span class="n">here</span><span class="p">(</span><span class="s2">"rmd_config.R"</span><span class="p">))</span><span class="w">
</span></code></pre></div></div>

<p>For a Jekyll blog, you’ll also want to include certain YAML header content such as tags or the title of the post. To do this we can use the <code class="language-plaintext highlighter-rouge">preserve_yaml</code> output setting in generating our .md file and then insert whatever YAML content we need into the header. Below is an example YAML header (the first part of your R Markdown document) which will generate a github-style (“gfm”) .md document. In this example I’ve added the fields “layout”, “title”, “date”, “author”, and “tags” which are all used by Jekyll in creating the blog post.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">---</span><span class="w">
</span><span class="n">layout</span><span class="o">:</span><span class="w"> </span><span class="n">post</span><span class="w">
</span><span class="n">title</span><span class="o">:</span><span class="w">  </span><span class="s2">"Deploying R Markdown Online"</span><span class="w">
</span><span class="n">date</span><span class="o">:</span><span class="w">   </span><span class="m">2020-03-22</span><span class="w">
</span><span class="n">author</span><span class="o">:</span><span class="w"> </span><span class="n">Jesse</span><span class="w"> </span><span class="n">Cambon</span><span class="w">
</span><span class="n">tags</span><span class="o">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="p">]</span><span class="w">
</span><span class="n">output</span><span class="o">:</span><span class="w"> 
  </span><span class="n">md_document</span><span class="o">:</span><span class="w">
    </span><span class="n">pandoc_args</span><span class="o">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"--wrap=none"</span><span class="p">]</span><span class="w">
    </span><span class="n">variant</span><span class="o">:</span><span class="w"> </span><span class="n">gfm</span><span class="w">
    </span><span class="n">preserve_yaml</span><span class="o">:</span><span class="w"> </span><span class="kc">TRUE</span><span class="w">
</span><span class="o">---</span><span class="w">
</span></code></pre></div></div>

<p>Note that the <code class="language-plaintext highlighter-rouge">pandoc_args</code> setting is to prevent the knit process from inserting extra line breaks into the Markdown file that don’t exist in our R Markdown file. The extra line breaks normally are invisible, but I found they showed up when I pushed content to <a href="https://www.r-bloggers.com/">R-Bloggers</a> which caused paragraphs to be broken up.</p>

<p>One other note on Jekyll is that it uses the <a href="https://jekyllrb.com/docs/liquid/">liquid template language</a>. If you want to display characters on your blog that are used by liquid such as <code class="language-plaintext highlighter-rouge">{{}}</code> (R’s “curly-curly” operator) then you will need to wrap these problematic characters with the <code class="language-plaintext highlighter-rouge">raw</code> and <code class="language-plaintext highlighter-rouge">endraw</code> liquid tags <a href="https://shopify.github.io/liquid/tags/raw/">as described here</a>. This prevents Jekyll from attempting to parse these characters as liquid syntax and passes them on in raw form to the HTML file for display.</p>

<h2 id="conclusion">Conclusion</h2>

<p>To see this solution in action, you can look at the GitHub repository that produces this blog <a href="https://github.com/jessecambon/jessecambon.github.io">here</a> and the R Markdown file for this specific blog post <a href="https://github.com/jessecambon/jessecambon.github.io/blob/master/_posts/2020-03-22-deploying-rmarkdown-online.Rmd">here</a>. To provide a self-contained example of a figure displaying, I’ve created a simple histogram plot below and you’ll find the image file neatly filed away in the <code class="language-plaintext highlighter-rouge">rmd_images</code> directory underneath a subfolder named after this blog post.</p>

<p>One caveat is that this approach does assume that each R Markdown filename is unique. If this is not the case then you’ll need to make some modifications to the central <code class="language-plaintext highlighter-rouge">rmd_config.R</code> file above; otherwise figure images from different R Markdown files may save in the same directory (and possibly overwrite each other). However, the solution described here is quite flexible and could be adapted to a variety of use cases with tweaks to the <code class="language-plaintext highlighter-rouge">rmd_config.R</code> file.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">hist</span><span class="p">(</span><span class="n">mtcars</span><span class="o">$</span><span class="n">disp</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p><img src="/rmd_images/2020-03-22-deploying-rmarkdown-online/sampleplot-1.png" alt="" /><!-- --></p>

<p><em><sub> March 26 2021: this post has been updated with simplified R Markdown code. </sub></em></p>]]></content><author><name>Jesse Cambon</name></author><category term="r" /><summary type="html"><![CDATA[R Markdown is a great tool for creating a variety of documents with R code and it’s a natural choice for producing blog posts such as this one. However, depending on which blog software you use, you may run into some problems related to the file paths for figure images (such as ggplot charts) which will require tweaks in your R Markdown workflow.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="https://jessecambon.github.io/images/hex-rmarkdown.png" /><media:content medium="image" url="https://jessecambon.github.io/images/hex-rmarkdown.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry><entry><title type="html">Data Science Essentials</title><link href="https://jessecambon.github.io/2020/01/12/data-science-essentials.html" rel="alternate" type="text/html" title="Data Science Essentials" /><published>2020-01-12T00:00:00+00:00</published><updated>2020-01-12T00:00:00+00:00</updated><id>https://jessecambon.github.io/2020/01/12/data-science-essentials</id><content type="html" xml:base="https://jessecambon.github.io/2020/01/12/data-science-essentials.html"><![CDATA[<p>One the greatest strengths of R for data science work is the vast number and variety of packages and capabilities that are available. However, it can be intimidating to navigate this large and dynamic open source ecosystem, especially for a newcomer. All the information you need is out there, but it is often fragmented across numerous <a href="https://stackoverflow.com/">stack overflow</a> threads and websites.</p>

<p>In an attempt to consolidate some of this information, this blog post demonstrates fundamental methods that I have used repeatedly as a data scientist. This code should get you started in performing some essential and broadly useful data science tasks with R - data manipulation, summarization, and visualization.</p>

<p>I will mainly rely on the <a href="https://dplyr.tidyverse.org/">dplyr</a>, <a href="https://tidyr.tidyverse.org/">tidyr</a>, and <a href="https://ggplot2.tidyverse.org/">ggplot2</a> packages which all have excellent documentation that you can refer to for further details. Datasets that are built into these packages will be used so that there is no need to download external data. Also note that the input and output datasets will be displayed for each example, but at times only the first several rows will be shown for display purposes.</p>

<p>If you’d like to follow along while running the code, you can find the RMarkdown file that generated this blog post <a href="https://github.com/jessecambon/jessecambon.github.io/blob/master/_posts/2020-1-12-data-science-essentials.Rmd">here</a>. Also, if you haven’t installed the <a href="https://www.tidyverse.org/">tidyverse packages</a> already, you’ll need to do that first with this command: <code class="language-plaintext highlighter-rouge">install.packages('tidyverse')</code>.</p>

<h2 id="basic-data-manipulation">Basic Data Manipulation</h2>

<p>To begin, we need to load the tidyverse packages:</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">tidyverse</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p>Now, let’s take a look at the <a href="https://ggplot2.tidyverse.org/reference/mpg.html">mpg</a> dataset from the <a href="https://ggplot2.tidyverse.org/index.html">ggplot2</a> package:</p>

<table>
  <thead>
    <tr>
      <th style="text-align: left">manufacturer</th>
      <th style="text-align: left">model</th>
      <th style="text-align: right">displ</th>
      <th style="text-align: right">year</th>
      <th style="text-align: right">cyl</th>
      <th style="text-align: left">trans</th>
      <th style="text-align: left">drv</th>
      <th style="text-align: right">cty</th>
      <th style="text-align: right">hwy</th>
      <th style="text-align: left">fl</th>
      <th style="text-align: left">class</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a4</td>
      <td style="text-align: right">1.8</td>
      <td style="text-align: right">1999</td>
      <td style="text-align: right">4</td>
      <td style="text-align: left">auto(l5)</td>
      <td style="text-align: left">f</td>
      <td style="text-align: right">18</td>
      <td style="text-align: right">29</td>
      <td style="text-align: left">p</td>
      <td style="text-align: left">compact</td>
    </tr>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a4</td>
      <td style="text-align: right">1.8</td>
      <td style="text-align: right">1999</td>
      <td style="text-align: right">4</td>
      <td style="text-align: left">manual(m5)</td>
      <td style="text-align: left">f</td>
      <td style="text-align: right">21</td>
      <td style="text-align: right">29</td>
      <td style="text-align: left">p</td>
      <td style="text-align: left">compact</td>
    </tr>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a4</td>
      <td style="text-align: right">2.0</td>
      <td style="text-align: right">2008</td>
      <td style="text-align: right">4</td>
      <td style="text-align: left">manual(m6)</td>
      <td style="text-align: left">f</td>
      <td style="text-align: right">20</td>
      <td style="text-align: right">31</td>
      <td style="text-align: left">p</td>
      <td style="text-align: left">compact</td>
    </tr>
  </tbody>
</table>

<p>We’ll perform a few of the most commonly used data manipulation operations on this dataset using the <a href="https://dplyr.tidyverse.org/">dplyr</a> package. If you’re new to R, the <strong>&lt;-</strong> operator that you see below is used to assign the value of what follows it to the dataset that precedes it. In this example, we are manipulating the ‘mpg’ dataset and saving it as the ‘mpg_subset’ dataset.</p>

<p>If you’re not familiar with dplyr, note that the “pipe” operator <strong>%&gt;%</strong> is used to pass the output of a function to the following function. This allows us to perform data manipulations in sequence in a clear and readable way.</p>

<p>In this example, we select the two rows that contain Nissan vehicles years 2005 and later with 4 cylinders, create two new columns, order the columns, remove four columns, and rename a column. In the order that they are used below, here are the main functions used to accomplish this:</p>

<ul>
  <li><a href="https://dplyr.tidyverse.org/reference/filter.html">filter</a> controls which rows we want to keep from the input dataset. In this example, three conditions are applied using the “&amp;” (AND) operator.</li>
  <li><a href="https://dplyr.tidyverse.org/reference/mutate.html">mutate</a> is used to create new columns.</li>
  <li><a href="https://stringr.tidyverse.org/reference/str_c.html">str_c</a> combines multiple strings. In this case we are combining the manufacturer and model string fields into a single field with a single space in between.</li>
  <li><a href="https://dplyr.tidyverse.org/reference/select.html">select</a> is used to pick which columns from the input dataset we want to keep. This select statement sets the order of the first four columns, includes the remaining columns, but then removes four columns.
    <ul>
      <li>A ‘-’ before a column name indicates that we want to remove that column.</li>
      <li>The everything() function is shorthand for selecting all remaining columns and is an example of a <a href="https://www.rdocumentation.org/packages/dplyr/versions/0.7.3/topics/select_helpers">select helper</a>.</li>
    </ul>
  </li>
  <li><a href="https://dplyr.tidyverse.org/reference/select.html">rename</a> is used to rename the ‘fl’ column to ‘fuel_type’</li>
</ul>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">mpg_subset</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">filter</span><span class="p">(</span><span class="n">cyl</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="m">4</span><span class="w"> </span><span class="o">&amp;</span><span class="w"> </span><span class="n">year</span><span class="w"> </span><span class="o">&gt;=</span><span class="w"> </span><span class="m">2005</span><span class="w"> </span><span class="o">&amp;</span><span class="w"> </span><span class="n">manufacturer</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s2">"nissan"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">mutate</span><span class="p">(</span><span class="w">
    </span><span class="n">mpg_ratio</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">hwy</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">cty</span><span class="p">,</span><span class="w">
    </span><span class="n">make_model</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">str_c</span><span class="p">(</span><span class="n">manufacturer</span><span class="p">,</span><span class="w"> </span><span class="s2">" "</span><span class="p">,</span><span class="w"> </span><span class="n">model</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">select</span><span class="p">(</span><span class="w">
    </span><span class="n">make_model</span><span class="p">,</span><span class="w"> </span><span class="n">year</span><span class="p">,</span><span class="w"> </span><span class="n">hwy</span><span class="p">,</span><span class="w"> </span><span class="n">cty</span><span class="p">,</span><span class="w"> </span><span class="n">everything</span><span class="p">(),</span><span class="w">
    </span><span class="o">-</span><span class="n">manufacturer</span><span class="p">,</span><span class="w"> </span><span class="o">-</span><span class="n">model</span><span class="p">,</span><span class="w"> </span><span class="o">-</span><span class="n">drv</span><span class="p">,</span><span class="w"> </span><span class="o">-</span><span class="n">trans</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">rename</span><span class="p">(</span><span class="n">fuel_type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">fl</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">make_model</th>
      <th style="text-align: right">year</th>
      <th style="text-align: right">hwy</th>
      <th style="text-align: right">cty</th>
      <th style="text-align: right">displ</th>
      <th style="text-align: right">cyl</th>
      <th style="text-align: left">fuel_type</th>
      <th style="text-align: left">class</th>
      <th style="text-align: right">mpg_ratio</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">nissan altima</td>
      <td style="text-align: right">2008</td>
      <td style="text-align: right">31</td>
      <td style="text-align: right">23</td>
      <td style="text-align: right">2.5</td>
      <td style="text-align: right">4</td>
      <td style="text-align: left">r</td>
      <td style="text-align: left">midsize</td>
      <td style="text-align: right">1.347826</td>
    </tr>
    <tr>
      <td style="text-align: left">nissan altima</td>
      <td style="text-align: right">2008</td>
      <td style="text-align: right">32</td>
      <td style="text-align: right">23</td>
      <td style="text-align: right">2.5</td>
      <td style="text-align: right">4</td>
      <td style="text-align: left">r</td>
      <td style="text-align: left">midsize</td>
      <td style="text-align: right">1.391304</td>
    </tr>
  </tbody>
</table>

<h2 id="summary-statistics">Summary Statistics</h2>

<p>Calculating summary statistics like counts, means, and medians is a good initial step to understand a dataset. To count observations (rows) by a categorical variable, we can use the <a href="https://dplyr.tidyverse.org/reference/tally.html">count</a> function. Here we find the number of rows for each value of the ‘cyl’ (cylinders) column:</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">count_cyl</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">count</span><span class="p">(</span><span class="n">cyl</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: right">cyl</th>
      <th style="text-align: right">n</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: right">4</td>
      <td style="text-align: right">81</td>
    </tr>
    <tr>
      <td style="text-align: right">5</td>
      <td style="text-align: right">4</td>
    </tr>
    <tr>
      <td style="text-align: right">6</td>
      <td style="text-align: right">79</td>
    </tr>
    <tr>
      <td style="text-align: right">8</td>
      <td style="text-align: right">70</td>
    </tr>
  </tbody>
</table>

<p>A broader variety of statistics can be calculated using the <a href="https://dplyr.tidyverse.org/reference/group_by.html">group_by</a> and <a href="https://dplyr.tidyverse.org/reference/summarise.html">summarize</a> functions. In this example, we create a new categorical column ‘class_c’ (which combines 2 seaters and subcompact vehicles into a single category) using the <a href="https://dplyr.tidyverse.org/reference/case_when.html">case_when</a> function and then calculate a variety of basic summary statistics by this column.</p>

<p>The <a href="https://dplyr.tidyverse.org/reference/arrange.html">arrange</a> function is used to order the rows in the dataset in descending order of the created ‘count’ variable. Note that the ‘ungroup’ function is not strictly necessary in this case, but it is a good practice if we plan to manipulate our dataset in the future without using groups.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">mpg_stats</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">select</span><span class="p">(</span><span class="n">class</span><span class="p">,</span><span class="w"> </span><span class="n">hwy</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">mutate</span><span class="p">(</span><span class="n">class_c</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">case_when</span><span class="p">(</span><span class="w">
    </span><span class="n">class</span><span class="w"> </span><span class="o">%in%</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="s2">"2seater"</span><span class="p">,</span><span class="w"> </span><span class="s2">"subcompact"</span><span class="p">)</span><span class="w"> </span><span class="o">~</span><span class="w"> </span><span class="s2">"subcompact"</span><span class="p">,</span><span class="w">
    </span><span class="kc">TRUE</span><span class="w"> </span><span class="o">~</span><span class="w"> </span><span class="n">class</span><span class="w">
  </span><span class="p">))</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">group_by</span><span class="p">(</span><span class="n">class_c</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">summarize</span><span class="p">(</span><span class="w">
    </span><span class="n">count</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">n</span><span class="p">(),</span><span class="w">
    </span><span class="n">min_hwy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">min</span><span class="p">(</span><span class="n">hwy</span><span class="p">),</span><span class="w">
    </span><span class="n">max_hwy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">max</span><span class="p">(</span><span class="n">hwy</span><span class="p">),</span><span class="w">
    </span><span class="n">median_hwy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">median</span><span class="p">(</span><span class="n">hwy</span><span class="p">),</span><span class="w">
    </span><span class="n">mean_hwy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">mean</span><span class="p">(</span><span class="n">hwy</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">ungroup</span><span class="p">()</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">arrange</span><span class="p">(</span><span class="n">desc</span><span class="p">(</span><span class="n">count</span><span class="p">))</span><span class="w"> </span><span class="c1"># sort dataset</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">class_c</th>
      <th style="text-align: right">count</th>
      <th style="text-align: right">min_hwy</th>
      <th style="text-align: right">max_hwy</th>
      <th style="text-align: right">median_hwy</th>
      <th style="text-align: right">mean_hwy</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">suv</td>
      <td style="text-align: right">62</td>
      <td style="text-align: right">12</td>
      <td style="text-align: right">27</td>
      <td style="text-align: right">17.5</td>
      <td style="text-align: right">18.12903</td>
    </tr>
    <tr>
      <td style="text-align: left">compact</td>
      <td style="text-align: right">47</td>
      <td style="text-align: right">23</td>
      <td style="text-align: right">44</td>
      <td style="text-align: right">27.0</td>
      <td style="text-align: right">28.29787</td>
    </tr>
    <tr>
      <td style="text-align: left">midsize</td>
      <td style="text-align: right">41</td>
      <td style="text-align: right">23</td>
      <td style="text-align: right">32</td>
      <td style="text-align: right">27.0</td>
      <td style="text-align: right">27.29268</td>
    </tr>
    <tr>
      <td style="text-align: left">subcompact</td>
      <td style="text-align: right">40</td>
      <td style="text-align: right">20</td>
      <td style="text-align: right">44</td>
      <td style="text-align: right">26.0</td>
      <td style="text-align: right">27.72500</td>
    </tr>
    <tr>
      <td style="text-align: left">pickup</td>
      <td style="text-align: right">33</td>
      <td style="text-align: right">12</td>
      <td style="text-align: right">22</td>
      <td style="text-align: right">17.0</td>
      <td style="text-align: right">16.87879</td>
    </tr>
    <tr>
      <td style="text-align: left">minivan</td>
      <td style="text-align: right">11</td>
      <td style="text-align: right">17</td>
      <td style="text-align: right">24</td>
      <td style="text-align: right">23.0</td>
      <td style="text-align: right">22.36364</td>
    </tr>
  </tbody>
</table>

<h2 id="stacking-data">Stacking Data</h2>

<p>If you have datasets whose columns or rows align, you can combine them by stacking the datasets vertically or horizontally. To demonstrate this, we will first use the <a href="https://dplyr.tidyverse.org/reference/slice.html">slice</a> function to subset the ‘mpg’ dataset by row numbers to create the ‘mpg1’ and ‘mpg2’ datasets.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">mpg1</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">slice</span><span class="p">(</span><span class="m">1</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">select</span><span class="p">(</span><span class="n">manufacturer</span><span class="p">,</span><span class="w"> </span><span class="n">model</span><span class="p">,</span><span class="w"> </span><span class="n">hwy</span><span class="p">,</span><span class="w"> </span><span class="n">cty</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">mutate</span><span class="p">(</span><span class="n">dataset</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">manufacturer</th>
      <th style="text-align: left">model</th>
      <th style="text-align: right">hwy</th>
      <th style="text-align: right">cty</th>
      <th style="text-align: right">dataset</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a4</td>
      <td style="text-align: right">29</td>
      <td style="text-align: right">18</td>
      <td style="text-align: right">1</td>
    </tr>
  </tbody>
</table>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">mpg2</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">slice</span><span class="p">(</span><span class="m">44</span><span class="o">:</span><span class="m">45</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">select</span><span class="p">(</span><span class="n">manufacturer</span><span class="p">,</span><span class="w"> </span><span class="n">model</span><span class="p">,</span><span class="w"> </span><span class="n">hwy</span><span class="p">,</span><span class="w"> </span><span class="n">cty</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">mutate</span><span class="p">(</span><span class="n">dataset</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">2</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">manufacturer</th>
      <th style="text-align: left">model</th>
      <th style="text-align: right">hwy</th>
      <th style="text-align: right">cty</th>
      <th style="text-align: right">dataset</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">dodge</td>
      <td style="text-align: left">caravan 2wd</td>
      <td style="text-align: right">17</td>
      <td style="text-align: right">11</td>
      <td style="text-align: right">2</td>
    </tr>
    <tr>
      <td style="text-align: left">dodge</td>
      <td style="text-align: left">caravan 2wd</td>
      <td style="text-align: right">22</td>
      <td style="text-align: right">15</td>
      <td style="text-align: right">2</td>
    </tr>
  </tbody>
</table>

<p>Since these two datasets we just created have the same columns we can stack them vertically using <a href="https://dplyr.tidyverse.org/reference/bind.html">bind_rows</a>:</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">mpg_stack_vert</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg1</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">bind_rows</span><span class="p">(</span><span class="n">mpg2</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">manufacturer</th>
      <th style="text-align: left">model</th>
      <th style="text-align: right">hwy</th>
      <th style="text-align: right">cty</th>
      <th style="text-align: right">dataset</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a4</td>
      <td style="text-align: right">29</td>
      <td style="text-align: right">18</td>
      <td style="text-align: right">1</td>
    </tr>
    <tr>
      <td style="text-align: left">dodge</td>
      <td style="text-align: left">caravan 2wd</td>
      <td style="text-align: right">17</td>
      <td style="text-align: right">11</td>
      <td style="text-align: right">2</td>
    </tr>
    <tr>
      <td style="text-align: left">dodge</td>
      <td style="text-align: left">caravan 2wd</td>
      <td style="text-align: right">22</td>
      <td style="text-align: right">15</td>
      <td style="text-align: right">2</td>
    </tr>
  </tbody>
</table>

<p>Now let’s create a third subsection of the ‘mpg’ dataset using the same rows that generated ‘mpg1’ and ‘mpg2’ above, but with different columns. We’ll call it ‘mpg3’:</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">mpg3</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">slice</span><span class="p">(</span><span class="m">1</span><span class="p">,</span><span class="w"> </span><span class="m">44</span><span class="o">:</span><span class="m">45</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">select</span><span class="p">(</span><span class="n">displ</span><span class="p">,</span><span class="w"> </span><span class="n">year</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: right">displ</th>
      <th style="text-align: right">year</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: right">1.8</td>
      <td style="text-align: right">1999</td>
    </tr>
    <tr>
      <td style="text-align: right">3.3</td>
      <td style="text-align: right">2008</td>
    </tr>
    <tr>
      <td style="text-align: right">3.8</td>
      <td style="text-align: right">1999</td>
    </tr>
  </tbody>
</table>

<p>We can stack the ‘mpg_stack_vert’ and ‘mpg3’ datasets horizontally since their rows align (we used the ‘slice’ function to subset the ‘mpg’ dataset on the same row numbers). We use the <a href="https://dplyr.tidyverse.org/reference/bind.html">bind_cols</a> function to do this.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">mpg_stack_horz</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg_stack_vert</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">bind_cols</span><span class="p">(</span><span class="n">mpg3</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">manufacturer</th>
      <th style="text-align: left">model</th>
      <th style="text-align: right">hwy</th>
      <th style="text-align: right">cty</th>
      <th style="text-align: right">dataset</th>
      <th style="text-align: right">displ</th>
      <th style="text-align: right">year</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a4</td>
      <td style="text-align: right">29</td>
      <td style="text-align: right">18</td>
      <td style="text-align: right">1</td>
      <td style="text-align: right">1.8</td>
      <td style="text-align: right">1999</td>
    </tr>
    <tr>
      <td style="text-align: left">dodge</td>
      <td style="text-align: left">caravan 2wd</td>
      <td style="text-align: right">17</td>
      <td style="text-align: right">11</td>
      <td style="text-align: right">2</td>
      <td style="text-align: right">3.3</td>
      <td style="text-align: right">2008</td>
    </tr>
    <tr>
      <td style="text-align: left">dodge</td>
      <td style="text-align: left">caravan 2wd</td>
      <td style="text-align: right">22</td>
      <td style="text-align: right">15</td>
      <td style="text-align: right">2</td>
      <td style="text-align: right">3.8</td>
      <td style="text-align: right">1999</td>
    </tr>
  </tbody>
</table>

<h2 id="joining-data">Joining Data</h2>

<p>If you have datasets that contain a common “key” column (or a set of key columns) then you can use one of the <a href="https://dplyr.tidyverse.org/reference/join.html">join functions from dplyr</a> to combine these datasets. First let’s create a dataset named ‘car_type’ which contains the unique combinations of the ‘manufacturer’, ‘model’, and ‘class’ column values using the <a href="https://dplyr.tidyverse.org/reference/distinct.html">distinct</a> function.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">car_type</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">select</span><span class="p">(</span><span class="n">manufacturer</span><span class="p">,</span><span class="w"> </span><span class="n">model</span><span class="p">,</span><span class="w"> </span><span class="n">class</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">distinct</span><span class="p">()</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">manufacturer</th>
      <th style="text-align: left">model</th>
      <th style="text-align: left">class</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a4</td>
      <td style="text-align: left">compact</td>
    </tr>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a4 quattro</td>
      <td style="text-align: left">compact</td>
    </tr>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a6 quattro</td>
      <td style="text-align: left">midsize</td>
    </tr>
    <tr>
      <td style="text-align: left">chevrolet</td>
      <td style="text-align: left">c1500 suburban 2wd</td>
      <td style="text-align: left">suv</td>
    </tr>
  </tbody>
</table>

<p>Now we will join this newly created ‘car_type’ dataset to the ‘mpg_stack_horz’ dataset (created above) using the ‘left_join’ function. The ‘manufacturer’ and ‘model’ columns are used as joining keys. The resulting dataset, ‘joined’, now contains all the columns from ‘mpg_stack_horz’ as well as the ‘class’ column from the ‘car_type’ dataset.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">joined</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mpg_stack_horz</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">left_join</span><span class="p">(</span><span class="n">car_type</span><span class="p">,</span><span class="w"> </span><span class="n">by</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="s2">"manufacturer"</span><span class="p">,</span><span class="w"> </span><span class="s2">"model"</span><span class="p">))</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">select</span><span class="p">(</span><span class="o">-</span><span class="n">dataset</span><span class="p">,</span><span class="w"> </span><span class="n">everything</span><span class="p">())</span><span class="w"> </span><span class="c1"># make the 'dataset' column last</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">manufacturer</th>
      <th style="text-align: left">model</th>
      <th style="text-align: right">hwy</th>
      <th style="text-align: right">cty</th>
      <th style="text-align: right">displ</th>
      <th style="text-align: right">year</th>
      <th style="text-align: left">class</th>
      <th style="text-align: right">dataset</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">audi</td>
      <td style="text-align: left">a4</td>
      <td style="text-align: right">29</td>
      <td style="text-align: right">18</td>
      <td style="text-align: right">1.8</td>
      <td style="text-align: right">1999</td>
      <td style="text-align: left">compact</td>
      <td style="text-align: right">1</td>
    </tr>
    <tr>
      <td style="text-align: left">dodge</td>
      <td style="text-align: left">caravan 2wd</td>
      <td style="text-align: right">17</td>
      <td style="text-align: right">11</td>
      <td style="text-align: right">3.3</td>
      <td style="text-align: right">2008</td>
      <td style="text-align: left">minivan</td>
      <td style="text-align: right">2</td>
    </tr>
    <tr>
      <td style="text-align: left">dodge</td>
      <td style="text-align: left">caravan 2wd</td>
      <td style="text-align: right">22</td>
      <td style="text-align: right">15</td>
      <td style="text-align: right">3.8</td>
      <td style="text-align: right">1999</td>
      <td style="text-align: left">minivan</td>
      <td style="text-align: right">2</td>
    </tr>
  </tbody>
</table>

<h2 id="converting-long-to-wide-format">Converting Long to Wide Format</h2>

<p>Let’s take a look at the <a href="https://tidyr.tidyverse.org/reference/us_rent_income.html">us_rent_income</a> dataset from the <a href="https://tidyr.tidyverse.org">tidyr</a> package:</p>

<table>
  <thead>
    <tr>
      <th style="text-align: left">GEOID</th>
      <th style="text-align: left">NAME</th>
      <th style="text-align: left">variable</th>
      <th style="text-align: right">estimate</th>
      <th style="text-align: right">moe</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">01</td>
      <td style="text-align: left">Alabama</td>
      <td style="text-align: left">income</td>
      <td style="text-align: right">24476</td>
      <td style="text-align: right">136</td>
    </tr>
    <tr>
      <td style="text-align: left">01</td>
      <td style="text-align: left">Alabama</td>
      <td style="text-align: left">rent</td>
      <td style="text-align: right">747</td>
      <td style="text-align: right">3</td>
    </tr>
    <tr>
      <td style="text-align: left">02</td>
      <td style="text-align: left">Alaska</td>
      <td style="text-align: left">income</td>
      <td style="text-align: right">32940</td>
      <td style="text-align: right">508</td>
    </tr>
    <tr>
      <td style="text-align: left">02</td>
      <td style="text-align: left">Alaska</td>
      <td style="text-align: left">rent</td>
      <td style="text-align: right">1200</td>
      <td style="text-align: right">13</td>
    </tr>
  </tbody>
</table>

<p>Each row of this dataset pertains to either income or rent as we can see by looking at the value of the ‘variable’ column. This is an example of a “long” data format. The long format is versatile and desirable for data manipulation, but we may want to convert to the “wide” data format in some cases, particularly for presenting data.</p>

<p>To perform this conversion, we can use the <a href="https://tidyr.tidyverse.org/reference/pivot_wider.html">pivot_wider</a> function from <a href="https://tidyr.tidyverse.org/">tidyr</a>. The end result is that the rent and income variables are put into separate columns. This function has two arguments you will need to set:</p>

<ul>
  <li><strong>names_from</strong>: name of the column which contains values that will become our new column names.</li>
  <li><strong>values_from</strong>: name of the column which contains the values that will populate our new columns.</li>
</ul>

<p>Additionally we use the select function to drop two columns, <a href="https://tidyr.tidyverse.org/reference/drop_na.html">drop_na</a> to remove rows with missing values, and mutate to create an income to rent ratio.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">col_ratio</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">us_rent_income</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">select</span><span class="p">(</span><span class="o">-</span><span class="n">GEOID</span><span class="p">,</span><span class="w"> </span><span class="o">-</span><span class="n">moe</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">pivot_wider</span><span class="p">(</span><span class="n">names_from</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">variable</span><span class="p">,</span><span class="w"> </span><span class="n">values_from</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">estimate</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">drop_na</span><span class="p">()</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">mutate</span><span class="p">(</span><span class="n">income_rent_ratio</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">income</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="p">(</span><span class="m">12</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">rent</span><span class="p">))</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">NAME</th>
      <th style="text-align: right">income</th>
      <th style="text-align: right">rent</th>
      <th style="text-align: right">income_rent_ratio</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">Alabama</td>
      <td style="text-align: right">24476</td>
      <td style="text-align: right">747</td>
      <td style="text-align: right">2.730478</td>
    </tr>
    <tr>
      <td style="text-align: left">Alaska</td>
      <td style="text-align: right">32940</td>
      <td style="text-align: right">1200</td>
      <td style="text-align: right">2.287500</td>
    </tr>
    <tr>
      <td style="text-align: left">Arizona</td>
      <td style="text-align: right">27517</td>
      <td style="text-align: right">972</td>
      <td style="text-align: right">2.359139</td>
    </tr>
  </tbody>
</table>

<h2 id="converting-wide-to-long-format">Converting Wide to Long Format</h2>

<p>Now let’s look at the <a href="https://tidyr.tidyverse.org/reference/world_bank_pop.html">world_bank_pop</a> dataset from tidyr (only the first 6 columns are shown for display purposes):</p>

<table>
  <thead>
    <tr>
      <th style="text-align: left">country</th>
      <th style="text-align: left">indicator</th>
      <th style="text-align: right">2000</th>
      <th style="text-align: right">2001</th>
      <th style="text-align: right">2002</th>
      <th style="text-align: right">2003</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">ABW</td>
      <td style="text-align: left">SP.URB.TOTL</td>
      <td style="text-align: right">42444.000000</td>
      <td style="text-align: right">43048.000000</td>
      <td style="text-align: right">43670.000000</td>
      <td style="text-align: right">44246.00000</td>
    </tr>
    <tr>
      <td style="text-align: left">ABW</td>
      <td style="text-align: left">SP.URB.GROW</td>
      <td style="text-align: right">1.182632</td>
      <td style="text-align: right">1.413021</td>
      <td style="text-align: right">1.434559</td>
      <td style="text-align: right">1.31036</td>
    </tr>
    <tr>
      <td style="text-align: left">ABW</td>
      <td style="text-align: left">SP.POP.TOTL</td>
      <td style="text-align: right">90853.000000</td>
      <td style="text-align: right">92898.000000</td>
      <td style="text-align: right">94992.000000</td>
      <td style="text-align: right">97017.00000</td>
    </tr>
  </tbody>
</table>

<p>This dataset is in “wide” format since a categorical variable, in this case the year, is stored in the column names. To convert this dataset to the “long” format”, which can be more convenient for data manipulation, we use the <a href="https://tidyr.tidyverse.org/reference/pivot_longer.html">pivot_longer</a> function from tidyr. This function takes three inputs:</p>

<ul>
  <li><strong>cols</strong> (1st argument): a list of the columns we want to pivot. In this example we create this list by subtracting the columns we don’t want to pivot.</li>
  <li><strong>names_to</strong> : the name of new column which will have the current column names as values.</li>
  <li><strong>values_to</strong> : name of the new column which will contain values.</li>
</ul>

<p>We also use the ‘mutate’ and ‘as.numeric’ functions to convert our new ‘year’ variable to numeric and then filter so that our output dataset only includes certain years using the ‘seq’ function. The <a href="https://dplyr.tidyverse.org/reference/across.html">across</a> function is used to apply the ‘as.numeric’ function to the ‘year’ column. The format for the ‘seq’ function is seq(start, stop, increment).</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">wb_pop</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">world_bank_pop</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">pivot_longer</span><span class="p">(</span><span class="nf">c</span><span class="p">(</span><span class="o">-</span><span class="n">country</span><span class="p">,</span><span class="w"> </span><span class="o">-</span><span class="n">indicator</span><span class="p">),</span><span class="w"> </span><span class="n">names_to</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"year"</span><span class="p">,</span><span class="w"> </span><span class="n">values_to</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"value"</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">mutate</span><span class="p">(</span><span class="n">across</span><span class="p">(</span><span class="n">year</span><span class="p">,</span><span class="w"> </span><span class="n">as.numeric</span><span class="p">))</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> </span><span class="c1"># convert to numeric</span><span class="w">
  </span><span class="n">filter</span><span class="p">(</span><span class="n">year</span><span class="w"> </span><span class="o">%in%</span><span class="w"> </span><span class="n">seq</span><span class="p">(</span><span class="m">2000</span><span class="p">,</span><span class="w"> </span><span class="m">2016</span><span class="p">,</span><span class="w"> </span><span class="m">2</span><span class="p">))</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: left">country</th>
      <th style="text-align: left">indicator</th>
      <th style="text-align: right">year</th>
      <th style="text-align: right">value</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">ABW</td>
      <td style="text-align: left">SP.URB.TOTL</td>
      <td style="text-align: right">2000</td>
      <td style="text-align: right">42444</td>
    </tr>
    <tr>
      <td style="text-align: left">ABW</td>
      <td style="text-align: left">SP.URB.TOTL</td>
      <td style="text-align: right">2002</td>
      <td style="text-align: right">43670</td>
    </tr>
    <tr>
      <td style="text-align: left">ABW</td>
      <td style="text-align: left">SP.URB.TOTL</td>
      <td style="text-align: right">2004</td>
      <td style="text-align: right">44669</td>
    </tr>
  </tbody>
</table>

<h2 id="visualizations">Visualizations</h2>

<p>Now that we have manipulated and summarized some datasets, we’ll make a few visualizations with <a href="https://ggplot2.tidyverse.org/">ggplot2</a>. Ggplot graphs are constructed by adding together a series of ggplot functions with the “+” operator. This gives us a large amount of customization options since ggplot functions can be combined in many different ways.</p>

<p>Below you will find code for several commonly used charts, but you can refer to <a href="https://ggplot2.tidyverse.org/reference/">ggplot’s documentation</a> for more information. Here is a brief overview of the package:</p>

<ul>
  <li>The <a href="https://ggplot2.tidyverse.org/reference/ggplot.html">ggplot</a> function initializes a graph and typically specifies the dataset that is being used.</li>
  <li>Atleast one <a href="https://ggplot2.tidyverse.org/reference/#section-layer-geoms">geom (geometric object) function</a> such as geom_histogram, geom_point, or geom_line is included which controls how data will be displayed.</li>
  <li>The <a href="https://ggplot2.tidyverse.org/reference/aes.html">aes</a> (aesthetic mappings) function controls which variables are used in the plot. This function can be included as part of the ggplot function or in a geom function depending on whether you want the effect to be global or specific to a geom function.</li>
  <li>The formatting of the chart (such as margins, legend position, and grid lines) can be modified using <a href="https://ggplot2.tidyverse.org/reference/ggtheme.html">preset themes such as theme_bw and theme_classic</a> or the <a href="https://ggplot2.tidyverse.org/reference/theme.html">theme function</a> which gives more manual control.</li>
  <li>The ‘color’ parameter is used for setting the color of plot lines and points while the ‘fill’ parameter controls the color of areas (such as bars on bar charts). These parameters can be set to a value such as ‘navy’ or to a categorical variable. You can read more about this on ggplot’s site <a href="https://ggplot2.tidyverse.org/reference/aes_colour_fill_alpha.html">here</a>.</li>
  <li>To save a plot to a file use the <a href="https://ggplot2.tidyverse.org/reference/ggsave.html">ggsave</a> function.</li>
</ul>

<h3 id="scatter-plots">Scatter Plots</h3>

<p>Scatter plots are used to visually examine the relationship between two continuous variables and can be created using <a href="https://ggplot2.tidyverse.org/reference/geom_point.html">geom_point</a>. In this example, we plot engine displacement against highway MPG for the ‘mpg’ dataset. A ‘Transmission’ column is created to combine the various transmission types in the ‘trans’ variable into the ‘auto’ (automatic) and ‘manual’ categories using the <a href="https://stringr.tidyverse.org/reference/str_detect.html">str_detect</a> function.</p>

<p>The ‘color’ argument in the ‘aes’ function is used to color our points according to the newly created ‘Transmission’ variable. A legend is automatically created and we’ve positioned it at the top of our graph.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ggplot</span><span class="p">(</span><span class="w">
  </span><span class="n">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">mpg</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
    </span><span class="n">mutate</span><span class="p">(</span><span class="n">Transmission</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">case_when</span><span class="p">(</span><span class="n">str_detect</span><span class="p">(</span><span class="n">trans</span><span class="p">,</span><span class="w"> </span><span class="s2">"auto"</span><span class="p">)</span><span class="w"> </span><span class="o">~</span><span class="w"> </span><span class="s2">"auto"</span><span class="p">,</span><span class="w"> </span><span class="kc">TRUE</span><span class="w"> </span><span class="o">~</span><span class="w"> </span><span class="s2">"manual"</span><span class="p">)),</span><span class="w">
  </span><span class="n">aes</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">displ</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">hwy</span><span class="p">,</span><span class="w"> </span><span class="n">color</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Transmission</span><span class="p">)</span><span class="w">
</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_point</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme_light</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme</span><span class="p">(</span><span class="w">
    </span><span class="n">legend.position</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"top"</span><span class="p">,</span><span class="w">
    </span><span class="n">legend.text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_text</span><span class="p">(</span><span class="n">size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">11</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">xlab</span><span class="p">(</span><span class="s2">"Displacement (L)"</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">ylab</span><span class="p">(</span><span class="s2">"Highway MPG"</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p><img src="/rmd_images/2020-1-12-data-science-essentials/scatter-1.png" alt="" /><!-- --></p>

<h3 id="line-charts">Line Charts</h3>

<p>Here we create a line graph with the SP.POP.GROW indicator from the ‘wb_pop’ dataset we created earlier based on world bank data. SP.POP.GROW is the percent population growth of a country and we divide its value (which is in the ‘value’ column) by 100 to convert it to a decimal percentage value.</p>

<p>In this example, both lines and points are displayed for our data because we have used both the <a href="https://ggplot2.tidyverse.org/reference/geom_point.html">geom_point</a> and <a href="https://ggplot2.tidyverse.org/reference/geom_path.html">geom_line</a> functions. The <a href="https://ggplot2.tidyverse.org/reference/expansion.html">expansion</a> function is used to control the margins in the x axis. We’ve also formatted the y axis as a percentage using the ‘labels’ argument in <a href="https://ggplot2.tidyverse.org/reference/scale_continuous.html">scale_y_continuous</a>.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ggplot</span><span class="p">(</span><span class="w">
  </span><span class="n">wb_pop</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> </span><span class="n">filter</span><span class="p">(</span><span class="n">country</span><span class="w"> </span><span class="o">%in%</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="s2">"USA"</span><span class="p">,</span><span class="w"> </span><span class="s2">"CAN"</span><span class="p">,</span><span class="w"> </span><span class="s2">"MEX"</span><span class="p">)</span><span class="w"> </span><span class="o">&amp;</span><span class="w"> </span><span class="n">indicator</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s2">"SP.POP.GROW"</span><span class="p">),</span><span class="w">
  </span><span class="n">aes</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">year</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">value</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="m">100</span><span class="p">,</span><span class="w"> </span><span class="n">color</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">country</span><span class="p">)</span><span class="w">
</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme_minimal</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_line</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_point</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="c1"># lines and points</span><span class="w">
  </span><span class="n">scale_x_continuous</span><span class="p">(</span><span class="n">expand</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">expansion</span><span class="p">(</span><span class="n">mult</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="m">.05</span><span class="p">,</span><span class="w"> </span><span class="m">.05</span><span class="p">)))</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">scale_y_continuous</span><span class="p">(</span><span class="n">labels</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">scales</span><span class="o">::</span><span class="n">percent</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme</span><span class="p">(</span><span class="w">
    </span><span class="n">legend.title</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_blank</span><span class="p">(),</span><span class="w"> </span><span class="c1"># suppress legend title</span><span class="w">
    </span><span class="n">panel.grid.minor.x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_blank</span><span class="p">(),</span><span class="w">
    </span><span class="n">legend.text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_text</span><span class="p">(</span><span class="n">size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">11</span><span class="p">),</span><span class="w">
    </span><span class="n">legend.position</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"right"</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">xlab</span><span class="p">(</span><span class="s2">"Year"</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">ylab</span><span class="p">(</span><span class="s2">"Population Growth"</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p><img src="/rmd_images/2020-1-12-data-science-essentials/linechart-1.png" alt="" /><!-- --></p>

<h3 id="histograms">Histograms</h3>

<p>Histograms display distributions of variables. We use a histogram to look at the distribution of highway MPG below. You may want to experiment with the ‘binwidth’ argument in the <a href="https://ggplot2.tidyverse.org/reference/geom_histogram.html">geom_histogram</a> function to see how it effects what your histogram looks like. The <a href="https://ggplot2.tidyverse.org/reference/expansion.html">expansion</a> function is used to control the margins in the y axis.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ggplot</span><span class="p">(</span><span class="n">mpg</span><span class="p">,</span><span class="w"> </span><span class="n">aes</span><span class="p">(</span><span class="n">hwy</span><span class="p">))</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_histogram</span><span class="p">(</span><span class="n">binwidth</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme_bw</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">scale_y_continuous</span><span class="p">(</span><span class="n">expand</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">expansion</span><span class="p">(</span><span class="n">mult</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="m">0</span><span class="p">,</span><span class="w"> </span><span class="m">.05</span><span class="p">)))</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">xlab</span><span class="p">(</span><span class="s2">"Highway MPG"</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">ylab</span><span class="p">(</span><span class="s2">"Vehicles"</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p><img src="/rmd_images/2020-1-12-data-science-essentials/histogram-1.png" alt="" /><!-- --></p>

<h3 id="bar-charts">Bar Charts</h3>

<p>Bar charts are commonly used to show relative size and can be created with <a href="https://ggplot2.tidyverse.org/reference/geom_bar.html">geom_bar</a>. I find it helpful to order the bars by their size which I’ve done with the reorder function below. The <a href="https://ggplot2.tidyverse.org/reference/geom_text.html">geom_text</a> function is used to add the labels to the top of the bars.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ggplot</span><span class="p">(</span><span class="w">
  </span><span class="n">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">mpg_stats</span><span class="p">,</span><span class="w">
  </span><span class="n">aes</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">reorder</span><span class="p">(</span><span class="n">class_c</span><span class="p">,</span><span class="w"> </span><span class="o">-</span><span class="n">mean_hwy</span><span class="p">),</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">mean_hwy</span><span class="p">)</span><span class="w">
</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_bar</span><span class="p">(</span><span class="n">stat</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"identity"</span><span class="p">,</span><span class="w"> </span><span class="n">color</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"black"</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">scale_y_continuous</span><span class="p">(</span><span class="n">expand</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">expansion</span><span class="p">(</span><span class="n">mult</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="m">0</span><span class="p">,</span><span class="w"> </span><span class="m">.1</span><span class="p">)))</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="c1"># expand top margin</span><span class="w">
  </span><span class="n">geom_text</span><span class="p">(</span><span class="n">aes</span><span class="p">(</span><span class="n">label</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">round</span><span class="p">(</span><span class="n">mean_hwy</span><span class="p">)),</span><span class="w"> </span><span class="n">vjust</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">-0.5</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="c1"># label bars</span><span class="w">
  </span><span class="n">theme_bw</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">xlab</span><span class="p">(</span><span class="s2">"Vehicle Class"</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">ylab</span><span class="p">(</span><span class="s2">"Mean Highway MPG"</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="c1"># no axis labels</span><span class="w">
  </span><span class="n">theme</span><span class="p">(</span><span class="n">panel.grid</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_blank</span><span class="p">())</span><span class="w"> </span><span class="c1"># turn off grid</span><span class="w">
</span></code></pre></div></div>

<p><img src="/rmd_images/2020-1-12-data-science-essentials/bar-1.png" alt="" /><!-- --></p>

<h3 id="lollipop-charts">Lollipop Charts</h3>

<p><a href="https://www.data-to-viz.com/graph/lollipop.html">Lollipop charts</a> can be an attractive alternative to bar charts. We construct one here using <a href="https://ggplot2.tidyverse.org/reference/geom_segment.html">geom_segment</a> and <a href="https://ggplot2.tidyverse.org/reference/geom_point.html">geom_point</a>. The <a href="https://ggplot2.tidyverse.org/reference/coord_flip.html">coord_flip</a> function is used to orient the chart horizontally instead of vertically. We use the theme function to hide all grid lines except for the major vertical lines. The reorder function is again used to order the axis (in this case by rent in descending order).</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">ggplot</span><span class="p">(</span><span class="n">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">col_ratio</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> </span><span class="n">arrange</span><span class="p">(</span><span class="n">desc</span><span class="p">(</span><span class="n">rent</span><span class="p">))</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> </span><span class="n">head</span><span class="p">(</span><span class="m">15</span><span class="p">),</span><span class="w"> </span><span class="n">aes</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">NAME</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">rent</span><span class="p">))</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_segment</span><span class="p">(</span><span class="n">aes</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">reorder</span><span class="p">(</span><span class="n">NAME</span><span class="p">,</span><span class="w"> </span><span class="n">rent</span><span class="p">),</span><span class="w"> </span><span class="n">xend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">NAME</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">0</span><span class="p">,</span><span class="w"> </span><span class="n">yend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">rent</span><span class="p">),</span><span class="w"> </span><span class="n">color</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"grey"</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_point</span><span class="p">(</span><span class="n">size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">3</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme_minimal</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme</span><span class="p">(</span><span class="w">
    </span><span class="n">plot.subtitle</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_text</span><span class="p">(</span><span class="n">face</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"bold"</span><span class="p">,</span><span class="w"> </span><span class="n">hjust</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">0.5</span><span class="p">),</span><span class="w">
    </span><span class="n">plot.title</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_text</span><span class="p">(</span><span class="n">lineheight</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span><span class="p">,</span><span class="w"> </span><span class="n">face</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"bold"</span><span class="p">,</span><span class="w"> </span><span class="n">hjust</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">0.5</span><span class="p">),</span><span class="w">
    </span><span class="n">panel.grid.minor.y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_blank</span><span class="p">(),</span><span class="w">
    </span><span class="n">panel.grid.major.y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_blank</span><span class="p">(),</span><span class="w">
    </span><span class="n">panel.grid.minor.x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_blank</span><span class="p">()</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">coord_flip</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">scale_y_continuous</span><span class="p">(</span><span class="n">labels</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">scales</span><span class="o">::</span><span class="n">dollar</span><span class="p">,</span><span class="w"> </span><span class="n">expand</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">expansion</span><span class="p">(</span><span class="n">mult</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="m">0</span><span class="p">,</span><span class="w"> </span><span class="m">.1</span><span class="p">)))</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">labs</span><span class="p">(</span><span class="w">
    </span><span class="n">title</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"US States with the Highest Rent"</span><span class="p">,</span><span class="w">
    </span><span class="n">caption</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"Source: 2017 American Community Survey (Census)"</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">xlab</span><span class="p">(</span><span class="s2">""</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">ylab</span><span class="p">(</span><span class="s2">"Median Monthly Rent"</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p><img src="/rmd_images/2020-1-12-data-science-essentials/lollipop-1.png" alt="" /><!-- --></p>

<h2 id="additional-references">Additional References</h2>

<p>Here are some additional resources that you may find useful:</p>

<ul>
  <li>For importing data from files, refer to the <a href="https://readr.tidyverse.org/">readr</a> (for CSV and text files) or <a href="https://readxl.tidyverse.org/">readxl</a> (for excel spreadsheets) packages.</li>
  <li>To coerce a column in a dataset into a different format, you can use the as.numeric, as.character, as.Date, and as.factor functions (from base R). For more functions to work with date and datetime data see the <a href="https://lubridate.tidyverse.org/reference/index.html">lubridate</a> package, for strings reference the <a href="https://stringr.tidyverse.org/">stringr</a> package, and for manipulating factors you can use the <a href="https://forcats.tidyverse.org/">forcats</a> package.</li>
  <li>For quickly summarizing datasets with basic summary statistics, you can use the summary function (base R) or the <a href="https://docs.ropensci.org/skimr/">skimr</a> package.</li>
  <li>The <a href="https://purrr.tidyverse.org/">purrr</a> package allows you apply functions across the values of a list using the <a href="https://purrr.tidyverse.org/reference/map.html">map</a> function. One example of where this is useful is in reading and combining data from multiple sheets in an excel spreadsheet by applying a function that reads a single sheet to a list of sheets.</li>
  <li>I keep reference data science code (both R and Python) in <a href="https://github.com/jessecambon/Data-Science-Codex">a GitHub repository</a>. You’ll find some more advanced techniques like modeling demonstrated there.</li>
</ul>

<p><em><sub> March 26 2021: this post has been updated to reflect changes in ggplot and dplyr syntax.</sub></em></p>]]></content><author><name>Jesse Cambon</name></author><category term="r" /><summary type="html"><![CDATA[One the greatest strengths of R for data science work is the vast number and variety of packages and capabilities that are available. However, it can be intimidating to navigate this large and dynamic open source ecosystem, especially for a newcomer. All the information you need is out there, but it is often fragmented across numerous stack overflow threads and websites.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="https://jessecambon.github.io/rmd_images/2020-1-12-data-science-essentials/linechart-1.png" /><media:content medium="image" url="https://jessecambon.github.io/rmd_images/2020-1-12-data-science-essentials/linechart-1.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry><entry><title type="html">Practical Tidy Evaluation</title><link href="https://jessecambon.github.io/2019/12/08/practical-tidy-evaluation.html" rel="alternate" type="text/html" title="Practical Tidy Evaluation" /><published>2019-12-08T00:00:00+00:00</published><updated>2019-12-08T00:00:00+00:00</updated><id>https://jessecambon.github.io/2019/12/08/practical-tidy-evaluation</id><content type="html" xml:base="https://jessecambon.github.io/2019/12/08/practical-tidy-evaluation.html"><![CDATA[<p>Tidy evaluation is a framework for controlling how expressions and variables in your code are evaluated by <a href="https://www.tidyverse.org/">tidyverse</a> functions. This framework, housed in the <a href="https://rlang.r-lib.org">rlang package</a>, is a powerful tool for writing more efficient and elegant code. In particular, you’ll find it useful for passing variable names as inputs to functions that use tidyverse packages like <a href="https://dplyr.tidyverse.org/">dplyr</a> and <a href="https://ggplot2.tidyverse.org/">ggplot2</a>.</p>

<p>The goal of this post is to offer accessible examples and intuition for putting tidy evaluation to work in your own code. Because of this I will keep conceptual explanations brief, but for more comprehensive documentation you can refer to <a href="https://dplyr.tidyverse.org/reference/tidyeval.html">dplyr’s website</a>, <a href="https://rlang.r-lib.org/">rlang’s website</a>, the <a href="https://tidyeval.tidyverse.org/">‘Tidy Evaluation’ book</a> by Lionel Henry and Hadley Wickham, and the <a href="https://adv-r.hadley.nz/metaprogramming.html">Metaprogramming Section of the ‘Advanced R’ book</a> by Hadley Wickham.</p>

<h3 id="motivating-example">Motivating Example</h3>

<p>To begin, let’s consider a simple example of calculating summary statistics with the <a href="https://stat.ethz.ch/R-manual/R-devel/library/datasets/html/mtcars.html">mtcars dataset</a>. Below we calculate maximum and minimum horsepower (hp) by the number of cylinders (cyl) using the <a href="https://dplyr.tidyverse.org/reference/group_by.html">group_by</a> and <a href="https://dplyr.tidyverse.org/reference/summarise.html">summarize</a> functions from <a href="https://dplyr.tidyverse.org/">dplyr</a>.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">dplyr</span><span class="p">)</span><span class="w">
</span><span class="n">hp_by_cyl</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mtcars</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">group_by</span><span class="p">(</span><span class="n">cyl</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">summarize</span><span class="p">(</span><span class="w">
    </span><span class="n">min_hp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">min</span><span class="p">(</span><span class="n">hp</span><span class="p">),</span><span class="w">
    </span><span class="n">max_hp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">max</span><span class="p">(</span><span class="n">hp</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: right">cyl</th>
      <th style="text-align: right">min_hp</th>
      <th style="text-align: right">max_hp</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: right">4</td>
      <td style="text-align: right">52</td>
      <td style="text-align: right">113</td>
    </tr>
    <tr>
      <td style="text-align: right">6</td>
      <td style="text-align: right">105</td>
      <td style="text-align: right">175</td>
    </tr>
    <tr>
      <td style="text-align: right">8</td>
      <td style="text-align: right">150</td>
      <td style="text-align: right">335</td>
    </tr>
  </tbody>
</table>

<p>Now let’s say we wanted to repeat this calculation multiple times <em>while changing which variable we group by</em>. A brute force method to accomplish this would be to copy and paste our code as many times as necessary and modify the group by variable in each iteration. However, this is inefficient especially if our code gets more complicated, requires many iterations, or requires further development.</p>

<p>To avoid this inelegant solution you might think to store the name of a variable inside of another variable like this <code class="language-plaintext highlighter-rouge">groupby_var &lt;- "vs"</code>. Then you could attempt to use your newly created “groupby_var” variable in your code: <code class="language-plaintext highlighter-rouge">group_by(groupby_var)</code>. However, if you try this you will find it doesn’t work. The “group_by” function expects the name of the variable you want to group by as an input, not the name of a variable that <em>contains</em> the name of the variable you want to group by.</p>

<p>This is the kind of headache that tidy evaluation can help you solve. In the example below we use the <a href="https://rlang.r-lib.org/reference/quotation.html">quo</a> function and the “bang-bang” <a href="https://rlang.r-lib.org/reference/nse-force.html">!!</a> operator to set “vs” (engine type, 0 = automatic, 1 = manual) as our group by variable. The “quo” function allows us to store the variable name in our “groupby_var” variable and “!!” extracts the stored variable name.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">groupby_var</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">quo</span><span class="p">(</span><span class="n">vs</span><span class="p">)</span><span class="w">

</span><span class="n">hp_by_vs</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mtcars</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">group_by</span><span class="p">(</span><span class="o">!!</span><span class="n">groupby_var</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">summarize</span><span class="p">(</span><span class="w">
    </span><span class="n">min_hp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">min</span><span class="p">(</span><span class="n">hp</span><span class="p">),</span><span class="w">
    </span><span class="n">max_hp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">max</span><span class="p">(</span><span class="n">hp</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: right">vs</th>
      <th style="text-align: right">min_hp</th>
      <th style="text-align: right">max_hp</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: right">0</td>
      <td style="text-align: right">91</td>
      <td style="text-align: right">335</td>
    </tr>
    <tr>
      <td style="text-align: right">1</td>
      <td style="text-align: right">52</td>
      <td style="text-align: right">123</td>
    </tr>
  </tbody>
</table>

<p>The code above provides a method for setting the group by variable by modifying the input to the “quo” function when we define “groupby_var”. This can be useful, particularly if we intend to reference the group by variable multiple times. However, if we want to use code like this repeatedly in a script then we should consider packaging it into a function. This is what we will do next.</p>

<h3 id="making-functions-with-tidy-evaluation">Making Functions with Tidy Evaluation</h3>

<p>To use tidy evaluation in a function, we will still use the “!!” operator as we did above, but instead of “quo” we will use the <a href="https://rlang.r-lib.org/reference/nse-defuse.html">enquo</a> function. Our new function below takes the group by variable and the measurement variable as inputs so that we can now calculate maximum and minimum values of any variable we want. Also note two new features I have introduced in this function:</p>

<ul>
  <li>The <a href="https://rlang.r-lib.org/reference/as_label.html">as_label</a> function extracts the string value of the “measure_var” variable (“hp” in this case). We use this to set the value of the “measure_var” column.</li>
  <li>The “walrus operator” <a href="https://rlang.r-lib.org/reference/quasiquotation.html#forcing-names">:=</a> is used to create a column named after the variable name stored in the “measure_var” argument (“hp” in the example). The walrus operator allows you to use strings and evaluated variables (such as “measure_var” in our example) on the left hand side of an assignment operation (where there would normally be a “=” operator) in functions such as “mutate” and “summarize”.</li>
</ul>

<p>Below we define our function and use it to group by “am” (transmission type, 0 = automatic, 1 = manual) and calculate summary statistics with the “hp” (horsepower) variable.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">car_stats</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="k">function</span><span class="p">(</span><span class="n">groupby_var</span><span class="p">,</span><span class="w"> </span><span class="n">measure_var</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">groupby_var</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">enquo</span><span class="p">(</span><span class="n">groupby_var</span><span class="p">)</span><span class="w">
  </span><span class="n">measure_var</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">enquo</span><span class="p">(</span><span class="n">measure_var</span><span class="p">)</span><span class="w">
  </span><span class="nf">return</span><span class="p">(</span><span class="n">mtcars</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
    </span><span class="n">group_by</span><span class="p">(</span><span class="o">!!</span><span class="n">groupby_var</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
    </span><span class="n">summarize</span><span class="p">(</span><span class="w">
      </span><span class="n">min</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">min</span><span class="p">(</span><span class="o">!!</span><span class="n">measure_var</span><span class="p">),</span><span class="w">
      </span><span class="n">max</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nf">max</span><span class="p">(</span><span class="o">!!</span><span class="n">measure_var</span><span class="p">)</span><span class="w">
    </span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
    </span><span class="n">mutate</span><span class="p">(</span><span class="w">
      </span><span class="n">measure_var</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">as_label</span><span class="p">(</span><span class="n">measure_var</span><span class="p">),</span><span class="w">
      </span><span class="o">!!</span><span class="n">measure_var</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="kc">NA</span><span class="w">
    </span><span class="p">))</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="n">hp_by_am</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">car_stats</span><span class="p">(</span><span class="n">am</span><span class="p">,</span><span class="w"> </span><span class="n">hp</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: right">am</th>
      <th style="text-align: right">min</th>
      <th style="text-align: right">max</th>
      <th style="text-align: left">measure_var</th>
      <th style="text-align: left">hp</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: right">0</td>
      <td style="text-align: right">62</td>
      <td style="text-align: right">245</td>
      <td style="text-align: left">hp</td>
      <td style="text-align: left">NA</td>
    </tr>
    <tr>
      <td style="text-align: right">1</td>
      <td style="text-align: right">52</td>
      <td style="text-align: right">335</td>
      <td style="text-align: left">hp</td>
      <td style="text-align: left">NA</td>
    </tr>
  </tbody>
</table>

<p>We now have a flexible function that contains a dplyr workflow. You can experiment with modifying this function for your own purposes. Additionally, as you might suspect, you could use the same tidy evaluation functions we just used with tidyverse packages other than dplyr.</p>

<p>As an example, below I’ve defined a function that builds a scatter plot with <a href="https://ggplot2.tidyverse.org/">ggplot2</a>. The function takes a dataset and two variable names as inputs. You will notice that the dataset argument “df” needs no tidy evaluation. The <a href="https://rlang.r-lib.org/reference/as_label.html">as_label</a> function is used to extract our variable names as strings to create a plot title with the “ggtitle” function.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">ggplot2</span><span class="p">)</span><span class="w">
</span><span class="n">scatter_plot</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="k">function</span><span class="p">(</span><span class="n">df</span><span class="p">,</span><span class="w"> </span><span class="n">x_var</span><span class="p">,</span><span class="w"> </span><span class="n">y_var</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">x_var</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">enquo</span><span class="p">(</span><span class="n">x_var</span><span class="p">)</span><span class="w">
  </span><span class="n">y_var</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">enquo</span><span class="p">(</span><span class="n">y_var</span><span class="p">)</span><span class="w">

  </span><span class="nf">return</span><span class="p">(</span><span class="n">ggplot</span><span class="p">(</span><span class="n">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">df</span><span class="p">,</span><span class="w"> </span><span class="n">aes</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">!!</span><span class="n">x_var</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">!!</span><span class="n">y_var</span><span class="p">))</span><span class="w"> </span><span class="o">+</span><span class="w">
    </span><span class="n">geom_point</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
    </span><span class="n">theme_bw</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
    </span><span class="n">theme</span><span class="p">(</span><span class="n">plot.title</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_text</span><span class="p">(</span><span class="n">lineheight</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span><span class="p">,</span><span class="w"> </span><span class="n">face</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"bold"</span><span class="p">,</span><span class="w"> </span><span class="n">hjust</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">0.5</span><span class="p">))</span><span class="w"> </span><span class="o">+</span><span class="w">
    </span><span class="n">geom_smooth</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
    </span><span class="n">ggtitle</span><span class="p">(</span><span class="n">str_c</span><span class="p">(</span><span class="n">as_label</span><span class="p">(</span><span class="n">y_var</span><span class="p">),</span><span class="w"> </span><span class="s2">" vs. "</span><span class="p">,</span><span class="w"> </span><span class="n">as_label</span><span class="p">(</span><span class="n">x_var</span><span class="p">))))</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="n">scatter_plot</span><span class="p">(</span><span class="n">mtcars</span><span class="p">,</span><span class="w"> </span><span class="n">disp</span><span class="p">,</span><span class="w"> </span><span class="n">hp</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p><img src="/rmd_images/2019-12-8-practical-tidy-evaluation/unnamed-chunk-7-1.png" alt="" /><!-- --></p>

<p>As you can see, we’ve plotted the “hp” (horsepower) variable against “disp” (displacement) and added a regression line. Now, instead of copying and pasting ggplot code to create the same plot with different datasets and variables, we can just call our function.</p>

<h3 id="the-curly-curly-shortcut-and-passing-multiple-variables">The “Curly-Curly” Shortcut and Passing Multiple Variables</h3>

<p>To wrap things up, I’ll cover a few additional tricks and shortcuts for your tidy evaluation toolbox.</p>

<ul>
  <li>The “curly-curly” <a href="https://www.tidyverse.org/blog/2019/06/rlang-0-4-0/">{{ }}</a> operator directly extracts a stored variable name from “measure_var” in the example below. In the prior example we needed both “enquo” and “!!” to evaluate a variable like this so the “curly-curly” operator is a convenient shortcut. However, note that if you want to extract the string variable name with the “as_label” function, you will still need to use “enquo” and “!!” as we have done below with “measure_name”.</li>
  <li>The <a href="https://rlang.r-lib.org/reference/sym.html">syms</a> function and the “!!!” operator are used for passing a list of variables as a function argument. In prior examples “!!” was used to evaluate a single group by variable; we now use “!!!” to evaluate a list of group by variables. One quirk is that to use the “syms” function we will need to pass the variable names in quotes.</li>
  <li>The walrus operator “:=” is again used to create new columns, but now the column names are defined with a combination of a variable name stored in a function argument and another string (“_min” and “_max” below). We use the “enquo” and “as_label” functions to extract the string variable name from “measure_var” and store it in “measure_name” and then use the “str_c” function from <a href="https://stringr.tidyverse.org/">stringr</a> to combine strings. You can use similar code to build your own column names from variable name inputs and strings.</li>
</ul>

<p>Our new function is defined below and is first called to group by the “cyl” variable and then called to group by the “am” and “vs” variables. Note that the “!!!” operator and “syms” function can be used with either a list of strings or a single string.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">get_stats</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="k">function</span><span class="p">(</span><span class="n">data</span><span class="p">,</span><span class="w"> </span><span class="n">groupby_vars</span><span class="p">,</span><span class="w"> </span><span class="n">measure_var</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w">
  </span><span class="n">groupby_vars</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">syms</span><span class="p">(</span><span class="n">groupby_vars</span><span class="p">)</span><span class="w">
  </span><span class="n">measure_name</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">as_label</span><span class="p">(</span><span class="n">enquo</span><span class="p">(</span><span class="n">measure_var</span><span class="p">))</span><span class="w">
  </span><span class="nf">return</span><span class="p">(</span><span class="w">
    </span><span class="n">data</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> </span><span class="n">group_by</span><span class="p">(</span><span class="o">!!!</span><span class="n">groupby_vars</span><span class="p">)</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
      </span><span class="n">summarize</span><span class="p">(</span><span class="w">
        </span><span class="o">!!</span><span class="n">str_c</span><span class="p">(</span><span class="n">measure_name</span><span class="p">,</span><span class="w"> </span><span class="s2">"_min"</span><span class="p">)</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nf">min</span><span class="p">({{</span><span class="w"> </span><span class="n">measure_var</span><span class="w"> </span><span class="p">}}),</span><span class="w">
        </span><span class="o">!!</span><span class="n">str_c</span><span class="p">(</span><span class="n">measure_name</span><span class="p">,</span><span class="w"> </span><span class="s2">"_max"</span><span class="p">)</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nf">max</span><span class="p">({{</span><span class="w"> </span><span class="n">measure_var</span><span class="w"> </span><span class="p">}})</span><span class="w">
      </span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="n">cyl_hp_stats</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mtcars</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> </span><span class="n">get_stats</span><span class="p">(</span><span class="s2">"cyl"</span><span class="p">,</span><span class="w"> </span><span class="n">mpg</span><span class="p">)</span><span class="w">
</span><span class="n">gear_stats</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">mtcars</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w"> </span><span class="n">get_stats</span><span class="p">(</span><span class="nf">c</span><span class="p">(</span><span class="s2">"am"</span><span class="p">,</span><span class="w"> </span><span class="s2">"vs"</span><span class="p">),</span><span class="w"> </span><span class="n">gear</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>## `summarise()` has grouped output by 'am'. You can override using the `.groups` argument.
</code></pre></div></div>

<table>
  <thead>
    <tr>
      <th style="text-align: right">cyl</th>
      <th style="text-align: right">mpg_min</th>
      <th style="text-align: right">mpg_max</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: right">4</td>
      <td style="text-align: right">21.4</td>
      <td style="text-align: right">33.9</td>
    </tr>
    <tr>
      <td style="text-align: right">6</td>
      <td style="text-align: right">17.8</td>
      <td style="text-align: right">21.4</td>
    </tr>
    <tr>
      <td style="text-align: right">8</td>
      <td style="text-align: right">10.4</td>
      <td style="text-align: right">19.2</td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th style="text-align: right">am</th>
      <th style="text-align: right">vs</th>
      <th style="text-align: right">gear_min</th>
      <th style="text-align: right">gear_max</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: right">0</td>
      <td style="text-align: right">0</td>
      <td style="text-align: right">3</td>
      <td style="text-align: right">3</td>
    </tr>
    <tr>
      <td style="text-align: right">0</td>
      <td style="text-align: right">1</td>
      <td style="text-align: right">3</td>
      <td style="text-align: right">4</td>
    </tr>
    <tr>
      <td style="text-align: right">1</td>
      <td style="text-align: right">0</td>
      <td style="text-align: right">4</td>
      <td style="text-align: right">5</td>
    </tr>
    <tr>
      <td style="text-align: right">1</td>
      <td style="text-align: right">1</td>
      <td style="text-align: right">4</td>
      <td style="text-align: right">5</td>
    </tr>
  </tbody>
</table>

<p>This concludes my introduction to tidy evaluation. Hopefully this serves as a useful starting point for using these concepts in your own code.</p>]]></content><author><name>Jesse Cambon</name></author><category term="r" /><summary type="html"><![CDATA[Tidy evaluation is a framework for controlling how expressions and variables in your code are evaluated by tidyverse functions. This framework, housed in the rlang package, is a powerful tool for writing more efficient and elegant code. In particular, you’ll find it useful for passing variable names as inputs to functions that use tidyverse packages like dplyr and ggplot2.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="https://jessecambon.github.io/rmd_images/2019-12-8-practical-tidy-evaluation/unnamed-chunk-7-1.png" /><media:content medium="image" url="https://jessecambon.github.io/rmd_images/2019-12-8-practical-tidy-evaluation/unnamed-chunk-7-1.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry><entry><title type="html">Geocoding with Tidygeocoder</title><link href="https://jessecambon.github.io/2019/11/11/tidygeocoder-demo.html" rel="alternate" type="text/html" title="Geocoding with Tidygeocoder" /><published>2019-11-11T00:00:00+00:00</published><updated>2019-11-11T00:00:00+00:00</updated><id>https://jessecambon.github.io/2019/11/11/tidygeocoder-demo</id><content type="html" xml:base="https://jessecambon.github.io/2019/11/11/tidygeocoder-demo.html"><![CDATA[<p><a href="https://github.com/jessecambon/tidygeocoder">Tidygeocoder</a> is a newly published R package which provides a <a href="https://www.tidyverse.org/">tidyverse</a>-style interface for geocoding. It returns latitude and longitude coordinates in <a href="https://tibble.tidyverse.org/">tibble</a> format from addresses using the <a href="https://geocoding.geo.census.gov/">US Census</a> or <a href="https://nominatim.openstreetmap.org/">Nominatim (OSM)</a> geocoder services. In this post I will demonstrate how to use it for plotting a few Washington, DC landmarks on a map in honor of the <a href="https://fivethirtyeight.com/features/the-nationals-wouldnt-say-die/">recent Washington Nationals World Series win</a>.</p>

<p>First we will construct a dataset of addresses (<code class="language-plaintext highlighter-rouge">dc_addresses</code>) and use the <code class="language-plaintext highlighter-rouge">geocode</code> function from <code class="language-plaintext highlighter-rouge">tidygeocoder</code> to find longitude and latitude coordinates.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">dplyr</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">tidygeocoder</span><span class="p">)</span><span class="w">

</span><span class="n">dc_addresses</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">tribble</span><span class="p">(</span><span class="w">
  </span><span class="o">~</span><span class="n">name</span><span class="p">,</span><span class="w"> </span><span class="o">~</span><span class="n">addr</span><span class="p">,</span><span class="w">
  </span><span class="s2">"White House"</span><span class="p">,</span><span class="w"> </span><span class="s2">"1600 Pennsylvania Ave Washington, DC"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"National Academy of Sciences"</span><span class="p">,</span><span class="w"> </span><span class="s2">"2101 Constitution Ave NW, Washington, DC 20418"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"Department of Justice"</span><span class="p">,</span><span class="w"> </span><span class="s2">"950 Pennsylvania Ave NW, Washington, DC 20530"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"Supreme Court"</span><span class="p">,</span><span class="w"> </span><span class="s2">"1 1st St NE, Washington, DC 20543"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"Washington Monument"</span><span class="p">,</span><span class="w"> </span><span class="s2">"2 15th St NW, Washington, DC 20024"</span><span class="w">
</span><span class="p">)</span><span class="w">

</span><span class="n">coordinates</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">dc_addresses</span><span class="w"> </span><span class="o">%&gt;%</span><span class="w">
  </span><span class="n">geocode</span><span class="p">(</span><span class="n">addr</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p>The <code class="language-plaintext highlighter-rouge">geocode</code> function adds longitude and latitude coordinates as columns to our dataset of addresses. The default geocoder service used is the US Census, but Nominatim or a hybrid approach can be chosen with the <code class="language-plaintext highlighter-rouge">method</code> argument (see <a href="https://cran.r-project.org/web/packages/tidygeocoder/tidygeocoder.pdf">the documentation</a> for details). Our newly created <code class="language-plaintext highlighter-rouge">coordinates</code> dataset looks like this:</p>

<table>
  <thead>
    <tr>
      <th style="text-align: left">name</th>
      <th style="text-align: left">addr</th>
      <th style="text-align: right">lat</th>
      <th style="text-align: right">long</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">White House</td>
      <td style="text-align: left">1600 Pennsylvania Ave Washington, DC</td>
      <td style="text-align: right">38.89875</td>
      <td style="text-align: right">-77.03535</td>
    </tr>
    <tr>
      <td style="text-align: left">National Academy of Sciences</td>
      <td style="text-align: left">2101 Constitution Ave NW, Washington, DC 20418</td>
      <td style="text-align: right">38.89211</td>
      <td style="text-align: right">-77.04678</td>
    </tr>
    <tr>
      <td style="text-align: left">Department of Justice</td>
      <td style="text-align: left">950 Pennsylvania Ave NW, Washington, DC 20530</td>
      <td style="text-align: right">38.89416</td>
      <td style="text-align: right">-77.02501</td>
    </tr>
    <tr>
      <td style="text-align: left">Supreme Court</td>
      <td style="text-align: left">1 1st St NE, Washington, DC 20543</td>
      <td style="text-align: right">38.88990</td>
      <td style="text-align: right">-77.00591</td>
    </tr>
    <tr>
      <td style="text-align: left">Washington Monument</td>
      <td style="text-align: left">2 15th St NW, Washington, DC 20024</td>
      <td style="text-align: right">38.88979</td>
      <td style="text-align: right">-77.03291</td>
    </tr>
  </tbody>
</table>

<p>Now that we have the coordinates we want to plot, we will use the <a href="https://cran.r-project.org/package=OpenStreetMap">OpenStreetMap</a> package to make a map of DC.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">OpenStreetMap</span><span class="p">)</span><span class="w">
</span><span class="n">dc_map</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">openmap</span><span class="p">(</span><span class="nf">c</span><span class="p">(</span><span class="m">38.905</span><span class="p">,</span><span class="w"> </span><span class="m">-77.05</span><span class="p">),</span><span class="w"> </span><span class="nf">c</span><span class="p">(</span><span class="m">38.885</span><span class="p">,</span><span class="w"> </span><span class="m">-77.00</span><span class="p">))</span><span class="w">
</span><span class="n">dc_map.latlng</span><span class="w"> </span><span class="o">&lt;-</span><span class="w"> </span><span class="n">openproj</span><span class="p">(</span><span class="n">dc_map</span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p>Note that the coordinates supplied to the <code class="language-plaintext highlighter-rouge">openmap</code> function above were obtained using <a href="https://www.openstreetmap.org/">openstreetmap.org</a> (use the export button to extract coordinates). The <code class="language-plaintext highlighter-rouge">openmap</code> function downloads a street map and the <code class="language-plaintext highlighter-rouge">openproj</code> function projects it onto a latitude and longitude coordinate system so that we can overlay our coordinates, which is what we do next.</p>

<div class="language-r highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">library</span><span class="p">(</span><span class="n">ggplot2</span><span class="p">)</span><span class="w">
</span><span class="n">library</span><span class="p">(</span><span class="n">ggrepel</span><span class="p">)</span><span class="w">
</span><span class="n">autoplot</span><span class="p">(</span><span class="n">dc_map.latlng</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme_minimal</span><span class="p">()</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">theme</span><span class="p">(</span><span class="w">
    </span><span class="n">axis.text.y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_blank</span><span class="p">(),</span><span class="w">
    </span><span class="n">axis.title</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_blank</span><span class="p">(),</span><span class="w">
    </span><span class="n">axis.text.x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">element_blank</span><span class="p">(),</span><span class="w">
    </span><span class="n">plot.margin</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">unit</span><span class="p">(</span><span class="nf">c</span><span class="p">(</span><span class="m">0</span><span class="p">,</span><span class="w"> </span><span class="m">0</span><span class="p">,</span><span class="w"> </span><span class="m">0</span><span class="p">,</span><span class="w"> </span><span class="m">0</span><span class="p">),</span><span class="w"> </span><span class="s2">"cm"</span><span class="p">)</span><span class="w">
  </span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_point</span><span class="p">(</span><span class="n">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">coordinates</span><span class="p">,</span><span class="w"> </span><span class="n">aes</span><span class="p">(</span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">long</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">lat</span><span class="p">),</span><span class="w"> </span><span class="n">color</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"navy"</span><span class="p">,</span><span class="w"> </span><span class="n">size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">4</span><span class="p">,</span><span class="w"> </span><span class="n">alpha</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w">
  </span><span class="n">geom_label_repel</span><span class="p">(</span><span class="w">
    </span><span class="n">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">coordinates</span><span class="p">,</span><span class="w">
    </span><span class="n">aes</span><span class="p">(</span><span class="n">label</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">name</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">long</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">lat</span><span class="p">),</span><span class="w"> </span><span class="n">show.legend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">F</span><span class="p">,</span><span class="w"> </span><span class="n">box.padding</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">.5</span><span class="p">,</span><span class="w"> </span><span class="n">size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">5</span><span class="w">
  </span><span class="p">)</span><span class="w">
</span></code></pre></div></div>

<p><img src="/images/dc_osm_map.png" alt="dc-map" class="img-responsive" /></p>

<p>And that’s our map. The <code class="language-plaintext highlighter-rouge">geom_label_repel</code> function from <code class="language-plaintext highlighter-rouge">ggrepel</code> provides the text labels and <code class="language-plaintext highlighter-rouge">geom_point</code> from <code class="language-plaintext highlighter-rouge">ggplot2</code> supplies the points. Alternatively, the <a href="https://rstudio.github.io/leaflet/">leaflet package</a> provides an excellent interface to plot coordinates on an interactive map. For more information on tidygeocoder, visit its home on <a href="https://github.com/jessecambon/tidygeocoder">GitHub</a> or <a href="https://cran.r-project.org/package=tidygeocoder">CRAN</a>.</p>]]></content><author><name>Jesse Cambon</name></author><category term="r" /><category term="tidygeocoder" /><summary type="html"><![CDATA[Tidygeocoder is a newly published R package which provides a tidyverse-style interface for geocoding. It returns latitude and longitude coordinates in tibble format from addresses using the US Census or Nominatim (OSM) geocoder services. In this post I will demonstrate how to use it for plotting a few Washington, DC landmarks on a map in honor of the recent Washington Nationals World Series win.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="https://jessecambon.github.io/images/dc_osm_map.png" /><media:content medium="image" url="https://jessecambon.github.io/images/dc_osm_map.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry></feed>