Minimal header

---
title: "Air Quality Analysis"
author: "Marc Los Huertos"
date: "2024-03-15"
output: html_document
---

Dynamic date

Hard-coding the date means it goes stale. Use inline R instead so the date updates every time you knit:

date: "Compiled `r format(Sys.Date(), '%Y-%m-%d')`"

Output formats

The output: field determines what pandoc produces. The most common options:

HTML document options

output:
  html_document:
    toc: true              # table of contents
    toc_float: true        # floating sidebar TOC
    toc_depth: 3           # include h1, h2, h3 headings
    number_sections: true  # auto-number headings
    theme: flatly          # Bootswatch CSS theme
    highlight: tango       # syntax highlighting style
    self_contained: true   # embed all CSS/JS — one portable file
    df_print: paged        # paginated data frames
    code_folding: hide     # show "Code" buttons, hide by default

The custom knit: function

The modules in this course use a custom knit: field to redirect the output HTML to a specific folder. This is what lets the knit button send the file directly to the docs/ folder without any manual copying:

knit: (function(inputFile, encoding) {
    rmarkdown::render(
      inputFile,
      encoding = encoding,
      output_file = file.path(dirname(inputFile),
                              "../docs/RGuides/02_RMarkdown_knitr.html")
    )
  })

Without this, clicking Knit places the HTML in the same folder as the Rmd. The file.path(dirname(inputFile), "../docs/...") pattern navigates relative to the Rmd’s location — so the path works on any machine regardless of the absolute path to the project.

Headings

# Level 1 heading   (one #)
## Level 2 heading  (two ##)
### Level 3 heading (three ###)

