From 1ce2edf818966a4b9bcaf03fbd404b3fd98cbde8 Mon Sep 17 00:00:00 2001 From: Hao Ye Date: Mon, 12 Apr 2021 22:28:11 -0400 Subject: [PATCH] update slides and lesson file structure --- .github/workflows/pkgdown.yaml | 4 +- .zenodo.json | 19 ++++---- DESCRIPTION | 10 ++++- README.Rmd | 64 +++++++++++++++++++++++++++ README.md | 28 +++++++----- _pkgdown.yml | 6 +-- resources.md | 4 +- slides/slides.Rmd | 79 +++++++++++++++++++++++++--------- 8 files changed, 165 insertions(+), 49 deletions(-) create mode 100644 README.Rmd diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 5960f27..ecff13c 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -41,9 +41,9 @@ jobs: - name: Install package run: R CMD INSTALL . - - name: Generate syllabus + - name: Generate notes run: | - RMDconverter::process_slides("slides/slides.Rmd", out_file = "syllabus.md") + RMDconverter::process_slides("slides/slides.Rmd", out_file = "notes.md") shell: Rscript {0} - name: Render slides diff --git a/.zenodo.json b/.zenodo.json index e2ea6b2..cce11bd 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -1,21 +1,22 @@ { -"title": "An Introduction to Writing Reproducible Manuscripts Using RMarkdown", -"creators": [ + "title": "An Introduction to Writing Reproducible Manuscripts Using RMarkdown", + "creators": [ { "affiliation": "University of Florida", "name": "Hao Ye", "orcid": "0000-0002-8630-1458" } -], - "description": "RMarkdown is a versatile document format that can combine text, R code, figures, and tables together in a single document, and create formatted output as PDFs, MS Word files, slides, websites, and more. This workshop will provide a basic introduction to using RMarkdown, how to insert code, tables, figures, and format references, and an overview of the possible output formats.", - "keywords": [ + ], + "description": "RMarkdown is a versatile document format that can combine text, R code, figures, and tables together in a single document, and create formatted output as PDFs, MS Word files, slides, websites, and more. This workshop will provide a basic introduction to using RMarkdown, how to insert code, tables, figures, and format references, and an overview of the possible output formats.", + "keywords": [ "Open Educational Resources", "Research Support Skills", "Reproducible Report", "Literate Programming", - "R Markdown" + "R Markdown", + "Workshop" ], - "access_right": "open", - "license": "CC-BY-4.0", - "upload_type": "lesson" + "access_right": "open", + "license": "CC-BY-4.0", + "upload_type": "lesson" } diff --git a/DESCRIPTION b/DESCRIPTION index 1a4d492..fbb3018 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,13 +1,13 @@ Package: RMDintro Title: An Introduction to Writing Reproducible Manuscripts Using RMarkdown -Version: 1.0.1 +Version: 1.1.0 Authors@R: person(given = "Hao", family = "Ye", role = c("aut", "cre"), email = "haoye@ufl.edu", comment = c(ORCID = "0000-0002-8630-1458")) -Description: What the package does (one paragraph). +Description: RMarkdown is a versatile document format that can combine text, R code, figures, and tables together in a single document, and create formatted output as PDFs, MS Word files, slides, websites, and more. This workshop will provide a basic introduction to using RMarkdown, how to insert code, tables, figures, and format references, and an overview of the possible output formats. License: CC BY 4.0 Encoding: UTF-8 LazyData: true @@ -19,3 +19,9 @@ Imports: xaringan (>= 0.18), xaringanthemer URL: https://github.com/uf-repro/rmarkdown-intro +learningOutcomes: * describe the principles of reproducible documents + * apply markdown syntax to format text + * run code chunks in R Markdown + * format tables in R Markdown + * generate figures in R Markdown + * format references in R Markdown diff --git a/README.Rmd b/README.Rmd new file mode 100644 index 0000000..c3c8526 --- /dev/null +++ b/README.Rmd @@ -0,0 +1,64 @@ +--- +output: github_document +--- + + + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>", + fig.path = "man/figures/README-", + out.width = "100%" +) +``` + +```{r, include = FALSE} + +lesson_title <- "An Introduction to Writing Reproducible Manuscripts Using RMarkdown" +lesson_description <- "RMarkdown is a versatile document format that can combine text, R code, figures, and tables together in a single document, and create formatted output as PDFs, MS Word files, slides, websites, and more. This workshop will provide a basic introduction to using RMarkdown, how to insert code, tables, figures, and format references, and an overview of the possible output formats." +lesson_keywords <- c("Open Educational Resources", + "Research Support Skills", + "Reproducible Report", + "Literate Programming", + "R Markdown", + "Workshop") + +desc::desc_set(Title = lesson_title, + Description = lesson_description) + +zenodo_json <- jsonlite::read_json(".zenodo.json") +zenodo_json$title <- lesson_title +zenodo_json$description <- lesson_description +zenodo_json$keywords <- as.list(lesson_keywords) +jsonlite::write_json(zenodo_json, ".zenodo.json", + auto_unbox = TRUE, pretty = TRUE) +``` + +# `r lesson_title` + + +[![GitHub Actions pkgdown workflow](https://github.com/uf-repro/rmarkdown-intro/workflows/pkgdown/badge.svg)](https://github.com/uf-repro/rmarkdown-intro/actions?query=workflow%3Apkgdown) +[![DOI](https://zenodo.org/badge/277827412.svg)](https://zenodo.org/badge/latestdoi/277827412) + + +## Description + +`r lesson_description` + +## Learning Outcomes + +```{r, include = FALSE} +learning_outcomes <- c("describe the principles of reproducible documents", + "apply markdown syntax to format text", + "run code chunks in R Markdown", + "format tables in R Markdown", + "generate figures in R Markdown", + "format references in R Markdown") +outcomes_text <- paste0("* ", learning_outcomes, collapse = "\n") +desc::desc_set("learningOutcomes", outcomes_text) +``` + +By the end of the workshop, participants will be able to: + +`r outcomes_text` diff --git a/README.md b/README.md index e8923a6..b35ddc4 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,31 @@ + + # An Introduction to Writing Reproducible Manuscripts Using RMarkdown -[![GitHub Actions pkgdown workflow](https://github.com/uf-repro/rmarkdown-intro/workflows/pkgdown/badge.svg)](https://github.com/uf-repro/rmarkdown-intro/actions?query=workflow%3Apkgdown) + +[![GitHub Actions pkgdown +workflow](https://github.com/uf-repro/rmarkdown-intro/workflows/pkgdown/badge.svg)](https://github.com/uf-repro/rmarkdown-intro/actions?query=workflow%3Apkgdown) [![DOI](https://zenodo.org/badge/277827412.svg)](https://zenodo.org/badge/latestdoi/277827412) ## Description -RMarkdown is a versatile document format that can combine text, R code, figures, and tables together in a single document, and create formatted output as PDFs, MS Word files, slides, websites, and more. This workshop will provide a basic introduction to using RMarkdown, how to insert code, tables, figures, and format references, and an overview of the possible output formats. +RMarkdown is a versatile document format that can combine text, R code, +figures, and tables together in a single document, and create formatted +output as PDFs, MS Word files, slides, websites, and more. This workshop +will provide a basic introduction to using RMarkdown, how to insert +code, tables, figures, and format references, and an overview of the +possible output formats. ## Learning Outcomes By the end of the workshop, participants will be able to: -* describe the principles of reproducible documents -* apply markdown syntax to format text -* run code chunks in R Markdown -* format tables in R Markdown -* generate figures in R Markdown -* format references in R Markdown - -## References + + - describe the principles of reproducible documents + - apply markdown syntax to format text + - run code chunks in R Markdown + - format tables in R Markdown + - generate figures in R Markdown + - format references in R Markdown diff --git a/_pkgdown.yml b/_pkgdown.yml index 720cc81..f6be752 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -28,9 +28,9 @@ navbar: home: icon: fas fa-home fa-lg href: index.html - syllabus: - text: Syllabus - href: syllabus.html + notes: + text: Notes + href: notes.html slides: text: Slides href: slides.html diff --git a/resources.md b/resources.md index 7e0b2f2..131cb80 100644 --- a/resources.md +++ b/resources.md @@ -1,6 +1,6 @@ # Additional Resources / Readings -## Examples +## Example Research Papers * ["Unequal Representation and Gender Stereotypes in Image Search Results for Occupations"](https://github.com/mjskay/gender-in-image-search) - example paper (`README.Rmd`) by Kay, Matthew, Matuszek, Cynthia, and Munson, Sean. @@ -19,7 +19,7 @@ ## Tutorials * ["R Markdown for Scientists"](https://rmd4sci.njtierney.com/) - - A guide from Nick Tierney on the essentials of using R Markdown for scientists + - A self-guided tutorial on the essentials of R Markdown reports from Nick Tierney * [R Markdown](https://rmarkdown.rstudio.com/lesson-1.html) - Multi-part introduction to R Markdown and output formats from R Studio. diff --git a/slides/slides.Rmd b/slides/slides.Rmd index 5455bf5..122eb67 100644 --- a/slides/slides.Rmd +++ b/slides/slides.Rmd @@ -1,5 +1,5 @@ --- -title: "An Introduction to Writing Reproducible Manuscripts Using RMarkdown" +title: "`r desc::desc_get('Title', '..')`" author: "Hao Ye" institute: "Health Science Center Libraries, University of Florida" date: "(updated: `r Sys.Date()`)" @@ -7,6 +7,7 @@ output: xaringan::moon_reader: lib_dir: libs css: xaringan-themer.css + fig_caption: false nature: highlightStyle: github highlightLines: true @@ -37,28 +38,30 @@ style_mono_accent( "margin-block-end" = "0.5em"), "pre" = list("margin-top" = "0.5em", "margin-bottom" = "0.5em", - "white-space" = "pre-wrap"), - ".caption" = list("display" = "none")), + "white-space" = "pre-wrap"), + ".small" = list("font-size" = "80%")), link_color = "#339944" ) ``` class: inverse, center, middle -# `r rmarkdown::metadata$title` +# `r desc::desc_get('Title', '..')` ### `r rmarkdown::metadata$author` ### `r rmarkdown::metadata$institute` ### (updated: `r Sys.Date()`) +--- +# Motivations + +Unnecessary pain points when writing a manuscript: +* syncing changes in results with text (e.g. p-values, number of data points, figures, tables) +* formatting bibliographies for different journals + --- # Learning Objectives -* describe the principles of reproducible documents -* apply markdown syntax to format text -* format numerical results in R Markdown -* format tables in R Markdown -* generate figures in R Markdown -* format references in R Markdown +`r gsub("\n ", "\n", desc::desc_get("learningOutcomes"))` --- class: inverse, center, middle @@ -100,10 +103,10 @@ class: inverse, center, middle # R Markdown Tools * **`rmarkdown`** is the file-format and main interface with R (`*.Rmd`) -* **`knitr`** is the underlying engine that runs code -* `pandoc` is a software tool that converts markdown documents into other formats +* **`knitr`** runs code and formats results into markdown +* `pandoc` converts markdown documents into other formats -```{r, echo = FALSE, fig.cap = "A diagram from https://rmarkdown.rstudio.com/lesson-2.html, showing the workflow for R Markdown, where an Rmd file is transformed by `knitr` into a markdown file, and then by `pandoc` into multiple output files."} +```{r, echo = FALSE, fig.alt = "A diagram from https://rmarkdown.rstudio.com/lesson-2.html, showing the workflow for R Markdown, where an Rmd file is transformed by `knitr` into a markdown file, and then by `pandoc` into multiple output files."} knitr::include_graphics("rmarkdownflow.png") ``` @@ -117,7 +120,7 @@ knitr::include_graphics("rmarkdownflow.png") -- -For PDF output, you will want LaTeX. The [**`tinytex`** package](https://yihui.org/tinytex/) provides a mechanism for a lightweight LaTeX install: +For PDF output, you also need LaTeX. The [**`tinytex`** package](https://yihui.org/tinytex/) provides a mechanism for a lightweight LaTeX install: ```{r, eval = FALSE} tinytex::install_tinytex() ``` @@ -135,7 +138,7 @@ rmarkdown::render({document.Rmd}) .center[**OR**] Use the `Knit` button in RStudio. -```{r, echo = FALSE, fig.cap = "A screenshot of the Knit button in RStudio, which appears as an image of a ball of yarn with a needle in it, next to the text 'Knit' and an optional pulldown menu in the form of a down arrow."} +```{r, echo = FALSE, fig.alt = "A screenshot of the Knit button in RStudio, which appears as an image of a ball of yarn with a needle in it, next to the text 'Knit' and an optional pulldown menu in the form of a down arrow."} knitr::include_graphics("knit-button.png") ``` @@ -143,8 +146,8 @@ knitr::include_graphics("knit-button.png") # What happens during knitting? For a given `document.Rmd` -1. **`knitr`** runs the code chunks and merges the output with the remainder of `document.Rmd` into a markdown file: `document.md` -2. `pandoc` converts the markdown into the final outputs. +1. **`knitr`** runs the code chunks and merges the output back into a markdown file: `document.md` +2. `pandoc` converts the markdown into the final output format(s). --- class: inverse, center, middle @@ -163,7 +166,7 @@ output: html_document --- ``` -* this specifies metadata about the document that gets incorporated in the final output +* this metadata about the document will be incorporated in the final output --- # A More Complex Header @@ -180,6 +183,18 @@ output: --- ``` +--- +# Markdown + +Other than code chunks, R Markdown documents are written in markdown. + +-- + +**Markdown** is a lightweight way to format text: +* it is written in plaintext (including formatting) +* formatting is readable in plaintext +* ideal for version control and documents that don't require extensive typesetting + --- # Syntax: Headings @@ -236,7 +251,7 @@ output: Raw URLs: https://cran.r-project.org/ -And formatted links: +Formatted links: [CRAN](https://cran.r-project.org/) ``` .center[*renders into*] @@ -244,7 +259,7 @@ And formatted links: Raw URLs: https://cran.r-project.org/ -And formatted links: +Formatted links: [CRAN](https://cran.r-project.org/) --- @@ -252,9 +267,29 @@ class: inverse, center, middle # Code Chunks +--- + +# Code Chunks + +Unexecuted code can be marked with triple back-ticks (**not** the same as a single-quote!) + +```` +``` +print("Hello World!") +``` +```` + +.center[*renders into*] + +``` +print("Hello World!") +``` + --- # Inserting Code +Including `{r}` will execute the code in R and display the result: + ```` ```{r}`r ''` 1 + 1 @@ -286,6 +321,8 @@ See the description of [chunk options](https://yihui.org/knitr/options/) for det --- # Inline code +Code expressions can be embedded inline with text, too. + ```` The square root of 10 is `r`r ''` sqrt(10)`. Today's date is `r`r ''` Sys.Date()`. @@ -347,7 +384,7 @@ knitr::kable(mtcars[1:4,1:3], format = "markdown") # Figures (code) -```{r, out.height=400, out.width = 400} +```{r, out.height=400, out.width = 400, fig.alt="A scatterplot of mileage (mpg) vs. engine displacement (disp) from the mtcars dataset. There is a general inverse relationship (curvilinear, with a hint of being concave-up) with higher displacement corresponding to lower mileage. Displacement on the x-axis ranges from 71.1 to 472 (cubic centimeters?) and mileage on the y-axis ranges from 10.4 to 33.9 (miles per gallon)."} plot(mpg ~ disp, data = mtcars, cex = 2, cex.lab = 2, cex.axis = 2) ```