Chapter 1 Introduction

1.1 A preliminary guide

This is a non-exhaustive, non-expert guide to writing your dissertation using rmarkdown and bookdown.

The materials for this tutorial can be found on Google Drive or GitHub

Specifically, it will walk you through one person’s method of organizing, writing, and rendering a dissertation with these tools, using an adapted version of the Western University thesis templates, building off the techniques outlined by Lucy D’Agostino McGowan, and following Yihui Xie’s incredibly helpful bookdown and rmarkdown guides. See Section 11 for even more resources! The essence of bookdown is to provide a means of combining multiple chapters, each written as separate R Markdown files. This makes it an excellent tool for dissertation writing, as it allows you to seamlessly knit R code and narrative text in a modular, manageable structure. It’s also not just for books!

Despite the package name containing the word “book”, bookdown is not only for books. The “book” can be anything that consists of multiple R Markdown documents meant to be read in a linear sequence, such as course handouts, study notes, a software manual, a thesis, or even a diary. Yihui Xie

Caveat: At the time of writing, I am currently in the throes of dissertating. This means that there are likely several details I haven’t quite hammered out yet, or techniques I’ve missed. In the last year and a half, I’ve been collecting other people’s tutorials and resources on using RMarkdown + for the purposes of using it to write a dissertation. The final product is my interpretation of these resources, adapted to my needs, and presented here as a “What-I’ve-learned-so-far”-style tutorial.

via GIPHY

This tutorial will use a Kaggle dataset that reports nutritional information about Starbucks bevarages1. We’ve seen this dataset used twice in previous R-Ladies #LdnOnt presentations, so the primary motivation behind using it here is for continuity’s sake (also, coffee is a nice thing to have during dissertation writing). This tutorial loosely builds on another tutorial I gave in 2017 about using RMarkdown to write journal articles. Presumably this could be a realistic step for many people: write an article during your PhD (using RMarkdown), and eventually incorporate it into a dissertation.

While the focus of this tutorial is technically about dissertation writing, it will hopefully be a practical tool for learning more about R Markdown and Bookdown in general from the perspective of somebody who’s learning as she goes.

1.2 Setting up

In order to use this tutorial, you need the following:

  • R
  • RStudio
    • Recent versions of RStudio also include Pandoc, which is required to compile documents
  • Latex for Mac or Windows (if you want to compile to PDF).
    • Alternatively, install TinyTex, the Latex distribution created and recommended by Yihui Xie, creator of RMarkdown and bookdown23.
  • bookdown R package. Installing bookdown will automatically import knitr and rmarkdown pacakges as well. Install it by entering the following code into your R console:
install.packages("bookdown")

Yihui also has a super bookdown tutorial to follow. The bookdown manual is incredibly comprehensive and easy to follow, and will cover way more than what we’ll go in to here.

1.3 My current process: A glimpse

  1. ✏️ As I collected data and started gearing up to write the capital D Dissertation, I started keeping my notes in a separate bookdown project. This also helped me cut my teeth on bookdown, and made my notes wayyyyy easier to sift through than previous attempts (Google Docs, actual notebooks, txt files, readmes… I have found a lot of ways to flail).

  2. 🗒 Get some data in a .csv file

  3. 🧹 Load, tidy, and explore data in a designated .R file (e.g., 1_tidy.R)

  4. 📈 Carry out tats and prep data for use in text in a second designated .R file (2_models.R), sourcing the work done in 1_tidy.R.

  5. 📖 R Markdown files

  • Separate files for Intro, Methods, Results, Discussion, References
    • Many of these main chapters further broken down into smaller, more modular .Rmd files
  • The Results .Rmd files make heavy use of the work done in 3 & 4.
    • Figures coded in text.
    • Stats reported from final models defined in 2_models.R, with help from predefined functions and code snippets.

  1. 💻 Preview dissertation for myself in an .html format (compiles faster, easier to navigate, and I save it to my Chrome bookmarks for quick access)

  2. 📝 Preview multiple .Rmd files in Word to send to my supervisor as a .docx draft

    • previews/tmp_preview.Rmd uses child files to knit together a subset of my .Rmd files to send to my supervisor
    • There is also a “preview” function with Bookdown you could explore using!

  3. 📚 After major changes, compile the whole dissertation with what I have so far

    • Ensures that I am able to notice and fix any compiling errors at the interim stages and makes me feel like I am making real progress

  1. I don’t know how accurate the actual nutritional information is… I wouldn’t rely on this tutorial as a source for Starbucks info if I were you…↩

  2. TinyTex is probably the best way to go because Yihui always anticipates the problems we will run into, but I personally have not used it.↩

  3. Errors installing TinyTex? See if this advice helps.↩