Bio Reporting Rmarkdown Reports

Version Compatibility

Reference examples tested with: rmarkdown 2.25+, knitr 1.45+, bookdown 0.37+, DESeq2 1.42+, ggplot2 3.5+, DT 0.31+, kableExtra 1.4+

Before using code patterns, verify installed versions match. If versions differ:

• R: packageVersion('<pkg>') then ?function_name to verify parameters

If code throws an error, introspect the installed package (?rmarkdown::render, ?knitr::opts_chunk) and adapt the example to the actual API rather than retrying.

R Markdown Reports

"Create an R Markdown report" -> Write an R-centric document combining code chunks, results, and narrative that knits to HTML/PDF/Word.

• R: rmarkdown::render('report.Rmd'), or the Knit button in RStudio

The Pipeline: knitr, Then Pandoc

An .Rmd always renders in two stages: knitr executes the chunks and weaves the results into an intermediate .md, then pandoc converts that .md into the target format (LaTeX via a TeX engine for PDF). knitr is the only execution engine for .Rmd (other languages run only as knitr engines); it is the successor to Sweave, adding caching, hooks, and markdown hosting. rmarkdown::render() orchestrates both stages. Knowing the split explains most failures: a chunk error is knitr; a formatting or cross-reference problem is usually pandoc/bookdown.

The "Works Interactively, Fails on Knit" Trap

This is the single most common reproducibility surprise. rmarkdown::render() defaults to envir = parent.frame(), so calling it from the console evaluates chunks in the caller's environment - it can SEE objects sitting in the interactive global env. The RStudio Knit button does NOT: it spawns a fresh, clean R session. So a report that relies on a df created interactively renders fine via render() from the console, then fails when a colleague clicks Knit or CI runs it, because the fresh session has no df.

Guards:

• Treat the document as self-sufficient - every object must be CREATED in a chunk, never assumed present.
• To mimic the button before trusting a report, render in isolation: rmarkdown::render('r.Rmd', envir = new.env()), or in a fresh process via callr::r(...) / xfun::Rscript_call(rmarkdown::render, ...).

Caching: cache Keys on Code, Not Data

cache=TRUE stores a chunk's result in a *_cache/ dir and reloads it on re-knit if the chunk is "unchanged" - where the cache key is an MD5 of the chunk CODE plus evaluating options. The footgun: if a chunk reads data.csv and the FILE changes but the chunk code is byte-identical, the hash is unchanged and knitr serves the STALE cached result. Bind the data into the key:

```{r de-analysis, cache=TRUE, cache.extra=tools::md5sum('counts.csv')}
dds <- DESeq(DESeqDataSetFromMatrix(counts, metadata, ~ condition))
```

Cross-chunk dependencies are not tracked automatically either: if chunk B uses an object from chunk A, editing A does not invalidate B's cache by default - declare dependson='de-analysis' (or autodep=TRUE, best-effort).

The Working-Directory Trap

knitr evaluates chunks with the working directory set to the directory of the .Rmd, NOT the project root. So read.csv('data/x.csv') works when run interactively from the project root but breaks on knit if the .Rmd lives in reports/. Fixes, in order of preference: here::here('data/x.csv') (anchors to the project root, most robust); knitr::opts_knit$set(root.dir = '...') in the setup chunk (note opts_knit, not opts_chunk); or rmarkdown::render('r.Rmd', knit_root_dir = '...'). Never setwd() in a chunk - it desyncs figure/cache file placement.

Cross-References Require bookdown

Base rmarkdown CANNOT cross-reference figures, tables, sections, or equations. Use a bookdown output format - bookdown::html_document2, bookdown::pdf_document2, bookdown::word_document2 - which add numbering and \@ref(type:label). Two hard requirements: the figure/table chunk must be LABELED, and it must have a CAPTION (fig.cap=); a captionless figure is emitted unnumbered and cannot be referenced.

output:
  bookdown::html_document2:
    toc: true

```{r volcano, fig.cap="Volcano plot of differential expression"}
plot(res$log2FoldChange, -log10(res$pvalue))
```
See Figure \@ref(fig:volcano).

(Quarto has native cross-references without bookdown - see reporting/quarto-reports.)