⭐⭐ Add dynamic elements to reports

✅ Step-by-step correction

Author
Affiliation

Hélène Langet

Swiss TPH Research-IT

Published

March 3, 2025

This page provides a step-by-step correction for adding dynamic elements to a simple MS Word report.

Important

To get the most out of your learning experience, attempt to solve the exercise on your own before looking at this correction. Trial and error is an essential part of the learning process, helping to strengthen your understanding and build confidence. Remember, simply copying and pasting the solution without trying to solve the exercise by yourself first will limit your long-term growth. Take your time, experiment, and learn actively!

1 Improve navigation and readability

---
title: My outbreak report
author: Helene Langet
date: "2023-12-31"

format:
 docx:
1  toc: true
2  number-sections: true
3  toc-depth: 2

execute:  
 echo: false        
 warning: false      
---
1
Set the toc field to true to enable a table of contents (toc) at the beginning of your rendered MS Word report, making it easier for readers to navigate through sections.
2
This option automatically numbers all section headings (e.g., 1, 1.1, 1.2), providing a clear, hierarchical structure.
3
This limits the table of contents to display only two levels of headings.
Important
  • Remember that YAML is a whitespace-sensitive language where indentation determines the structure
  • 🚫 Do NOT use tabs—they are not recognized.
  • ✅ Use two spaces per indentation level to ensure consistency and avoid errors.
  • In this example, the table of contents settings are applied specifically to the MS Word document output. If you want these settings to apply to all output formats (like HTML or PDF), move them to a higher level in the YAML header.
  • When you open the rendered MS Word document, you might see the following warning message: This document contains fields that may refer to other files. Do you want to update the fields in this document?. Do not worry, this is completely normal and does not indicate an error. This message appears because the document contains dynamic fields, such as the table of contents, cross-references, or figure/table captions. Click “Yes” to ensure all references and the table of contents are properly updated. If you click “No,” the document will still open, but some fields may not reflect the latest changes. This is a standard behavior in MS Word when working with dynamic content.

2 Implement dynamic calculations

2.1 In the YAML header

---
title: My outbreak report
author: Helene Langet
4date: last-modified
5date-format: long

format:
 docx:
  toc: true       
  number-sections: true
  toc-depth: 2

execute:  
 echo: false        
 warning: false       
---
4
Instead of manually entering a date (e.g., 2023-12-31), this setting automatically updates the date to the last time the MS Word document was generated (but this does not reflect when the source Quarto document was last edited).
5
Formats the date to be displayed in a full, human-readable format December 31, 2023. This improves readability, making the report look more polished.

2.2 In the Quarto notebook

```{r}
# Filter the data frame to include only the cases that occurred within the defined period
subdf <- df |>
 dplyr::filter(date >= period_start & date <= period_end)
```
```{r}
6n_all <- nrow(subdf)
7n_confirmed <- nrow(subdf |> dplyr::filter(confirmed == 1))
8n_death <- nrow(subdf |> dplyr::filter(death == 1))
```
6
Compute the total number of cases.
7
Compute the total number of confirmed cases.
8
Compute the total number of death cases.

To insert dynamic values directly into the text, use backticks with {r} within curly brackets. This allows you to run inline R commands within a Quarto document. For example:

  • “The outbreak ran from `​{r} start_date` to `​{r} end_date`.”
  • “This report covers the period `​{r} period_start` to `​{r} period_end`.”
  • “Over the studied period, there were `​{r} n_all` cases, including `​{r} n_confirmed` confirmed cases and `​{r} n_deaths` confirmed deaths.”

The outbreak ran from 2021-01-03 to 2022-12-31. This report covers the period 2021-01-03 to 2022-12-31. Over the studied period, there were 65669 cases, including 52434 confirmed cases and 1214 confirmed deaths.

3 Reference tables

Table 1

```{r}
9#| label: tbl-1
#| tbl-cap: Population characteristics

#Table 1
#Generate a summary table displaying population characteristics
subdf |>                
  dplyr::select(age,
                sex,
                bmi,
                confirmed,
                death) |>
  gtsummary::tbl_summary() |> 
  gtsummary::as_flex_table()
```
9
Assign a label to the table using the prefix tbl-. This label allows you to refer to the table later in the document, making it easier to create cross-references. After the label is defined, you can refer to this table in your text using the syntax @tbl-1, e.g., “@tbl-1 provides a summary of the demographic characteristics and the outcome proportion for the overall population”.
Table 1: Population characteristics

Characteristic

N = 65,6691

age

50 (35, 65)

sex

1

33,114 (50%)

2

32,555 (50%)

bmi

29 (21, 38)

confirmed

0

13,235 (20%)

