-
Notifications
You must be signed in to change notification settings - Fork 0
/
mod_reports.qmd
134 lines (84 loc) · 8.05 KB
/
mod_reports.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
---
title: "Reproducible Reports"
code-annotations: hover
---
## Overview
At this point in the course, we anticipate that you're likely approaching the end of your team's synthesis project (see our suggested [milestones page](https://lter.github.io/ssecr/proj_milestones.html) for more information). As the end of your project and the course as a whole nears, it might be valuable for your group to consider how you can reproducibly document all of the work you've been doing for the last several months. "**Computational notebooks**" (e.g., Quarto documents, Jupyter Notebooks, R Markdown files, etc.) can be a reproducible way of documenting your results in a format that allows you to leverage _both_ your technical skills and your scientific communication skills.
This module focuses on the structure and content of these notebooks from a <u>primarily technical</u> lens, so please consult the [communicating findings](https://lter.github.io/ssecr/mod_findings.html) module for the team science perspective.
## Learning Objectives
After completing this module you will be able to:
- <u>Describe</u> contexts where computational notebooks are useful
- <u>Identify</u> the three fundamental elements of a typical notebook
- <u>Use</u> Markdown syntax to accomplish text styling
- <u>Create</u> notebooks that include a blend of plain text and embedded code chunks
- <u>Make</u> a Quarto website
- <u>Define</u> the purpose of GitHub Actions
- <u>Deploy</u> a notebook with GitHub Pages
## Preparation
TBD (<u>T</u>o <u>B</u>e <u>D</u>etermined)
## Notebook Structure & Value
Files that combine plain text with embedded code chunks are an excellent way of reproducibly documenting workflows and faciliating conversations about said workflows (or their outputs). Examples of notebook files include Quarto documents, Jupyter Notebooks, and R Markdown files. Regardless of the specific type, all of them function in the same way. Each of them allows you to use code chunks in the same way that you might use a typical script but between the code chunks you can add--and format--plain, human-readable text. Arguably you could do this with comments in a script but this format is built around the idea that this plain text is **intended to be interpretable without any prior coding experience**. The plain text can be formatted with Markdown syntax (we'll discuss that in greater depth later) but even unformatted text outside of code chunks is visually 'easier on the eyes' than comment lines in scripts.
Another shared facet of notebook interfaces is that they are meant to be "rendered" (a.k.a. "knit") to produce a different file type that translates code chunks and Markdown-formatted text into something that looks much more similar to what you might produce in Microsoft Word or a Google Doc. Typically such files are rendered into PDFs or HTMLs though there are other output options. These rendered files can then be shared (and opened) outside of coding platforms and thus make their content even more accessible to non-coders.
In synthesis work these reports can be especially valuable because your team may include those with a wealth of discipline insight but not necessarily coding literacy. <u>Creating reports with embedded code can enable these collaborators to engage more fully than they might otherwise be able to if there was essentially a minimum threshold of coding literacy required in order to contribute</u>. These reports can also be useful documentation of past coding decisions and serve as reminders for judgement calls for which no one in the team remembers the rationale.
### Structural Elements
Typically, these notebooks have three structural components:
1. YAML
- Pronounced '_YEAH-mull_'
2. Plain text
- Possibly formatted with Markdown syntax
3. Embedded code chunks
:::{.panel-tabset}
#### YAML
The YAML (<u>Y</u>et <u>A</u>nother <u>M</u>arkup <u>L</u>anguage) defines document-level metadata. Most fundamentally, the YAML defines what file type will be produced when the report is rendered. It can also be used to define the top-level title, author, and date information. Finally, it can change the default options for code chunks throughout the document (more on code chunk options elsewhere).
Different notebook file types will specify the YAML differently but in both Quarto documents and R Markdown files, the YAML is defined in the first few lines of the report and starts/ends with a line containing three hyphens. This looks something like this:
```{.bash}
---
title: "Reproducible Reports"
output: html_document
---
```
#### Markdown Text
The text outside of the YAML and code chunks is plain text that accepts Markdown syntax to accomplish text format tweaks. Dedicated text-formatting software (e.g., Microsoft Word, Gmail, etc.) provides buttons and hot keys for these sorts of format alterations but many programming IDEs do not provide such user interface elements.[^1] Markdown syntax is used to support this same functionality.
Some fundamental Markdown options include:
- \*\*bold text\*\* {{< fa arrow-right >}} **bold text**
- \_italic text\_ {{< fa arrow-right >}} _italic text_
- \`code text\` {{< fa arrow-right >}} `code text`
- \[hyperlinked text\]\(https://lter.github.io/ssecr/mod_reports.html\) {{< fa arrow-right >}} [hyperlinked text](https://lter.github.io/ssecr/mod_reports.html)
For a more complete glossary of fundamental Markdown syntax options see [here](https://www.markdownguide.org/basic-syntax/). You may also want to explore [the 'back end' of this course's website](https://github.com/lter/ssecr) as _every_ page is built using computational notebook files.
[^1]: Note that with the addition of the "Visual" tab in RStudio there are button options for many text format changes. Markdown syntax is still useful to know for general knowledge reasons though!
#### Code Chunks
The code chunks embedded in notebooks are essentially a fragmented script containing runable code. These chunks may contain code and/or comments and share an environment with one another when rendered (i.e., if you load a particular library in one chunk you'll be able to use functions from that library in subsequent chunks). When used in concert with the Markdown text in a given notebook the code chunks can be used to effectively demonstrate a workflow while providing as much human-readable context as is desired.
In Quarto documents, code chunks look like this[^2]:
```{.bash}
\```{r demo-chunk}
#| echo: true # <1>
# Round pi to 2 digits #<2>
round(x = pi, digits = 2)
\```
```
1. You may specify chunk-specific options using this syntax (i.e., `#| option_name: option_setting`). Options you want to apply to _all_ chunks across a notebook should be specified once in the YAML and can exclude the leading `#|` bit of the format.
2. If your Markdown text provides sufficient context you may exclude comments in code chunks but opinions differ on which is "more" appropriate
```{r demo-chunk}
#| echo: false
# Round pi to 2 digits
round(x = pi, digits = 2)
```
[^2]: Normally code chunks start and end with three backticks (\`\`\`) but to embed this code chunk example we need to "escape" the first backtick (using a backslash) so that the notebook interprets it correctly.
:::
### Script vs. Report Decision
See [here](https://nceas.github.io/scicomp.github.io/best_practices.html#r-scripts-versus-r-markdowns) for more information.
## Applications
- Static PDF/HTML files
- Full manuscripts
- Deployed website
## Deployment & GitHub
## Additional Resources
### Papers & Documents
-
### Workshops & Courses
- Csik, S. [Creating Your Personal Website Using Quarto](https://ucsb-meds.github.io/creating-quarto-websites/). **2024**.
- National Center for Ecological Analysis and Synthesis (NCEAS) Learning Hub. [coreR: Literate Analysis with Quarto](https://learning.nceas.ucsb.edu/2023-10-coreR/session_04.html). **2023**.
- Mecum, B. [Reproducible Papers with RMarkdown](https://nceas.github.io/oss-lessons/reproducible-papers-with-rmd/reproducible-papers-with-rmd.html). **2019**.
### Websites
- [The Markdown Guide: Basic Syntax](https://www.markdownguide.org/basic-syntax/).
- Posit. [Welcome to Quarto](https://quarto.org/)