class: middle, title-slide # Using R Markdown ## An Introduction ### Dennis A. V. Dittrich ### 2022 --- layout: true <div class="my-footer"> <span><img src="img/tcb-logo.png" height="40px"></span> </div> --- .row[ .col-6[ ## Why R Markdown? <blockquote class="twitter-tweet"><p lang="en" dir="ltr">Hey, here's a short story whose moral is this: Consider writing empirical reports in RMarkdown... THREAD /1</p>— Heather Urry (@HeatherUrry) <a href="https://twitter.com/HeatherUrry/status/1100585163829006341?ref_src=twsrc%5Etfw">February 27, 2019</a></blockquote> <blockquote class="twitter-tweet"data-conversation="none"><p lang="en" dir="ltr">My point is this: If you think you'll ever be in the position of having to re-do stats for a manuscript at some point - and, c'mon, you know you will - then invest some time in establishing a reproducible manuscript workflow. 11/</p>— Heather Urry (@HeatherUrry) <a href="https://twitter.com/HeatherUrry/status/1100585200159985665?ref_src=twsrc%5Etfw">February 27, 2019</a></blockquote> ] .col-6[ <blockquote class="twitter-tweet" data-conversation="none"><p lang="en" dir="ltr">A new PDF compiled in a matter of seconds with all of the results - text stats, tables, figures - updated automatically throughout the manuscript LIKE MAGIC. ITS LIKE GODDAMN FUCKING MAGIC. /9 <a href="https://t.co/x32sN8eaai">pic.twitter.com/x32sN8eaai</a></p>— Heather Urry (@HeatherUrry) <a href="https://twitter.com/HeatherUrry/status/1100585195349135361?ref_src=twsrc%5Etfw">February 27, 2019</a></blockquote> ] ] ??? maybe embed this one too: https://twitter.com/dgkeyes/status/1101554699566641152 --- # Reproducible Research .row[.col-7[ **Computational reproducibility**: when detailed information is provided about code, software, hardware and implementation details. * Reviewable Research. * Replicable Research. * Confirmable Research. * Auditable Research. * Open or Reproducible Research. **Empirical reproducibility**: when detailed information is provided about non-computational empirical scientific experiments and observations. In practice this is enabled by making data freely available, as well as details of how the data was collected. ] .col-5[ **Statistical reproducibility**: when detailed information is provided about the choice of statistical tests, model parameters, threshold values, etc. This mostly relates to pre-registration of study design to prevent p-value hacking and other manipulations. <br/> A closely related concept is that of whether research is **replicable**, which is the idea that research results can be reproduced by independent researchers using different methods. .footnote[See [Reproducibility in Science](https://ropensci.github.io/reproducibility-guide/)] ]] ??? Reviewable Research. The descriptions of the research methods can be independently assessed and the results judged credible. (This includes both traditional peer review and community review, and does not necessarily imply reproducibility.) Replicable Research. Tools are made available that would allow one to duplicate the results of the research, for example by running the authors’ code to produce the plots shown in the publication. (Here tools might be limited in scope, e.g., only essential data or executables, and might only be made available to referees or only upon request.) Confirmable Research. The main conclusions of the research can be attained independently without the use of software provided by the author. (But using the complete description of algorithms and methodology provided in the publication and any supplementary materials.) Auditable Research. Sufficient records (including data and software) have been archived so that the research can be defended later if necessary or differences between independent confirmations resolved. The archive might be private, as with traditional laboratory notebooks. Open or Reproducible Research. Auditable research made openly available. This comprised well-documented and fully open code and data that are publicly available that would allow one to (a) fully audit the computational procedure, (b) replicate and also independently reproduce the results of the research, and (c) extend the results or apply the method to new problems. --- ## Anatomy of an R Markdown Document .row[ .col-7[.midi[ ````markdown --- title: "Diamond sizes" date: 2016-08-25 author: "First Last" output: html_document --- ```{r setup, include=FALSE} library(ggplot2) library(dplyr) smaller <- diamonds %>% filter(carat <= 2.5) ``` # Shine bright like a diamond We have data about `r nrow(diamonds)` diamonds. Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats. The distribution of the remainder is shown below: ```{r} smaller %>% ggplot(aes(carat)) + geom_freqpoly(binwidth = 0.01) ``` ```` ]] .col-5[ R Markdown file plain text file with extension _.Rmd_ ]] ??? This is what an R Markdown file looks like - plain text that you save with the extension .Rmd It has three parts --- ### Metadata: YAML header .row[.col-7[ ````markdown *--- *title: "Diamond sizes" *date: 2016-08-25 *author: "First Last" *output: html_document *--- ```{r setup, include=FALSE} library(ggplot2) library(dplyr) smaller <- diamonds %>% filter(carat <= 2.5) ``` # Shine bright like a diamond We have data about `r nrow(diamonds)` diamonds. Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats. The distribution of the remainder is shown below: ```` ] .col-5[#### "YAML Ain't Markup Language" It starts and ends with three dashes `---`, and has fields like the following: `title`, `author`, and `output`. `title` and `author` are special inputs which place the title and author information at the top of the document in large font. They are optional! `output: html_document` tells us we want this to be a HTML document. ]] ??? - a header between three dashes - we have these key-value pairs, like 'title: "Diamond sizes"' - with these we specify meta-data about the document, such as title, author date, etc. and information about what kind of output format we want --- ### Text .row[.col-7[ ````markdown --- title: "Diamond sizes" date: 2016-08-25 author: "First Last" output: html_document --- ```{r setup, include=FALSE} library(ggplot2) library(dplyr) smaller <- diamonds %>% filter(carat <= 2.5) ``` *# Shine bright like a diamond *We have data about `r nrow(diamonds)` diamonds. *Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats. *The distribution of the remainder is shown below: ```{r} smaller %>% ggplot(aes(carat)) + geom_freqpoly(binwidth = 0.01) ``` ```` ] .col-5[ **Text** is markdown. It provides a simple way to mark up text. ]] --- ### Code .row[.col-7[ ````markdown --- title: "Diamond sizes" date: 2016-08-25 author: "First Last" output: html_document --- *```{r setup, include=FALSE} *library(ggplot2) *library(dplyr) * *smaller <- diamonds %>% * filter(carat <= 2.5) *``` # Shine bright like a diamond We have data about `r nrow(diamonds)` diamonds. Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats. The distribution of the remainder is shown below: *```{r} *smaller %>% * ggplot(aes(carat)) + * geom_freqpoly(binwidth = 0.01) *``` ```` ] .col-5[Commands to be interpreted by R need to be inside of code chunks. ]] --- class: center ## What Can It Do? **Document** your analyses, make a **website**, write your **paper**, make **slides**... <img src="img/rmarkdown_universe.jpg" width="87%" style="display: block; margin: auto;" /> ??? let's do a quick demo credit: https://www.williamrchase.com/slides/intro_r_anthropology_2018#82 --- ## HTML, PDF, and Word (and more!) .center[ ![](img/rmarkdownflow.png) ] .row[.col-6[ One of the really great, powerful things about rmarkdown is that we can convert it to many different output types. The top three that you might be most likely to use are HTML, PDF, and Microsoft Word. There are others that we can discuss later. ] .col-6[ ### Questions * How do I convert to HTML, PDF, or Word? * How do I set options specific to each of these? * How can I include a screenshot of an interactive graphic in PDF or Word? ]] --- ## How do I convert to HTML, PDF, or Word? .row[.col-6[ Here are three ways to do this: 1. You can control this in the "knit" button <img src="img/rstudio-knit-button.png" width="60%" style="display: block; margin: auto;" /> You might notice that depending on the option you select, this changes things in the YAML - which is another way to control which output you have: <ol start = 2> <li>You can change the YAML option</li></ol> ```YAML title: "Exploring gapminder" output: html_document ``` ```YAML title: "Exploring gapminder" output: pdf_document ``` ```YAML title: "Exploring gapminder" output: word_document ``` </li></ol> ] .col-6[ <ol start = 3> <li>You can call the .remark-inline-code[render] function.</li></ol> ```r rmarkdown::render("example.Rmd", output_format = "html_document") rmarkdown::render("example.Rmd", output_format = "pdf_document") rmarkdown::render("example.Rmd", output_format = "word_document") ``` ]] --- ## A note on workflow with rmarkdown: ## HTML first, PDF/word later .row[.col-7[ It can be easy to get caught up with how your document looks. I highly recommend avoiding compiling to PDF or word until _you really need to_. [This is also recommended by the author of rmarkdown and knitr, Yihui Xie](https://yihui.name/en/2018/07/in-html-i-trust/). Because HTML doesn't have page breaks, this means that you can spend time working on generating content, and not trying to get figures to line up correctly. ]] --- ## Keyboard Shortcuts .row[.col-6[ Keyboard shortcuts tend to make our lives easier. Some that you might already be familiar with in day to day life include quickly saving (Cmd + S or Ctrl + S), or Undo (Cmd + Z or Ctrl + Z). ] .col-6[ There are many keyboard shortcuts that you can access in R, this section provides a brief tour of them, and why you might want to use them. ]] .center[.caption[Table of Common Shortcuts]] | Action | Windows/Linux | Mac | |-------------|---------------|----------------| | Knit document | Ctrl + Shift + K | Cmd + Shift + K | | Insert Chunk | Ctrl + Alt + I | Cmd + Option + I | | Run Current Chunk | Ctrl + Alt + C | Cmd + Option + C | | Jump to | Shift+Alt+J | Cmd+Shift+Option+J | | Show Keyboard Shortcut Reference | Alt+Shift+K | Option+Shift+K | | Delete the current line | Ctrl + D | Cmd + D| | Un/Comment out a line | Ctrl + Shift + C | Cmd + Shift + C| | Reformat Section | Ctrl + Shift + A | Cmd + Shift + A| --- class: center, middle # Basic markdown syntax --- .pull-left[ ### This... \*italics\* and \*\*bold\*\* <span>`</span>inline code` sub~2~ / superscript^2^ \~\~strikethrough\~\~ escaped: \\* \\_ \\\ endash: --, emdash: --- \> blockquote *Line break: End line with 2+ spaces, or backslash:* <br> Roses are red <br> Violets are blue Roses are red \ <br> Violets are blue ] .pull-right[ ### turns into this... *italics* and **bold** `inline code` sub<sub>2</sub> / superscript<sup>2</sup> ~~strikethrough~~ escaped: \* \_ \\ endash: –, emdash: — > blockquote Roses are red Violets are blue Roses are red <br> Violets are blue ] --- .pull-left[ ### This... \- unordered list <br> \- sub-item <br> \- sub-item 2 <br> \- sub-sub-item <br> 1\. ordered list <br> 2\. item 2 <br> \- sub-item 1 <br> \- sub-item 2 <br> <br> inline-math: $A = \pi\cdot r^{2}$ math-block: <span>$</span>$A = \pi\times r^{2}$$ ] .pull-right[ ### turns into this... - unordered list - sub-item - sub-item 2 - sub-sub-item 1. ordered list 1. item 2 <br> - sub-item 1 <br> - sub-item 2 inline-math: `\(A = \pi\cdot r^{2}\)` math-block: `$$A = \pi\times r^{2}$$` ] --- .pull-left[ ### This... \[text for hyperlink\](https://www.google.com) A footnote [^1] [^1]: here is the footnote text. <span><!-</span>- this is a comment that won't be shown -<span>-></span> \# Header 1 \#\# Header 2 \#\#\# Header 3 ] .pull-right[ ### turns into this... [text for hyperlink](https://www.google.com) A footnote<sup>1</sup> .footnote[[1] Here is the footnote text.] # Header 1 ## Header 2 ### Header 3 ] --- .your-turn[ ## Your Turn: Time for practice! .row[.col-7[ * *Create a new R Markdown file* (File > New File > R Markdown...) * *Knit to* - HTML, - PDF, - Word * *Tweak the content* - add your name and today's date to YAML header - add a paragraph, containing a header, **bold**, and *italics* - knit to output of your choice - what creates linebreaks and new paragraphs? ]]]
06
:
00
--- ### Code: Code chunks .col-11[ ![](img/chunk-parts.png) ] **Some common chunk options** (see e.g. [bookdown.org](https://bookdown.org/yihui/rmarkdown/r-code.html)) - `echo`: whether or not to display code in knitted output - `eval`: whether or to to run the code in the chunk when knitting - `include`: wheter to include anything from the from a code chunk in the output document ??? - `fig.cap`: figure caption - label: every chunk should ideally have a name. Naming things is hard, but follow these rules and you'll be fine: * one word that describes the action (e.g., "read") or the thing inside the code * separate words with "-" or "_" (e.g., `read-gapminder`) --- .row[.col-7[ ````markdown ```{r setup , include=FALSE} knitr::opts_chunk$set(echo = FALSE, fig.align = "center", fig.width = 4, fig.height = 4, dev = "png", cache = TRUE) ``` ```{r library} library(tidyverse) ``` ```{r functions} # A function to scale input to 0-1 scale_01 <- function(x){ (x - min(x, na.rm = TRUE)) / diff(range(x, na.rm = TRUE)) } ``` ```{r read-data} gapminder <- read_csv(here::here("data", "gapminder.csv")) ``` ```` ] .col-5[ ## RMarkdown hygiene recommendations You can control how the code is output by changing the code chunk options which follow the title. You can read more about the options at the official documentation: https://yihui.name/knitr/options/#code-evaluation I highly recommend that each document you write has separate chunks at the top for different kinds of tasks. ] ] --- ## Rmarkdown hygiene recommendations: .row[.col-6[ ### `setup` Normally, an R Markdown document starts with a chunk that's used to set some options that you want to define globally. `knitr::opts_chunk$set` sets default options for all chunks. ] .col-6[ ````markdown ```{r setup , include=F} knitr::opts_chunk$set( echo = FALSE, fig.align = "center", fig.width = 4, fig.height = 4, dev = "png", cache = TRUE) ``` ```` ] ] .row[.col-6[ In this case, I've told Rmarkdown: * `echo = FALSE`: I don't want any code printed by setting `echo = FALSE`. * `fig.align = "center"` Align my figures in the center ] .col-6[ * `fig.width = 4` & `fig.height = 4`. Set the width and height to 4 inches. * `dev = "png"`. Save the images as PNG * `cache = TRUE`. Save the output results of all my chunks so that they don't need to be run again. ]] --- ## Rmarkdown hygiene recommendations: .row[.col-6[ ### `library` In the `library` chunk, you put all the library calls. This helps make it clearer for anyone else who might read your work what is needed to run this document. I often go through the process of moving these `library` calls to the top of the document when I have a moment, or when I'm done writing. ] .col-6[ ````markdown ```{r library} library(tidyverse) ``` ```` ]] --- ## Rmarkdown hygiene recommendations: .row[.col-6[ ### `functions` In the `functions` chunk, you put any functions that you write in the process of writing your document. Similar to the `library` chunk, I write these functions as I go, as needed, and them move these to the top when I get a moment, or once I'm done. The benefit of this is that all your functions are in one spot, and you might be able to identify ways to make them work better together, or improve them separately. ] .col-6[ ````markdown ```{r functions} # A function to scale input to 0-1 scale_01 <- function(x){ (x - min(x, na.rm = TRUE)) / diff(range(x, na.rm = TRUE)) } ``` ```` ]] --- ## Rmarkdown hygiene recommendations: .row[.col-6[ ### `readr` In the `readr` chunk, you read in any data you are going to be using in the document. ] .col-6[ ````markdown ```{r read-data} gapminder <- read_csv(here::here("data", "gapminder.csv")) ``` ```` ]] .row[.col-7[ ### Benefits 1. The "top part" of your document contains all the metadata / setup info, and your global options. 1. It helps another person get oriented with your work - they know the settings, the functions used, and the special things that you wrote (your functions). 1. Remember, "another person" includes yourself in 6 months. ]] --- ## Including images .row[.col-6[ ### markdown syntax The markdown syntax to insert an image is: `![caption](path/to/image)` So we could insert the RMarkdown logo by doing the following: ````markdown ![R Markdown logo](img/rmarkdown.png) ```` ] .col-6[ Which would give us the following output: ![R Markdown logo](img/rmarkdown.png) ]] --- ## Including images .row[.col-7[ ### knitr syntax When we want more control over the output, like to center the image, and to make it smaller, then you can use `knitr::include_graphics()`, and control the figure size using the options `out.width`, and add a caption with `fig.cap`. ````markdown ```{r, out.width="30%", fig.align='center', fig.cap="R Markdown logo"} knitr::include_graphics("img/rmarkdown.png") ``` ```` ] .col-5[ <div class="figure" style="text-align: center"> <img src="img/rmarkdown.png" alt="R Markdown logo" width="30%" /> <p class="caption">R Markdown logo</p> </div> ]] --- ### Including plots .pull-left[ Printing figures is straightforward in the case of plots. You provide the plot you want to show in a code chunk! ````markdown ```{r, fig.cap = "A ggplot of car stuff"} cars %>% ggplot() + aes(x = speed, y = dist) + geom_point() + theme_minimal() ``` ```` ] .pull-right[ <img src="02.Rmd-intro_files/figure-html/unnamed-chunk-5-1.png" width="90%" style="display: block; margin: auto;" /> .caption[ A ggplot of car stuff ] ] --- ## Customising your figures .pull-left[ When you produce figures, you usually want to tweak them a little bit. A bit wider, perhaps a bit taller. Perhaps a different image type than "png". Maybe you need 600dpi because you're going to print it really big. So, how do you control these features? You can control the size and features of figures with the chunk options. Here, we are going to talk more specifically about how to customise your figures. ] .pull-right[ ### Questions * How do I change the height and width of a figure? * How to I change the type of output of a figure? (e.g., PDF, TIFF, PNG, JPG, SVG) * Can I set all the figure features globally? * How do I save the figures? ] --- ## Which chunk options should you care about for figures? .row[.col-6[ There are many chunk options that control your output, but only a few that you really need to worry about for your figures: - `fig.align`: How do you want your figure aligned? Takes one of the following inputs: "default", "center", "left", or "right"? - `fig.cap`: Would you like a caption for your figure? It takes a character vector as input: "My Amazing Graph" ] .col-6[ - `fig.height` & `fig.width`: How tall and wide would you like your figure in inches? Each takes one number (e.g., 7, or 9) [Note: these numbers are not quoted] - `out.height` & `out.width`: The height and width of your plot in the final file. This can be handy if you like the current aspect ratio of your plot, but you want to shrink it by say 50% - which you would do with "50%". You can also include LaTeX output or HTML output. Say for example, ".8/linewidth" or "8cm" for LaTeX, or "300px" for HTML. ]] --- .your-turn[ ## Your Turn: Time for practice! .row[.col-6[ Let's take a plot and show how it's output can change. * with `fig.height`, `fig.width`, `out.width`. 1. In your Rmarkdown document, create a new figure: ````markdown ```{r figure-1} library(ggplot2) ggplot(airquality, aes(x = Ozone, y = Solar.R)) + geom_point() ``` ```` ] .col-6[ <ol start=2> <li>Based on this first figure, create three new figures, with the respective dimensions (.remark-inline-code[fig.height] and .remark-inline-code[fig.width]) <ul> <li>2x2</li> <li>10x10</li> <li>4x7</li> </ul> </li> <li> Now add to those figures, the following: <ul> <li>.remark-inline-code[fig.align = "center"]</li> <li>.remark-inline-code[out.width = 50%]</li> </ul> </li></ol> ] ] ]
06
:
00
--- ## Setting global options .row[.col-7[ If we repeat adding the same chunk options for each figure, we might want to consider setting them globally. We can do this with the following code: ]] .row[.col-8[ ```r knitr::opts_chunk$set(chunk_option1 = TRUE, ...) ``` ]] --- ## Keeping your figures .row[.col-7[ You can set the options for your figures, which will change how they appear on the page, but this won't save the figures anywhere. In order to save the figures to file, you need to edit the YAML option `keep_md: true`: ```YAML --- title: "Awesome report" author: "You" output: html_document: keep_md: true --- ``` You'll notice that this creates some folders called "FILENAME_files" - you can control the specific name of the folder by setting `fig.path` like so: ```r knitr::opts_chunk$set(fig.path = "figs") ``` Which would instead create a new folder called "figs". ]] --- .your-turn[ ## Your Turn: Time for practice! .row[.col-7[ 1. Set global options in your document for: * `fig.height` * `figh.width` * `dev` 2. Save your images in your document by setting `keep_md: true` ] ]]
03
:
00
--- ## Including tables: `kable()` .row[.col-7[ To produce a table, I recommend you use the `kable` function from the `knitr` package. ]] .row[.col-9[ ````markdown ```{r} gapminder <- readr::read_csv(here::here("data", "gapminder.csv")) gapminder %>% head() %>% knitr::kable(caption = "A knitr kable table") ``` ```` <table> <caption>A knitr kable table</caption> <thead> <tr> <th style="text-align:left;"> country </th> <th style="text-align:left;"> continent </th> <th style="text-align:right;"> year </th> <th style="text-align:right;"> lifeExp </th> <th style="text-align:right;"> pop </th> <th style="text-align:right;"> gdpPercap </th> </tr> </thead> <tbody> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1952 </td> <td style="text-align:right;"> 28.801 </td> <td style="text-align:right;"> 8425333 </td> <td style="text-align:right;"> 779.4453 </td> </tr> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1957 </td> <td style="text-align:right;"> 30.332 </td> <td style="text-align:right;"> 9240934 </td> <td style="text-align:right;"> 820.8530 </td> </tr> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1962 </td> <td style="text-align:right;"> 31.997 </td> <td style="text-align:right;"> 10267083 </td> <td style="text-align:right;"> 853.1007 </td> </tr> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1967 </td> <td style="text-align:right;"> 34.020 </td> <td style="text-align:right;"> 11537966 </td> <td style="text-align:right;"> 836.1971 </td> </tr> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1972 </td> <td style="text-align:right;"> 36.088 </td> <td style="text-align:right;"> 13079460 </td> <td style="text-align:right;"> 739.9811 </td> </tr> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1977 </td> <td style="text-align:right;"> 38.438 </td> <td style="text-align:right;"> 14880372 </td> <td style="text-align:right;"> 786.1134 </td> </tr> </tbody> </table> ]] --- ## Including tables: `kable()` .row[.col-7[ Some other useful features of `kable` include setting the rounding number, with the `digits` option. For example, we could present the first 2 digits of each number like so: ]] .row[.col-10[ ````markdown ```{r} gapminder %>% head(n=4) %>% knitr::kable(caption = "The first 4 rows of the dataset gapminder", digits = 2) ``` ```` <table> <caption>The first 4 rows of the dataset gapminder</caption> <thead> <tr> <th style="text-align:left;"> country </th> <th style="text-align:left;"> continent </th> <th style="text-align:right;"> year </th> <th style="text-align:right;"> lifeExp </th> <th style="text-align:right;"> pop </th> <th style="text-align:right;"> gdpPercap </th> </tr> </thead> <tbody> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1952 </td> <td style="text-align:right;"> 28.80 </td> <td style="text-align:right;"> 8425333 </td> <td style="text-align:right;"> 779.45 </td> </tr> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1957 </td> <td style="text-align:right;"> 30.33 </td> <td style="text-align:right;"> 9240934 </td> <td style="text-align:right;"> 820.85 </td> </tr> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1962 </td> <td style="text-align:right;"> 32.00 </td> <td style="text-align:right;"> 10267083 </td> <td style="text-align:right;"> 853.10 </td> </tr> <tr> <td style="text-align:left;"> Afghanistan </td> <td style="text-align:left;"> Asia </td> <td style="text-align:right;"> 1967 </td> <td style="text-align:right;"> 34.02 </td> <td style="text-align:right;"> 11537966 </td> <td style="text-align:right;"> 836.20 </td> </tr> </tbody> </table> ]] --- ## Including tables: `kable()` .row[.col-7[ - When using [`kable`](https://www.rdocumentation.org/packages/knitr/versions/1.21/topics/kable), captions are set inside the `kable` function - The `kable` package is often used with the [`kableExtra`](https://cran.r-project.org/web/packages/kableExtra/vignettes/awesome_table_in_html.html) package - A number of other packages are available for making pretty tables, see [rmarkdown.rstudio.com](https://rmarkdown.rstudio.com/lesson-7.html) ]] --- ## Inline code .row[.col-7[ Inside your text you can include code with the syntax <span>`</span>r code here`. For example, <span>`</span>r 4 + 4` would output 8 in your text. ]] .row[.col-10[ ```r print(diamonds, n = 4) ``` ``` ## # A tibble: 53,940 × 10 ## carat cut color clarity depth table price x y z ## <dbl> <ord> <ord> <ord> <dbl> <dbl> <int> <dbl> <dbl> <dbl> ## 1 0.23 Ideal E SI2 61.5 55 326 3.95 3.98 2.43 ## 2 0.21 Premium E SI1 59.8 61 326 3.89 3.84 2.31 ## 3 0.23 Good E VS1 56.9 65 327 4.05 4.07 2.31 ## 4 0.29 Premium I VS2 62.4 58 334 4.2 4.23 2.63 ## # … with 53,936 more rows ``` ```r num_diamonds <- nrow(diamonds) ``` ]] .pull-left[ There are <span>`</span>r num_diamonds` rows in the `diamonds` dataset. ] .pull-right[ There are 53940 rows in the `diamonds` dataset. ] .row[.col-7[ What's great about this is that if your data changes upstream, then you don't need to work out where you mentioned your data, you just update the document. ]] --- .your-turn[ ## Your Turn: Time for practice! .row[.col-7[ In your R Markdown file, use code chunks to 1. include an image with `knitr::include_graphics` 2. include a table (using `kable`) 3. report a calculation inline 4. How do you set `knitr`'s global options to hide code by default? ] ]]
08
:
00
--- # Math .pull-left[ Want to include equations in your writing? Easy. rmarkdown supports LaTeX style equation writing. This section introduces the two types equations, inline, and display form, and how to number equations. ] .pull-right[ ### Questions - How to I create an equation? - LaTeX is funky, what are the basic math commands? ] .row[.col-7[ ### Some history Equation editing was first made available in TeX, which later become LaTeX, named after Leslie Lamport. ]] --- ## Some basic equations types .pull-left[ ### Inline equations are referenced by a pair of dollar signs: `$`. ``` So this text would have an equation here $E = mc^2$ ``` Generates: So this text would have an equation here `\(E = mc^2\)` ] .pull-right[ ### Display equations are referenced by two pairs of dollar signs: ```latex $$ E = mc^2 $$ ``` Generates: $$ E = mc^2 $$ ] .row[.col-7[ #### Viewing equations Understanding whether or not you have created the right equation can be difficult. Rstudio provides previews of your equations in text. ]] --- # Example math commands .row[.col-7[ LaTeX is an amazing language, but understanding how to create the equations can be (more than) a bit confusing at times. This section demonstrates some example equations that you might be familiar with. ]] .pull-left[ ### Fractions ```latex $$ \frac{1}{2} $$ ``` $$ \frac{1}{2} $$ ] .pull-right[ ### Sub and Super Scripts ```latex $$ Y = X_1 + X_2 $$ ``` $$ Y = X_1 + X_2 $$ ```latex $$ a^2 + b^2 = c^2 $$ ``` $$ a^2 + b^2 = c^2 $$ ] --- # Example math commands: .pull-left[ ### Square roots ```latex $$ \sqrt{p} $$ ``` $$ \sqrt{p} $$ ```latex $$ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$ ``` $$ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$ ] .pull-right[ ### Summations ```latex $$ \sum_{i = 1}^{n}{(\bar{x} - x_i)^2} $$ ``` $$ \sum_{i = 1}^{n}{(\bar{x} - x_i)^2} $$ ] --- # Example math commands: .row[.col-8[ ### Bayes Rule ```latex $$ Pr(\theta | y) = \frac{Pr(y | \theta) Pr(\theta)}{Pr(y)} $$ ``` $$ Pr(\theta | y) = \frac{Pr(y | \theta) Pr(\theta)}{Pr(y)} $$ ```latex $$ Pr(\theta | y) \propto Pr(y | \theta) Pr(\theta) $$ ``` $$ Pr(\theta | y) \propto Pr(y | \theta) Pr(\theta) $$ ]] --- # Example math commands: .row[.col-8[ ### Linear Model ```latex $$ Y \sim X\beta_0 + X\beta_1 + \epsilon $$ ``` $$ Y \sim X\beta_0 + X\beta_1 + \epsilon $$ ```latex $$ \epsilon \sim N(0,\sigma^2) $$ ``` $$ \epsilon \sim N(0,\sigma^2) $$ ]] --- .your-turn[ ## Your Turn: Time for practice! .row[.col-7[ * Add some math to your example document ] ]]
03
:
00
--- ## Citing Articles & Bibliography Styles .pull-left[ Now that you are near the end of your data analysis, you want to make sure that you've correctly cited the articles and software you wanted to mention. ] .pull-right[ ### Questions * What sort of things can I cite? * How do I manage my `.bib` file? * How do I change the citation style? ] --- ## Citations .row[.col-8[ Put references in a plain text file with the extension **.bib**, in **BibTex** format (most reference managers can do this - e.g. [Zotero](https://www.zotero.org), or [Mendelay](https://www.mendeley.com)).<sup>1</sup> In the highlighed section, 'Shea2014' is the **citation identifier**. .small[ ```bibtex *@article{Shea2014, author = {Shea, Nicholas and Boldt, Annika}, journal = {Trends in Cognitive Sciences}, pages = {186--193}, title = {{Supra-personal cognitive control}}, volume = {18}, year = {2014}, doi = {10.1016/j.tics.2014.01.006}, } ``` ] Reference this file in your YAML header ```yaml --- title: "Citation test" *bibliography: example.bib output: html_document --- ``` ] .col-4[ .small[[1] The bibliography can be in other formats as well, including EndNote (**.enl**) and RIS (**.ris**), see [rmarkdown.rstudio.com/ authoring_bibliographies_and_citations.html](https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html) ]]] --- ## Citations .row[.col-7[ In your text, citations go inside brackets and separated by semicolons. By default the Chicago author-date format is used in the output: ]] .row[.col-6[ ### This... Blah blah [@Shea2014; @Lottridge2012]. ] .col-6[ ### turns into this... Blah blah (Shea et al. 2014; Lottridge et al. 2012). ]] .row[.col-6[ Shea et al. says blah [-@Shea2014]. @Shea2014 says blah. Blah blah [see @Shea2014, pp. 33-35; also @Wu2016, ch. 1]. ] .col-6[ Shea et al. says blah (2014). Shea et al. (2014) says blah. Blah blah (see Shea et al. 2014, 33–35; also Wu 2016, ch. 1). ]] .row[.col-7[ You can add e.g `csl: my-style.csl` in the YAML header to change to other formats - browse through and download styles at [zotero.org/styles](https://www.zotero.org/styles) ]] --- .row[ .col-4[ ## Citations For an easy way to insert citations, try the [`citr`](https://github.com/crsh/citr) RStudio add-in. `install.packages("citr")` or `devtools:: install_github("crsh/citr")` ] .col-8[ .center[ <img src="https://raw.githubusercontent.com/crsh/citr/master/tools/images/addin_demo.gif" width="85%" style="display: block; margin: auto;" /> ]]] --- ## What is a .bib file? .row[.col-7[ Good question. `.bib` is a format for storing references from the haydey of LaTeX. It contains reference information for the article. Here's an example one ]] .row[.col-8[ ```bibtex @Book{ggplot2, author = {Hadley Wickham}, title = {ggplot2: Elegant Graphics for Data Analysis}, publisher = {Springer-Verlag New York}, year = {2016}, isbn = {978-3-319-24277-4}, url = {http://ggplot2.org}, } ``` ]] --- ## And how do I generate these .bib files? .row[.col-7[ You can use the `citation` function in R for R itself, and for specific R packages. We can get the citation for R with: `citation()` ]] .small[ ``` ## ## To cite R in publications use: ## ## R Core Team (2021). R: A language and environment for ## statistical computing. R Foundation for Statistical ## Computing, Vienna, Austria. URL ## https://www.R-project.org/. ## ## A BibTeX entry for LaTeX users is ## ## @Manual{, ## title = {R: A Language and Environment for Statistical Computing}, ## author = {{R Core Team}}, ## organization = {R Foundation for Statistical Computing}, ## address = {Vienna, Austria}, ## year = {2021}, ## url = {https://www.R-project.org/}, ## } ## ## We have invested a lot of time and effort in creating R, ## please cite it when using it for data analysis. See also ## 'citation("pkgname")' for citing R packages. ``` ] --- ## And how do I generate these .bib files? .row[.col-7[ For journals or books, you'll need to get a specific .bib file. Yes, this can be a bit of a pain, but this is where you need to use a reference management software like * [Zotero](https://www.zotero.org/), * [Mendeley](https://www.mendeley.com/), * [papers](https://www.papersapp.com/), * [paperpile](https://paperpile.com/), * [JabRef](http://www.jabref.org/). The important thing to to **use something**. These all allow you to get .bib files of your articles, which you can then placed in your `references.bib` file. ]] --- ## How to change the bibliography style .row[.col-7[ OK so now you've got your bibliography, but you now need to change it to _a specific journal format_. Luckily, this is now pretty easy. You can change your citation style from the [citation style language](https://citationstyles.org/) Similar to how you referred to your `.bib` file with `bibliography: ref.bib`, you do something similar: ```YAML --- title: author: output: html_document bibliography: references.bib csl: my_journal.csl --- ``` ]] --- .your-turn[ ## Your Turn: Time for practice! .row[.col-7[ 1. Generate a references.bib file to place your citations 1. Using the `citation()` function, generate citations for the packages we have used, "dplyr", "ggplot2", "gapminder", and for the R software, place these in your `references.bib` file 1. Reference these in your document 1. Add a final heading in your file called `# References` 1. Render the document 1. select your bibliography style to be one from your favourite journal at the CSL github repo here: https://github.com/citation-style-language/styles (> 1800 citation styles and counting) or https://www.zotero.org/styles ] .col-5[ <ol start=7> <li> place this in your rstudio project</li> <li> refer to it in the YAML</li> <li> Render your document and observe your greatness</li> </ol> ] ]]
10
:
00
--- class: center, middle # That's all for today <img src="img/mindblown.gif" width="100%" style="display: block; margin: auto;" /> --- # Further Reading .row[.col-7[ ### Keyboard Shortcuts - The [Rstudio Cheat Sheet](https://www.rstudio.com/wp-content/uploads/2016/01/rstudio-IDE-cheatsheet.pdf) has an index of shortcuts. - This [help file](https://support.rstudio.com/hc/en-us/articles/206382178-Customizing-Keyboard-Shortcuts) has a guide to customising keyboard shortcuts. ### Knitr Options - [Official knitr documentation](https://yihui.name/knitr/options/#plots) ### Math - https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#equations - https://oeis.org/wiki/List_of_LaTeX_mathematical_symbols ]]