Open Scholarship Workshop

R, Markdown, & Quarto

Open Scholarship

Rationale and Definition

Motivation

More than 70% of researchers have tried and failed to reproduce another scientist’s experiments, and more than half have failed to reproduce their own experiments. Those are some of the telling figures that emerged from Nature’s survey of 1,576 researchers who took a brief online questionnaire on reproducibility in research. (Baker 2016)¹

Some definitions

According to this article in Science Translational Medicine, reproducibility …

… [is a] set of procedures that permit the reader of a paper to see the entire processing trail from the raw data and code to figures and tables. (Goodman et al. 2016)

Or the U.S. National Science Foundation (NSF) defines it this way …

… refers to the ability of a researcher to duplicate the results of a prior study using the same materials as were used by the original investigator. (Cacioppo et al. 2015)

Main principles

Examples

Publication Workflows

Publication: Microbial diversity declines in warmed tropical soil and respiration rise exceed predictions as communities adapt

Workflow: SWELTR created in the Quarto framework.

Publication: Rapid ecosystem-scale consequences of acute deoxygenation on a Caribbean reef.

Workflow: Hypocolypse created using Distll.

Publication: Intestinal microbes as an axis of functional diversity among large marine consumers.

Workflow: ProjectDIGEST created using native R Markdown.

Other R Markdown examples

The Istmobiome Project Project site created with blogdown and Hugo.

Cacao Fermentation Presentation created using reveal.js.

How the Isthmus of Panama changed the world Presentation created with the xaringan package.

R Markdown Fieldguide R Markdown tutorial website for the 2022 STRI-McGill NEO field course. Made with the Distill blog template.

Interactive fish phylogeny Workflow on database scraping and visualization.

My CV created using pagedown.

Quarto

An open-source scientific and technical publishing system

Rendering Process

Quarto document (.qmd) contains code and Markdown formatted text.
knitr executes all the R code, knits the results together with Markdown text, and creates a new Markdown document.
The new Markdown document is then processed by PanDoc, which converts the Markdown syntax into HTML and CSS code. PanDoc is like a swiss-army knife for Markdown—it can covert many types of Markdown documents into a variety of other formats. All of these steps happen behind the scenes. As long as you have a properly formatted R Markdown document, these tools will take care of the rest.

Markdown

Defined

Markdown is a “lightweight markup language with plain-text-formatting syntax.”

What this means is that Markdown is easy-to-write using any generic text editor and easy-to-read in its raw form.

Markdown Resources

Here are a few resources I recommend to augment your skill development.

Basic Markdown Syntax Reference from The Markdown Guide, a free and open-source reference guide.
Extended Markdown Syntax Reference. Advanced features that build on the basic Markdown syntax. Also from The Markdown Guide.
Interactive Markdown Tutorial for beginners. Each lesson contains an explanation of Markdown syntax. Hit the Try it button to test your skills and see what your solution looks like when it is rendered. There is also an option to see the HTML equivalent of the Markdown text. This is a nice tutorial.
Markdown Tables Generator. Tired of typing all of those hyphens and pipes?
Character Entity Reference Chart for coding special symblos in Markdown.
Hacks. Workarounds for things not officially supported by Markdown.

Markdown Editors

Markdown editors are a great tool to learn Markdown because you can see a live preview of what the rendered text will look like.

Markdown Online Editors

Online editors are universally supported across operating systems. Here are a few to get you started.

StackEdit. In-browser Markdown editor
Dillinger. “The Last Markdown Editor, Ever.”
MarkTwo. Free, open source progressive web app.

Markdown Desktop Editors

I only listing free desktop editors here. There are plenty more if you are willing to pony up some cash. Some of these are operating system specific while others are universal.

MarkText is a simple and elegant open-source markdown editor that focused on speed and usability.. Universal.
Zettlr ships with a lot of features helpful in writing markdown. It is especially aimed at writing research papers in the arts and humanities (and therefore offers writing aids such as automatic footnote insertion and in-place editing, or a global search). Universal.
Znote is a free, elegant program meant to help you write beautifully organized Markdown documents. You can organize your texts, notes, and files even better, using the simplistic left-side widget organizer for smoothly navigating different files. Universal.
MarkdownPad and MarkdownPad 2 are full-featured Markdown editors for Windows.
MacDown is an open source Markdown editor for macOS.

Live Code a Website

Adding Code

Code chunk anatomy

Naming Things

Goal is to ensure your files are Machine and Human readable.

This applies to:

files
directories
variables in code
tabular data (row and column names)

Do not use spaces to separate words

Kebab case: Words delimited by a hyphen (-)¹.

file-one
directory-two

Snake case: Words delimited by an underscore (_).

file_one
variable_two

Pascal case: Words delimited by capital letters.

FileOne
VariableTwo

Camel case: Words delimited by capital letters, except the initial word.

fileOne
variableTwo

Special characters

Never use special characters in your naming scheme.

(e.g., * # : \ / < > | " ? [ ] ; , = + & £ $ , and so on).

Many symbols are prohibited and a lot of software will reject these symbols.

Letters, numbers, dashes, underscores only.


$$
\begin{cases}
\dot{x}  = \sigma(y-x)  \\
\dot{y} = \rho x - y - xz  \\
\dot{z} = -\beta z + xy
\end{cases}
$$

\begin{gather*}
e^{i\pi} + 1 = 0
\end{gather*}

\begin{align}
f(k) = {n \choose k} p^{k} (1-p)^{n-k}
\end{align}

\[ \begin{cases} \dot{x} = \sigma(y-x) \\ \dot{y} = \rho x - y - xz \\ \dot{z} = -\beta z + xy \end{cases} \] \[\begin{gather*} e^{i\pi} + 1 = 0 \end{gather*}\]

\[\begin{align} f(k) = {n \choose k} p^{k} (1-p)^{n-k} \end{align}\]

Baker, Monya. 2016. “1,500 Scientists Lift the Lid on Reproducibility.” Nature 533 (7604). https://doi.org/10.1038/533452a.

Cacioppo, John T, Robert M Kaplan, Jon A Krosnick, James L Olds, and Heather Dean. 2015. “Social, Behavioral, and Economic Sciences Perspectives on Robust and Reliable Science.” Report of the Subcommittee on Replicability in Science Advisory Committee to the National Science Foundation Directorate for Social, Behavioral, and Economic Sciences 1.

Goodman, Steven N, Daniele Fanelli, and John PA Ioannidis. 2016. “What Does Research Reproducibility Mean?” Science Translational Medicine 8 (341): 341ps12–12. https://doi.org/10.1126/scitranslmed.aaf5027.