slides.qmd

---
title: "Parametrized Nice Reports with Quarto and PDF"
subtitle: "UseR 2024"
author: "Thomas Vroylandt, Kantiles"
format: 
  revealjs:
    theme: "assets/custom.scss"
    code-overflow: wrap
    df-print: paged
    pdf-separate-fragments: true
filters: [assets/bg_inverse.lua]
execute: 
  echo: true
  eval: false
  message: false
  warning: false
---

## whoami

- Founded a consultancy business <span class="bottom-img">![](img/logo_kantiles_new_dark.png){width=20%}</span>

- Also work with [R for the Rest of Us](https://rfortherestofus.com/consulting)  <span class="bottom-img">![](https://rfortherestofus.com/visuals/rru-logo-blue-square.png){width=10%}</span>

- Creator of the `pagedreport` package [{{< fa link >}}](https://pagedreport.rfortherestofus.com/)

- Produced 1000+ parametrized reports

**Contact me:**
[thomas@kantiles.com](mailto:thomas@kantiles.com)
[{{< iconify fa6-brands github >}}](https://github.com/tvroylandt)
[{{< iconify fa6-brands linkedin >}}](https://www.linkedin.com/in/thomas-vroylandt-9a2334190/)
[{{< fa link >}}](https://tvroylandt.github.io/personal/)

# Parametrized Reporting ? {background-image="img/print.jpg"}

## From one report many

:::{style="text-align: center;"}
:::{.icon-list}
{{< fa sliders size=3x >}}  {{< fa plus size=2x >}} {{< fa file size=3x >}} {{< fa plus size=2x >}} {{< fa database size=3x >}} {{< fa plus size=2x >}} {{< fa chart-simple size=3x >}} {{< fa plus size=2x >}} {{< fa comments size=3x >}}
:::
:::{.fragment}
{{< fa equals size=2x >}}
:::

:::{.fragment}
{{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}}{{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}}{{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}}{{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}}{{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}} {{< fa file-pdf size=3x >}}
:::
:::

## PSC Housing [{{< fa link >}}](https://housingprofiles.pschousing.org/) [{{< fa link >}}](https://www.ctdata.org/blog/2020-psc-housing-data-profiles)

:::{layout="[1,1]" .shadow}
![](img/psc 1.jpg){width=90%}

![](img/psc 2.jpg){width=90%}
:::

## Oregon Voices [{{< fa link >}}](https://orvoices.org/your-county/)

:::{layout="[1,1]" .shadow}
![](img/or_voices_1.jpg){width=90%}

![](img/or_voices_2.jpg){width=90%}
:::

## IA2030 [{{< fa link >}}](https://scorecard.immunizationagenda2030.org/pdfs/afg.pdf) [{{< fa link >}}](https://publichealth.jhu.edu/ivac/2024/new-ia2030-country-profiles-to-track-immunization-achievements)

:::{layout="[1,1]" .shadow}
![](img/Afghanistan a.jpg){width=90%}

![](img/Afghanistan b.jpg){width=90%}
:::

## Child Welfare Program

:::{layout="[1,1]" .shadow}
![](img/cwp_1.jpg){width=90%}

![](img/cwp_2.jpg){width=90%}
:::

## Why not a dashboard ?

:::columns
:::{.column .fragment}

**Dashboard**

- <u>Pull</u> approach

- Bring global & detailed understanding

- Interactive viz and tables

- For analysts & data practitioners

- https://

:::


:::{.column .fragment}

**Reports**

- <u>Push</u> approach

- Bring local comprehension & awareness

- Static tailored viz

- For people on the field & partners

- <u>Portable</u> Document Format (PDF)

:::
:::

## Why not something else ?

- Infographics
- Graphs
- Analysis note
- Excel files
- Data API
- ...

## Why not something else ?

Ask: 

- for what ?
- for who ?
- frequency
- ability to build yourself
- maintenance

# Parameters {background-image="img/music.jpg"}

## Choose your parameters

:::{layout="[1,1,1]"}
:::fragment
Areas

![](img/map.png)
:::
:::fragment
Sectors

![](img/sectors.png)
:::
:::fragment
Units

![](img/units.png)
:::
:::

:::fragment
> {{< fa lightbulb >}} Combine them but check you have enough data
:::

## Put them on the header

```{yaml}
---
title: "IA2030 Country Profile"
subtitle: "`r params$country`: 2023"

# params to change here
params:
  country: "Somalia"
---
```

And re-use them with `params$XXX` :

- in code
- in inline text
- in your style

## Pass the salt

- CSS

```{css}
<style>
:root{
  --country-name: "`r params$country`";
}
</style>
```

- Typst (can be nested)

```{yaml}
---
country_name: '`r params$country`'
---
```

# Tools {background-image="img/tools.jpg"}

## Pick up a tool

:::fragment
![](https://quarto.org/quarto.png){width=50% fig-align="center"}
:::

:::columns

:::{.column width=33% .fragment}
**Text**

![](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/416px-Markdown-mark.svg.png){width=40%}

:::

:::{.column width=33% .fragment}
**Computations**

![](https://upload.wikimedia.org/wikipedia/commons/thumb/1/1b/R_logo.svg/1448px-R_logo.svg.png){width=35%}

![](https://upload.wikimedia.org/wikipedia/commons/thumb/c/c3/Python-logo-notext.svg/230px-Python-logo-notext.svg.png){width=30%}

:::

:::{.column width=33% .fragment}
**PDF engines**

<span class="bottom-img">![](https://upload.wikimedia.org/wikipedia/commons/thumb/9/92/LaTeX_logo.svg/1599px-LaTeX_logo.svg.png){width=40%}</span>

<span class="bottom-img">![](https://typst.app/assets/images/typst.svg){width=36%}</span>

<span class="bottom-img">![](https://raw.githubusercontent.com/Kozea/WeasyPrint/gh-pages/css/img/logotype-black.svg){width=80%}</span>

<span class="bottom-img">![](img/pagedjs.png){width=80%}</span>

:::


:::

## Comparison

:::columns
:::{.column width=33% .fragment}

**Typst**

- Quarto format

- Lightning quick

- Custom langage for layout

- Great for simple templates

:::


:::{.column width=33% .fragment}

**`weasyprint`**

- Pandoc engine

- Quick

- No preview

- Best tool for most of the cases

- French {{< fa frog >}}

:::


:::{.column width=33% .fragment}

**`pagedjs-cli`**

- Pandoc engine

- No direct preview

- Most complete tool

- JS based

:::
:::

## Design advices

- Make your parameters explicit

![](img/country_name_explicit.jpg)

:::fragment
- Think about the extreme cases like long names in margins

![](img/long_name_2.png)

![](img/long_name_1.png)
:::

## Design advices

- Make your sections visuals with named pages & colors

:::{layout="[1,1,1]" .shadow}
![](img/psc_4.jpg){width=100%}

![](img/psc_3.jpg){width=100%}

![](img/psc 2.jpg){width=100%}
:::

## Design advices

- Columns are great but difficult to handle

:::{layout="[1,1]" .shadow}
![](img/Afghanistan b.jpg){width=70%}

![](img/or_voices_2.jpg){width=70%}
:::


## Create a template with [Typst](https://typst.app/)

Set up the format + use partials:

```{yaml}
format: 
  typst:
    template-partials: 
      - typst-template.typ
      - typst-show.typ
    font-paths: fonts/
```

- `typst-show.typ` transfer the parameters
- `typst-template.typ` is the template

:::fragment
> {{< fa lightbulb >}} `font-paths` allow you to use custom fonts by putting them in a folder
:::

## Create a template with [Typst](https://typst.app/)

`typst-show.typ`

```{typst}
#show: my-report.with(
  // main params
  $if(title)$
    title: "$title$",
  $endif$
  $if(subtitle)$
    subtitle: "$subtitle$",
  $endif$

  // add params
  $if(country-name)$
    country_name: "$country-name$",
  $endif$
  )
```

## Create a template with [Typst](https://typst.app/)

`typst-template.typ`: **all is valid until replaced**
  
```{typst}
// format with custom parameters
#let my-report(
  title: "Title",
  subtitle: none,
  country_name: none
  body,
) = {
  // text default
  set text(
    font: "Calibri",
    size: 11pt,
  )

  // --- Configure first page ---
  set page(
    "us-letter",
    background: place(right, rect(fill: rgb(#123456), width: 30%, height: 100%)),
    margin: (left: 1in, right: 1in, top: 0.7in, bottom: 1in),
  )

  // --- title grid ---
  v(5%)
  // logo
  image("logo.svg", height: 10%)
  v(10%)
  pad(text(16pt, weight: "regular", country_name), right: 30%)
  v(5%)

  pagebreak()
```

## Create a template with [Typst](https://typst.app/)

```{typst}
  // --- Configure the rest of the pages ---
  set page(
    "us-letter",
    background: place(top, rect(fill: rgb(#123456), width: 100%, height: 0.5in)),
    footer: {
      line(length: 100%)
    },
    margin: (left: 1in, right: 1in, top: 0.7in, bottom: 1in),
  )

  // --- headings ---
  // level 1 is ## if there is no #
  // level 2 is ###
  // level 3 is ####
  show heading.where(level: 1): it => [
    #set text(17pt, weight: "bold")
    #block(it.body)
  ]

  show heading.where(level: 2): it => [
    #set text(fill: rgb(maincolor), size: 15pt, weight: "regular")
    #block(it.body)
  ]

  show heading.where(level: 3): it => [
    #set text(fill: rgb(maincolor), size: 12pt, weight: "regular")
    #block(it.body)
  ]

  // --- body ---
  body
}
```

## Create a template with CSS tools

- All the others tools are based on [CSS Paged Media](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_paged_media)

- Differences but more or less compatible between them

- I did a [full talk](https://github.com/tvroylandt/pagedown_rr2021) about how to template things (in French) for `pagedown`. See the video [{{< fa video >}}](https://www.youtube.com/watch?v=Vk5q_pvp1EE)

:::fragment
- Print to PDF:

  - output to HTML + use bash command `weasyprint` (or `pagedjs-cli`)
  - output to PDF + use `pdf-engine: weasyprint`

:::

## Quick how-to

- Add your parameters as CSS vars: fonts, colors, margins, images

```{css}
:root {
  /* colors */
  --report-navy: #1f4675;
  --report-light-blue: #59b8cd;
  --report-red: #eb5a53;

  /* fonts */
  --main-font: "Calibri";
  --header-font: "Montserrat";

  /* margin units */
  --unit: 0.7in;
  --unit_neg: -0.45in;
}
```

## Quick how-to

- Create your global style with them :

```{css}
body {
  font-family: var(--main-font);
}
h1, h2, h3 {
  color: var(--report-red);
}
p {
  font-weight: 400;
  font-size: 12pt;
  color: var(--report-navy);
  padding-left: 0.55in;
}
```
  
> {{< fa lightbulb >}} Vars that have been created in the Quarto file can also be used

## Quick how-to

- Define page size and margins

```{css}
@page {
  /* page size */
  size: Letter;

  /* margins */
  margin-top: 1in;
  margin-left: 0.3in;
  margin-right: 1in;
  margin-bottom: 1in;

}
```

## Quick how-to

- Add content in margins

```{css}
@page {
  /* country name */
  @top-left {
    content: var(--country-name);
  }
   /* logo */
  @top-right {
    content: "";
    width: 3.3in;
    background: url(img/logo_white.svg);
    background-repeat: no-repeat;
    background-size: 3in;
  }
}
```

:::fragment
> {{< fa lightbulb >}} Use `content: "";` to display the background color or image.
:::

## Quick how-to

- Add content in margins

```{css}
@page {
  /* numbering */
  @bottom-right {
    content: counter(page);
    width: 7.1in;
    font-weight: bold;
  }
}
```

> To learn more about content in margins [{{< fa link >}}](https://pagedjs.org/documentation/7-generated-content-in-margin-boxes/)

## Quick how-to

- Build title page

```{css}
@page:first{
  background-image: var(--cover-url);
  background-repeat: no-repeat, no-repeat;
  background-size: 5in, cover;
  background-position: 10% 10%, 50% 50%;
  @bottom-left {
    display: none;
  }
}
```

- Don't forget `.title` and others

:::fragment
> {{< fa lightbulb >}} `display: none;` helps to remove the global content in margins
:::

## Quick how-to

- Define named pages
  
    - with fenced div `:::named1` + `:::` 
    - or classic HTML `<div class="named1">` + `</div>`
    
    - CSS side :

```{css}
.named1 {
  page: .namedLayout;
}

@page .namedLayout {
  @top-left {
    background-color: var(--report-navy);
    color: white;
  }
}
```

## Quick how-to

- And the content inside too

```{css}
.named1 > h3 {
  color: var(--report-navy);
}
```


## Quick how-to

- Define utility functions :

  - columns (use [CSS Grid](https://www.w3schools.com/css/css_grid.asp) first !)
  - `img` -> remove defaults margins
  - ...

:::fragment
> {{< fa lightbulb >}} You can arrange some positions with negative margins and positive paddings. Play with them !
:::

:::fragment
> {{< fa lightbulb >}} Since page size is fixed, think to use `position: absolute;` if needed
:::

## Presenting `quarto.report` [{{< iconify fa6-brands github >}}](https://github.com/kantiles/quarto.report)

:::incremental
- Quarto extension
- based on `weasyprint`
- Aim at facilitating templating
- Can be use for parametrized reporting
- Both R & Python
:::

:::fragment
```{bash}
quarto add kantiles/quarto.report
```
:::

## Presenting `quarto.report` [{{< iconify fa6-brands github >}}](https://github.com/kantiles/quarto.report)

Change parameters in the YAML (or `_quarto.yml` file)

```{yaml}
style:
  font:
    header: "Outfit"
    main: "Montserrat"
    mono: "Fira Code"
    size: 12pt
  color:
    font: "#404040"
    font-accent: "#fdfdfd"
    accent: "#123456"
    third: "#987654"
  pagesize:
    width: 210mm
    height: 297mm
  logo: url(logo_url)
  main-img: url(img_url)
```

## `quarto.report` - `typewriter`

```{yaml}
format:
    quarto.report-pdf+typewriter
```

- main image on title page
- table of contents by default

:::{layout="[1,1,1,1]" .shadow}
![](img/typewriter_1.jpg){width=90%}

![](img/typewriter_2.jpg){width=90%}

![](img/typewriter_3.jpg){width=90%}

![](img/typewriter_4.jpg){width=90%}
:::

## `quarto.report` - `chalk`

```{yaml}
format:
    quarto.report-pdf+chalk
```

- two colors template
- table of contents by default

:::{layout="[1,1,1,1]" .shadow}
![](img/chalk_1.jpg){width=90%}

![](img/chalk_2.jpg){width=90%}

![](img/chalk_3.jpg){width=90%}

![](img/chalk_4.jpg){width=90%}
:::


## `quarto.report` - `corner`

```{yaml}
format:
    quarto.report-pdf+corner
```

- well suited for parametrised reporting
- one additional named page by default

:::{layout="[1,1,1,1]" .shadow}
![](img/corner_1.jpg){width=90%}

![](img/corner_2.jpg){width=90%}

![](img/corner_3.jpg){width=90%}

![](img/corner_4.jpg){width=90%}
:::

# Data {background-image="img/reference.jpg"}

## Prepare your data

- Avoid as much as possible computations within the report

- Pay attention to formats - use `scales`

- {{< fa warning >}} **Make sure your data is unique by parameter**

## Check missing data

Compute explicit missing data with `tidyr::complete`

![](img/na_problem.png)

# Graphs {background-image="img/graphs.jpg"}

## Pay attention to limits

- Your graphs should work in all cases
- The more granular you go, the more extreme your values will be
- You should plot your data first

:::fragment
> {{< fa lightbulb >}} If you got this warning from `ggplot2`, you probably messed up something with limits
>
>```
>Warning message:
>Removed 7 rows containing missing values or values outside the scale range
>(`geom_point()`).
>```
:::

## Pay attention to limits

Limits can be set dynamically 

```{r}
ggplot(...) +
  ... +
  scale_x_continuous(
    breaks = seq(2021, 2023, 1),
    limits = c(min(df$year) - .1, max(df$year) + .1),
    position = "top",
    labels = c("Baseline", "2022", "2023")
  ) 
```

## Handle the size

- Output as `svg` or `svglite` (with `fig-format`)
- Setup `fig-width` and `fig-height` for all plots

:::fragment
- Size can be set dynamically (in inches)

```{r}
if(params$country == "Somalia") {
  maps_width <- 5
  maps_height <- 4
} else{
  ...
}
```

Then used in chunks with `!expr`

````{verbatim}
```{r}
#| fig-width: !expr maps_width + .5
#| fig-height: !expr maps_height
```
````
:::

## Set up a reference

:::{layout="[1,1,1]"}
:::fragment
To the global level

![](img/units_global.png)
:::
:::fragment
To others

![](img/units_others.png)
:::
:::fragment
In time

![](img/time_serie.png)
:::
:::

:::fragment
{{< fa lightbulb >}} You can pick them all
:::

## Set up a reference

![](img/ref_bar.png)

## Set up a reference

![](img/ref_others.png)

## Set up a reference

![](img/ref_time_global.png)

## Declutter & highlight

> {{< fa magnifying-glass >}} David talked about all of this at Cascadia R conf [{{< fa link >}}](https://github.com/rfortherestofus/data-viz-parameterized-reporting)

:::fragment
- use facets
- don't label everything
- hide small values
- think about labels position
- highlight what's important
:::

# Text {background-image="img/text.jpg"}

## Stay dynamic

:::fragment
- Be informative about comparisons :

  - growth
  - difference

:::

:::fragment
- Compute before display
:::

:::fragment
- Use [`glue`](https://glue.tidyverse.org/) or [`epoxy`](https://pkg.garrickadenbuie.com/epoxy/index.html)

````{verbatim}
```{epoxy, .data=txt_data_1_3}
In {year}, measles elimination was <span class = "txt-navy">achieved
</span>in {nb_achieved} countries in the WHO region, while it was
<span class = "txt-yellow">re-established</span> in
{nb_reestablished} countries and <span class = "txt-red">
not achieved</span> in {nb_not_achieved} countries.
```
````
:::

## Highlight

:::columns
:::{.column .fragment}
Use :

- <span style="font-size:2em;">size</span>
- <span style="color:#FFAE49;">color</span>
- **weight**

{{< fa arrow-right >}} `<span>...</span>`

:::
:::{.column .fragment}
![](img/big_numbers)

![](img/highlight_text)
:::
:::

# Generate {background-image="img/render.jpg"}

## Render them all

- list of parameters
- `map`
- `quarto_render`

## Render them all

```{r}
map(
  country_list,
  \(x)quarto_render(
    input = "path.qmd",
    output = glue::glue("report_{x}"),
    params = list(country = country)
  ),
  .progress = TRUE
)
```

> {{< fa lightbulb >}} Use `fs::file_move` to move your reports to the right folder (see [{{< fa link >}}](https://github.com/quarto-dev/quarto-r/issues/81))

## Quality insurance

:::fragment
- Check the number of pages !

```{r}
walk(list.files("generated_reports/", full.names = TRUE),
     function(x) {
       pdf_length <- pdftools::pdf_length(x)
       if (pdf_length != 6) {
         print(paste0(x, " reports ERROR"))
       } else{
         print("OK")
       }
     })
```
:::

:::fragment
- Check reports with extreme values :

  - long names
  - outliers in data
  - missing data

:::

# Thanks !