class: center, middle, inverse, title-slide .title[ # Getting Started with R Markdown ] .subtitle[ ## Beginner to intermediate level tutorial for R Markdown ] .author[ ### Dave Bosworth
EMRR Branch
Collaborative Science and Innovation Section ] .date[ ### Part 1: October 17, 2022
Part 2: December 6, 2022 ] --- # Introduction - A little about me -- - About you - Most of you have used R before - Some of you have used R Markdown before - All of you want to learn about using R Markdown to help with communicating your scientific work --- # Tutorial Outline -- R Markdown basics: What is it, and why should I use it? **Activity 1:** Open test file, load data, and run code -- Basic syntax and structure **Activity 2:** Create new document, practice using some syntax options, knit file to html -- Code chunks and inline code **Activity 3:** Inserting and running code -- Code chunk options **Activity 4:** Modify code chunk options -- Basic Pandoc-header options **Activity 5:** Modify YAML options --- # Tutorial Outline - continued Adding and formatting tables **Activity 6:** Tables -- Adding interactive elements: plotly, leaflet, datatable (DT) **Activity 7:** Interactive elements -- Adding tabs **Activity 8:** Tabs -- Open Questions -- GitHub Introduction --- # What is R Markdown? - R-specific file type (.Rmd) that provides a platform for science communication -- - Used to save and execute code just like an R script, but in a notebook format -- - Allows for code and text narrative in the same document --- # How is R Markdown different than an R script? - Results from code and narrative text can be stitched ("knitted") together in the output -- - Allows for many output options including: - HTML, PDF, and Microsoft Word - presentation slides - books and scientific articles - dashboards and shiny applications - websites --- # Why use R Markdown? - Organize your code into "chunks" that can be run individually (notebook format) -- - Save code and narrative text together in one document -- - Share code and results with others - reproducible, transparent, clearly communicated -- - Can be used to create automated reports --- class: inverse, middle # Activity 1 ### Basic Setup - Create new R Project for tutorial - Add files to new R Project: - markdown_format_examples.Rmd - Monthly_Catch_CPUE.csv - rmarkdown_activities_code.R - test_rmarkdown.Rmd - DWR_Logo.png - Open test_rmarkdown.Rmd file - Knit test_rmarkdown.Rmd to make sure it renders correctly --- # R Markdown Document Structure ## Metadata (YAML header) Optional section for rendering options (pandoc) as key: value pairs ```r --- title: "Testing R Markdown" author: "Dave Bosworth" date: '`r format(Sys.Date(), "%B %d, %Y")`' output: html_document --- ``` --- # R Markdown Document Structure ## Narrative Text Narration formatted with markdown - - Plain text - Headers - Text formatting (bold, italic) - Links - Images - Numbered and unordered lists - Code - Equations [R Markdown Reference Guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf) --- # R Markdown Document Structure ## Code chunks - Sections of embedded R code within the document - Code is run when R Markdown file is "knitted" with results displayed in the output document ```r plot(pressure) ``` <!-- --> --- class: inverse, middle # Activity 2 ### Basic Usage - Create new Rmd document - Practice using some markdown syntax options - see markdown_format_examples.Rmd file for examples - "Knit" Rmd file to html --- # Code within R Markdown ### Code chunks ```r summary(cars) ``` ``` ## speed dist ## Min. : 4.0 Min. : 2.00 ## 1st Qu.:12.0 1st Qu.: 26.00 ## Median :15.0 Median : 36.00 ## Mean :15.4 Mean : 42.98 ## 3rd Qu.:19.0 3rd Qu.: 56.00 ## Max. :25.0 Max. :120.00 ``` -- *** ### Inline code ```r # Today's date is `r Sys.Date()` ``` Today's date is 2022-12-06 --- # File paths and working directories in R Markdown This can be a source of confusion, so its worthwhile taking a moment to cover this: - The default working directory when an .Rmd file is knitted is the .Rmd document directory - The default working directory of an R project is the root directory of the R project - So it's possible to have different working directories when you are running code from code blocks in an .Rmd file versus when you knit the .Rmd file - A useful R package to help with working directories and file paths is the [`here` R package](https://here.r-lib.org/) - The `here::here()` function points to the root directory of an R project regardless of what the current working directory is --- class: inverse, middle # Activity 3 ### Inserting and running code - Add code chunks to Rmd document: - Load R packages - Import Monthly CPUE data - Plot monthly CPUE data - Practice using inline code --- # Code Chunk Options ### message, warning `message = TRUE` ```r library(tidyverse) ``` ``` ## ── Attaching packages ─────────────────────────────────────── tidyverse 1.3.2 ── ## ✔ ggplot2 3.3.6 ✔ purrr 0.3.5 ## ✔ tibble 3.1.8 ✔ dplyr 1.0.10 ## ✔ tidyr 1.2.1 ✔ stringr 1.4.1 ## ✔ readr 2.1.3 ✔ forcats 0.5.2 ## ── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ── ## ✖ dplyr::filter() masks stats::filter() ## ✖ dplyr::lag() masks stats::lag() ``` -- *** `message = FALSE` ```r library(tidyverse) ``` --- # Code Chunk Options ### eval, include, echo - `eval` - default is `eval = TRUE` - if `eval = FALSE`, the code will not run in the code block when "knitted", but the code appears in the output file -- - `include` - default is `include = TRUE` - if `include = FALSE`, the code and results won't appear in output file, but the code is still executed and results can be used by other code chunks -- - `echo` - default is `echo = TRUE` - if `echo = FALSE`, the code won't appear in the output file, but the results are still displayed --- # Code Chunk Options ### Figure output options - `fig.height`, `fig.width` - the height and width in inches for figures created by the code chunk - Default figure dimensions are `fig.width = 7` and `fig.height = 5` -- - `fig.align` - allows for custom alignment of figures in the output file. Can be "left", "right", or "center" - Default alignment is left -- - `fig.cap` - figure caption - `fig.alt` - alt text for a figure --- class: inverse, middle # Activity 4 ### Modify code chunk options - message TRUE vs FALSE - eval = FALSE - include = FALSE - echo = FALSE - Figure output options --- # Basic Pandoc-header options Standard options: title, author, date, output type ```r --- title: "Testing R Markdown" author: "Dave Bosworth" date: "October 17, 2022" output: html_document --- ``` -- Make the date dynamic by using R code in the YAML header: ```r --- title: "Testing R Markdown" author: "Dave Bosworth" date: "`r Sys.Date()`" output: html_document --- ``` --- # Basic Pandoc-header options ## HTML Output Options - Table of Contents .pull-left[ #### Header *** ```r --- output: html_document: toc: true toc_float: collapsed: false --- ``` ] .pull-right[ #### Output *** <img src="images/YAML_TOC.png" width="80%" /> ] --- # Basic Pandoc-header options ## HTML Output Options - Code Folding and Download .pull-left[ #### Header *** ```r --- output: html_document: code_folding: show code_download: true --- ``` ] .pull-right[ #### Output *** <img src="images/YAML_code_folding_download.png" width="40%" /> ] --- # Basic Pandoc-header options ## HTML Output Options - Bootswatch Themes .pull-left[ #### Header *** ```r --- output: html_document: theme: bootswatch: solar --- ``` ] .pull-right[ #### Output *** <img src="images/YAML_solar_theme.png" width="90%" /> ] Use `bslib::bootswatch_themes()` to list available themes --- class: inverse, middle # Activity 5 ### Modify YAML options - Dynamic date - Table of contents - Code folding and download - bootswatch themes --- # Adding and formatting tables ### Basic printing ```r df <- head(mtcars) df ``` ``` ## mpg cyl disp hp drat wt qsec vs am gear carb ## Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4 ## Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4 ## Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1 ## Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1 ## Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2 ## Valiant 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1 ``` --- # Adding and formatting tables ### Kable ```r library(knitr) kable(df) ``` | | mpg| cyl| disp| hp| drat| wt| qsec| vs| am| gear| carb| |:-----------------|----:|---:|----:|---:|----:|-----:|-----:|--:|--:|----:|----:| |Mazda RX4 | 21.0| 6| 160| 110| 3.90| 2.620| 16.46| 0| 1| 4| 4| |Mazda RX4 Wag | 21.0| 6| 160| 110| 3.90| 2.875| 17.02| 0| 1| 4| 4| |Datsun 710 | 22.8| 4| 108| 93| 3.85| 2.320| 18.61| 1| 1| 4| 1| |Hornet 4 Drive | 21.4| 6| 258| 110| 3.08| 3.215| 19.44| 1| 0| 3| 1| |Hornet Sportabout | 18.7| 8| 360| 175| 3.15| 3.440| 17.02| 0| 0| 3| 2| |Valiant | 18.1| 6| 225| 105| 2.76| 3.460| 20.22| 1| 0| 3| 1| --- # Adding and formatting tables ### Kable styling ```r library(kableExtra) kable(df, format = "html") %>% kable_styling(font_size = 10) ``` <table class="table" style="font-size: 10px; margin-left: auto; margin-right: auto;"> <thead> <tr> <th style="text-align:left;"> </th> <th style="text-align:right;"> mpg </th> <th style="text-align:right;"> cyl </th> <th style="text-align:right;"> disp </th> <th style="text-align:right;"> hp </th> <th style="text-align:right;"> drat </th> <th style="text-align:right;"> wt </th> <th style="text-align:right;"> qsec </th> <th style="text-align:right;"> vs </th> <th style="text-align:right;"> am </th> <th style="text-align:right;"> gear </th> <th style="text-align:right;"> carb </th> </tr> </thead> <tbody> <tr> <td style="text-align:left;"> Mazda RX4 </td> <td style="text-align:right;"> 21.0 </td> <td style="text-align:right;"> 6 </td> <td style="text-align:right;"> 160 </td> <td style="text-align:right;"> 110 </td> <td style="text-align:right;"> 3.90 </td> <td style="text-align:right;"> 2.620 </td> <td style="text-align:right;"> 16.46 </td> <td style="text-align:right;"> 0 </td> <td style="text-align:right;"> 1 </td> <td style="text-align:right;"> 4 </td> <td style="text-align:right;"> 4 </td> </tr> <tr> <td style="text-align:left;"> Mazda RX4 Wag </td> <td style="text-align:right;"> 21.0 </td> <td style="text-align:right;"> 6 </td> <td style="text-align:right;"> 160 </td> <td style="text-align:right;"> 110 </td> <td style="text-align:right;"> 3.90 </td> <td style="text-align:right;"> 2.875 </td> <td style="text-align:right;"> 17.02 </td> <td style="text-align:right;"> 0 </td> <td style="text-align:right;"> 1 </td> <td style="text-align:right;"> 4 </td> <td style="text-align:right;"> 4 </td> </tr> <tr> <td style="text-align:left;"> Datsun 710 </td> <td style="text-align:right;"> 22.8 </td> <td style="text-align:right;"> 4 </td> <td style="text-align:right;"> 108 </td> <td style="text-align:right;"> 93 </td> <td style="text-align:right;"> 3.85 </td> <td style="text-align:right;"> 2.320 </td> <td style="text-align:right;"> 18.61 </td> <td style="text-align:right;"> 1 </td> <td style="text-align:right;"> 1 </td> <td style="text-align:right;"> 4 </td> <td style="text-align:right;"> 1 </td> </tr> <tr> <td style="text-align:left;"> Hornet 4 Drive </td> <td style="text-align:right;"> 21.4 </td> <td style="text-align:right;"> 6 </td> <td style="text-align:right;"> 258 </td> <td style="text-align:right;"> 110 </td> <td style="text-align:right;"> 3.08 </td> <td style="text-align:right;"> 3.215 </td> <td style="text-align:right;"> 19.44 </td> <td style="text-align:right;"> 1 </td> <td style="text-align:right;"> 0 </td> <td style="text-align:right;"> 3 </td> <td style="text-align:right;"> 1 </td> </tr> <tr> <td style="text-align:left;"> Hornet Sportabout </td> <td style="text-align:right;"> 18.7 </td> <td style="text-align:right;"> 8 </td> <td style="text-align:right;"> 360 </td> <td style="text-align:right;"> 175 </td> <td style="text-align:right;"> 3.15 </td> <td style="text-align:right;"> 3.440 </td> <td style="text-align:right;"> 17.02 </td> <td style="text-align:right;"> 0 </td> <td style="text-align:right;"> 0 </td> <td style="text-align:right;"> 3 </td> <td style="text-align:right;"> 2 </td> </tr> <tr> <td style="text-align:left;"> Valiant </td> <td style="text-align:right;"> 18.1 </td> <td style="text-align:right;"> 6 </td> <td style="text-align:right;"> 225 </td> <td style="text-align:right;"> 105 </td> <td style="text-align:right;"> 2.76 </td> <td style="text-align:right;"> 3.460 </td> <td style="text-align:right;"> 20.22 </td> <td style="text-align:right;"> 1 </td> <td style="text-align:right;"> 0 </td> <td style="text-align:right;"> 3 </td> <td style="text-align:right;"> 1 </td> </tr> </tbody> </table> --- class: inverse, middle # Activity 6 ### Tables - Basic table printing - Kables - Basic kable options - kableExtra --- # Adding interactive elements ## datatable (DT) ```r library(DT) datatable(mtcars, options = list(pageLength = 5)) ```
--- # Adding interactive elements ## plotly .pull-left[ ```r library(plotly) plt <- ggplot( data = mtcars, aes(x = wt, y= mpg, color = cyl) ) + geom_point() ggplotly(plt, width = 500, height = 400) ``` ] .pull-right[
] --- # Adding interactive elements ## leaflet .pull-left[ ```r library(leaflet) leaflet(width = 400, height = 400) %>% addTiles() %>% addMarkers( lng = 174.768, lat = -36.852, popup = "The birthplace of R" ) ``` ] .pull-right[
] --- class: inverse, middle # Activity 7 ### Interactive elements - Datatables - Datatable options - Plotly - Leaflet maps - Leaflet map options --- # Adding tabs <img src="images/Tabset_example.png" width="70%" /> --- class: inverse, middle # Activity 8 ### Tabs - Adding tabs - Format appearance and behavior of tabs --- # Open Questions??? --- # GitHub Introduction - Participants poll -- - Tutorial will be held through MS Teams - **Date and Time to be Announced**