File: here.html

package info (click to toggle)
r-cran-here 1.0.2-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 340 kB
sloc: sh: 13; makefile: 2
file content (665 lines) | stat: -rw-r--r-- 36,757 bytes
<!DOCTYPE html>

<html>

<head>

<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />

<meta name="viewport" content="width=device-width, initial-scale=1" />



<title>here</title>

<script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
// be compatible with the behavior of Pandoc < 2.8).
document.addEventListener('DOMContentLoaded', function(e) {
  var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
  var i, h, a;
  for (i = 0; i < hs.length; i++) {
    h = hs[i];
    if (!/^h[1-6]$/i.test(h.tagName)) continue;  // it should be a header h1-h6
    a = h.attributes;
    while (a.length > 0) h.removeAttribute(a[0].name);
  }
});
</script>

<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>



<style type="text/css">
code {
white-space: pre;
}
.sourceCode {
overflow: visible;
}
</style>
<style type="text/css" data-origin="pandoc">
html { -webkit-text-size-adjust: 100%; }
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } 
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.at { color: #7d9029; } 
code span.bn { color: #40a070; } 
code span.bu { color: #008000; } 
code span.cf { color: #007020; font-weight: bold; } 
code span.ch { color: #4070a0; } 
code span.cn { color: #880000; } 
code span.co { color: #60a0b0; font-style: italic; } 
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.do { color: #ba2121; font-style: italic; } 
code span.dt { color: #902000; } 
code span.dv { color: #40a070; } 
code span.er { color: #ff0000; font-weight: bold; } 
code span.ex { } 
code span.fl { color: #40a070; } 
code span.fu { color: #06287e; } 
code span.im { color: #008000; font-weight: bold; } 
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.kw { color: #007020; font-weight: bold; } 
code span.op { color: #666666; } 
code span.ot { color: #007020; } 
code span.pp { color: #bc7a00; } 
code span.sc { color: #4070a0; } 
code span.ss { color: #bb6688; } 
code span.st { color: #4070a0; } 
code span.va { color: #19177c; } 
code span.vs { color: #4070a0; } 
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } 
</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try { var rules = sheets[i].cssRules; } catch (e) { continue; }
    var j = 0;
    while (j < rules.length) {
      var rule = rules[j];
      // check if there is a div.sourceCode rule
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") {
        j++;
        continue;
      }
      var style = rule.style.cssText;
      // check if color or background-color is set
      if (rule.style.color === '' && rule.style.backgroundColor === '') {
        j++;
        continue;
      }
      // replace div.sourceCode by a pre.sourceCode rule
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
</script>




<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap; 
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }

code > span.kw { color: #555; font-weight: bold; } 
code > span.dt { color: #902000; } 
code > span.dv { color: #40a070; } 
code > span.bn { color: #d14; } 
code > span.fl { color: #d14; } 
code > span.ch { color: #d14; } 
code > span.st { color: #d14; } 
code > span.co { color: #888888; font-style: italic; } 
code > span.ot { color: #007020; } 
code > span.al { color: #ff0000; font-weight: bold; } 
code > span.fu { color: #900; font-weight: bold; } 
code > span.er { color: #a61717; background-color: #e3d2d2; } 
</style>




</head>

<body>




<h1 class="title toc-ignore">here</h1>



<p>The here package enables easy file referencing by using the top-level
directory of a file project to easily build file paths. This is in
contrast to using <code>setwd()</code>, which is fragile and dependent
on the way you order your files on your computer. Read more about
project-oriented workflows:</p>
<ul>
<li><p>What They Forgot to Teach You About R: <a href="https://rstats.wtf/projects.html">“Project-oriented workflow”</a>
chapter by Jenny Bryan and Jim Hester</p></li>
<li><p><a href="https://www.tidyverse.org/blog/2017/12/workflow-vs-script/">“Project-oriented
workflow”</a> blog post by Jenny Bryan</p></li>
<li><p>R for data science: <a href="https://r4ds.had.co.nz/workflow-projects.html">“Workflow:
projects”</a> chapter by Hadley Wickham</p></li>
</ul>
<div id="basic-functionality" class="section level2">
<h2>Basic functionality</h2>
<p>For demonstration, this article uses a data analysis project that
lives in
<code>/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project</code>
on my machine. This is the <em>project root</em>. The path will most
likely be different on your machine, the here package helps deal with
this situation.</p>
<p>The project has the following structure:</p>
<pre><code>#&gt; /private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project
#&gt; ├── analysis
#&gt; │   └── report.Rmd
#&gt; ├── data
#&gt; │   └── penguins.csv
#&gt; ├── demo-project.Rproj
#&gt; └── prepare
#&gt;     └── penguins.R</code></pre>
<p>You can review the project on <a href="https://github.com/r-lib/here/tree/main/inst/demo-project">GitHub</a>
and also download a copy.</p>
<p>To start working on this project in RStudio, open the
<code>demo-project.Rproj</code> file. This ensures that the <a href="https://en.wikipedia.org/wiki/Working_directory">working
directory</a> is set to
<code>/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project</code>,
the project root. Opening only the <code>.R</code> or the
<code>.Rmd</code> file may be insufficient!</p>
<p>Other development environments may have a different notion of a
project. Either way, it is important that the working directory is set
to the project root or a subdirectory of that path. You can check
with:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a><span class="fu">setwd</span>(project_path)</span></code></pre></div>
<div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="fu">getwd</span>()</span>
<span id="cb3-2"><a href="#cb3-2" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project&quot;</span></span></code></pre></div>
<p>(See <code>vignette(&quot;rmarkdown&quot;)</code> for an example where the
working directory is set to a subdirectory on start.)</p>
<div id="declare-the-location-of-the-current-script" class="section level3">
<h3>Declare the location of the current script</h3>
<p>The intended use is to add a call to <code>here::i_am()</code> at the
beginning of your script or in the first chunk of your rmarkdown
report.<a href="#fn1" class="footnote-ref" id="fnref1"><sup>1</sup></a>
This achieves the following:</p>
<ul>
<li>The location of the current script or report within the project is
declared</li>
<li>The project root is initialized, consistent with the location of the
current script or report</li>
<li>An informative message is emitted.<a href="#fn2" class="footnote-ref" id="fnref2"><sup>2</sup></a></li>
</ul>
<p>The first argument to <code>here::i_am()</code> should be the path to
the current file, relative to the project root. The
<code>penguins.R</code> script uses:</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb4-1"><a href="#cb4-1" tabindex="-1"></a>here<span class="sc">::</span><span class="fu">i_am</span>(<span class="st">&quot;prepare/penguins.R&quot;</span>)</span>
<span id="cb4-2"><a href="#cb4-2" tabindex="-1"></a><span class="co">#&gt; here() starts at /private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project</span></span></code></pre></div>
<p><code>here::i_am()</code> displays the top-level directory of the
current project. Because the project has a <code>prepare/</code>
directory in its root that contains <code>penguins.R</code>, it is
correctly inferred as the project root.</p>
<p>After <code>here::i_am()</code>, insert <code>library(here)</code> to
make the <code>here()</code> function available:<a href="#fn3" class="footnote-ref" id="fnref3"><sup>3</sup></a></p>
<div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1" tabindex="-1"></a><span class="fu">library</span>(here)</span></code></pre></div>
<p>The top-level directory is also returned from the <code>here()</code>
function:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb6-1"><a href="#cb6-1" tabindex="-1"></a><span class="fu">here</span>()</span>
<span id="cb6-2"><a href="#cb6-2" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project&quot;</span></span></code></pre></div>
<p>One important distinction from the working directory is that this
remains stable even if the working directory is changed:</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb7-1"><a href="#cb7-1" tabindex="-1"></a><span class="fu">setwd</span>(<span class="st">&quot;analysis&quot;</span>)</span>
<span id="cb7-2"><a href="#cb7-2" tabindex="-1"></a><span class="fu">getwd</span>()</span>
<span id="cb7-3"><a href="#cb7-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project/analysis&quot;</span></span>
<span id="cb7-4"><a href="#cb7-4" tabindex="-1"></a><span class="fu">here</span>()</span>
<span id="cb7-5"><a href="#cb7-5" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project&quot;</span></span>
<span id="cb7-6"><a href="#cb7-6" tabindex="-1"></a><span class="fu">setwd</span>(<span class="st">&quot;..&quot;</span>)</span></code></pre></div>
<p>(I suggest to steer clear from ever changing the working directory.
This may not always be feasible, in particular if the working directory
is changed by code that you do not control.)</p>
</div>
<div id="use-project-relative-paths" class="section level3">
<h3>Use project-relative paths</h3>
<p>You can build a path relative to the top-level directory in order to
build the full path to a file:</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a><span class="fu">here</span>(<span class="st">&quot;data&quot;</span>, <span class="st">&quot;penguins.csv&quot;</span>)</span>
<span id="cb8-2"><a href="#cb8-2" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project/data/penguins.csv&quot;</span></span>
<span id="cb8-3"><a href="#cb8-3" tabindex="-1"></a>readr<span class="sc">::</span><span class="fu">read_csv</span>(</span>
<span id="cb8-4"><a href="#cb8-4" tabindex="-1"></a>  <span class="fu">here</span>(<span class="st">&quot;data&quot;</span>, <span class="st">&quot;penguins.csv&quot;</span>),</span>
<span id="cb8-5"><a href="#cb8-5" tabindex="-1"></a>  <span class="at">col_types =</span> <span class="fu">list</span>(<span class="at">.default =</span> readr<span class="sc">::</span><span class="fu">col_guess</span>()),</span>
<span id="cb8-6"><a href="#cb8-6" tabindex="-1"></a>  <span class="at">n_max =</span> <span class="dv">3</span></span>
<span id="cb8-7"><a href="#cb8-7" tabindex="-1"></a>)</span>
<span id="cb8-8"><a href="#cb8-8" tabindex="-1"></a><span class="co">#&gt; # A tibble: 3 × 8</span></span>
<span id="cb8-9"><a href="#cb8-9" tabindex="-1"></a><span class="co">#&gt;   species island    bill_length_mm bill_depth_mm flipper_length_mm body_mass_g</span></span>
<span id="cb8-10"><a href="#cb8-10" tabindex="-1"></a><span class="co">#&gt;   &lt;chr&gt;   &lt;chr&gt;              &lt;dbl&gt;         &lt;dbl&gt;             &lt;dbl&gt;       &lt;dbl&gt;</span></span>
<span id="cb8-11"><a href="#cb8-11" tabindex="-1"></a><span class="co">#&gt; 1 Adelie  Torgersen           39.1          18.7               181        3750</span></span>
<span id="cb8-12"><a href="#cb8-12" tabindex="-1"></a><span class="co">#&gt; 2 Adelie  Torgersen           39.5          17.4               186        3800</span></span>
<span id="cb8-13"><a href="#cb8-13" tabindex="-1"></a><span class="co">#&gt; 3 Adelie  Torgersen           40.3          18                 195        3250</span></span>
<span id="cb8-14"><a href="#cb8-14" tabindex="-1"></a><span class="co">#&gt; # ℹ 2 more variables: sex &lt;chr&gt;, year &lt;dbl&gt;</span></span></code></pre></div>
<p>This works regardless of where the associated source file lives
inside your project. With <code>here()</code>, the path will always be
relative to the top-level project directory.</p>
<p><code>here()</code> works very similarly to <code>file.path()</code>
or <code>fs::path()</code>, you can pass path components or entire
subpaths:</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb9-1"><a href="#cb9-1" tabindex="-1"></a><span class="fu">here</span>(<span class="st">&quot;data/penguins.csv&quot;</span>)</span>
<span id="cb9-2"><a href="#cb9-2" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project/data/penguins.csv&quot;</span></span></code></pre></div>
<p>As seen above, <code>here()</code> returns absolute paths (starting
with <code>/</code>, <code>&lt;drive letter&gt;:\</code> or
<code>\\</code>). This makes it safe to pass these paths to other
functions, even if the working directory is changed along the way.</p>
<p>As of version 1.0.0, absolute paths passed to <code>here()</code> are
returned unchanged. This means that you can safely use both absolute and
project-relative paths in <code>here()</code>.</p>
<div class="sourceCode" id="cb10"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb10-1"><a href="#cb10-1" tabindex="-1"></a>data_path <span class="ot">&lt;-</span> <span class="fu">here</span>(<span class="st">&quot;data&quot;</span>)</span>
<span id="cb10-2"><a href="#cb10-2" tabindex="-1"></a><span class="fu">here</span>(data_path)</span>
<span id="cb10-3"><a href="#cb10-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project/data&quot;</span></span>
<span id="cb10-4"><a href="#cb10-4" tabindex="-1"></a><span class="fu">here</span>(data_path, <span class="st">&quot;penguins.csv&quot;</span>)</span>
<span id="cb10-5"><a href="#cb10-5" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project/data/penguins.csv&quot;</span></span></code></pre></div>
</div>
<div id="situation-report" class="section level3">
<h3>Situation report</h3>
<p>The <code>dr_here()</code> function explains the reasoning behind
choosing the project root:</p>
<div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb11-1"><a href="#cb11-1" tabindex="-1"></a><span class="fu">dr_here</span>()</span>
<span id="cb11-2"><a href="#cb11-2" tabindex="-1"></a><span class="co">#&gt; here() starts at /private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project.</span></span>
<span id="cb11-3"><a href="#cb11-3" tabindex="-1"></a><span class="co">#&gt; - This directory contains a file &quot;prepare/penguins.R&quot;</span></span>
<span id="cb11-4"><a href="#cb11-4" tabindex="-1"></a><span class="co">#&gt; - Initial working directory: /private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project</span></span>
<span id="cb11-5"><a href="#cb11-5" tabindex="-1"></a><span class="co">#&gt; - Current working directory: /private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project</span></span></code></pre></div>
<p>The <code>show_reason</code> argument can be set to
<code>FALSE</code> to reduce the output to one line:</p>
<div class="sourceCode" id="cb12"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb12-1"><a href="#cb12-1" tabindex="-1"></a><span class="fu">dr_here</span>(<span class="at">show_reason =</span> <span class="cn">FALSE</span>)</span>
<span id="cb12-2"><a href="#cb12-2" tabindex="-1"></a><span class="co">#&gt; here() starts at /private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project</span></span></code></pre></div>
</div>
<div id="what-if-the-working-directory-is-wrong" class="section level3">
<h3>What if the working directory is wrong?</h3>
<p>The declaration of the active file via <code>here::i_am()</code> also
protects against accidentally running the script from a working
directory outside of your project. The example below calls
<code>here::i_am()</code> from the temporary directory, which is clearly
outside our project:</p>
<div class="sourceCode" id="cb13"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb13-1"><a href="#cb13-1" tabindex="-1"></a>withr<span class="sc">::</span><span class="fu">with_dir</span>(<span class="fu">tempdir</span>(), {</span>
<span id="cb13-2"><a href="#cb13-2" tabindex="-1"></a>  <span class="fu">print</span>(<span class="fu">getwd</span>())</span>
<span id="cb13-3"><a href="#cb13-3" tabindex="-1"></a>  here<span class="sc">::</span><span class="fu">i_am</span>(<span class="st">&quot;prepare/penguins.R&quot;</span>)</span>
<span id="cb13-4"><a href="#cb13-4" tabindex="-1"></a>})</span>
<span id="cb13-5"><a href="#cb13-5" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpTB4noC&quot;</span></span>
<span id="cb13-6"><a href="#cb13-6" tabindex="-1"></a><span class="co">#&gt; Error: Could not find associated project in working directory or any parent directory.</span></span>
<span id="cb13-7"><a href="#cb13-7" tabindex="-1"></a><span class="co">#&gt; - Path in project: prepare/penguins.R</span></span>
<span id="cb13-8"><a href="#cb13-8" tabindex="-1"></a><span class="co">#&gt; - Current working directory: /private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpTB4noC</span></span>
<span id="cb13-9"><a href="#cb13-9" tabindex="-1"></a><span class="co">#&gt; Please open the project associated with this file and try again.</span></span></code></pre></div>
<p>This can also happen when a file has been renamed or moved without
updating the <code>here::i_am()</code> call. In the future, a helper
function will assist with installing and updating suitably formatted
<code>here::i_am()</code> calls in your scripts and reports.</p>
</div>
</div>
<div id="extra-safety" class="section level2">
<h2>Extra safety</h2>
<div id="conflicts-with-other-packages" class="section level3">
<h3>Conflicts with other packages</h3>
<p>Other packages also export a <code>here()</code> function. Loading
these packages after loading here masks our <code>here()</code>
function:</p>
<div class="sourceCode" id="cb14"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb14-1"><a href="#cb14-1" tabindex="-1"></a><span class="fu">library</span>(plyr)</span>
<span id="cb14-2"><a href="#cb14-2" tabindex="-1"></a><span class="co">#&gt; Error in library(plyr): there is no package called &#39;plyr&#39;</span></span>
<span id="cb14-3"><a href="#cb14-3" tabindex="-1"></a><span class="fu">here</span>()</span>
<span id="cb14-4"><a href="#cb14-4" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project&quot;</span></span></code></pre></div>
<p>One way to work around this problem is to use
<code>here::here()</code>:</p>
<div class="sourceCode" id="cb15"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb15-1"><a href="#cb15-1" tabindex="-1"></a>here<span class="sc">::</span><span class="fu">here</span>()</span>
<span id="cb15-2"><a href="#cb15-2" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project&quot;</span></span></code></pre></div>
<p>The conflicted package offers an alternative: it detects that
<code>here()</code> is exported from more than one package and allows
you to use neither until you indicate a preference.</p>
<div class="sourceCode" id="cb16"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb16-1"><a href="#cb16-1" tabindex="-1"></a><span class="fu">library</span>(conflicted)</span>
<span id="cb16-2"><a href="#cb16-2" tabindex="-1"></a><span class="fu">here</span>()</span>
<span id="cb16-3"><a href="#cb16-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project&quot;</span></span>
<span id="cb16-4"><a href="#cb16-4" tabindex="-1"></a></span>
<span id="cb16-5"><a href="#cb16-5" tabindex="-1"></a>conflicted<span class="sc">::</span><span class="fu">conflict_prefer</span>(<span class="st">&quot;here&quot;</span>, <span class="st">&quot;here&quot;</span>)</span>
<span id="cb16-6"><a href="#cb16-6" tabindex="-1"></a><span class="co">#&gt; [conflicted] Will prefer here::here over any other package.</span></span>
<span id="cb16-7"><a href="#cb16-7" tabindex="-1"></a><span class="fu">here</span>()</span>
<span id="cb16-8"><a href="#cb16-8" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project&quot;</span></span></code></pre></div>
</div>
<div id="specify-a-unique-identifier" class="section level3">
<h3>Specify a unique identifier</h3>
<p>To eliminate potential confusion, <code>here::i_am()</code> accepts a
<code>uuid</code> argument. The idea is that each script and report
calls <code>here::i_am()</code> very early (in the first 100 lines) with
a universally unique identifier. Even if a file location is reused
across projects (e.g. two projects contain a “prepare/data.R” file), the
files can be identified correctly if the <code>uuid</code> argument in
the <code>here::i_am()</code> call is different.</p>
<p>If a <code>uuid</code> argument is passed to
<code>here::i_am()</code>:</p>
<ul>
<li>a project root that contains a file at the specified file path is
searched</li>
<li>the first 100 lines of that file are read</li>
<li>for the correct file, the <code>here::i_am()</code> call that passes
this very <code>uuid</code> is among those 100 lines, and will be
matched</li>
<li>for the wrong file, <code>uuid</code> is not found in the text</li>
</ul>
<p>Use <code>uuid::UUIDgenerate()</code> to create universally unique
identifiers:</p>
<div class="sourceCode" id="cb17"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb17-1"><a href="#cb17-1" tabindex="-1"></a>uuid<span class="sc">::</span><span class="fu">UUIDgenerate</span>()</span>
<span id="cb17-2"><a href="#cb17-2" tabindex="-1"></a><span class="co">#&gt; [1] &quot;2276eeed-46b3-41fa-b458-0c46e3d96d63&quot;</span></span></code></pre></div>
<p>Ensure that the <code>uuid</code> arguments are actually unique
across your files! In the future, a helper function will assist with
installing and updating suitably formatted <code>here::i_am()</code>
calls in your scripts and reports.</p>
</div>
</div>
<div id="beyond-here" class="section level2">
<h2>Beyond here</h2>
<div id="change-project-root" class="section level3">
<h3>Change project root</h3>
<p>It is advisable to <a href="https://rstats.wtf/source-and-blank-slates">start a fresh R
session</a> as often as possible, especially before focusing on another
project. There still may be legitimate cases when it is desirable to
reset the project root.</p>
<p>To start, let’s create a temporary project for demonstration:</p>
<div class="sourceCode" id="cb18"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb18-1"><a href="#cb18-1" tabindex="-1"></a>temp_project_path <span class="ot">&lt;-</span> <span class="fu">tempfile</span>()</span>
<span id="cb18-2"><a href="#cb18-2" tabindex="-1"></a><span class="fu">dir.create</span>(temp_project_path)</span>
<span id="cb18-3"><a href="#cb18-3" tabindex="-1"></a>scripts_path <span class="ot">&lt;-</span> <span class="fu">file.path</span>(temp_project_path, <span class="st">&quot;scripts&quot;</span>)</span>
<span id="cb18-4"><a href="#cb18-4" tabindex="-1"></a><span class="fu">dir.create</span>(scripts_path)</span>
<span id="cb18-5"><a href="#cb18-5" tabindex="-1"></a>script_path <span class="ot">&lt;-</span> <span class="fu">file.path</span>(scripts_path, <span class="st">&quot;script.R&quot;</span>)</span>
<span id="cb18-6"><a href="#cb18-6" tabindex="-1"></a><span class="fu">writeLines</span>(</span>
<span id="cb18-7"><a href="#cb18-7" tabindex="-1"></a>  <span class="fu">c</span>(</span>
<span id="cb18-8"><a href="#cb18-8" tabindex="-1"></a>    <span class="st">&#39;here::i_am(&quot;scripts/script.R&quot;)&#39;</span>,</span>
<span id="cb18-9"><a href="#cb18-9" tabindex="-1"></a>    <span class="st">&#39;print(&quot;Hello, world!&quot;)&#39;</span></span>
<span id="cb18-10"><a href="#cb18-10" tabindex="-1"></a>  ),</span>
<span id="cb18-11"><a href="#cb18-11" tabindex="-1"></a>  script_path</span>
<span id="cb18-12"><a href="#cb18-12" tabindex="-1"></a>)</span>
<span id="cb18-13"><a href="#cb18-13" tabindex="-1"></a>fs<span class="sc">::</span><span class="fu">dir_tree</span>(temp_project_path)</span>
<span id="cb18-14"><a href="#cb18-14" tabindex="-1"></a><span class="co">#&gt; /var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T//RtmpTB4noC/file22302f8ea490</span></span>
<span id="cb18-15"><a href="#cb18-15" tabindex="-1"></a><span class="co">#&gt; └── scripts</span></span>
<span id="cb18-16"><a href="#cb18-16" tabindex="-1"></a><span class="co">#&gt;     └── script.R</span></span>
<span id="cb18-17"><a href="#cb18-17" tabindex="-1"></a><span class="fu">writeLines</span>(<span class="fu">readLines</span>(script_path))</span>
<span id="cb18-18"><a href="#cb18-18" tabindex="-1"></a><span class="co">#&gt; here::i_am(&quot;scripts/script.R&quot;)</span></span>
<span id="cb18-19"><a href="#cb18-19" tabindex="-1"></a><span class="co">#&gt; print(&quot;Hello, world!&quot;)</span></span></code></pre></div>
<p>The <code>script.R</code> file contains a call to
<code>here::i_am()</code> to declare its location. Running it from the
current working directory will fail:</p>
<div class="sourceCode" id="cb19"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb19-1"><a href="#cb19-1" tabindex="-1"></a><span class="fu">source</span>(script_path, <span class="at">echo =</span> <span class="cn">TRUE</span>)</span>
<span id="cb19-2"><a href="#cb19-2" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb19-3"><a href="#cb19-3" tabindex="-1"></a><span class="co">#&gt; &gt; here::i_am(&quot;scripts/script.R&quot;)</span></span>
<span id="cb19-4"><a href="#cb19-4" tabindex="-1"></a><span class="co">#&gt; Error: Could not find associated project in working directory or any parent directory.</span></span>
<span id="cb19-5"><a href="#cb19-5" tabindex="-1"></a><span class="co">#&gt; - Path in project: scripts/script.R</span></span>
<span id="cb19-6"><a href="#cb19-6" tabindex="-1"></a><span class="co">#&gt; - Current working directory: /private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project</span></span>
<span id="cb19-7"><a href="#cb19-7" tabindex="-1"></a><span class="co">#&gt; Please open the project associated with this file and try again.</span></span></code></pre></div>
<p>To reset the project root mid-session, change the working directory
with <code>setwd()</code>. Now, the subsequent call to
<code>here::i_am()</code> from within <code>script.R</code> works:</p>
<div class="sourceCode" id="cb20"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb20-1"><a href="#cb20-1" tabindex="-1"></a><span class="fu">setwd</span>(temp_project_path)</span></code></pre></div>
<div class="sourceCode" id="cb21"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb21-1"><a href="#cb21-1" tabindex="-1"></a><span class="fu">source</span>(script_path, <span class="at">echo =</span> <span class="cn">TRUE</span>)</span>
<span id="cb21-2"><a href="#cb21-2" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb21-3"><a href="#cb21-3" tabindex="-1"></a><span class="co">#&gt; &gt; here::i_am(&quot;scripts/script.R&quot;)</span></span>
<span id="cb21-4"><a href="#cb21-4" tabindex="-1"></a><span class="co">#&gt; here() starts at /private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpTB4noC/file22302f8ea490</span></span>
<span id="cb21-5"><a href="#cb21-5" tabindex="-1"></a><span class="co">#&gt; </span></span>
<span id="cb21-6"><a href="#cb21-6" tabindex="-1"></a><span class="co">#&gt; &gt; print(&quot;Hello, world!&quot;)</span></span>
<span id="cb21-7"><a href="#cb21-7" tabindex="-1"></a><span class="co">#&gt; [1] &quot;Hello, world!&quot;</span></span></code></pre></div>
<p>To reiterate: a fresh session is almost always the better, cleaner,
safer, and more robust solution. Use this approach only as a last
resort.</p>
</div>
<div id="under-the-hood-rprojroot" class="section level3">
<h3>Under the hood: rprojroot</h3>
<p>The here package has a very simple and restricted interface, by
design. The underlying logic is provided by the much more powerful
rprojroot package. If the default behavior of here does not suit your
workflow for one reason or another, the rprojroot package may be a
better alternative. It is also recommended to import rprojroot and not
here from other packages.</p>
<p>The following example shows how to find an RStudio project starting
from a directory:</p>
<div class="sourceCode" id="cb22"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb22-1"><a href="#cb22-1" tabindex="-1"></a><span class="fu">library</span>(rprojroot)</span>
<span id="cb22-2"><a href="#cb22-2" tabindex="-1"></a><span class="fu">find_root</span>(is_rstudio_project, <span class="fu">file.path</span>(project_path, <span class="st">&quot;analysis&quot;</span>))</span>
<span id="cb22-3"><a href="#cb22-3" tabindex="-1"></a><span class="co">#&gt; [1] &quot;/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpP5W5BF/Rinst22067b4435c4/here/demo-project&quot;</span></span></code></pre></div>
<p>Arbitrary criteria can be defined. See
<code>vignette(&quot;rprojroot&quot;, package = &quot;rprojroot&quot;)</code> for an
introduction.</p>
</div>
</div>
<div class="footnotes footnotes-end-of-document">
<hr />
<ol>
<li id="fn1"><p>Prior to version 1.0.0, it was recommended to attach the
here package via <code>library(here)</code>. This still works, but is no
longer the recommended approach.<a href="#fnref1" class="footnote-back">↩︎</a></p></li>
<li id="fn2"><p><code>library(here)</code> no longer emits an
informative message if <code>here::i_am()</code> has been called
before.<a href="#fnref2" class="footnote-back">↩︎</a></p></li>
<li id="fn3"><p><code>library(here)</code> emits a message that may be
confusing if followed by the message from <code>here::i_am()</code>.<a href="#fnref3" class="footnote-back">↩︎</a></p></li>
</ol>
</div>



<!-- code folding -->


<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

</body>
</html>