diff --git a/episodes/05-reproducible-reports.Rmd b/episodes/05-reproducible-reports.Rmd index 8f067392..80f3451f 100644 --- a/episodes/05-reproducible-reports.Rmd +++ b/episodes/05-reproducible-reports.Rmd @@ -5,23 +5,19 @@ exercises: 15 source: Rmd --- -::::::::::::::::::::::::::::::::::::::: objectives - -- Describe the value of reproducible reporting. -- Create a new Quarto document (`.qmd`) in RStudio. -- Use Markdown syntax to format text. -- Create and run code chunks within a Quarto document. -- Render a Quarto document to an HTML report. - -:::::::::::::::::::::::::::::::::::::::::::::::::: - -:::::::::::::::::::::::::::::::::::::::: questions - -- How can I combine my code, results, and narrative into a single document? -- How can I automatically update my reports when my data changes? -- What is Quarto and how does it differ from a standard R script? - -:::::::::::::::::::::::::::::::::::::::::::::::::: +::: objectives +- Describe the value of reproducible reporting. +- Create a new Quarto document (`.qmd`) in RStudio. +- Use Markdown syntax to format text. +- Create and run code chunks within a Quarto document. +- Render a Quarto document to an HTML report. +::: + +::: questions +- How can I combine my code, results, and narrative into a single document? +- How can I automatically update my reports when my data changes? +- What is Quarto and how does it differ from a standard R script? +::: ```{r, include=FALSE} source("files/download_data.R") @@ -73,7 +69,7 @@ books2 <- read_csv("data/books.csv") %>% ## Introduction to Reproducible Reporting -So far, we have been writing code in `.R` scripts. This is excellent for data analysis, but what happens when you need to share your findings with a colleague or a library director? You might copy a plot into a Word document or an email, then type out your interpretation. +So far, we have been writing code in `.R` scripts. This is excellent for data analysis, but what happens when you need to share your findings with a colleague or a library director? You might copy a plot into a Word document or an email, then type out your interpretation. But what if the data changes next month? You would have to re-run your script, re-save the plot, copy it back into Word, and update your text. This manual process is prone to errors and tedious. @@ -83,21 +79,19 @@ But what if the data changes next month? You would have to re-run your script, r To create a new Quarto document in RStudio: -1. Click the **File** menu. -2. Select **New File** > **Quarto Document...** -3. In the dialog box, give your document a **Title** (e.g., "Library Usage Report") and enter your name as **Author**. -4. Ensure **HTML** is selected as the output format. -5. Click **Create**. +1. Click the **File** menu. +2. Select **New File** \> **Quarto Document...** +3. In the dialog box, give your document a **Title** (e.g., "Library Usage Report") and enter your name as **Author**. +4. Ensure **HTML** is selected as the output format. +5. Click **Create**. RStudio will open a new file with some example content. Notice the file extension is `.qmd`. -::::::::::::::::::::::::::::::::::::::::: callout - +::: callout ## Quarto vs. RMarkdown If you have used R before, you might be familiar with RMarkdown (`.Rmd`). Quarto (`.qmd`) is the next-generation version of RMarkdown. It works very similarly but supports more languages (like Python and Julia) and has better features for scientific publishing. - -::::::::::::::::::::::::::::::::::::::::: +::: ## Anatomy of a Quarto Document @@ -107,7 +101,7 @@ A Quarto document has three main parts: At the very top, enclosed between two lines of `---`, is the **YAML Header**. This contains metadata about the document. -```yaml +``` yaml --- title: "Library Usage Report" author: "Your Name" @@ -117,24 +111,22 @@ format: html ### 2. Markdown Text -The white space is where you write your narrative. You use **Markdown** syntax to format text. +The white space is where you write your narrative. You use **Markdown** syntax to format text. -- `**Bold**` for **bold text** -- `*Italics*` for *italics* -- `# Heading 1` for a main title -- `## Heading 2` for a section title -- `- List item` for bullet points +- `**Bold**` for **bold text** +- `*Italics*` for *italics* +- `# Heading 1` for a main title +- `## Heading 2` for a section title +- `- List item` for bullet points ### 3. Code Chunks -Code chunks are where your R code lives. They start with ` ```{r} ` and end with ` ``` `. +Code chunks are where your R code lives. They start with ```` ```{r} ```` and end with ```` ``` ````. -```` ```{r} # This is a code chunk summary(cars) ``` -```` You can insert a new chunk by clicking the **+C** button in the editor toolbar, or by pressing Ctrl+Alt+I (Windows/Linux) or Cmd+Option+I (Mac). @@ -145,7 +137,7 @@ Let's clean up the example file and create a report using our `books` data. 1. Delete everything in the file *below* the YAML header. 2. Add a new **setup** code chunk to load our libraries and prepare the data. -```{{r}} +```{r} #| label: setup #| include: false @@ -167,21 +159,17 @@ books2 <- read_csv("data/books.csv") %>% ) ``` -::::::::::::::::::::::::::::::::::::::::: callout - +::: callout ## Chunk Options -Notice the lines starting with `#|`. These are **chunk options**. -- `#| label: setup` gives the chunk a name. -- `#| include: false` runs the code but hides the code and output from the final report. This is great for loading data silently. - -::::::::::::::::::::::::::::::::::::::::: +Notice the lines starting with `#|`. These are **chunk options**. - `#| label: setup` gives the chunk a name. - `#| include: false` runs the code but hides the code and output from the final report. This is great for loading data silently. +::: ### Adding Analysis Now, let's add a section header and some text. -```markdown +``` markdown ## High Usage Items We are analyzing items with more than 10 checkouts to understand circulation patterns across sub-collections. @@ -189,7 +177,6 @@ We are analyzing items with more than 10 checkouts to understand circulation pat Next, insert a new code chunk and paste the plotting code we developed in the previous episode (ggplot2). -```` ```{r} #| label: plot-high-usage #| echo: false @@ -211,7 +198,6 @@ ggplot(data = booksHighUsage, theme_bw() + theme(axis.text.x = element_text(angle = 45, hjust = 1)) ``` -```` Setting `#| echo: false` will display the *plot* in the report, but hide the R *code* that generated it. This is often preferred for reports intended for non-coders. @@ -220,14 +206,14 @@ Setting `#| echo: false` will display the *plot* in the report, but hide the R * Now comes the magic. Click the **Render** button (blue arrow icon) at the top of the editor pane. RStudio will: + 1. Run all your code chunks from scratch. 2. Generate the plots and results. 3. Combine them with your text. 4. Create a new file named `library_usage_report.html` in your project folder. 5. Open a preview of the report. -::::::::::::::::::::::::::::::::::::::: challenge - +:::: challenge ## Challenge: Add a Summary Table 1. Add a new header `## Summary Statistics` to your Quarto document. @@ -235,20 +221,18 @@ RStudio will: 3. Write code to calculate the mean checkouts per format (Hint: use `group_by(format)` and `summarize()`). 4. Render the document again to see your new table included in the report. -::::::::::::::: solution - +::: solution ## Solution Add this to your document: -```markdown +``` markdown ## Summary Statistics The table below shows the average checkouts for each item format. ``` -```` -```{r} +```{{r}} #| label: summary-table books2 %>% @@ -256,31 +240,27 @@ books2 %>% summarize(mean_checkouts = mean(tot_chkout, na.rm = TRUE)) %>% arrange(desc(mean_checkouts)) ``` -```` Render the document to see the updated report. - -::::::::::::::::::::::::: - -:::::::::::::::::::::::::::::::::::::::::::::::::: +::: +:::: ## Why This Matters -By using Quarto, your report is now **reproducible**. +By using Quarto, your report is now **reproducible**. If you download a new version of `books.csv` next month: + 1. Save it to your `data/` folder. 2. Open your Quarto document. 3. Click **Render**. Your report will automatically update with the new data, creating a fresh plot and table without you having to copy-paste a single thing. -:::::::::::::::::::::::::::::::::::::::: keypoints - -- **Quarto** allows you to mix code and text to create reproducible reports. -- Use the **YAML header** to configure document metadata like title and output format. -- **Code chunks** run R code and can display or hide input/output using options like `#| echo: false`. -- **Rendering** the document executes the code and produces the final output (HTML, PDF, etc.). -- This workflow saves time and reduces errors when reporting on data that changes over time. - -:::::::::::::::::::::::::::::::::::::::::::::::::: +::: keypoints +- **Quarto** allows you to mix code and text to create reproducible reports. +- Use the **YAML header** to configure document metadata like title and output format. +- **Code chunks** run R code and can display or hide input/output using options like `#| echo: false`. +- **Rendering** the document executes the code and produces the final output (HTML, PDF, etc.). +- This workflow saves time and reduces errors when reporting on data that changes over time. +::: diff --git a/lc-r.Rproj b/lc-r.Rproj index be803829..76d454cc 100644 --- a/lc-r.Rproj +++ b/lc-r.Rproj @@ -1,4 +1,5 @@ Version: 1.0 +ProjectId: 0c1aa31e-0b52-4784-994c-ceebf424a714 RestoreWorkspace: Default SaveWorkspace: Default