Here’s the agenda for today:

  1. markdown and R Markdown basics
  2. producing some R Markdown documents
  3. concluding…

1. markdown and R Markdown basics

1.1 what is markdown and what is R markdown?!

Markdown is a format for writing in plain text. There are many “flavors” of markdown, but they’re all fairly similar. For example there’s wordpress-flavored markdown, wikipedia-flavored markdown, and stack overflow-flavored markdown. There’s also something like “R-flavored markdown”, which is typed directly into a plain-text document with extension .Rmd (like this one).

Markdown documents usually end up getting compiled by some system or another. Basically what the compiler does is it takes your plain text document and builds a fancy version of it: the “compiled”/“output” version has the same content but is now a different kind of document – like .docx or .pdf or .html – and has whatever kind of style/formatting you’d expect for that kind of document.

When you’re actually writing, special formatting makes the structure of the document visible (e.g. with ###’s for section headings). And when you actually compile the document, those same structural components will still be there – they’ll just be prettified and adapted to whatever the output format it (e.g. html, pdf, or docx).

The point of markdown is that it’s simultaneously easy for humans to use and easy for computers to understand. Writing in markdown is much, much simpler than writing in e.g. Microsoft Word. There’s no dropdowns and no options relating to indentation, page-margins, etc.: you’re just typing whatever you want to type into a text editor. All the formatting is done externally, e.g. by some css rules that you have somewhere else, or by the engine that’s making your output document (which will be knitr in our case).

note: key to markdown is the idea that content is specified separate from style. This principle also drives the internet, and (I’d say) is directly reflected in the recent move away from older html protocols and towards the complete integration of HTML5 and CSS.

1.2 structure of an R markdown source document (.rmd file)

  • header (“YAML header”)
  • text
    • just normal text, in markdown format
    • any html you want to add (optional)
  • code chunks
    • the setup chunk (specify defaults)
    • all other chunks (show code and/or output)
  • inline R code
    • to evaluate and format as text:
    • to display as code:
  • html/css (optional)

1.3 output formats you can create from .rmd files

  • html document
  • pdf document (via \(\LaTeX\))
  • MS Word document
  • slides (various output options, but beyond scope of course)
  • “flexdashboards” (beyond scope of course)
  • Shiny apps (beyond scope of course)

1.4 making a “quick report” from an R script

You can use the shortcut ctrl+shift+k to build an output document, even on a normal R script. This will cause knitr to build a “quick report” – basically, a visually nice version of your R script.

2. producing some R Markdown documents

2.1 quick example documents

the simplest one

Here’s the simplest R Markdown file that one could make, alongside its output: