Create a reproducible R report with Quarto

Create an R analysis whose input data, executable source, rendered report, and environment record live together in one CoCalc project. This example calculates the mean of four synthetic measurements and produces an HTML report.

Prepare the project and check its tools

Use an editable project with R, Quarto, and the R packages knitr and rmarkdown installed. The repository's Quarto image recipe combines cocalc/r, cocalc/quarto, and cocalc/rstudio; available published images vary by deployment. Follow Project images to inspect or change your environment. This example uses the terminal and CoCalc's Quarto editor; opening a separate RStudio session is optional.

In a project terminal, run:

Rscript --version
quarto --version
Rscript --vanilla -e 'stopifnot(requireNamespace("knitr", quietly=TRUE), requireNamespace("rmarkdown", quietly=TRUE)); cat("R report dependencies ready\n")'

The first two commands must print installed versions. The last must end with R report dependencies ready. Resolve missing executables or packages in the selected project environment before creating the report. Do not substitute a notebook kernel for the terminal's R without checking which environment is actually rendering the document.

If R is available but the two packages are missing, install them into R's configured user library, then rerun the dependency check in a new R process:

Rscript --vanilla - <<'RS'
user_lib <- Sys.getenv("R_LIBS_USER")
stopifnot(nzchar(user_lib))
dir.create(user_lib, recursive = TRUE, showWarnings = FALSE)
install.packages(c("knitr", "rmarkdown"), lib = user_lib,
                 repos = "https://cloud.r-project.org")
RS

This requires outbound network access and a writable user library. If R or Quarto itself is missing, select an available prepared image or have its owner build one using the RootFS recipe workflow and the repository's Quarto recipe. Changing the image can restart the project, so preserve ongoing work first. Quarto's installation guide describes installation outside a prepared image.

Create the data and report source

Use a new folder to keep source and outputs together. These terminal commands refuse to reuse an existing quarto-demo directory:

cd "$HOME"
mkdir quarto-demo && cd quarto-demo

Continue only if both commands succeeded and your terminal is in quarto-demo. Create the input:

cat > measurements.csv <<'CSV'
value
2
4
6
8
CSV

In Files, open quarto-demo, create report.qmd, and replace any starter content with the following. Use the full editor; from Essential choose File actions -> Full CoCalc. Keep measurements.csv in the same folder as report.qmd.

---
title: "A reproducible measurement report"
format:
  html:
    embed-resources: true
execute:
  echo: true
---

## Question and inputs

What is the mean of the four synthetic measurements in measurements.csv?
These values illustrate the workflow; they are not research observations.

```{r}
measurements <- read.csv("measurements.csv")
stopifnot(identical(names(measurements), "value"))
stopifnot(is.numeric(measurements$value))
stopifnot(nrow(measurements) == 4L, !anyNA(measurements$value))
stopifnot(all(is.finite(measurements$value)))
result <- mean(measurements$value)
stopifnot(result == 5)
cat(sprintf("count=%d\nmean=%.1f\n", nrow(measurements), result))
```

## Inspect the measurements

```{r}
plot(seq_len(nrow(measurements)), measurements$value,
     type = "b", xlab = "Measurement number", ylab = "Value")
abline(h = result, col = "blue", lty = 2)
```

## Result and interpretation

The four supplied values have mean 5.0. This example checks a calculation;
it does not estimate uncertainty or establish a scientific conclusion.

## Environment used to render this report

```{r}
sessionInfo()
```

The complete report.qmd and CSV are also available in the example directory.

Render and verify the HTML

Save report.qmd. In the terminal, run from the report's directory:

cd "$HOME/quarto-demo"
quarto render report.qmd --log-level info

This is also the command shape used by CoCalc's Quarto build integration. In the full Quarto editor you can instead choose Build, inspect Build Log, and view HTML (Converted). Use one build at a time. Merely opening the source document is not a request to render it.

Check that the render finishes successfully and produces report.html. Open the HTML in Files or the editor's converted HTML view. Verify all of the following:

1. The title reads A reproducible measurement report.
2. The first executed code block reports count=4 and mean=5.0.
3. The plot has four points at values 2, 4, 6, and 8, and a horizontal line at 5.
4. The environment section contains the actual R version and session details.

The report includes the analysis code because echo: true is enabled. embed-resources: true keeps this report's plot and supporting resources inside the HTML. Inspect the result after downloading it as well if you intend to distribute that file. HTML is the intended output here; PDF requires a separately configured PDF toolchain.

Preserve a rerun and collaborator handoff

Record tool versions and the input checksum next to the report:

cd "$HOME/quarto-demo"
quarto --version > quarto-version.txt
Rscript --vanilla -e 'print(tools::md5sum("measurements.csv")); sessionInfo()' > environment.txt

Use the checksum to detect changed inputs, not as a security signature. Keep measurements.csv, report.qmd, report.html, quarto-version.txt, and environment.txt together. Add README.md containing the input description, selected project image, render command, checked result, and next research question.

Follow Research handoff to grant a coauthor collaborator access and share links to the source, data, and HTML. A link alone does not grant access. Someone who only needs to read the result can receive the downloaded HTML or appropriately configured viewer access.

To check independence from the original working directory, create a new quarto-rerun folder, copy only measurements.csv and report.qmd into it, and render there. Compare the reported count and mean rather than the entire HTML file, which can contain generated metadata. For an environment reproduction claim, repeat that step in a separately prepared project, following Reproduce an analysis. An environment record describes installed versions; it is not a dependency lockfile.

Troubleshooting and cleanup

• Command not found: check the selected image and terminal environment. Having an R notebook kernel does not by itself prove that the Quarto CLI and its R dependencies are available to document builds.
• Cannot open measurements.csv: check spelling and case, keep the input beside the source, and run the terminal render from that directory.
• A stopifnot check fails: inspect the data. The expected result is deliberately fixed for this example; update both the analysis and its checks when you replace the synthetic inputs.
• Old output remains after a failed build: inspect the latest build log and rerun successfully before treating an existing report.html as current. Open or reload the converted view after the successful build.
• No PDF file has been generated: this example requests HTML. Inspect HTML (Converted), or explicitly configure and verify a PDF format and toolchain before expecting a PDF.

Keep the source, data, and checked HTML for the handoff. Remove the disposable rerun folder only after comparing results. No long-running preview server is started by this render workflow. For R Markdown rather than Quarto source, see R Markdown.