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

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

Announcements

Quarto

Anatomy of a `qmd` file

What to do with `qmd` files

Writing with Quarto
Day 2

Three components of a qmd file

Markdown options

Markdown options, con’t

Markdown options, con’t

Markdown options, con’t

R code chunks

R code chunks, con’t

R code chunks, con’t

R code chunks, con’t

R code chunks, con’t

R code chunks, con’t

References