Writing with Quarto

Announcements

  • Activity 1 due next week

  • Instructions are available at the top of the activity

  • For graduate students: identify 5 papers that are important to your dissertation, whose results you think it would be important to reproduce

    • Characteristics of good papers:
    • Ideally published within ~20 years
    • Analysis does not rely on extremely heavy computation
    • Original authors did not make a fully reproducible pipeline available
    • (But if they did, we can discuss potential ways forward.)

  • For undergraduate students: identify 5 openly available datasets that you would like to explore in your project

    • What are some features of this dataset? (e.g. what types of data available?)
    • What kinds of analysis/figures can you envision generating?

Quarto

Quarto files are designed to be used in three ways:

  • For communicating to decision-makers, who want to focus on the conclusions, not the code behind the analysis.

  • For collaborating with other data scientists (including future you!), who are interested in both your conclusions, and how you reached them (i.e. the code).

  • As an environment in which to do data science, as a modern-day lab notebook where you can capture not only what you did, but also what you were thinking.

— R for Data Science, Ch. 28

Anatomy of a qmd file

(link to download this file)

Lines 1–5: “YAML” header - this is the space to add information about your file (title, author, date, additional details).

  • Demarcated by three dashes (---)
  • Always appear in key: value format
  • Lots of possible options – see this guide for details.
    • No need to get overwhelmed by the options for now - but good to keep in mind for future projects.

Lines 7–15: R code chunk

  • Demarcated by three ticks, followed by the programming language name (```{r} {code} ```)
  • Lines 8–9 are options for the R code chunk - these control, e.g. whether the code is run or not, how big figures are, etc.
  • Lines 11–15 are standard R code

Lines 16–20: Text in Markdown

  • This is text meant to be read by humans
  • Can customize how text is rendered, e.g. adding * around a word to italicize: *quarto* becomes quarto
  • Read about additional formatting options here

What to do with qmd files

  • Render (i.e. “generate”) into a “public facing” document, with all the source code readily available.
  • Settings for rendering are based on the YAML header of the file

Quarto as a “swiss army knife” for scientific writing

  • When preparing a manuscript for journal submission, there’s several moving pieces to manage:

    • Reference management/inserting citations
    • Inserting figures, tables, equations
    • Generating appendices/supplements
    • Sharing code with reviewers
    • Keeping track of your changes during peer-review

Quarto can help with all!

Reference management/inserting citations

  • Add journal stylesheet to YAML
csl: <journalname>.csl
  • Save stylesheet into your project directory
  • Long list of journals in this repository

Reference management/inserting citations

“Old school” approach

  • Add a bibliography file to your project (e.g. references.bib)
  • Add bibliography file to YAML header
bibliography: admin-files/references.bib
  • Content of references.bib should be BibTex entries (available online), e.g.
      @article{wickham2014tidy,
        title={Tidy data},
        author={Wickham, Hadley},
        journal={Journal of statistical software},
        volume={59},
        pages={1--23},
        year={2014}
      }

Reference management/inserting citations

A modern alternative:

  • Using in RStudio’s “Visual” editor (live demo)

Inserting figures, tables, equations

  • If your figures are generated by code within the quarto document, no need to separately insert them - automatically inserted when you render the file!
  • If you have additional figures (e.g. to add a microscopy photo), use markdown syntax:
![Figure caption](path/to/figure.png)
  • For equations, use Latex formatting, e.g. $\frac{dN}{dt}$ generates \(\frac{dN}{dt}\)

Generating appendices/supplements

  • At the bottom of your “Main Text” document, you can simply include references to other .qmd files.

{{< include appendix-1.qmd >}}

Sharing code with reviewers

  • Since all analysis is integrated with the writing, you can simply share the source code

Keeping track of your changes during peer-review

  • Since you are using git to keep track of your changes, you have a clear history of what lines you changed.
  • (Even without git, you can use the bash command diff to identify exactly what changed between your initial submission and re-submission).

Thursday exercises

https://carpentries-incubator.github.io/reproducible-publications-quarto/

Writing with Quarto
Day 2

Three components of a qmd file

  1. YAML header
  2. R code chunks
  3. Markdown text

Markdown options

  • Goal: write in plain text to generate documents with “rich” formatting

  • *text in italics* \(\to\) text in italics

  • **text in bold** \(\to\) text in bold

  • ***text in bold-italic*** \(\to\) text in bold-italic

  • [underlined text]{.underline} \(\to\) underlined text

  • [text in small caps]{.smallcaps} \(\to\) text in small caps

  • text with ^superscript^ or ~subscript~ \(\to\)
      text with superscript or subscript

  • $\frac{dN}{dt} = rN$ \(\to\) \(\frac{dN}{dt} = rN\)

  • Community ecology is a mess [@lawton_1999] \(\to\) Community ecology is a mess (Lawton 1999)

  • You can also add footnotes^[like this] \(\to\) You can also add footnotes1

Markdown options, con’t

![Here's a picture of a Panamenian golden frog](https://upload.wikimedia.org/wikipedia/commons/5/55/Atelopus_zeteki1.jpg) \(\to\)

Here’s a picture of a Panamenian golden frog

Markdown options, con’t

# Header 1

## Header 2

### Header 3

Markdown options, con’t

See https://quarto.org/docs/authoring/markdown-basics.html for a comprehensive guide to markdown options

R code chunks

  • To write R Code in qmd documents, we need to insert code “chunks”

  1. The keyboard shortcut Cmd + Option + I / Ctrl + Alt + I.

  2. The “Insert” button icon in the editor toolbar.

  3. By manually typing the chunk delimiters ```{r} and ```.

— R for Data Science, Ch. 28

```{r}
1 + 1
```
[1] 2

R code chunks, con’t

  • Code chunks can be modified with several options
  • Simple example: labeling the chunk with a name
```{r}
#| label: simple-addition
1 + 1
```
[1] 2

R code chunks, con’t

  • Some R chunks can be shown but not run (“evaluated”)
```{r}
#| label: simple-multiplication
#| eval: false
2 * 2
```

R code chunks, con’t

  • R code chunks can control the appearance of the output
```{r}
#| label: first-figure
#| fig-width: 2

cars |> 
  ggplot(aes(x = speed, y = dist)) + 
  geom_point()
```

R code chunks, con’t

  • R code chunks can control the appearance of the output
```{r}
#| label: second-figure
#| fig-width: 8

cars |> 
  ggplot(aes(x = speed, y = dist)) + 
  geom_point()
```

R code chunks, con’t

  • R code chunks can control the appearance of the output
```{r}
#| label: third-figure
#| fig-width: 8
#| fig-cap: "Plot of speed vs. dist"
#| fig-subcap: "Generated from `cars` dataset in R"

cars |> 
  ggplot(aes(x = speed, y = dist)) + 
  geom_point()
```

Generated from cars dataset in R

Plot of speed vs. dist

References

Lawton, John H. 1999. “Are There General Laws in Ecology?” Oikos, 177–92.