04_yourThesisMarkdown.md

title	Your RMarkdown Thesis
author	Simon Goring
date	15/09/2021
output	revealjs::revealjs_presentation theme css self_contained transition reveal_options reveal_plugins simple ../templates/custom.css false fade slideNumber previewLinks true true notes

Your Markdown Thesis - Advantages

• Combine code & text
• Widely used plain-text format
• Output to multiple formats
• Easily tracked with git
• Works with many software tools

---

Your Markdown Thesis - Disadvantages

• Disadvantages
  • Can be a pain to edit collaboratively
  • "Some" learning curve

---

Overall Benefits

• Final product is reproducible
• You are awesome
• Can be easily shared, modified & updated

---

Getting Started

---

Start a New RMarkdown File

• Or open our file. . . see GIF here

  • Navigate to the repository for this workshop
  • Fork the repository see video
  • Start a project from Version Control
  • Link to ThesisIsCode
  • Open the file in thesis/myThesis_Revised.Rmd

---

How Do We Write?

---

Main Elements

• Folders!

  • Figures (raw, finished); Code; Data (input/output); Save Google Sheet to file.

image ref

---

Main Elements

• YAML header (metadata for the document)
• Markdown formatting
• Fenced code blocks (using backticks)
• Data import
• Analysis
• Conclusions

---

Main Elements - YAML

• YAML Ain't Markup Language
• Tells Pandoc how to render the finished file.

---
title: Some title
author: Simon Goring
---

---

YAML - Continues

• Any tags are accepted (date, abstract, keywords)

---
title: Some title
author: 
- Simon Goring
- Socorro Dominguez
abstract: >
  I can move stuff to a new line.
---

---

YAML - Continues pt 2

• Any tags are accepted (date, abstract, keywords)

---
title: Some title
author: 
- Simon Goring
- Socorro Dominguez
abstract: >
  I can move stuff to a new line.
---

Format specific options for html, pdf, Word, &cetera.

---

Main Elements - Markdown

• How you actually apply styles/links &cetera
• Good Markdown Resources:
  • RMarkdown the Definitive Guide
  • GitHub Markdown Guide

---

Main Elements - Code Blocks

• This is the R part of RMarkdown. R executes the code and places it inline into the text.

Here is writing
```{r namedCodeBlock}
this <- is(code)
```
Here is writing that uses `r this` result.

---

Then knit the Document

Rscript -e "rmarkdown::render('filename.Rmd')"

Or, with bash (Mac & Linux) you can build on save.

---

Let's all Gaze in Wonder

• We can knit to PDF, HTML, DOCX (and other formats)
• Options depend on options in the yaml header (in part)
• RMarkdown render:
  • Runs each R code block
  • Creates a raw Markdown file
  • Replaces code with code results (knits)
  • Converts file format to desired output with Pandoc

---

Main Elements - Data Import

• Lets load in our file in thesis/data/input:

```{r loadData}
table <- read.csv('data/input/GitHubRepos.csv')
```

The table has `r nrow(rows)`, but there are less READMEs than a dozen eggs.

---

How Does it Look?

• Are there errors we can fix?
• We need to check our assumptions
• Formalize them with assertthat()

---

Using Assertions

---

Why Use Assertions?

• We want to make sure our text follows from our analysis.

```{r loadData}
table <- read.csv('data/input/GitHubRepos.csv')
```

The table has `r nrow(rows)`, but there are less READMEs than a dozen eggs.

• But are there?

---

Writing Assertions

assertthat::assert_that(sum(!is.na(table$README)) < 12, msg="There are more readme's than a dozen eggs.")

• If the assertion fails then the code doesn't knit and you have an informative error message telling you why.

---

Summary

• You've created a thesis chapter.