Literate Programming with Quarto

Quick Setup with Quarto

T provides a specialized Quarto filter (tlang) that allows you to execute T code chunks directly in your .qmd documents.

Installing the T Plugin

The T plugin is managed automatically within a T project. You don’t need to download it manually; T’s dependency management handles it.

1. Add Quarto to your project: In your tproject.toml, ensure quarto is in the additional-tools: toml [additional-tools] packages = ["quarto"]
2. Provision the extension: Run t update in your terminal.
3. Enter the environment: Run nix develop.

Upon entering the environment, T will symlink the tlang extension from the Nix store into your project’s _extensions/ directory.

Enabling the Filter

Add the tlang filter to your document’s YAML front matter:

---
title: "My T Analysis"
format: html
filters:
  - tlang
---

Writing Quarto Blocks

You can now use {t} code chunks in your document. These chunks are executed by the T interpreter during rendering.

```{t}
#| label: load-data
df = read_csv("mtcars.csv")
df |> glimpse
```

Block Options

• eval: Set to false to show the code without executing (default: true).
• echo: Set to false to hide the code and only show the output (default: true).
• results: Set to hide to suppress any printed output.
• fig-cap: Add a caption if the chunk generates a plot (via an R/Python sub-node).

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.