1

52,434 (80%)

death

0

64,455 (98%)

1

1,214 (1.8%)

1Median (Q1, Q3); n (%)

Table 1 provides a summary of the demographic characteristics and the outcome proportion for the overall population.

Table 2

```{r}
10#| label: tbl-2
#| tbl-cap: Demographic characteristics of deceased vs. alive

subdf |>                           
  dplyr::select(sex,
                age,
                bmi,
                death) |>
  gtsummary::tbl_summary(by = death) |>
  gtsummary::add_overall() |> 
  gtsummary::as_flex_table()
```
10
Assign a label to the table using the prefix tbl-. This label allows you to refer to the table later in the document, making it easier to create cross-references. After the label is defined, you can refer to this table in your text using the syntax @tbl-2, e.g., “@tbl-2 compares the demographic characteristics of individuals who died versus those who are still alive.”.
Table 2: Demographic characteristics of deceased vs. alive

Characteristic

Overall
N = 65,6691

0
N = 64,4551

1
N = 1,2141

sex

1

33,114 (50%)

32,504 (50%)

610 (50%)

2

32,555 (50%)

31,951 (50%)

604 (50%)

age

50 (35, 65)

50 (35, 65)

52 (37, 67)

bmi

29 (21, 38)

29 (21, 38)

34 (28, 41)

1n (%); Median (Q1, Q3)

…, while Table 2 compares the demographic characteristics of individuals who died versus those who are still alive.

4 Reference figures

Figure 1

```{r}
11#| label: fig-1
#| fig-cap: Weekly count of all cases, confirmed cases and deaths
12#| fig-width: 8
13#| fig-height: 4

# Aggregate the data to get the weekly count of all cases, confirmed cases and deaths
weekly_data <- subdf |>
 dplyr::group_by(week) |>
 dplyr::summarise(count = dplyr::n(),
          confirmed_count = sum(confirmed == "1"),
          death_count = sum(death == "1"))

# Plot the weekly cases, confirmed cases and deaths
ggplot2::ggplot(weekly_data, ggplot2::aes(x = week)) +
 ggplot2::geom_line(ggplot2::aes(y = count,
                 color = "All cases"),
           size = 1) +
 ggplot2::geom_line(ggplot2::aes(y = confirmed_count,
                 color = "Confirmed cases"),
           size = 1) +
 ggplot2::geom_line(ggplot2::aes(y = death_count,
                 color = "Confirmed deaths"),
           size = 1) +
 ggplot2::labs(x = "Week",
        y = "Count",
        color = "Legend") +
 ggplot2::scale_color_manual(values = c("All cases" = "#440e54",
                     "Confirmed cases" = "#f8766d",
                     "Confirmed deaths" = "#128984")) +
 ggplot2::theme_minimal() +
 ggplot2::theme(panel.grid.major.y = ggplot2::element_line(linewidth = 0.5, linetype = "dashed", color = "grey"),
         panel.grid.minor.y = ggplot2::element_line(linewidth = 0.5, linetype = "dashed", color = "grey"),
         panel.grid.major.x = ggplot2::element_blank(),
         panel.grid.minor.x = ggplot2::element_blank())
```
11
Assign a label to the figure using the prefix fig-. This label allows you to refer to the table later in the document, making it easier to create cross-references. After the label is defined, you can refer to this table in your text using the syntax @fig-1, e.g., “@fig-1 illustrates the outbreak’s progression, which can be divided into distinct phases.”.
12
Set the width of the figure to 8 inches by using the fig-width option. This option can also be specified globally in the YAML header of the Quarto notebook.
13
Set the height of the figure to 4 inches by using the fig-height option. This option can also be specified globally in the YAML header of the Quarto notebook.
Figure 1: Weekly count of all cases, confirmed cases and deaths

Figure 1 illustrates the outbreak’s progression, which can be divided into distinct phases.

Example of rendering with fig-width and fig-height both set to 4

Weekly count of all cases, confirmed cases and deaths

Example of rendering with fig-width set to 10 and fig-height set to 3

Weekly count of all cases, confirmed cases and deaths

5 Reference code chunks

Listing 1: R code for modelling 
```{r}
#| lst-label: lst-1            
#| lst-cap: "R code for modelling"

coeffs <- glm(death ~ bmi + age,       
       subdf |> dplyr::filter(confirmed == "1"), 
       family = binomial)
```
  • Assign a label to the code chunk by using the lst-label chunk option. After the label is defined, you can refer to this code chunk in your text using the syntax @lst-1, e.g., “It is implemented in R as shown in the code chunk referenced by @lst-1”.
  • Add a caption to the code-chunk by using the lst-cap chunk option.

