update slides and lesson file structure

.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

.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"
 }

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

README.Rmd

@@ -0,0 +1,64 @@
+---
+output: github_document
+---
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+```{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`
+
+<!-- badges: start -->
+[![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)
+<!-- badges: end -->
+
+## 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`

README.md

@@ -1,23 +1,31 @@
 
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
 # An Introduction to Writing Reproducible Manuscripts Using RMarkdown
 
 <!-- badges: start -->
-[![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)
 <!-- badges: end -->
 
 ## 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

_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

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.

slides/slides.Rmd

@@ -1,12 +1,13 @@
 ---
-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()`)"
 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,16 +138,16 @@ 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")
 ```
 
 ---
 # 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,25 +251,45 @@ output:
 Raw URLs:
 https://cran.r-project.org/
 
-And formatted links:
+Formatted links:
 [CRAN](https://cran.r-project.org/)
 ```
 .center[*renders into*]
 
 Raw URLs:
 https://cran.r-project.org/
 
-And formatted links:
+Formatted links:
 [CRAN](https://cran.r-project.org/)
 
 ---
 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)
 ```