Creating basic R workflows and literate programming

.title[
# Creating basic R workflows and literate programming
]
.author[
### Ernest Guevarra
]
.date[
### 26 November 2024
]

---

# Outline

* Project-oriented workflows in R

* Why organise workflows into projects
    * How to organise workflows into projects

* Literate programming

* Why use literate programming
    * RMarkdown for literate programming

* Practical session

---

# Project-orientd workflows in R

---

# Why organise workflows into projects

* key word is *"organise"*;

* organisation ensures *coherence* and *order* which is helpful to the user whenever he/she goes back to the same work again later;

* organisation supports good documentation; and,

* organisation allows for collaboration.

---

# How to organise workflows into projects

* a unique piece of *"work"* should be its own *project*;

* all resources and tools needed for a *project* should be within the same directory; and,

* group resources and tools within appropriately into their own directories with the project directory.

]

---

# Literate programming

---

# Why use literate programming

* write code that satisfies both the machine/computer and the human reader/user;

* highlight and give as much importance to the documentation of the processes and the outputs that your code represents;

* focus on communication and understanding of the process and the output; and,

* single document that integrates both code and textual documentation.

---

# R Markdown for literate programming

* R Markdown provides an authoring framework for literate programming;

* A single R Markdown file is used to both save and execute code, and generate high quality reports that can be shared with an audience; and,

* R Markdown documents are fully reproducible and support dozens of static and dynamic output formats.

---

# R Markdown example - PDF report

---

# R Markdown example - HTML report

---

# R Markdown example - Website

---

# R Markdown example - slide deck

---

# Basics of R Markdown

* An R Markdown document is written in markdown (an easy-to-write plain text format) and contains chunks of embedded R code, like the document below.

---

# Basic Markdown syntax

### Markdown syntax

* ```*italics*``` or ```_italics_```

* ```**bold**``` or ```__bold__```

* ```> block quote```

* ```# Header 1```

* ```## Header 2```

* ```### Header 3```

* ```#### Header 4```

]

### Resulting output

* *italics*

* **bold**

* > block quote

* # Header 1

* ## Header 2

* ### Header 3

* #### Header 4

]

---

# Basic Markdown syntax

### Markdown syntax

* ```[link to Open Reproducible Science website](https://oxford-ihtm.io/open-reproducible-science/)```

* adding an image: ```![](path/to/Tux.svg)```

]

### Resulting output

* [link to Open Reproducible Science website](https://oxford-ihtm.io/open-reproducible-science/)

* adding an image: ![](images/Tux.svg)

]

---

# Questions?

---

# Practical session

We'll work through *Exercise 5 - Extending R with packages* in Practical R for Epidemiologists (https://practical-r.org/exercise5.html) as a GitHub Classroom assignment

---

# Thank you!

Slides can be viewed at https://oxford-ihtm.io/open-reproducible-science/session5.html

PDF version of slides can be downloaded at https://oxford-ihtm.io/open-reproducible-science/pdf/session5-literate-programming.pdf

R scripts for slides available [here](https://github.com/OxfordIHTM/open-reproducible-science/blob/main/session5.Rmd)