R course

Daniel Vaulot

2023-01-22

Markdown and Quarto

R - Session 04

  • What is Markown ?
  • Rmarkdown syntax
  • R chunks
  • Some applications

What is markdown

Installation and Resources

Packages

  • rmarkdown (will install also knitr)
  • tinytex (Latex)

Resources

  • [On-line Book][https://bookdown.org/yihui/rmarkdown]

  • Cheat sheet

What is markdown ?

  • Created in 2004 by John Gruber and Aaron Swartz

  • Goal : “to write using an easy-to-read and easy-to-write plain text format, optionally convert it to structurally valid HTML”.

Many flavors…

  • MultiMarkdown
  • GitHub Flavored Markdown (GFM)
  • Pandoc
  • CommonMark

Rmarkdown

Mix

  • Markdown

    • paragraph structure
    • comments
    • links

  • R code (“chunks”)

  • Output of R code

Your first Rmarkdown file

Your first Rmarkdown file

  • Who has not been able to install Rmarkdown and Latex ?

Your first Rmarkdown file

Knit to HTML

  • Save to “xxx.Rmd”

Knit to HTML

Knit of pdf

Knit of pdf

Markdown syntax

Quick guide

Structure

Headings

# Heading - level 1   

## Heading - level 2

Heading - level 1

Heading - level 2

Paragraphs

Paragraphs are separated
by a blank line.

Two spaces at the end of a line  
produces a line break.

Paragraphs are separated by a blank line.

Two spaces at the end of a line
produces a line break.

Formatting

Characters

_italic_, *italic*, **bold**, `monospace`.

italic, italic, bold, monospace.

  • Do not mix straight and backward quotes

Bullet lists

Bullet list:

  * apples
  * oranges
  * pears
      * passe crassane (4 spaces to indent)
  • apples
  • oranges
  • pears
    • passe crassane

Numbered lists

Numbered list:

1. wash
1. rinse
1. repeat
  1. wash
  2. rinse
  3. repeat

Tables

ID | First | Last
 --| -- | --
1 | Joe | Biden
ID First Last
1 Joe Biden

Alignement

| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |
| 1       | 1    |     1 |   1    |
Default Left Right Center
12 12 12 12
123 123 123 123
1 1 1 1

Rmarkdown

Rmarkdown conversion process

  • knitr : R library

  • Pandoc : command line tool

    • Converts from md to pdf, html, docx…
# HTML
> pandoc test1.md -f markdown -t html -s -o test1.html

# pdf
> pandoc test1.md -s -o test1.pdf

The Rmarkdown file structure

Knit process

Output

Insert R chunk

Run R chunk

Two options

Run R chunk

Option 1: Run R chunk inside Rmd file

  • Use when building and debugging an Rmd file

Run R chunk

Option 2: Knit R chunk to HTML

  • Use for final production

Options for R chunks

Useful options


Options Default value Aim
echo TRUE Print code (= FALSE in a report for example)
eval TRUE Evaluate code (= FALSE if want to show code only)
warning TRUE Warning message (= FALSE to remove long warnings)
message TRUE Messages (= FALSE to remove long messages)
cache FALSE If TRUE only modified chunks will be evaluated
very useful for computing heavy codes
fig.height inches
fig.width inches

What can you do with Rmarkdown ?

Document your data analyses

  • If the data changes, you can re-run analysis in a matter of minutes
  • More and more journal request analyses scripts

Presentation

https://github.com/yihui/xaringan

Posters

https://github.com/brentthorne/posterdown

Curriculum vitae

https://cloud.r-project.org/web/packages/vitae/index.html

Website

https://bookdown.org/yihui/blogdown/

Quarto

Quarto

  • New flavor of markdown
  • Independant of R
  • Can include also Python, Julia chunks
  • Will evolve while R markdown will not be updated
  • Many new powerful feature

Quarto and R

  1. Different formatting of yaml options
  2. Different formatting of chunk options

Interactive documents (Shiny)

Recap

  • Rmarkdown: mix text, R chunk, R output
  • Compile to HTML or to PDF
  • Can be used for many different purposes
  • Use to document your analysis process (for papers…)
  • Use Quarto rather than R markdown

Next time: Metabarcode processing

R - markdown and Quarto