Skip to content

Commit

Permalink
Built site for gh-pages
Browse files Browse the repository at this point in the history
  • Loading branch information
Quarto GHA Workflow Runner committed Feb 27, 2024
1 parent bc2f054 commit 68c3cd4
Show file tree
Hide file tree
Showing 8 changed files with 128 additions and 25 deletions.
2 changes: 1 addition & 1 deletion .nojekyll
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
b79dc5e1
b8755f24
Binary file added images/image_proj-struct-v1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/image_proj-struct-v2.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/image_proj-struct-v3.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/image_proj-struct-v4.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
111 changes: 107 additions & 4 deletions mod_reproducibility.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,7 @@ <h2 id="toc-title">On this page</h2>
<li><a href="#project-organization-documentation" id="toc-project-organization-documentation" class="nav-link" data-scroll-target="#project-organization-documentation">Project Organization &amp; Documentation</a>
<ul class="collapse">
<li><a href="#fundamental-structure" id="toc-fundamental-structure" class="nav-link" data-scroll-target="#fundamental-structure">Fundamental Structure</a></li>
<li><a href="#organizing-example" id="toc-organizing-example" class="nav-link" data-scroll-target="#organizing-example">Organizing Example</a></li>
<li><a href="#documentation" id="toc-documentation" class="nav-link" data-scroll-target="#documentation">Documentation</a></li>
<li><a href="#organization-recommendations" id="toc-organization-recommendations" class="nav-link" data-scroll-target="#organization-recommendations">Organization Recommendations</a></li>
</ul></li>
Expand Down Expand Up @@ -442,9 +443,111 @@ <h4 class="anchored" data-anchor-id="naming-tips">Naming Tips</h4>
<p>Weird or unlikely outputs are easily traced to the scripts that created them because of their shared slug.</p>
</section>
</section>
<section id="organizing-example" class="level3">
<h3 class="anchored" data-anchor-id="organizing-example">Organizing Example</h3>
<p>These tips are all worthwhile but they can feel a little abstract without a set of files firmly in mind. Let’s consider an example synthesis project where we incrementally change the project structure to follow increasing more of the guidelines we suggest above.</p>
<div class="tabset-margin-container"></div><div class="panel-tabset">
<ul class="nav nav-tabs" role="tablist"><li class="nav-item" role="presentation"><a class="nav-link active" id="tabset-1-1-tab" data-bs-toggle="tab" data-bs-target="#tabset-1-1" role="tab" aria-controls="tabset-1-1" aria-selected="true" aria-current="page">Version 1</a></li><li class="nav-item" role="presentation"><a class="nav-link" id="tabset-1-2-tab" data-bs-toggle="tab" data-bs-target="#tabset-1-2" role="tab" aria-controls="tabset-1-2" aria-selected="false">Version 2</a></li><li class="nav-item" role="presentation"><a class="nav-link" id="tabset-1-3-tab" data-bs-toggle="tab" data-bs-target="#tabset-1-3" role="tab" aria-controls="tabset-1-3" aria-selected="false">Version 3</a></li><li class="nav-item" role="presentation"><a class="nav-link" id="tabset-1-4-tab" data-bs-toggle="tab" data-bs-target="#tabset-1-4" role="tab" aria-controls="tabset-1-4" aria-selected="false">Version 4</a></li></ul>
<div class="tab-content">
<div id="tabset-1-1" class="tab-pane active" role="tabpanel" aria-labelledby="tabset-1-1-tab">
<div class="columns">
<div class="column" style="width:40%;">
<p><img src="images/image_proj-struct-v1.png" alt="" width="90%"></p>
</div><div class="column" style="width:60%;">
<section id="positives" class="level4">
<h4 class="anchored" data-anchor-id="positives">Positives</h4>
<ul>
<li>All project files are in one folder</li>
</ul>
</section>
<section id="areas-for-improvement" class="level4">
<h4 class="anchored" data-anchor-id="areas-for-improvement">Areas for Improvement</h4>
<ul>
<li>No use of sub-folders to divide logically-linked content</li>
<li>File names lack key context (e.g., workflow order, inputs vs.&nbsp;outputs, etc.)</li>
<li>Inconsistent use of delimiters</li>
</ul>
</section>
</div>
</div>
</div>
<div id="tabset-1-2" class="tab-pane" role="tabpanel" aria-labelledby="tabset-1-2-tab">
<div class="columns">
<div class="column" style="width:40%;">
<p><img src="images/image_proj-struct-v2.png" alt="" width="90%"></p>
</div><div class="column" style="width:60%;">
<section id="positives-1" class="level4">
<h4 class="anchored" data-anchor-id="positives-1">Positives</h4>
<ul>
<li>Sub-folders used to divide content</li>
<li>Project documentation included in top level (README and license files)</li>
</ul>
</section>
<section id="areas-for-improvement-1" class="level4">
<h4 class="anchored" data-anchor-id="areas-for-improvement-1">Areas for Improvement</h4>
<ul>
<li>File names still inconsistent
<ul>
<li>File names contain different information in different order</li>
<li>Mixed use of delimiters</li>
<li>Many file names include spaces</li>
</ul></li>
</ul>
</section>
</div>
</div>
</div>
<div id="tabset-1-3" class="tab-pane" role="tabpanel" aria-labelledby="tabset-1-3-tab">
<div class="columns">
<div class="column" style="width:40%;">
<p><img src="images/image_proj-struct-v3.png" alt="" width="90%"></p>
</div><div class="column" style="width:60%;">
<section id="positives-2" class="level4">
<h4 class="anchored" data-anchor-id="positives-2">Positives</h4>
<ul>
<li>Most file names contain context</li>
<li>Standardized use of casing and–within sub-folder–consistent delimiters used</li>
</ul>
</section>
<section id="areas-for-improvement-2" class="level4">
<h4 class="anchored" data-anchor-id="areas-for-improvement-2">Areas for Improvement</h4>
<ul>
<li>Workflow order “guessable” but not explicit</li>
<li>Unclear which files are inputs / outputs (and of which scripts)</li>
</ul>
</section>
</div>
</div>
</div>
<div id="tabset-1-4" class="tab-pane" role="tabpanel" aria-labelledby="tabset-1-4-tab">
<div class="columns">
<div class="column" style="width:40%;">
<p><img src="images/image_proj-struct-v4.png" alt="" width="90%"></p>
</div><div class="column" style="width:60%;">
<section id="positives-3" class="level4">
<h4 class="anchored" data-anchor-id="positives-3">Positives</h4>
<ul>
<li>Scripts include zero-padded numbers indicating order of operations</li>
<li>Inputs / outputs share zero padded slug with source script</li>
<li>Report file names machine sorted from least to most recent (top to bottom)</li>
</ul>
</section>
<section id="areas-for-improvement-3" class="level4">
<h4 class="anchored" data-anchor-id="areas-for-improvement-3">Areas for Improvement</h4>
<ul>
<li>Depending on sub-folder complexity, could add sub-folder specific README files</li>
<li>Graph file names still include spaces</li>
</ul>
</section>
</div>
</div>
</div>
</div>
</div>
</section>
<section id="documentation" class="level3">
<h3 class="anchored" data-anchor-id="documentation">Documentation</h3>
<p>Documenting a project can feel like a Sisyphean task but it is often not as hard as one might imagine and well worth the effort! One simple practice you can adopt to dramatically improve the reproducibility of your project is to create a “README” file in the top-level of your project’s folder system. This file can be formatted however you’d like but generally READMEs should include (1) a project overview written in plain language, (2) a basic table of contents for the primary folders in your project folder, and (3) a brief description of the file naming scheme you’ve adopted for this project.</p>
<p>Documenting a project can feel daunting but it is often not as hard as one might imagine and always well worth the effort! One simple practice you can adopt to dramatically improve the reproducibility of your project is to create a “README” file in the top-level of your project’s folder system. This file can be formatted however you’d like but generally READMEs should include (1) a project overview written in plain language, (2) a basic table of contents for the primary folders in your project folder, and (3) a brief description of the file naming scheme you’ve adopted for this project.</p>
<p>Your project’s README becomes the ‘landing page’ for those navigating your repository and makes it easy for team members to know where documentation should go (in the README!). You may also choose to create a README file for some of the sub-folders of your project. This can be particularly valuable for your “data” folder(s) as it is an easy place to store data source/provenance information that might be overwhelming to include in the project-level README file.</p>
<p>Finally, you should choose a place to keep track of ideas, conversations, and decisions about the project. While you can take notes on these topics on a piece of paper, adopting a digital equivalent is often helpful because you can much more easily search a lengthy document when it is machine readable. We will discuss GitHub during the <a href="https://lter.github.io/ssecr/mod_version-control.html">Version Control module</a> but GitHub offers something called <a href="https://nceas.github.io/scicomp-workshop-collaborative-coding/issues.html">Issues</a> that can be a really effective place to record some of this information.</p>
</section>
Expand Down Expand Up @@ -508,9 +611,9 @@ <h3 class="anchored" data-anchor-id="code-comments">Code Comments</h3>
<p>A “comment” in a script is a human readable, non-coding line that helps give context for the code. In R (and Python), comment lines start with a hashtag (#). Including comments is a low effort way of both (A) creating internal documentation for the script and (B) increasing the reproducibility of the script. It is difficult to include “too many” comments, so when in doubt: add more comments!</p>
<p>There are two major strategies for comments and either or both might make sense for your project.</p>
<div class="tabset-margin-container"></div><div class="panel-tabset">
<ul class="nav nav-tabs" role="tablist"><li class="nav-item" role="presentation"><a class="nav-link active" id="tabset-1-1-tab" data-bs-toggle="tab" data-bs-target="#tabset-1-1" role="tab" aria-controls="tabset-1-1" aria-selected="true" aria-current="page">“What” Comments</a></li><li class="nav-item" role="presentation"><a class="nav-link" id="tabset-1-2-tab" data-bs-toggle="tab" data-bs-target="#tabset-1-2" role="tab" aria-controls="tabset-1-2" aria-selected="false">“Why” Comments</a></li></ul>
<ul class="nav nav-tabs" role="tablist"><li class="nav-item" role="presentation"><a class="nav-link active" id="tabset-2-1-tab" data-bs-toggle="tab" data-bs-target="#tabset-2-1" role="tab" aria-controls="tabset-2-1" aria-selected="true">“What” Comments</a></li><li class="nav-item" role="presentation"><a class="nav-link" id="tabset-2-2-tab" data-bs-toggle="tab" data-bs-target="#tabset-2-2" role="tab" aria-controls="tabset-2-2" aria-selected="false">“Why” Comments</a></li></ul>
<div class="tab-content">
<div id="tabset-1-1" class="tab-pane active" role="tabpanel" aria-labelledby="tabset-1-1-tab">
<div id="tabset-2-1" class="tab-pane active" role="tabpanel" aria-labelledby="tabset-2-1-tab">
<p>Comments describe <em>what</em> the code is doing.</p>
<ul>
<li>Benefits: allows team members to understand workflow without code literacy</li>
Expand All @@ -519,7 +622,7 @@ <h3 class="anchored" data-anchor-id="code-comments">Code Comments</h3>
<div class="sourceCode" id="cb1"><pre class="sourceCode r code-with-copy"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Remove all pine trees from dataset</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>no_pine_df <span class="ot">&lt;-</span> dplyr<span class="sc">::</span><span class="fu">filter</span>(full_df, genus <span class="sc">!=</span> <span class="st">"Pinus"</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
</div>
<div id="tabset-1-2" class="tab-pane" role="tabpanel" aria-labelledby="tabset-1-2-tab">
<div id="tabset-2-2" class="tab-pane" role="tabpanel" aria-labelledby="tabset-2-2-tab">
<p>Comments describe <em>rationale</em> and/or <em>context</em> for code.</p>
<ul>
<li>Benefits: built-in documentation for team decisions</li>
Expand Down
2 changes: 1 addition & 1 deletion search.json
View file

Large diffs are not rendered by default.

38 changes: 19 additions & 19 deletions sitemap.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,78 +2,78 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://lter.github.io/ssecr/mod_version-control.html</loc>
<lastmod>2024-02-22T19:12:15.279Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_thinking.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_wrangle.html</loc>
<lastmod>2024-02-22T19:12:15.279Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_credit.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_findings.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_data-disc.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/topic_interactivity.html</loc>
<lastmod>2024-02-22T19:12:15.279Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_facilitation.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_data-viz.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_team-sci.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/index.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_reports.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/topic_spatial.html</loc>
<lastmod>2024-02-22T19:12:15.279Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_stats.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_reproducibility.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_spatial.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_logic-models.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/CONTRIBUTING.html</loc>
<lastmod>2024-02-22T19:12:15.255Z</lastmod>
<lastmod>2024-02-27T17:40:52.304Z</lastmod>
</url>
<url>
<loc>https://lter.github.io/ssecr/mod_project-mgmt.html</loc>
<lastmod>2024-02-22T19:12:15.275Z</lastmod>
<lastmod>2024-02-27T17:40:52.328Z</lastmod>
</url>
</urlset>

0 comments on commit 68c3cd4

Please sign in to comment.