Literate Programming with Quarto

T supports Quarto as a first-class runtime for literate programming within pipelines. This allows you to combine T code, R, Python, and markdown to generate beautiful, reproducible reports, websites, and books.

Defining a Quarto Node

A Quarto node in a pipeline takes a .qmd file as input and renders it to a target format (default is HTML).

p = pipeline {
  data = node(command = read_csv("data.csv") |> filter($age > 18))
  
  report = node(
    script = "analysis.qmd",
    runtime = Quarto
  )
}

Implicit Dependencies

When a .qmd file uses read_node("name"), T automatically detects this and adds a dependency from the Quarto node to the specified node (data in the example above).

Using Data from T in Quarto

Within your .qmd file, you can access data generated by other nodes in the same pipeline using the read_node() function.

In R Chunks

---
title: "Pipeline Analysis"
format: html
---

# Analysis

```{r}
# read_node is substituted by T during the build
df <- read_node("data")
summary(df)
```

How it Works

When the pipeline is built via Nix: 1. T detects read_node("node_name") calls in the .qmd source. 2. It generates a Nix derivation where the absolute path to the node’s artifact (in the Nix store) is provided via environment variables. 3. During the Nix build, a sed substitution replaces read_node("node_name") with the actual path to the artifact. 4. Quarto renders the document using these absolute paths.

Exporting Results

Because T pipelines are built in the Nix store (which is read-only), rendered reports remain in /nix/store/.... To inspect or publish them, use the pipeline_copy() function to bring them into your local workspace.

-- Build the pipeline
populate_pipeline(p, build = true)

-- Copy all artifacts to ./pipeline-output/
pipeline_copy()

The rendered HTML and its accompanying files will be available in pipeline-output/report/artifact/.

Configuring Dependencies

If your Quarto document uses R or Python chunks, you must ensure the necessary packages are available in the project’s tproject.toml.

[r-dependencies]
packages = ["jsonlite", "ggplot2"]

[additional-tools]
packages = ["quarto", "which"]

[!NOTE] Always include quarto and which in additional-tools if you are using Quarto nodes.

Multi-Language Reporting

Quarto allows you to blend multiple languages in a single document. Since T orchestrates the data flow, you can: 1. Process raw data in T. 2. Perform complex statistical modeling in R. 3. Render a comprehensive reporting doc in Quarto that consumes both the processed data and the model parameters.