---
title: "Percentages and sums"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Percentages and sums}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, include = FALSE}
library(scrutiny)
```

Two tests check whether reported percentages and sums can have been derived from reported counts:

- `percentage_of()` and `percentage_of_map()` check whether a reported percentage is consistent with a reported count and total.
- `add_up_to()` and `add_up_to_map()` check whether reported counts, such as group sizes, sum to a reported total.

The math is trivial. What the functions add is safe application at scale: the `*_map()` functions test every row of a data frame, `audit()` summarizes their results, and `percentage_of()` handles rounding in exact integer arithmetic, so floating-point error cannot change a result. All of these functions are experimental.

## Percentages

### Single cases: `percentage_of()`

40 out of 120 is 33.33...%, so it can be reported as 33 or 33.3, but not as 34:

```{r}
percentage_of(absolute = 40, percentage = 33, n = 120, digits_percentage = 0)
percentage_of(40, 34, 120, digits_percentage = 0)

percentage_of(
  absolute = 40,
  percentage = 33.3,
  n = 120,
  digits_percentage = 1
)
```

`digits_percentage` is required, like `digits_x` in `grim()`, since a numeric value does not keep trailing zeros. `rounding`, `threshold`, and `symmetric` work as in `grim()`.

This check is stricter than `grim()` with `x_meaning = "percentage"`, which only asks whether *some* count out of `n` could have produced the percentage. `percentage_of()` asks about one specific count, so it needs that count to be reported.

### Many cases: `percentage_of_map()`

`percentage_of_map()` tests every row of a data frame with the columns `absolute`, `percentage`, and `n`:

```{r}
df <- tibble::tibble(
  absolute = c(40, 37, 25),
  percentage = c(33, 31, 20),
  n = 120
)

df |>
  percentage_of_map(digits_percentage = 0)
```

25 out of 120 is 20.8%, which would have been reported as 21, so the third row is inconsistent. `audit()` summarizes the results:

```{r}
df |>
  percentage_of_map(digits_percentage = 0) |>
  audit()
```

### Investigating possible causes of inconsistencies

A `FALSE` result means that the three values cannot all be correct as reported, not why. The cause might be trivial: the percentage may be based on a denominator other than `n`, such as the number of valid responses or the sample size before loss to follow-up.

`percentage_of_map_seq()` varies the counts, percentages, and totals a few steps up and down and tests each resulting value set, as `grim_map_seq()` does. With `var = "n"`, it shows which nearby denominators would make the percentage consistent:

```{r}
df |>
  percentage_of_map_seq(digits_percentage = 0, var = "n")
```

The nearest consistent total is two steps away: 25 out of 122 is 20.49%, reported as 20.

`audit()` counts the "hits", the varied value sets that are consistent:

```{r}
df |>
  percentage_of_map_seq(digits_percentage = 0, var = "n") |>
  audit()
```

## Sums

### Single cases: `add_up_to()`

`add_up_to()` checks whether counts sum to a total:

```{r}
add_up_to(c(40, 37, 43), total = 120)
add_up_to(c(40, 37, 44), total = 120)
```

A missing or fractional value gives `NA`: a fractional count describes no group, and a sum of decimals is not exact in floating-point arithmetic.

### Many cases: `add_up_to_map()`

`add_up_to_map()` adds up any number of columns, selected with [tidyselect syntax](https://dplyr.tidyverse.org/reference/dplyr_tidy_select.html) as in `dplyr::select()`, and compares the sum to a `total` column:

```{r}
df_groups <- tibble::tribble(
  ~n_control , ~n_treatment , ~n_waitlist , ~total ,
          40 ,           37 ,          43 ,    120 ,
          25 ,           26 ,          24 ,     75 ,
          31 ,           30 ,          30 ,     90 ,
)

df_groups |>
  add_up_to_map(summands = starts_with("n_"))

df_groups |>
  add_up_to_map(summands = starts_with("n_")) |>
  audit()
```