Headings also create anchor links. Adding {#my-id} after the heading text lets you link to it:

## Results {#results}

See the [Results section](#results) for details.

Emphasis, lists, and links

**bold text**
*italic text*
`inline code` — use for function names, variable names, file paths

- unordered list item
- another item
  - nested item (two spaces of indent)

1. ordered list item
2. second item

[link text](https://example.com)

Block quotes and horizontal rules

> A blockquote — useful for key questions or callouts.

---    (three dashes = horizontal rule)

Tables

| Column A | Column B | Column C |
|----------|----------|----------|
| value 1  | value 2  | value 3  |
| value 4  | value 5  | value 6  |

The colons in the separator row control alignment:

| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| text     | text     | text     |

Equations

R Markdown supports LaTeX math using $ for inline and $$ for display:

The mean is $\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i$.

$$
\text{PM}_{2.5} = \beta_0 + \beta_1 T + \varepsilon
$$

Renders as:

The mean is \(\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i\).

Chunk anatomy

Every chunk has the same structure:

```{r chunk-label, option1 = value, option2 = value}
# your R code here
x <- 1 + 1
x
```

• The opening fence is exactly ```{r — three backticks, open brace, the letter r, a space, then the label.
• The label is optional but strongly recommended. It appears in error messages and the knitr progress log, making debugging far easier.
• Labels must be unique across the entire document — duplicate labels cause an error at knit time.
• The closing fence is exactly ``` — three backticks, nothing else.

Inserting a chunk

Three ways:

1. Keyboard shortcut: Ctrl+Alt+I (Windows/Linux) or Cmd+Option+I (Mac)
2. Toolbar: the green Insert button → R
3. Typing: type the backtick fence manually

What gets printed

Whatever R would print to the Console also appears in the document:

# Expressions that print their result automatically
42

## [1] 42

c(1, 2, 3)

## [1] 1 2 3

summary(c(2.1, 3.4, 2.8, 4.1, 3.9))

##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
##    2.10    2.80    3.40    3.26    3.90    4.10

Assignments do not print unless you explicitly print the object or wrap in parentheses:

x <- 10      # silent — nothing appears below this line
x            # now it prints

## [1] 10

(y <- 20)    # wrapping assignment in () also prints

## [1] 20

Plots are output too

Any plot created inside a chunk is captured and embedded in the document:

distance_m  <- c(10, 25, 50, 100, 200, 400)
pm25_ug_m3  <- c(38, 29, 21, 15,  11,   8)

plot(distance_m, pm25_ug_m3,
     xlab = "Distance from highway (m)",
     ylab = expression(PM[2.5] ~ (µg/m^3)),
     pch  = 19, col = "#4a7c5e",
     main = "PM2.5 vs Distance from Source")
lines(distance_m, pm25_ug_m3, col = "#4a7c5e", lwd = 1.5)

Particulate matter decreases with distance from the highway.

The essential options

Common combinations

Rather than listing chunk headers in a code block (which knitr would try to parse), here is a reference table of the most useful combinations:

Each option goes inside the chunk header after the label, separated by commas:

# Example: a results table — output only, no code shown
# ```{r results-table, echo=FALSE}

# Example: install instructions — show code but never run
# ```{r install-packages, eval=FALSE}

# Example: setup — run silently, nothing in output
# ```{r setup, include=FALSE}

Seeing options in action

The next three chunks are identical code but with different options — compare what appears in the rendered output:

# echo=TRUE (default) — you see this code AND the output below
sqrt(144)

## [1] 12

## [1] 13

# results='hide' — code appears, output is suppressed
sqrt(196)

fig.show — controlling multi-plot chunks

When a chunk produces more than one plot, fig.show controls whether they share a figure environment or each get their own:

```{r two-plots, fig.show='hold', fig.cap="Both plots side by side."}
# hold — both plots collected and placed together in one figure
hist(rnorm(200))
hist(rexp(200))
```


``` r
# asis (default) — each plot placed immediately where it is produced
hist(rnorm(200))
```



First plot.


``` r
hist(rexp(200))
```



Second plot.

Note the fig.cap as a character vector — when fig.show = 'asis' produces multiple figures from one chunk, supply a caption per plot:

{r figcap-vector-demo, fig.show='hold', fig.width=3.5, fig.height=3, fig.cap=c("PM2.5 — roughly normal.", "PM10 — right-skewed.")} set.seed(1) hist(rnorm(300, mean = 12, sd = 4), main = "PM2.5", xlab = "µg/m³", col = "#4a7c5e", border = NA) hist(rexp(300, rate = 0.08), main = "PM10", xlab = "µg/m³", col = "#c8832a", border = NA)

ref.label — reusing a chunk without repeating code

ref.label runs a previous chunk again without copying its code. This is useful when you want to show code in one place and output in another, or produce the same plot at two different sizes:

```{r my-plot, echo=TRUE, fig.show='hide'}
# Define and show the code here — suppress the figure with fig.show='hide'
plot(1:10, (1:10)^2, pch = 19, col = "#4a7c5e",
     xlab = "x", ylab = expression(x^2))
```

Some prose explaining the plot...

results = 'asis' — passing raw HTML to the output

The default results = 'markup' wraps printed output in a code block. results = 'asis' passes the output directly into the document as raw HTML or markdown — required any time you generate tables or headings programmatically:

# knitr::kable() generates an HTML table — needs results='asis' to render
# Without it, you'd see raw HTML tags as plain text
knitr::kable(
  data.frame(
    Site    = c("Kern", "Mojave", "Coast"),
    PM2.5   = c(12.1, 8.4, 18.0),
    n       = c(5L, 4L, 6L)
  ),
  caption = "Summary table generated inside a chunk."
)

Formatting numbers for prose

x <- 12345.6789

# Too many decimals for prose
x

## [1] 12345.68

# Rounded
round(x, 2)

## [1] 12345.68

# Formatted with thousands separator
format(x, big.mark = ",", nsmall = 2)

## [1] "12,345.68"

# Scientific notation suppressed
format(1.23e-5, scientific = FALSE, digits = 4)

## [1] "0.0000123"

# Percentage
paste0(round(0.734 * 100, 1), "%")

## [1] "73.4%"

Why load all packages at the top?

If library(ggplot2) is inside chunk 7 and the document fails during knit at chunk 5, you may spend time wondering why ggplot2 “isn’t loaded” — when the real error is earlier and ggplot2 never got a chance to load. A single setup chunk makes the dependency list visible and ensures it runs first.

Global vs local options

A local option on a single chunk overrides the global default from opts_chunk$set(). Use this to make a specific chunk behave differently without changing all chunks:

Markdown syntax

![Alt text describing the image](path/to/image.png)

![Caption shown below the image](figures/site_map.png){width=70%}

The path is relative to the Rmd file’s location. {width=70%} is a pandoc attribute that scales the image in HTML output. This approach is fine for decorative images but gives you no chunk-level control.

knitr::include_graphics() — the preferred approach

```{r site-map, echo=FALSE, fig.cap="Sensor deployment locations, Spring 2024.",
    out.width="80%", fig.align="center"}
knitr::include_graphics("figures/site_map.png")
```

Use out.width (not fig.width) for images loaded from disk — fig.width controls the size of generated R plots; out.width controls the display size of any figure in the output HTML.

Finding and specifying the path

The path is always relative to the Rmd file. If your project looks like:

project/
  reports/
    my_analysis.Rmd      ← Rmd lives here
  figures/
    site_map.png
  data/
    field_data.csv

Then the correct path inside the Rmd is "../figures/site_map.png" — one level up (..), then into figures/. The same logic applies to data files.

# Rmd is in reports/; figure is in figures/ at the project root
knitr::include_graphics("../figures/site_map.png")

# If figures/ is a subfolder of the same folder as the Rmd:
knitr::include_graphics("figures/site_map.png")

Supported formats

knitr::include_graphics() accepts .png, .jpg/.jpeg, .gif, and .svg for HTML output. For PDF output, use .png or .pdf — .gif and .svg are not supported by LaTeX.

Step 1 — Create a .bib file

A .bib file is a plain-text file containing reference entries. Each entry has a type (@article, @book, etc.), a cite key you invent, and fields:

@article{smith2022pm25,
  author  = {Smith, Jane and Jones, Robert},
  title   = {Particulate Matter Trends in Southern California},
  journal = {Environmental Science \& Technology},
  year    = {2022},
  volume  = {56},
  number  = {4},
  pages   = {2341--2350},
  doi     = {10.1021/acs.est.1c07890}
}

@book{wickham2023r4ds,
  author    = {Wickham, Hadley and Cetinkaya-Rundel, Mine and Grolemund, Garrett},
  title     = {R for Data Science},
  edition   = {2},
  year      = {2023},
  publisher = {O'Reilly Media},
  url       = {https://r4ds.hadley.nz}
}

@manual{r-base,
  title        = {R: A Language and Environment for Statistical Computing},
  author       = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address      = {Vienna, Austria},
  year         = {2024},
  url          = {https://www.R-project.org/}
}

Save this as references.bib in the same folder as your Rmd (or a bib/ subfolder — adjust the path in YAML accordingly).

Step 2 — Add bibliography: to the YAML header

---
title: "Air Quality Analysis"
author: "Marc Los Huertos"
output: html_document
bibliography: references.bib
csl: apa.csl               # optional — citation style (APA, MLA, etc.)
link-citations: true       # make in-text citations clickable links
---

Without csl:, pandoc uses its built-in Chicago author-date style. Download .csl files for other styles from the Zotero Style Repository.

Step 3 — Cite in your prose

Particulate matter exposure is linked to cardiovascular disease [@smith2022pm25].

Smith and Jones [-@smith2022pm25] found that PM2.5 declined 40% over two decades.

For an introduction to R, see @wickham2023r4ds [p. 42].

Multiple citations: [@smith2022pm25; @r-base].

Step 4 — The bibliography appears automatically

Pandoc places the formatted reference list at the end of the document by default. To control placement — for example, before a footer — insert a heading with the {#refs} div exactly where you want it:

## References

::: {#refs}
:::

---
*Compiled on `r Sys.Date()`.*

Citing R packages

It is good practice to cite the R packages you use. knitr::write_bib() generates BibTeX entries for any installed packages automatically:

# Run once to generate/update the bib file for the packages you use
knitr::write_bib(
  c("base", "rmarkdown", "knitr", "tidyverse", "lubridate", "ggplot2"),
  file = "references.bib"
)

Then cite as normal: [@R-ggplot2], [@R-tidyverse]. The R- prefix is the key format write_bib() produces.

nocite: |
  @wickham2023r4ds, @r-base

The Knit button

The simplest way to render is the Knit button in the RStudio toolbar (the yarn-and-needle icon). It calls rmarkdown::render() on the current file, runs all chunks in a fresh R session, and opens the output in the Viewer pane.

From the Console

# Render to the default output format specified in YAML
rmarkdown::render("reports/my_analysis.Rmd")

# Render to a specific format regardless of YAML
rmarkdown::render("reports/my_analysis.Rmd",
                  output_format = "pdf_document")

# Render and save to a specific path
rmarkdown::render("reports/my_analysis.Rmd",
                  output_file  = "outputs/my_analysis.html")

What “fresh R session” means — and why it matters

When you click Knit, RStudio starts a new, empty R session to run your document. It does not use the objects already in your Environment pane. This is the most common source of “it works in the Console but fails to knit” confusion:

Rendering order

knitr executes chunks strictly top to bottom. An object created in chunk 5 is not available in chunk 3, even if you created it in the Console first. If you get object not found, check whether the object is created before it is used.

# This chunk creates the object
site_data <- tibble::tibble(
  site    = c("Kern", "Mojave", "Coast"),
  pm25    = c(12.1, 8.4, 18.0)
)

# This chunk uses it — works because it comes AFTER the chunk that creates it
site_data

## # A tibble: 3 × 2
##   site    pm25
##   <chr>  <dbl>
## 1 Kern    12.1
## 2 Mojave   8.4
## 3 Coast   18

Render vs Source vs Run All

Knit errors — reading the error output

When a knit fails, RStudio shows the error in the R Markdown tab. The format is always:

Quitting from R02_RMarkdown_knitr.Rmd:45-52 [chunk-label]
Error in ... : error message here

The numbers 45-52 are the line numbers where the failing chunk starts and ends. Go to that line in your Rmd to find the problem. The [chunk-label] confirms which chunk it was — another reason to always label your chunks.

Checklist for “it runs but won’t knit”

# 1. Is every object the document needs created INSIDE a chunk?
#    (Not just in your Console environment)

# 2. Are all packages loaded with library() inside a chunk?
#    (library() calls in the Console do nothing for the knit session)

# 3. Is every file path correct relative to the Rmd's location?
#    (The knit session's working directory is the folder the Rmd lives in)
getwd()   # run in Console to see where your Rmd's working directory is

# 4. Are all chunk labels unique?
#    (Duplicate labels cause an immediate error before any code runs)

# 5. Does the chunk header use commas between options, not semicolons?
#    CORRECT:  ```{r my-chunk, echo=FALSE, fig.width=6}
#    WRONG:    ```{r my-chunk; echo=FALSE; fig.width=6}

Working directory in the knit session

The knit session’s working directory is the folder the Rmd lives in — not your RStudio project root, and not wherever you last called setwd(). This means all relative file paths in read_csv(), source(), etc. should be relative to the Rmd file, not to the project root.

# If your Rmd is at:  project/reports/my_analysis.Rmd
# And your data is at: project/data/field_data.csv
# Then the correct relative path in the Rmd is:
df <- read_csv("../data/field_data.csv")   # one level up, then into data/

# NOT:
df <- read_csv("data/field_data.csv")      # wrong — that looks for
                                           # project/reports/data/ which doesn't exist

YAML parse errors

Error in yaml::yaml.load(string, ...) :
  Scanner error: ...

This means the YAML header is malformed. Common causes:

• Tabs instead of spaces — YAML requires spaces only
• Missing colon after a key name
• Special characters in the title not wrapped in quotes: title: My: Report fails; title: "My: Report" works
• Mismatched quotes — if your title contains a single quote (apostrophe), use double quotes around it
• Wrong indentation — nested fields must be exactly 2 spaces deeper than their parent

Chunk delimiter errors

Error: attempt to use zero-length variable name

or

Unterminated chunk

These usually mean a chunk fence is wrong:

CORRECT opening:  ```{r my-label}
WRONG — missing r: ```{my-label}
WRONG — extra space: ``` {r my-label}

CORRECT closing:  ```
WRONG — has text:  ``` r
WRONG — two ticks: ``

Package not available

Error in library(ggplot2) : there is no package called 'ggplot2'

The knit session installs nothing automatically. Install missing packages in the Console with install.packages("ggplot2"), then knit again. Never put install.packages() in a chunk that will be evaluated during knit — it re-installs the package every time.

What’s next?

• Data Import — reading CSV, Excel, and field-data files into R
• Data Wrangling — cleaning and reshaping with dplyr and tidyr
• Visualization — ggplot2 for publication-quality figures