--- output: html_document: toc: true toc_float: true bibliography: RMD_course_BibTeX.bib link-citations: true csl: nature.csl --- ```{r setup, include=FALSE} knitr::opts_chunk$set(echo = FALSE) tutblog <- read.csv("birgand_tutblogs.csv", encoding = "UTF-8") selection<-tutblog[tutblog$name=="Crash course on R markdown",] ``` `r paste0("# ",selection$name)` `r paste0("### *by ",selection$authors,"*")`
`r paste0("*started ",selection$date," and updated ",format(Sys.Date(), '%Y-%m-%d'),"*")`
*[code for this document](https://raw.githubusercontent.com/francoisbirgand/francoisbirgand.github.io/master/tutorial-RMarkdown_instructions.Rmd)*

# Overview The research world (and eventually the teaching world as well) is moving very fast towards requiring *reproducible research* [@Buckheit1995-ls; @Kuhne2009-tn; @The_Yale_Law_School_Roundtable_on_Data_and_Code_Sharing2010-xp; @Wicherts2012-oo; @Pasquier2017-os; @Peng2011-og]. "The ultimate product of academic research is the paper along with the laboratory notebooks and full computational environment used to produce the results in the paper such as the code, data, etc. that can be used to reproduce the results and create new work based on the research" ([Wikipedia](https://en.wikipedia.org/wiki/Reproducibility#Reproducible_research)). The consequences are that we should change our habits and certainly start preparing all our manuscripts, presentations, homework, etc., in a format that is clean and *reproducible*, i.e., if you give anyone the code, this person can reproduce the document exactly. This document seeks to make this transition somewhat easier using R Markdown.
# What is the Markdown language? I borrow much of the very good text from [Dr Shalizi](http://www.stat.cmu.edu/~cshalizi/rmarkdown/) from Carnegie Mellon University about Mark-up and Markdown. Many word processing programs, like Microsoft Word, employ the "what you see is what you get" (WYSIWYG) principle: you want some words to be printed in italics? You select/highlight the words or phrase, do ctrl-I or click Italic, and they're in italics right there on the screen. You want some words to be in a bigger, different font, so you just select the font, and so on. This works well enough for the vast majority of things that are still currently done but is not a reproducible basis for a system of text formatting, because it depends on a particular program (a) knowing what you mean and (b) implementing it well. > For several decades, really serious systems for writing have been based on a very different principle, that of _marking up_ text. The essential idea in a **mark-up language** is that it consists of ordinary text, _plus_ signs which indicate how to change the formatting or meaning of the text. Some mark-up languages, like HTML (Hyper-Text Markup Language) use very obtrusive markup; others, like the language called **Markdown**, are more subtle. Obviously, there has been a play-on-word between Mark-up and Markdown...! Much of the content of the paragraphs above looks like this in HTML: ```

What is the Markdown language?

I borrow ... from Dr Shalizi from ...

Many ...that of marking up text. The essential idea in a mark-up language is that it consists of ordinary text, plus signs which indicate how to change the formatting or meaning of the text. Some mark-up languages, like HTML (Hyper-Text Markup Language) use very obtrusive markup; others, like the language called Markdown, are more subtle.

``` and like this in Markdown: ``` ## What is the Markdown language? I borrow ... from [Dr Shalizi](http://www.stat.cmu.edu/~cshalizi/rmarkdown/) from ... Many ... that of _marking up_ text. The essential idea in a **mark-up language** is that it consists of ordinary text, _plus_ signs which indicate how to change the formatting or meaning of the text. Some mark-up languages, like HTML (Hyper-Text Markup Language) use very obtrusive markup; others, like the language called **Markdown**, are more subtle. ``` > Every mark-up language needs to be **rendered** somehow into a format which actually includes the fancy formatting, images, mathematics, computer code, etc., etc., specified by the mark-up. For HTML, the rendering program is called a "web browser". Most computers which know how to work with Markdown at all know how to render it as HTML (which you can then view in a browser), PDF (which you can then view in Acrobat or the like), or Word (which you can then view in Microsoft Word). > The advantages of mark-up languages are many: they tend to be more portable across machines, less beholden to particular software companies, and more stable over time than WYSIWYG word processing programs. R Markdown is, in particular, both "free as in beer" (you will never pay a dollar for software to use it) and "free as in speech" (the specification is completely open to all to inspect). The sheer stability of mark-up languages makes them superior for scientific documents. [**Markdown**](http://daringfireball.net/projects/markdown/basics) is thus a simple *mark-up language* with the goal of enabling people "to write using an easy-to-read, easy-to-write plain text format, and optionally convert it to structurally valid XHTML (or HTML)" [(wikipedia)](https://en.wikipedia.org/wiki/Markdown). OK, so imagine that this is a writing language that is very close to plain text, where the most useful alteration of text or *mark-up* (headings, bold, italic, web references, etc.) are simpler than the html codes. I encourage you to read the [wikipedia definition](https://en.wikipedia.org/wiki/Markdown) of Markdown to have more details of why and how it came about.
# The 'R twist' of Markdown: R Markdown Now the beauty of Markdown is that some very smart people have thought that one could in fact embed R codes, within the text, such that in the end, a document could contain all the text and code to create figures and tables. Other, just as smart people, have thought that one could use all the beauty of the [LaTeX](https://en.wikipedia.org/wiki/LaTeX), particularly for editing equations. They have also added the possibility to add citations, bibliography. All this to say that they have added all the features that students/researchers need and have dreamt about for a while! So the 'R twist' to Markdown is called 'R Markdown'. One of the hidden beauties is that R Mardown uses [Pandoc](https://pandoc.org/MANUAL.html), which is a universal document converter, to *render* the text. The result is that you and I will now write in R Markdown and will have the possibility of publishing what we have written in many output formats, which include among many others HTML, pdf, and Word. This is one of the major advantages compared to LaTeX, which can only produce pdf documents. Now, this is really a crash course on R Markdown for the applications I have found most useful until now. But since I started writing this tutorial, the people who have come up with all this fantastic concept have written and released the [Definitivie guide to R Markdown](https://bookdown.org/yihui/rmarkdown/). I cannot recommend enough to go in there to get all important details certainly missing in this tutorial. After browsing through the definitive guide, I find that there is still room for a 'crash course', and I will keep maintaining this tutorial.
# R Markdown in R Studio I have had a very low opinion of [R studio](https://www.rstudio.com/) until 2017 because I never liked the text editor, I always thought (still do in fact...!) that on a normal screen, things were just too cramped. *But*, I must say that I have come to change my mind, principally thanks to the possibilities that R Markdown offers, and because R Mardown is hosted in [R studio](https://en.wikipedia.org/wiki/RStudio). The goal of this document is thus to introduce you to R Markdown and the things you need to get to know quickly for authoring HTML, PDF, MS Word documents, but also many other interesting outputs. All the details on using R Markdown can be found at . I encourage you to browse the [gallery](http://rmarkdown.rstudio.com/gallery.html) and then spend time to get familiarized on what can be done with it on the [step by step tutorial](http://rmarkdown.rstudio.com/lesson-1.html). I still think that there is nothing like playing with examples to make sense of things. I assume that you have now browsed through the guide reference and you have installed the `rmarkdown and knitr` packages in RStudio. If not, in the console, type `install.packages("rmarkdown","knitr")`. First, you want to open a `Rmd` document. Go to `File -> New File -> R Markdown...` and click OK with the default variables. Click the `Knit` button just above the window where the document just appeared. Another 'Choose Encoding' pop-up window will appear, click OK with the default values. The system will ask you where you want to save this document and under what name. Then, an html preview pop-up window should appear where there is headings, text, hyperlinks, results from some `R commands` and a simple plot. OK, time to look at the `.Rmd` file content.
# Components of R Markdown There are three components to an R Mardown document (.Rmd): 1. **YAML header** 2. **Text** 3. **Code chunks** After you are done reading this document, you will want to be able to find a [reference summary of R markdown here](https://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf). * YAML header: The header of the document starts with a [YAML](https://en.wikipedia.org/wiki/YAML) which acronym started as "Yet Another Markup Language" and now apparently stands for "YAML Ain't Markup Language"... The YAML Header specifies how the document will be formatted. * Text: most of your writing will be done using plain text, very much like you have been doing with Word, with mark-up alterations. Many details on mark-up are in the [section devoted to text below](#text). Spell check can be done using + A spell check button to the right of the save button (with "ABC" and a check mark). + Edit > Check Spelling... + The F7 key * Code Chunks: This is where you will add the actual `R` code that will create tables and figures. The details are in the [section devoted to Code Chunks below](#code-chunks) ***
## YAML header The header of the document starts with a [YAML](https://en.wikipedia.org/wiki/YAML) which acronym started as "Yet Another Markup Language" and now apparently stands for "YAML Ain't Markup Language"... The YAML Header specifies how the document will be formatted. For example, in this case, we have specified that the output will be an HTML document. Yours should look very close to something like this: ``` --- title: "Untitled" author: "François Birgand" date: "12/10/2017" output: html_document --- ``` The `title` will appear as your title document. It is unrelated to the name of your file. If you are writing a paper, this will be the title of your paper. The `author` will appear when you render or 'knit' your document under the title and introduced by a "by"... The `date` corresponds to the initial date of creation. If you want to use the date at the time you `knit` the document, you may consider putting an inline code ([details below](#code-chunks)) such as `` `r '\x60r format(Sys.Date() \x60%d %B %Y\x60)\x60'` ``.
### Output document in YAML You can change the `output: html_document`, to `output: github_document`, to `output: word_document`, to `output: pdf_document`. If you are having trouble with the `pdf_document` output, this means that the LaTeX[^latex] engine is not installed on your computer. For this I am borrowing instructions from [here](https://rpubs.com/rcourse998/module6-rmarkdown) where they suggest these links: * For Windows: Go to [https://miktex.org/howto/install-miktex](https://miktex.org/howto/install-miktex) and follow directions to install MikTex. * For Mac: Go to [https://tug.org/mactex/mactex-download.html](https://tug.org/mactex/mactex-download.html) and follow directions to install MacTex. In the YAML, one puts some broad instructions on how [Pandoc](https://pandoc.org/MANUAL.html) needs to interpret the document, one big information being the `output`. You can see right away that with just one document, you can create at least 4 different documents. when you typed `output: github_document`, there was an html preview that popped-up, but in the background, a `*.md` file was created. This `*.md*` file is interpreted by GitHub to render the document within the GitHub environment. If you try to click on a `*.html` file that is hosted on GitHub, only code will appear, and not the rendered html document.
### Table Of Content R markdown provides the possibility of Table Of Content or `toc` that you put as a variable in the `YAML` part of the R Markdown. The `toc` will appear at the head of the document and will give you links to all the heading levels you have created. This is very useful to quickly give you an outline of your document and allows you to get directly to the section of your choice. The YAML of this document is ``` --- title: "Crash course on R Markdown" author: "François Birgand" date: "09/10/2017" output: html_document: toc: true toc_float: true bibliography: RMD_course_bibtex.bibtex link-citations: true csl: journal-of-hydrology.csl --- ``` Notice that the `html_document` has now been put on another line for organization purposes, but also note that a `:` has been added at the end of `html_document:`. This tells [Pandoc](https://pandoc.org/MANUAL.html) that among the `html_document`, a `toc` should be added.
### Bibliography I have created and maintained for over 15 years a database written in Microsoft Access of around 2000 articles, most of them photocopied and typed in the database by hand during and after my Ph.D. (yes, I should have a medal!...) but I have to admit that this system is past its time... I have now switched to Paperpile. There are many other referencing software out there now ([a list and comparison can be found here](https://en.wikipedia.org/wiki/Comparison_of_reference_management_software)). The beauty of them is that they will all export in recognized formats and this is what we care about here. So no more copy/paste of references from some pdf. We are going into *reproducible research*. This means that all the articles you want to work with will be entered in the reference database of your choice. Make sure you start one ASAP! In the YAML header, you can now see `bibliography: RMD_course_bibtex.bibtex`. This means that there is a file named `RMD_course_bibtex.bibtex` that is located in the same directory as the .Rmd file, which when we 'knit', [Pandoc](https://pandoc.org/MANUAL.html) will look for. You can access this `.bibtex` file in the GitHub directory. There is actually a possibility to add within the `.Rmd` document itself, the text needed for Pandoc to read the references, but unless you only have very few references, this can become very messy quickly. See the [RStudio Bibliographies documentation](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html#bibliographies) for more details. In short, in this file, there is a list of articles which information is coded according to the format chosen. By the way, a lot of the details for the bibliography are available on the [RStudio Bibliographies documentation](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html#bibliographies). R Markdown will recognize up to 10 different formats. The one Paperpile exports is `.bibtex`, so this is the one I have have added in the YAML header. The filename extension will determine the *rendering* process, so make sure you have the right extension as well. So, in the `.bibtex` file I have, the first article appears as ``` @ARTICLE{Kuhne2009-tn, title = "Improving the Traditional Information Management in Natural Sciences", author = "K{\"u}hne, Martin and Liehr, Andreas W", journal = "Data Sci. J.", volume = 8, pages = "18--26", year = 2009, issn = "1683-1470, 0308-9541", doi = "10.2481/dsj.8.18" } ``` The first item after "ARTICLE{" is the unique identifier for the article. The identifier of this article is `Kuhne2009-tn`. When one wants to cite this article, one will say something like "reproducible research has been suggested to become the norm [@Kuhne2009-tn]". And you would code like ``` "reproducible research has been suggested to become the norm [@Kuhne2009-tn]" ``` If you want to say that "Kühne et al. [-@Kuhne2009-tn] have shown that etc.", you would add a "dash" just before the "@" and code it as such: ``` Kühne et al. [-@Kuhne2009-tn] have shown that etc." ``` If you want to cite several references, you would add a semicolon between the two such as in: ``` "reproducible research has been suggested to become the norm [@Kuhne2009-tn; @Buckheit1995-ls]" ``` Notice that among all the fields from the example above, there are `doi` and `issn`. `doi` stands for "Digital Object Identifier". `issn` stands for International Standard Serial Number (ISSN), which is an eight-digit serial number used to uniquely identify a serial publication. The `doi` value in this example is `10.2481/dsj.8.18`, which is unique in the world. These `doi` are applied to articles but not only. They are also applied to data. Eventually, all data that will be used in an article will have to have its own `doi` and all the codes that are used to analyze the data will refer to this unique `doi`. This is not quite implemented yet (in 2017), but will likely be by 2022. `doi` or `url` (not added here; stands for Uniform Resource Locator. Quite a mouthful, really, for what it is: a web address) are not necessarily exported from your reference software by default. Make sure you add this possibility, as `doi` is almost routinely added in the reference list in most journals.
The reference list of the citations will appear right after you place ``` # References ``` at the bottom of your Rmd docucment. When rendering your document, the list will appear automatically afterwards, and if you have in text notes, these will appear underneath.
### Link to citations One very nice feature is to create hyperlinks from the in-text citations to the citations in the reference section. For this, just add `link-citations: true` in the YAML header.
### CSL and styling of citations CSL stands for Citation Style Language. The CSL line command is an option for the citation styles to be used in your document. You can comment it out by adding a "#" in front of it and the default .CSL file will apply without you noticing it. Each journal has its own way of handling how an article/reference should be cited in the text, and in the reference section, and there are hundreds of different styles out there... You can read lots of details on this [CSL primer](http://docs.citationstyles.org/en/stable/primer.html) about how all this works. While I was writing this tutorial, I did not specify at first the citation style. And I kept getting, using the same example as before, "(Kühne and Liehr 2009)”, although I wanted "(Kühne and Liehr, 2009)”, i.e., with a comma between the authors and the date, because this is the way I always did it and I think it is a lot better this way. Then I started thinking about the journals for which the inline citations are numbers, sometimes in brackets, sometimes without brackets... what a nightmare...! Actually it is extremely simple: all this is done automatically when you specify the CSL corresponding to the journal style following which you wish to write. For this, you can pick at [https://github.com/citation-style-language/styles](https://github.com/citation-style-language/styles) the *.CSL file you are looking for (actually there are too many of them and they are not all displayed). The fastest way is to Google " CSL", and you will land on the CSL file you are looking for. I recommend that you click on the `raw` icon on GitHub, and copy all the file in a text editor. Warning! You need to make sure that your text editor does not add any weird formatting or add an extension at the end of the file. I had that problem and I could not see the extension on my computer, although I had the option to display so. Save the file in the same directory as your .Rmd. So, to go back with my struggling to style the inline citation and the "missing comma", it turns out that the default CSL file uses a "[Chicago author-date format](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html#citation_styles)" (I am not sure what this means exactly), which in text styling is "(author date)", without the comma...! If you use "journal-of-hydrology.CSL", you will see that all of a sudden after you `knit`, the commas just appeared...! Eureka! If you use "nature.CSL" (because we all want to be ready when we publish in Nature!), you will see that there are no more in-line citations, just numbers in superscript, hyphenated when needed, and the references are all in order, with the journal names in italics, the journal volume in bold, the year in parenthesis at the end, etc.! Is not that wonderful? Without your doing anything, other than adding the citation properly in the text following the guidelines above. You can, if you want and have a lot of time to waste, take existing CSL files and modify them to have your own custom citation style. Make sure you take an "independent" CSL file and modify it. Most of them are dependent upon a "source" or independent one, and the code in the CSL file is just saying how the dependent file should slightly alter the independent one. Good instructions on how to do this can be found on the excellent [CSL primer](http://docs.citationstyles.org/en/stable/primer.html).
## Text The markdown syntax is very simple and this is one of the reasons why it is so attractive. You can find all the syntax with [this R Markdown reference document](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf), but I thought I would go through them as I have learned several tricks I could not easily find in the document.
### Paragraph Breaks and Forced Line Breaks To insert a break between paragraphs, include a single completely blank line. To force a line break, put _two_ blank spaces at the end of a line. ``` To insert a break between paragraphs, include a single completely blank line. To force a line break, put _two_ blank spaces at the end of a line. ```
### Headers The character `#` at the beginning of a line means that the rest of the line is interpreted as a section header. The number of `#`s at the beginning of the line indicates the level of the section (1,2,3, etc.). For instance, `Components of R Markdown` above is preceded by a single `#`, because it is of level 1 but `Headers` at the start of this paragraph is preceded by `###` because it is of level 3. Up to six levels are understood by Markdown. Do not interrupt these headers by line-breaks. Make sure that in your .Rmd file, you leave a blank line before a header, otherwise, `pandoc` will not render it as a header.
### Italics and bold ``` *italics* and _italics_ ``` renders *italics* and _italics_ ``` **bold** and __bold__ ``` renders **bold** and __bold__
### Supbscripts and superscripts To write sub- and superscripts, like in NO~3~^-^ or PO~4~^3-^ write as ``` NO~3~^-^ or PO~4~^3-^ ``` PO~4~^3-^ does not look as neat as $PO_4^{3-}$ ``` PO~4~^3-^ does not look as neat as $PO_4^{3-}$ ``` but looks more seamless in a normal text because the former does not appear as an [equation](#inline-equations) while the other does.
### Lists ``` * unordered list * item 2 + sub-item 1 #4 before + + sub-item 2 #4 before + ``` * unordered list * item 2 + sub-item 1 + sub-item 2 ``` 1. ordered list 2. item 2 + sub-item 1 #4 before + + sub-item 2 #4 before + ``` 1. ordered list 2. item 2 + sub-item 1 + sub-item 2 In the ordered list, there is a subtlety unrevealed in the Rmardown documentation, which is that the numbering *always* increases, and that *only* the number value of the first item matters. So, one cannot have a list in a decreasing order (which is too bad because when one makes a list of his/her publications, it is nice to have a decreasing order...), and the only number that matters is the first one. So this code
``` 5. ordered list 7. item 2 2. item 2 # blank line for list to take into effect b. sub-item 1 #4 before b a. sub-item 2 ```
renders this: 5. ordered list 7. item 2 2. item 2 b. sub-item 1 a. sub-item 2
### Quotations > R Markdown is, in particular, both "free as in beer" (you will never pay a dollar for software to use it) and "free as in speech" (the specification is completely open to all to inspect). Is a quotation from [Dr Shalizi](http://www.stat.cmu.edu/~cshalizi/rmarkdown/) which code starts with a `>` ``` > R Markdown is, in particular, both "free as in beer" etc. ```
### Computer type This is to differentiate regular text from `code text` so that both can be easily differentiated: `R` vs R. ``` This is to differentiate regular text from `code text` so that both can be easily differentiated: `R` vs R. ``` An entire paragraph of code which is rendered as a "code box" in html (but not in pdf) starts with three "back-ticks", and end the same
### Symbols and Special characters The principal keys, like the alphabet, are understood univocally across platforms such as Windows, Mac OS, or Linux. However, there are special characters such °, ² or µ that have different embedded codes across the different platforms. For example, if you and your co-worker work on the same document and one works using Windows and the other uses Mac, the actual symbol in the code text may not show the same one from one to the other plateform. For example, if I write in an R markdown document "10 m²" and I have added the ² symbol by typing on a PC "Alt+0178", as this corresponds to the ascii code for ² in Windows, the same document open on a Mac will render "10 m?", because it cannot interpret the embedded code for ²... Several consequences: 1. **NEVER** use special characters in variable names in an `R` code, 2. in an R markdown document, use the HTML Number or HTML name in the text [HTML Number and Names](https://www.ascii.cl/htmlcodes.htm) can be found on this [ascii page](https://www.ascii.cl/htmlcodes.htm) or on this page for [greek letter codes and some other symbols](http://www.dionysia.org/html/entities/symbols.html) So to type T°C, m², µm, or pε you type like this ``` So to type T°C, m², µm, or pε you type like this ``` Do not forget to add the ";" !!!


### Absolute Links ``` a link within the text as a [link](www.rstudio.com) ``` a link within the text as a [link](www.rstudio.com). Absolute links to images, see [Images](#images) below.
### Links within the document #### Linking to a heading If you want to provide a link (other than the Table Of Content at the beginning of the document) to an existing heading like [The 'R twist' of Markdown: R Markdown](#the-r-twist-of-markdown-r-markdown), you type it as below ``` If you want to provide a link back to an existing heading like [The 'R twist' of Mardown: R Markdown](#the-r-twist-of-markdown-r-markdown), you type it as below ``` It provides a link using the regular `[text](*address of text*)` syntax for a link. Now, this time the `*address of text*` is not an absolute address as shown in the [link example](#link_ref), but rather a relative one which has a format like `(#...)`. Mardown took the name of the heading `The 'R twist' of Markdown: R Markdown` and created for each heading what it referred to as a `
` in HTML and it gave it an identity or `id`, and for this example here, it gave in HTML code `
`. It is important to notice that the original text of the heading `"The 'R twist' of Markdown: R Markdown"` is transformed into `"the-r-twist-of-markdown-r-markdown"` where all signs have been removed, spaces replaced by a `"-"`, and all characters are in lower case.
#### Linking to anywhere in the document There is, to my knowledge, no native way of doing this in Markdown. One must borrow some HTML code and it is very simple. You must add an `anchor` link in your document. where you want the page to line up. So in the [link example](#link_ref) example above point to the absolute link example, the code is like that. ``` So in the [link example](#link_ref) example above point to the absolute link example, the code is like that. ``` I thus added in the line just above where I want the link this HTML code where `` stands for `anchor`. ``` ```
### Footnotes You can add footnotes in the text by adding `[^footnote]` right next to the word concerned and add the `[^footnote]:` with the text next to it JUST BEFORE the `# References` section.
### Images To add images in a document, add a `!` in front of the same syntax as for links such as: ``` ![](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png) ``` to render: ![](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png) You can modify the width of the image by adding e.g., `{width = 50%}` to have the image take 50% of the width of the page ``` ![](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=50%} ``` to render: ![](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=50%}
To align the image, there is no native way of doing it in Markdown, so you can use a little bit of HTML code like `
...
` such as below. Apparently, it might not work that great in html5 though... ```
![](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=25%}
``` to render:
![](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%}

You can add a caption by just adding the "Using a caption this time" in the brackets. ![Using a caption this time](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%} ``` ![Using a caption this time ](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%} ``` Now, you can add an image in the text like this ![Using a caption this time](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%} and it will work just fine. ``` Now, you can add an image in the text like this ![Using a caption this time](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%} and it will work just fine. ``` However, you can see that the caption was not added. So for the caption to be added, there needs to be a return before and after the image code. If you include the image like this ![Using a caption this time](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%} The caption does not appear. ``` However, you can see that the caption was not added. So for the caption to be added, there needs to be a return before and after the image code. If you include the image like this ![Using a caption this time](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%} The caption does not appear. ``` But if you leave a blank line before and after like this ![Using a caption this time](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%} The caption will appear. ``` But if you leave a blank line before and after like this ![Using a caption this time](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%} The caption will appear. ``` Now if you want to center **both figure and caption**, you need to add `
` a blank line, the image code, a blank line, then `
`, and it will appear like this:
![*__Using a caption this time__*](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%}
```
![*__Using a caption this time__*](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%}
``` And you can see that adding `*__ __*` aound the caption text put the caption in bold and italic as well. To have an image linked to a particular website, you can use this code: ``` [![caption](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png)](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png) ```
If you do that, however, the caption will not show any more, even though you have the proper number of lines before and after. If you want a caption below with a link, you will have to add this underneath. So if you want both the image and the caption to have clickable links, and centered like this
[![](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%}](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png) [This is the corresponding clickable caption I want](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png)

you would write: ```
[![](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png){width=33%}](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png) [This is the corresponding clickable caption I want](https://www.bae.ncsu.edu/wp-content/themes/riddick/dist/images/ncstate-logos/ncstate-brick-2x2-red.png)
```
## Editing equations in R Markdown We do not write nearly as much math in our field than our colleagues in statistics or math. But we do enough to have a bit of a tutorial. I have borrowed this entire section from the [excellent tutorial from Dr Shalizi](http://www.stat.cmu.edu/~cshalizi/rmarkdown/#math-in-r-markdown) again. R Markdown gives you the syntax to render complex mathematical formulas and derivations, and have them displayed very nicely. Like code, the math can either be inline or set off (displays).
### Inline equations Inline math is marked off witha pair of dollar signs (`$`), as $\pi r^2$ or $e^{i\pi}$. ``` Inline math is marked off witha pair of dollar signs (`$`), as $\pi r^2$ or $e^{i\pi}$. ```
### Set off equations Mathematical displays are marked off with `\[` and `\]`, as in \[ e^{i \pi} = -1 \] ``` Mathematical displays are marked off with `\[` and `\]`, as in \[ e^{i \pi} = -1 \] ``` Once your text has entered math mode, R Markdown turns over the job of converting your text into math to a different program, called LaTeX. This is the most common system for typesetting mathematical documents throughout the sciences, and has been for decades. It is extremely powerful, stable, available on basically every computer, and completely free. It is also, in its full power, pretty complicated. Fortunately, the most useful bits, for our purposes, are actually rather straightforward.
### Elements of Math Mode * Most letters will be rendered in italics (compare: a vs. `a` vs. $a$; only the last is in math mode, i.e., `$a$`). The spacing between letters also follows the conventions for math, so don't treat it as just another way of getting italics. (Compare _speed_, in simple italics, with $speed$, in math mode, i.e., `$speed$`) * Greek letters can be accessed with the slash in front of their names, as `\alpha` for $\alpha$. Making the first letter upper case gives the upper-case letter, as in `\Gamma` for $\Gamma$ vs. `\gamma` for $\gamma$. (Upper-case alpha and beta are the same as Roman A and B, so no special commands for them.) * There are other "slashed" (or "escaped") commands for other mathematical symbols: + `\times` for $\times$ + `\cdot` for $\cdot$ + `\leq` and `\geq` for $\leq$ and $\geq$ + `\subset` and `\subseteq` for $\subset$ and $\subseteq$ + `\leftarrow`, `\rightarrow`, `\Leftarrow`, `\Rightarrow`, `\rightleftharpoons` for $\leftarrow$, $\rightarrow$, $\Leftarrow$, $\Rightarrow$, $\rightleftharpoons$ + `\approx`, `\sim`, `\equiv` for $\approx$, $\sim$, $\equiv$ + See, e.g., http://web.ift.uib.no/Teori/KURS/WRK/TeX/symALL.html for a fuller listing of available symbols. (http://tug.ctan.org/info/symbols/comprehensive/symbols-a4.pdf lists _all_ symbols available in `LaTeX`, including many non-mathematical special chracters) * Subscripts go after an underscore character, `_`, and superscripts go after a caret, `^`, as `\beta_1` for $\beta_1$ or `a^2` for $a^2$. * Curly braces are used to create groupings that should be kept together, e.g., `a_{ij}` for $a_{ij}$ (vs. `a_ij` for $a_ij$). * If you need something set in ordinary (Roman) type within math mode, use `\mathrm`, as `t_{\mathrm{in}}^2` for $t_{\mathrm{in}}^2$. * If you'd like something set in an outline font ("blackboard bold"), use `\mathbb`, as `\mathbb{R}` for $\mathbb{R}$. * For bold face, use `\mathbf`, as ``` (\mathbf{x}^T\mathbf{x})^{-1}\mathbf{x}^T\mathbf{y} ``` for \[ (\mathbf{x}^T\mathbf{x})^{-1}\mathbf{x}^T\mathbf{y} \] * Accents on characters work rather like changes of font: `\vec{a}` produces $\vec{a}$, `\hat{a}` produces $\hat{a}$. Some accents, particularly hats, work better if they space out, as with `\widehat{\mathrm{Var}}` producing $\widehat{\mathrm{Var}}$. * Function names are typically written in romans, and spaced differently: thus $\log{x}$, not $log x$. `LaTeX`, and therefore `R Markdown`, knows about a lot of such functions, and their names all begin with `\`. For instance: `\log`, `\sin`, `\cos`, `\exp`, `\min`, etc. Follow these function names with the argument in curly braces; this helps `LaTeX` figure out what exactly the argument is, and keep it grouped together with the function name when it's laying out the text. Thus `\log{(x+1)}` is better than `\log (x+1)`. * Fractions can be created with `\frac`, like so: ``` \frac{a+b}{b} = 1 + \frac{a}{b} ``` produces \[ \frac{a+b}{b} = 1 + \frac{a}{b} \] * Sums can be written like so: ``` \sum_{i=1}^{n}{x_i^2} ``` will produce \[ \sum_{i=1}^{n}{x_i^2} \] The lower and upper limits of summation after the `\sum` are both optional. Products and integrals work similarly, only with `\prod` and `\int`: \[ n! = \prod_{i=1}^{n}{i} \] \[ \log{b} - \log{a} = \int_{x=a}^{x=b}{\frac{1}{x} dx} \] `\sum`, `\prod` and `\int` all automatically adjust to the size of the expression being summed, producted or integrated. * "Delimiters", like parentheses or braces, can automatically re-size to match what they're surrounding. To do this, you need to use `\left` and `\right`, as ``` \left( \sum_{i=1}^{n}{i} \right)^2 = \left( \frac{n(n-1)}{2}\right)^2 = \frac{n^2(n-1)^2}{4} ``` renders as \[ \left( \sum_{i=1}^{n}{i} \right)^2 = \left( \frac{n(n-1)}{2}\right)^2 = \frac{n^2(n-1)^2}{4} \] + To use curly braces as delimiters, precede them with slashes, as `\{` and `\}` for $\{$ and $\}$. * Multiple equations, with their equals signs lined up, can be created using `eqnarray`, as follows. ``` \[ \begin{eqnarray} X & \sim & \mathrm{N}(0,1)\\ Y & \sim & \chi^2_{n-p}\\ R & \equiv & X/Y \sim t_{n-p} \end{eqnarray} \] ``` \[ \begin{eqnarray} X & \sim & \mathrm{N}(0,1)\\ Y & \sim & \chi^2_{n-p}\\ R & \equiv & X/Y \sim t_{n-p} \end{eqnarray} \] Notice that `&` surrounds what goes in the middle on each line, and each line (except the last) is terminated with `\\`.
## Code in "Chunks" and within the text The real beauty of R Markdown is the ability of adding R codes that can be rendered or interpreted along with the mark-up text. R code can be inserted as "chunks" and "in-line".
### Inline code ``` You can embed some r code within the text by using `r '\x60r signif(max(Q),3)\x60'` to give 5 significant digits to the number $\pi$ ``` You can embed some r code within the text by using Maximum flow = `r signif(max(Q),3)` m³ to give 5 significant digits to the number $\pi$.
### Code chunks A code **chunk** is simply an off-set piece of code by itself. It is preceded by ` ```{r} ` on a line by itself, and ended by a line which just says ` ``` `. The code itself goes in between. The code
```{r cars}
summary(cars)
```
generates these results: ```{r cars} summary(cars) ``` First, in the syntax, the word "cars" after the "{r " is the name of the chunk (see below). To let the renderer program know that this is now a `R` code, the letter "r" needs to follow the "{". You can also embed plots, for example: ```{r pressure, echo=FALSE} plot(pressure) ```
#### Markdown tables and the "kable" function coming soon... #### Chunk results options Code chunks (but not inline code) can take a lot of **options** which modify how they are run, and how they appear in the document. These options go after the initial `r` and before the closing `}` that announces the start of a code chunk. One of the most common options turns off printing out the code, but leaves the results alone: ` ```{r, echo=FALSE} `
Another runs the code, but includes neither the text of the code nor its output. ` ```{r, include=FALSE} ` This might seem pointless, but it can be useful for code chunks which do set-up like loading data files, or initial model estimates, etc.
Another option prints the code in the document, but does not run it: ` ```{r, eval=FALSE} ` This is useful if you want to talk about the (nicely formatted) code.
Another option on the results of the code is that it generate all results "as-is", which is very nice when your code generates mark-up text to be rendered by `Pandoc`. ` ```{r, results="asis"} `
By default, the results of a chunk with have `##` as a prefix. You can remove this by putting ` ```{r, comment=FALSE} `
Sometimes, running of the code will generate warnings and messages. These can be turned off in the output by using ` ```{r, warning=FALSE, message = FALSE} ` #### Naming Chunks You can give chunks names immediately after their opening, like ` ```{r, clevername} `. This name is then used for the images (or other files) that are generated when the document is rendered. #### Adjusting figure sizes and alignments These details are discussed in the accompanying written article on instantaneous vs. interval-average flow data. #### "Caching" Code Chunks (Re-Running Only When Changed) By default, R Markdown will re-run all of your code every time you render your document. If some of your code is slow, this can add up to a lot of time. You can, however, ask R Markdown to keep track of whether a chunk of code has changed, and only re-run it if it has. This is called **caching** the chunk.
```{r, cache=TRUE}
summary(cars)
```
```{r, cache=TRUE} summary(cars) ``` One issue is that a chunk of code which hasn't changed itself might call on results of earlier, modified chunks, and then we _would_ want to re-run the downstream chunks. There are options for manually telling R Markdown "this chunk depends on this earlier chunk", but it's generally easier to let it take care of that, by setting the `autodep=TRUE` option. 1. If you load a package with the `library()` command, R Markdown isn't smart enough to check whether the package has changed (or indeed been installed, if you were missing it). So that won't trigger an automatic re-running of a cached code chunk. 2. To manually force re-running all code chunks, the easiest thing to do is to delete the directory R Markdown will create (named something like _filename_`_cache`) which it uses to store the state of all code chunks.
#### Setting Defaults for All Chunks You can tell R to set some defaults to apply to all chunks where you don't specifically over-ride them. Here are the ones I generally use:
```{r, eval=FALSE}
# Need the knitr package to set chunk options
library(knitr)

# Set knitr options for knitting code into the report:
# - Don't print out code (echo)
# - Save results so that code blocks aren't re-run unless code changes (cache),
# _or_ a relevant earlier code block changed (autodep), but don't re-run if the
# only thing that changed was the comments (cache.comments)
# - show the error messages (message)
# - Don't clutter R output with warnings (warning)
# This _will_ leave error messages showing up in the knitted report
opts_chunk$set(echo=FALSE,
               cache=TRUE, autodep=TRUE, cache.comments=FALSE,
               message=TRUE, warning=FALSE)
```
This sets some additional options beyond the ones I've discussed, like not re-running a chunk if only the comments have changed (`cache.comments = FALSE`), and leaving out messages and warnings. (I'd only recommend suppressing warnings once you're sure your code is in good shape.) I would typically give this set-up chunk itself the option `include=FALSE`. You can over-ride these defaults by setting options for individual chunks.
#### More Chunk options See [http://yihui.name/knitr/options/] for a complete listing of possible chunk options.


# Additional Subtleties ## Creating anchors and links within a page Now, further down in the document, you might be interested in linking back up if you want to make a link to a particular heading or a particular place in the document that is not a heading.
## Challenges with the "back-ticks" As I was writing this document, I wanted some of the code to appear as I wrote it, in the "code frames". It turns out that to illustrate that to run a code in line the text, one needs to use `` `r '\x60r signif(pi,5)\x60'` `` , well it is not simple because the `` `r '\x60'` `` is interpreted as containing some code! Therefore, it is not interpreted as text not intended to be rendered...!! So it is a bit of a tour de force to make it appear and being uninterpreted. It turns that in R, if you type ``` '\x60' ``` it will return the "back-tick" symbol `` `r '\x60'` ``. But to display it I have to type in the text ``` == =r '\x60'= == ``` where for illustration purposes, I have replaced the "back-ticks", by the "=" signs. For another example to display `` `r '\x60r signif(pi,5)\x60'` `` in the text, I actually coded ``` == =r '\x60r signif(pi,5)\x60'= == ``` where again I have replaced the "back-ticks" with "=" signs. [^latex]: In the 1970s, the great computer scientist Donald Knuth wrote a mark-up language, and a rendering program for that language, called `TeX` (pronounced "tech"), for writing complex mathematical documents. In the 1980s, the computer scientist Leslie Lamport extended `TeX` in ways that made it rather more user-friendly, and called the result `LaTeX` (pronounced "la-tech")
# References