Quarto for writing and analysis

Announcements

  • Activity 1 due at the end of 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: select five potential datasets that you might want to explore from the lterdatasampler package and for each, answer the following:

    • Name and source of dataset:
    • Why was this dataset originally collected? (I.e. what questions were the authors exploring when collecting these data?)
    • What is the type of data available? Describe both the technical features of the files (e.g. “a CSV table with 10 columns and 950 rows”), and the contents themselves (e.g. “columns 2 and 3 describe the latitude and longitude; column 4 describes the species name, […]”)
    • Brainstorm 1–2 figures that you would like to create with these data.1

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

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

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}
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
Listing 1: Simple Addition 
```{r}
#| lst-label: lst-simple-addition
#| lst-cap: Simple Addition

1 + 1
```
[1] 2

As seen in @lst-simple-addition, 1+1=2 \(\to\) As seen in Listing 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: fig-plot-dist
#| fig-width: 8
#| fig-cap: "Plot of speed vs. dist"
#| fig-subcap: "Generated from `cars` dataset in R"
#| fig-align: center

cars |> 
  ggplot(aes(x = speed, y = dist)) + 
  geom_point()
```
(a) Generated from cars dataset in R
Figure 1: Plot of speed vs. dist

As shown in @fig-plot-dist, speed and dist are positively correlated \(\to\)
As shown in ?@fig-third-figure, speed and dist are positively correlated

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!

  • See Editorial by Journal of Ecology for how Editors are thinking about the role of quarto/other reproducible report generation methods.

Quarto utilities for scientific writing

  • Changing output formats (beyond HTML)
  • Embedding figures, tables, and equations
  • Bibliography/reference management
  • Generating appendices/supplements
  • Word templates

Sandbox to try things in Quarto

  • Go into your rstudio project yourname-class-notes

  • Run git pull, either in the terminal or in the top-right Git pane (blue arrow downwards)

  • You should now have a file _demo-quarto.qmd in your working directory.

  • To run the next few steps, you may need to run install.packages('tinytex') and install.packages('rmarkdown') if you didn’t already do this in Week 1.

Things to try with _demo-quarto.qmd

References

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