Enough Markdown to Write a Thesis

Author

Richard J Telford

Published

August 20, 2024

1 Introduction

Schematic of the traditional workflow for writing a report or manuscript (left) with copy and paste, and the quarto workflow (right) with code and text in the same document. — Figure 1.1: Traditional non-reproducible workflow for writing a report or manuscript (left) with copy and paste, and the reproducible quarto workflow (right) with code and text in the same document.

The traditional way to write a report, manuscript or thesis is to run the analyses in R or some other software and then copy the figures, tables etc. into a word processor. Then you find an error in the code or data and need to repeat the process. Repeatedly.

This is very inefficient and error prone: there is a better way.

Quarto lets you have the code and the text in one document. If the code or the data are updated, new versions of the figures and tables are automatically generated and inserted into the corrected document. This is a much more reproducible process.

This book is written with Quarto.

Reading

Perkel (2022) Cut the tyranny of copy-and-paste with these coding tools, Nature 603, 191-192 doi: https://doi.org/10.1038/d41586-022-00563-z

1.1 Organisation of this book

First Steps with Quarto shows you how to create a quarto document, edit it, add figures and tables, and render it as a finished document.

Towards a Thesis shows you how author a manuscript, report or thesis in quarto by adding citations and cross-references to figures and tables.

Fixing Problems The final section has some trouble shooting suggestions.

Quarto and R markdown

Quarto is based on R markdown. If you know how to use R markdown, you know how to use quarto as almost any R markdown document should also work with quarto.

There are several improvements in quarto over R markdown which make it easier to use.

No need to remember different behaviour and capabilities of rmarkdown vs bookdown etc.
Simplified cross-references
Better support for multiple programming languages

Before you start

You will need to have installed

RStudio (version 2023.12 or newer)
R
quarto. RStudio should have installed this already.
quarto R package (install.packages("quarto"))

If you cannot install quarto on your computer (perhaps because of permission problems), either use the Rmarkdown tutorial, or use posit.cloud.

```{r setup, include=FALSE} library(palmerpenguins) library(tidyverse) source("../Templates/biostats_theme.R") ``` # Introduction ```{r} #| label: fig-quarto-workflow #| echo: false #| fig-cap: Traditional non-reproducible workflow for writing a report or manuscript (left) with copy and paste, and the reproducible quarto workflow (right) with code and text in the same document. #| fig-alt: Schematic of the traditional workflow for writing a report or manuscript (left) with copy and paste, and the quarto workflow (right) with code and text in the same document. knitr::include_graphics("Pics/quarto_workflow.png") ``` The traditional way to write a report, manuscript or thesis is to run the analyses in R or some other software and then copy the figures, tables etc. into a word processor. Then you find an error in the code or data and need to repeat the process. Repeatedly. This is very inefficient and error prone: there is a better way. Quarto lets you have the code and the text in one document. If the code or the data are updated, new versions of the figures and tables are automatically generated and inserted into the corrected document. This is a much more **reproducible** process. This book is written with Quarto. ::: callout-note ## Reading Perkel (2022) Cut the tyranny of copy-and-paste with these coding tools, Nature 603, 191-192 doi: <https://doi.org/10.1038/d41586-022-00563-z> ::: ## Organisation of this book **First Steps with Quarto** shows you how to create a quarto document, edit it, add figures and tables, and render it as a finished document. **Towards a Thesis** shows you how author a manuscript, report or thesis in quarto by adding citations and cross-references to figures and tables. **Fixing Problems** The final section has some trouble shooting suggestions. ::: callout-tip ## Quarto and R markdown Quarto is based on R markdown. If you know how to use R markdown, you know how to use quarto as almost any R markdown document should also work with quarto. There are several improvements in quarto over R markdown which make it easier to use. - No need to remember different behaviour and capabilities of rmarkdown vs bookdown etc. - Simplified cross-references - Better support for multiple programming languages ::: ::: callout-note ## Before you start You will need to have installed - [RStudio](https://www.rstudio.com/products/rstudio/) (version 2023.12 or newer) - [R](https://cran.r-project.org/) - [quarto](https://quarto.org/docs/get-started/ "Download quarto"). RStudio should have installed this already. - quarto R package (`install.packages("quarto")`) If you cannot install quarto on your computer (perhaps because of permission problems), either use the [Rmarkdown tutorial](https://biostats-r.github.io/biostats/rmarkdown/index.html), or use [posit.cloud](https://posit.cloud). :::