Module 11: Literate Programming

Amy Winter

Zane Billings

Learning goals

1. Define literate programming
2. Implement literate programming in R using knitr and either R Markdown or Quarto
3. Include plots, tables, and references along with your code in a written report.
4. Locate additional resources for literate programming with R Markdown or Quarto.

What is literate programming?

• Programming files contain code along with text, code results, and other supporting information.
• Instead of having separate code and text, that you glue together in Word, we have one document which combines code and text.

What is literate programming?

R markdown example, from https://rmarkdown.rstudio.com/authoring_quick_tour.html

Literate programming examples

• Writing a research paper with R Markdown: https://github.com/wzbillings/Patient-vs-Clinician-Symptom-Reports
• Writing a book with R Markdown: https://github.com/moderndive/ModernDive_book
• Personal websites (like my tutorial!): https://jadeyryan.com/blog/2024-02-19_beginner-quarto-netlify/
• Other examples: https://bookdown.org/yihui/rmarkdown/basics-examples.html

R Markdown and Quarto

• R Markdown and Quarto are both implementations of literate programming using R, with the knitr package for the backend. Both are supported by RStudio.
• To use R Markdown, you need to install.packages("rmarkdown").
• Quarto comes with new versions of RStudio, but you can also install the latest version from the Quarto website.
• R Markdown is older and now very commonly used. Quarto is newer and so has many fancy new features, but more bugs that are constantly being found and fixed.
• In this class, we will use R Markdown. But if you decide to use quarto, 90% of your knowledge will transfer since they are very similar.
  • Advantages of R Markdown: more online resources, most common bugs have been fixed over the years, many people are familiar with it.
  • Advantages of Quarto: supports other programming languages like Python and Julia, uses more modern syntax, less slapped together overall.

Getting started with R Markdown

A few sticking points

• Knitting to html format is really easy, but most scientist don’t like html format for some reason. If you want to knit to pdf, you should install the package tinytex and read the intro.
• If you want to knit to word (what many journals in epidemiology require), you need to have Word installed on your computer. Note that with word, you are a bit more restricted in your formatting options, so if weird things happen you’ll have to try some other options.
• You maybe noticed in the tutorial that I used the here::here() function for all of my file paths. This is because R Markdown and Quarto files use a different working directory from the R Project. Using here::here() translates relative paths into absolute paths based on your R Project, so it makes sure your R Markdown files can always find the right path!

Research paper example in R Markdown

You try it!

1. Create an R Markdown document. Write about either the measles or diphtheria example data sets, and include a figure and a table.
2. BONUS EXERCISE: read the intro of the bookdown book, and create a bookdown document. Modify your writeup to have a few references with a bibliography, and cross-references with your figures and tables.
3. BONUS: Try to structure your document like a report, with a section stating the questions you want to answer (intro), a section with your R code and results, and a section with your interpretations (discussion). This is a very open ended exercise but by now I believe you can do it, and you’ll have a nice document you can put on your portfolio or show employers!