Parameterised Reports with Quarto

Parameterised reports transform a single Quarto document into a flexible template. Instead of creating separate reports for each region, time period, or category, you define parameters once and let Quarto do the rest. This approach saves time, reduces errors, and makes your reporting workflow scalable.

When to Use Parameters

Parameters shine in recurring reporting scenarios. Monthly sales reports that filter by different regions benefit from parameters. Quarterly analyses that compare different time periods become trivial. Ad-hoc reports that need customization without code changes are perfect candidates.

You should use parameters when:

• You generate similar reports repeatedly with different filters
• Different stakeholders need tailored versions of the same analysis
• You want one source of truth that adapts to inputs
• Your report logic stays the same but the data changes

If your report changes significantly between versions, separate documents make more sense. Parameters work best when the structure remains constant.

Defining Parameters in YAML

Parameters live in the YAML header under the “parameters” key. Each parameter has a name and a default value. Quarto passes these to your R code as a list called “params”.

---
title: Regional Sales Report
parameters:
  region: "North"
  year: 2024
  target: 100000
---

This defines three parameters: “region” (a string), “year” (an integer), and “target” (a number). You can use any valid YAML value: strings, numbers, booleans, and even lists.

Using Parameters in R Code

Access parameters in your R code through the “params” object. This is a named list where each element corresponds to a parameter you defined.

# Access a single parameter
current_region <- params$region

# Use in your analysis
cat("Generating report for", params$region, "in year", params$year)

The real power emerges when you use parameters to filter data or control plot elements:

library(dplyr)
library(ggplot2)

# Filter data based on parameters
sales_data <- sales %>%
  filter(region == params$region, year == params$year)

# Create a plot with parameter-driven title
ggplot(sales_data, aes(x = month, y = sales)) +
  geom_line() +
  labs(title = paste("Sales in", params$region, "-", params$year))

You can also use parameters to conditionally include or exclude sections of your report:

# Conditionally render a section
if (params$include_forecasts) {
  # Generate forecast section
  print("Forecast section would be generated here")
}

Rendering with Different Parameters

Quarto provides two methods for rendering with custom parameter values.

Command Line Flags

The “-P” flag passes individual parameters from the command line:

quarto render report.qmd -P region:South

This overrides only the specified parameters. Others use their defaults from the YAML.

YAML Parameter Files

For complex parameter combinations, create a separate YAML file:

# params/northeast.yaml
region: "Northeast"
year: 2024
target: 150000

Render with the “—params” flag:

quarto render report.qmd --params-file params/northeast.yaml

This approach works well for batch processing. You can loop through multiple parameter files to generate all your reports at once.

Practical Example: Regional Sales Report

Lets build a complete example that ties everything together:

---
title: Regional Sales Report
parameters:
  region: "West"
  year: 2024
  target: 75000
---

#| include: false
library(dplyr)
library(ggplot2)

# Sample data (replace with your actual data source)
set.seed(123)
sales <- data.frame(
  year = rep(2021:2022, each = 6),
  month = month.abb,
  sales = runif(12, 5000, 15000) * (1 + params$year - 2020)
)

Filtering Data with Parameters

# Filter for the specified region and year
regional_sales <- sales %>%
  filter(year == params$year, region == params$region) %>%
  mutate(target = params$target)

regional_sales

Creating Parameterised Visualisations

ggplot(regional_sales, aes(x = month, y = sales, fill = sales > params$target)) +
  geom_col() +
  scale_fill_manual(values = c("FALSE" = "gray", "TRUE" = "green")) +
  labs(
    title = paste("Monthly Sales -", params$region, "Region"),
    subtitle = paste("Target:", scales::comma(params$target)),
    x = "Month",
    y = "Sales (USD)"
  ) +
  theme_minimal()

To generate this report for different regions, run:

# Generate for West (default)
quarto render sales-report.qmd

# Generate for East
quarto render sales-report.qmd -P region:East

# Generate for North
quarto render sales-report.qmd -P region:North

# Generate for South
quarto render sales-report.qmd -P region:South

Best Practices

Name parameters clearly. Use descriptive names that indicate purpose. “include_forecasts” is better than “if”. Document what each parameter does in a comment.

Provide sensible defaults. Your document should work immediately when rendered without parameters. This makes testing easier and provides a fallback.

Validate parameter values. Check that parameters are within expected ranges or match valid options. This prevents silent failures:

valid_regions <- c("North", "South", "East", "West")
if (!(params$region %in% valid_regions)) {
  stop("Invalid region: ", params$region, 
       ". Must be one of: ", paste(valid_regions, collapse = ", "))
}

Use type hints in comments. Since YAML does not enforce types, add comments reminding yourself what type each parameter expects:

parameters:
  region: "West"     # string: region name
  year: 2024         # integer: 4-digit year
  target: 75000      # number: sales target

Keep parameters and logic separate. Define all parameter values in the YAML or external files. Keep your R code focused on analysis, not parameter management.

Test with multiple values. Before deploying a parameterised report, render it at least three times with different parameter combinations. This catches edge cases and ensures flexibility.

Parameterised reports are a gateway to automated reporting workflows. Once you master them, you can build pipelines that generate hundreds of customized reports from a single Quarto document.