The logistic regression model uses death as the response variable, and bmi and age as predictor variables. It is implemented in R as shown in the code chunk referenced by Listing 1.

6 Add bibliographic references

6.1 To do in the YAML header

---
title: My outbreak report
author: Helene Langet
date: last-modified
date-format: long

format:
 docx:
  toc: true
  number-sections: true
  toc-depth: 2
  
14bibliography: my_biblio.bib

execute:  
 echo: false        
 warning: false
---
14
Link the bibliography (BibTeX) file my_biblio.bib file by adding it to the YAML header of your Quarto notebook using the bibliography option.
Important

The BibTeX file must be in the same folder as your Quarto notebook. If the BibTeX file is stored in a different folder, specify the path of the file relative to the Quarto notebook in the bibliography field.

6.2 To do in the bibTeX file

Open the file my_biblio.bib on your computer. If the file does not exist yet, create a new text file and name it my_biblio.bib. Once the file is open, you will need to add the following text, which contains the reference information for the article we want to cite. This text includes all the citation details you need, such as the article’s title, authors, journal name, volume, and publication date. Simply paste it exactly as shown into your my_biblio.bib file, and save the file.

@article{Bangwen2025,
 title = {Suspected and confirmed mpox cases in DR Congo: a retrospective analysis of national epidemiological and laboratory surveillance data, 2010–23},
 volume = {405},
 ISSN = {0140-6736},
 url = {http://dx.doi.org/10.1016/S0140-6736(24)02669-2},
 DOI = {10.1016/s0140-6736(24)02669-2},
 number = {10476},
 journal = {The Lancet},
 publisher = {Elsevier BV},
 author = {Bangwen, Eugene and Diavita, Ruth and De Vos, Elise and Vakaniaki, Emmanuel Hasivirwe and Nundu, Sabin Sabiti and Mutombo, Annie and Mulangu, Felix and Abedi, Aaron Aruna and Malembi, Emile and Kalonji, Thierry and Kacita, Cris and Kinganda-Lusamaki, Eddy and Wawina-Bokalanga, Tony and Kremer, Cécile and Brosius, Isabel and Van Dijck, Christophe and Bottieau, Emmanuel and Vercauteren, Koen and Amuri-Aziza, Adrienne and Makangara-Cigolo, Jean-Claude and Muyamuna, Elisabeth and Pukuta, Elisabeth and Nguete, Beatrice and Kaba, Didine and Kabamba, Joelle and Hughes, Christine M and Tshiani-Mbaya, Olivier and Rimoin, Anne W and Hoff, Nicole A and Kindrachuk, Jason and Hens, Niel and Peeters, Martine and Low, Nicola and McCollum, Andrea M and Shongo, Robert and Mukadi-Bamuleka, Daniel and Muyembe-Tamfum, Jean-Jacques and Ahuka-Mundeke, Steve and Liesenborghs, Laurens and Mbala-Kingebeni, Placide},
 year = {2025},
 month = feb,
 pages = {408–419}
}

6.3 To do in the Markdown text

You can refer to this citation in your Markdown text using the syntax [@Bangwen2025].

(1) describes trends in suspected and confirmed monkeypox virus cases in the Democratic Republic of Congo using epidemiological and laboratory surveillance data collected from 2010 to 2023.

6.4 Visual editor

If you are not familiar with BibTeX files or programming, Quarto’s visual mode offers user-friendly tools for managing citations, allowing you to handle most of the previous steps automatically.

7 Format MS Word reports with styles

---
title: My outbreak report
author: Helene Langet
date: last-modified
date-format: long

format:
 docx:
15  reference-doc: swisstph_template.docx
  toc: true
  number-sections: true
  toc-depth: 2
  
bibliography: my_biblio.bib

execute:  
 echo: false        
 warning: false
---
15
Apply the Swiss TPH template swisstph_template.docx to your rendered MS Word report using the reference-doc field (specific to MS Word outputs). This ensures that your report adheres to the Swiss TPH template, maintaining consistent styling across fonts, margins, headings, and other formatting elements.
Important

The MS Word template file must be in the same folder as your Quarto notebook. If the template file is stored in a different folder, specify the path of the file relative to the Quarto notebook in the reference-doc field.

References

1.
Bangwen E, Diavita R, De Vos E, Vakaniaki EH, Nundu SS, Mutombo A, et al. Suspected and confirmed mpox cases in DR congo: A retrospective analysis of national epidemiological and laboratory surveillance data, 2010–23. The Lancet [Internet]. 2025 Feb;405(10476):408–19. Available from: http://dx.doi.org/10.1016/S0140-6736(24)02669-2

Reuse

CC-BY