4 Literate Programming

See the video quarto.mp4 for a visual explanation of this document.

4.1 What is Literate Programming?

LIterate programming combines code (e.g., R or Python) with text to create documents that are both readable and executable. The text itself is written in Markdown, a lightweight formatting language that allows us to structure documents with headings, bullet points, bold and italic text, and more.

Two key tools for literate programming in R are R Markdown and Quarto.

5 R Markdown

5.1 What is R Markdown?

R Markdown was the original tool for embedding code within documents. It allows users to write reports, create presentations, and generate formatted documents that include both text and code outputs.

5.2 Structure of an R Markdown File

An R Markdown file (.Rmd) consists of three main components:

5.2.1 1. YAML Front Matter

The YAML front matter is the metadata at the top of the document. It controls the output format (e.g., HTML, PDF, Word).

Example:

---
title: "My Report"
output: html_document
---

This tells R Markdown to generate an HTML document. Other options include pdf_document and word_document.

5.2.2 2. Code Chunks

Code chunks are sections of executable code, enclosed by triple backticks (```) with a specified language. In our case, it will be R:

summary(cars)

Backticks (`) are usually found next to the number 1 key on the keyboard.
By default, all code in chunks is executed when the document is rendered.

Chunk Options:
- echo = FALSE → Hides the code but still runs it.
- echo = TRUE → Displays both the code and its output.
- Other options can control figure size, message display, and more.

Example:

     speed           dist       
 Min.   : 4.0   Min.   :  2.00  
 1st Qu.:12.0   1st Qu.: 26.00  
 Median :15.0   Median : 36.00  
 Mean   :15.4   Mean   : 42.98  
 3rd Qu.:19.0   3rd Qu.: 56.00  
 Max.   :25.0   Max.   :120.00

The summary will appear in the final document, but the code itself won’t be displayed.

5.2.3 3. Markdown Formatting

Markdown is used for structuring text.

Headings: Use # for headings (## for subheadings, ### for deeper levels).
Bullet points: Use - or *.
Numbered lists: Use 1., 2., etc.
Bold text: **bold** → bold
Italic text: *italic* → italic

5.3 Output

R Markdown can embed plots, tables, and formatted text into a document. When you include code that generates a plot, the plot will be displayed in the final output.

6 Quarto

6.1 What is Quarto?

Quarto is the successor to R Markdown. It is very similar but:
- Has a different YAML front matter structure.
- Supports more programming languages (via Jupyter).
- Provides a more unified workflow for reports, websites, and books.

6.2 Differences in YAML

Instead of specifying output: html_document like in R Markdown, Quarto uses:

---
title: "My Report"
format: html
---

Quarto uses format instead of output, making it more flexible.

6.3 Code Chunks in Quarto

Quarto code chunks function similarly to R Markdown, but chunk options can be specified in a cleaner way:

```{r}
#| eval: false
summary(cars)
```

Using #| option: value inside the chunk makes options easier to read and manage.

7 Quarto Projects

7.1 Why Use Quarto Projects?

One limitation of R Markdown was that while you could generate individual reports (.html, .pdf, etc.), managing multiple files in a project (e.g., a website) required extra tools like bookdown.

Quarto solves this by providing built-in support for project structures.

7.2 Starting a Quarto Project

7.2.1 Via `RStudio` GUI

Unfortunately, in RStudio one cannot start a Quart project via the New File menu. Instead, you have to start a new RStudio project entirely. The change is that you must select Quarto Project from the New Project menu.

7.2.2 By adding a `quarto.yml` file

Alternatively, what you can do is simply add a _quarto.yml file. Here is an example _quarto.yml file:

project:
  type: book
  render:
  - index.qmd
  output-dir: docs
book:
  title: Statistical Computing
  sidebar:
    border: true
    background: light
    position: right
  navbar:
    search: true
    background: light
  chapters:
  - index.qmd
format:
  html:
    theme: cosmo
    toc: true
    toc-depth: 3
    toc-location: left

A brief explanation of this file:

index.qmd is the “base” qmd. It is the first file that will be rendered. Always include it.
- If you want to include other files, then specify them in the chapters and render keys.
output-dir specifies where the output will be saved. In this case, it will be saved in a docs folder.
book specifies the title of the book, the sidebar, the navbar, and the chapters.
format specifies specific formatting options for the html outputL
- The theme defines the overall appearance of the website.
- toc specifies whether a table of contents should be generated, and the toc-depth specifies how many levels of headings should be included.

7.3 Defining a Quarto Project

A Quarto project is defined by a quarto.yml file, which specifies how multiple .qmd files should be compiled together.

Example of a quarto.yml file for a website:

project:
  type: website

format:
  html:
    toc: true
    toc-depth: 3

This tells Quarto:
- The project is a website. .
- A table of contents should be generated (toc: true) for headings up to level 3 (toc-depth: 3).

7.4 Website vs. Book

Website (type: website)
- Only outputs HTML.
- Has a navigation bar linking different pages.
Book (type: book)
- Can output HTML, PDF, or Word.
- Uses a chapters: key to define sections.

Example quarto.yml for a book:

project:
  type: book

book:
  chapters:
    - index.qmd
    - intro.qmd
    - analysis.qmd

format:
  pdf: 
    documentclass: book

Here:
- The chapters define the book structure.
- The format section customizes the outputs.

7.5 Rendering a Quarto Project

To build the entire project, use the quarto R package:

install.packages("quarto")
quarto::quarto_render()

This renders all files in the project according to quarto.yml.
For websites, output is saved in _site/.
For books, output is saved in _book/.

7.6 Important Notes

To start a new Quarto project, go to RStudio → New Project → Quarto Project.
If creating a website, ensure you have an index.qmd file—websites require an index.html as the main entry point.
Clicking the Knit button in RStudio will render the current .qmd file, but quarto::quarto_render() is needed for the entire project.

8 Summary

R Markdown is an older tool for combining code and text, using .Rmd files.
Quarto is the modern alternative, offering more flexibility and better multi-file management.
Quarto Projects allow multiple .qmd files to be rendered together, creating websites or books.

By using Quarto, we can write reports, build websites, and generate books—all from the same toolset!