Skip to contents

Inside the package: understanding and extending the report

package-architecture.Rmd
library(RoundtableReporting)
#> Loading RoundtableReporting version 0.3.6

Introduction

RoundtableReporting is an R package created for producing quarterly reports for the Aged Care Medication Roundtable. The package uses R to import data (processed in SAS at an earlier stage) and report settings and metadata, and use this to draw figures and do some minor data processing, then use Mustache to substitute data values into template files that use Typst markup. These template files are combined into a single .typ file that is compiled to produce the report.

Once set up, creating a report is a simple matter of updating details in a report_settings file to specify the correct dates and data location, then typing make_report("provider") to output a provider-specific report: see vignette("creating-reports").

The software underlying the package are Typst, R and Mustache (through an R package). Typst is a modern document markup language and compiler that produces PDFs. Documents are written in plain text with “markup” commands that specify what a text element is (e.g. heading, paragraph, figure caption) and how it should be formatted). The plain text .typ file can be compiled to a PDF. R is a statistical computing package. It is widely used for data analysis and visualisation. Mustache is a templating system that replaces tagged variables (like {{name}}) with actual values.

This article describes the structure of the package in detail, to enable modifying the report or adding new sections.

Package structure

This is a standard R packages as described in Writing R Extensions and R Packages. R code is in the R folder. The inst folder contains files that will be installed with the package. These include inst/templates, with subfolders template-files containing the Typst templates, and static-images containing logos, icons and cover image. There is also inst/extdata containing other data used in the reports (default configuration files, and the mapping from home codes to names), and inst/tinytest containing tests for the R functions and package as a whole. The Typst software is also included in the package in inst/typst. This was done to avoid issues with users having to install and configure Typst.

Template Types

Templates in inst/template-files/ use two extensions:

  • .typ.tmpl: Processed with Mustache to insert data
  • .typ.include: Inserted directly without processing

Report Structure

The report is built from templates in this order:

  1. setup-cover.typ.tmpl: Document setup, variables, cover page, formatting, What’s New, TOC
  2. overview.typ.tmpl: Overview chapter with quarterly summary
  3. provider.typ.tmpl: Provider-specific summary table
  4. [indicator].typ.tmpl: Individual indicator sections with definitions, results, figures
  5. facilities.typ.include: Home-level results tables
  6. Appendices: Additional information such as home codes or guides to reading the figures

Report generation process

Calling make_report("provider") executes these steps:

  1. Setup
    • Verify/create configuration files
    • Copy templates to working directory
    • Load configurations
    • Clean old outputs
  2. Data processing
    • Load data
    • Calculate summaries
    • Collect config and stats
  3. Report assembly
    • Generate figures
    • Process templates with Mustache
    • Combine into single Typst file
    • Compile to PDF

Configuration

User configuration

report_settings.yaml

This file sets the main user-modifiable settings for the report. These include the report dates, the location of the data files, and the “What’s new” text.

If necessary and appropriate, additional settings can be added here, but the R code and Typst templates will also need changes to use the new setting.

figure_settings.yaml

This file contains various settings for producing the figures for the report. These include user-modifiable settings for options such as the axis limits or the legend position. The default settings have worked well for past reports so users should rarely need to change these. There are also settings that are used for generating the figures but should not be changed by users.

Other configuration

indicator_config.R contains settings for loading the data for each indicator. This consists of a list with an entry for each indication. For each indication, there is a list containing the file name for the data, a column mapping named character vector that maps the names in the data file to the names used in the R code, and a function for processing the data after it has been loaded. Usually the additional processing function reshapes the data to the form needed for the R code.

setup-cover.typ.tmpl includes Typst code for the colour palettes used for each indicator.