gtsummary.Rmd

---
title: "Tableaux statistiques avancés avec gtsummary"
---

```{r options_communes, include=FALSE, cache=FALSE}
source("options_communes.R")
```

<div class="guide-R">
Le package `gtsummary`{.pkg} est, entre autres, abordé sur **guide-R** dans les chapitres suivants : [Statistique univariée & Intervalles de confiance](https://larmarange.github.io/guide-R/analyses/statistique-univariee.html), [Statistique bivariée & Tests de comparaison](https://larmarange.github.io/guide-R/analyses/statistique-bivariee.html), [Échelles de Likert](https://larmarange.github.io/guide-R/analyses/likert.html), [Régression linéaire](https://larmarange.github.io/guide-R/analyses/regression-lineaire.html), [Régression logistique binaire](https://larmarange.github.io/guide-R/analyses/regression-logistique-binaire.html), [Prédictions marginales, contrastes marginaux & effets marginaux](https://larmarange.github.io/guide-R/analyses/estimations-marginales.html).
</div>

<div class="webin-R">
Ce chapitre est évoqué dans le webin-R #22 (tableaux statistiques avec gtsummary) sur [YouTube](https://youtu.be/52AN4vHK3-c).

Ce chapitre est évoqué dans le webin-R #23 (tableaux statistiques avec gtsummary : suite) sur [YouTube](https://youtu.be/yPSIrTlfGS0).
</div>

L'extension `gtsummary`{.pkg} a déjà été abordée dans d'autres chapitres, notamment via les fonctions `tbl_summary`{data-pkg="gtsummary"} et `tbl_svysummary`{data-pkg="gtsummary"} dans le chapitre sur la [statistique bivariée](statistique-bivariee.html) ou la fonction `tbl_regression`{data-pkg="gtsummary"} dans le chapitre sur la [régression logistique](regression-logistique.html).

Dans ce chapitre, nous allons explorer plus en profondeur les différentes options offertes `gtsummary`{.pkg} pour la réalisation de tableaux statistiques prêts à être publiés.

Les personnes anglophones pourront également se référer à l'excellent site de documentation du package : <https://www.danieldsjoberg.com/gtsummary/>

```{r, results='hide'}
library(gtsummary)
```


## Remarques sur les types de variables et les sélecteurs associés {#type_variables}

`gtsummary`{.pkg} permets de réaliser des tableaux statistiques combinant plusieurs variables, l'affichage des résultats pouvant dépendre du type de variables. 

Par défaut, `gtsummary`{.pkg} considère qu'une variable est **catégorielle** s'il s'agit d'un facteur, d'une variable textuelle ou d'une variable numérique ayant moins de 10 valeurs différentes.

Une variable sera considérée comme **dichotomique** (variable catégorielle à seulement deux modalités) s'il s'agit d'un vecteur logique (`TRUE`/`FALSE`), d'une variable textuelle codée `yes`/`no` ou d'une variable numérique codée `0`/`1`.

Dans les autres cas, une variable numérique sera considérée comme **continue**.

<div class="note">
Si vous utilisez des vecteurs labellisés (voir le [chapitre dédié](facteurs-et-vecteurs-labellises.html)), vous devez les convertir, en amont, en facteur ou en variables numériques. Voir l'extension `labelled`{.pkg} et les fonctions `to_factor`{data-pkg="labelled"}, `unlabelled`{data-pkg="labelled"} et `unclass`{dta-pkg="base"}.
</div>

Nous verrons plus loin qu'il est possible de forcer le type d'une variable et l'existence d'autres types de variables.

`gtsummary`{.pkg} fournit des sélecteurs qui pourront être utilisés dans les options des différentes fonctions, en particulier `all_continuous`{data-pkg="gtsummary"} pour les variables continues, `all_dichotolous`{data-pkg="gtsummary"} pour les variables dichotomiques et `all_categorical`{data-pkg="gtsummary"} pour les variables catégorielles (incluant les variables dichotomiques, utiliser `all_categorical(dichotomous = FALSE)` pour sélectionner les variables catégorielles en excluant les variables dichotomiques).

Dans le cadre des tableaux présentant les résultats d'un modèle statistique, il existe en plus d'autres sélecteurs pour sélectionner certains termes spécifiques : `all_intercepts`{data-pkg="gtsummary"} (pour sélectionner seulement le ou les *intercepts* du modèle), `all_interaction`{data-pkg="gtsummary"} pour les termes d'interactions entre plusieurs variables, `all_contrasts`{data-pkg="gtsummary"} pour sélectionner les variables catégorielles codées avec un contraste particulier.

## Remarques sur la syntaxe des options

De nombreuses options des fonctions de `gtsummary`{.pkg} peuvent s'appliquer seulement à une ou certaines variables. Pour ces options-là, `gtsummary`{.pkg} attends une formule de la forme `variables concernées ~ valeur de l'option` ou bien une liste de formules ayant cette forme.

Par exemple, pour modifier l'étiquette associée à une certaine variable, on peut utiliser l'option `label` de `tbl_summary`{data-pkg="gtsummary"}.

```{r eval=FALSE}
tbl_summary(trial, label = age ~ "Âge")
tbl_summary(trial, label = list(age ~ "Âge", trt ~ "Traitement"))
```

`gtsummary`{.pkg} est très flexible sur la manière d'indiquer la ou les variables concernées. Il peut s'agir du nom de la variable, d'une chaîne de caractères contenant le nom de la variable, ou d'un vecteur contenant le nom de la variable. Les syntaxes ci-dessous sont ainsi équivalentes.

```{r eval=FALSE}
tbl_summary(trial, label = age ~ "Âge")
tbl_summary(trial, label = "age" ~ "Âge")
v <- "age"
tbl_summary(trial, label = v ~ "Âge")
tbl_summary(trial, label = vars(age) ~ "Âge")
```

Pour appliquer le même changement à plusieurs variables, plusieurs syntaxes sont acceptées pour lister plusieurs variables.

```{r eval=FALSE}
tbl_summary(trial, label = c("age", "trt") ~ "Une même étiquette")
tbl_summary(trial, label = c(age, trt) ~ "Une même étiquette")
tbl_summary(trial, label = vars(age, trt) ~ "Une même étiquette")
```

Il est également possible d'utiliser la syntaxe `tidyselect`{.pkg} et les sélecteurs de `tidyselect`{.pkg} comme `everything`{data-pkg="tidyselect"}, `starts_with`{data-pkg="tidyselect"}, `contains`{data-pkg="tidyselect"} ou `all_of`{data-pkg="tidyselect"}. Ces différents sélecteurs peuvent être combinés au sein d'un `c()` ou de `vars()`.

```{r eval=FALSE}
tbl_summary(trial, label = everything() ~ "Une même étiquette")
tbl_summary(trial, label = starts_with("a") ~ "Une même étiquette")
tbl_summary(trial, label = c(everything(), -age, -trt) ~ "Une même étiquette")
tbl_summary(trial, label = age:trt ~ "Une même étiquette")
```

Bien sûr, il est possible d'utiliser les sélecteurs propres à `gtsummary`{.pkg}.

```{r eval=FALSE}
tbl_summary(trial, label = all_continuous() ~ "Une même étiquette")
tbl_summary(trial, label = list(
  all_continuous() ~ "Variable continue",
  all_dichotomous() ~ "Variable dichotomique",
  all_categorical(dichotomous = FALSE) ~ "Variable catégorielle"
))
```

Enfin, si l'on ne précise rien à gauche du `~`, ce sera considéré comme équivalent à `everything()`. Les deux syntaxes ci-dessous sont donc équivalentes.

```{r eval=FALSE}
tbl_summary(trial, label = ~ "Une même étiquette")
tbl_summary(trial, label = everything() ~ "Une même étiquette")
```

## Thèmes

`gtsummary`{.pkg} fournit plusieurs fonctions préfixées `theme_gtsummary_*()` permettant de modifier l'affichage par défaut des tableaux.

La fonction `theme_gtsummary_journal`{data-pkg="gtsummary"} permets d'adopter les standards de certaines grandes revues scientifiques telles que *JAMA* (*Journal of the American Medical Association*), *The Lancet* ou encore le *NEJM* (*New England Journal of Medicine*).

Par défaut, `tbl_summary`{data-pkg="gtsummary"} utilise la médiane et l'intervalle interquartile pour les variables continues. Si on applique `theme_gtsummary_mean_sd`{data-pkg="gtsummary"}, la moyenne et l'écart-type seront utilisés par défaut.

La fonction `theme_gtsummary_language`{data-pkg="gtsummary"} permet de modifier la langue utilisée par défaut dans les tableaux. Les options `decimal.mark` et `big.mark` permettent de définir respectivement le séparateur de décimales et le séparateur des milliers. Ainsi, pour présenter un tableau en français, on appliquera en début de script :

```{r}
theme_gtsummary_language(language = "fr", decimal.mark = ",", big.mark = " ")
```

## Statistiques descriptives avec tbl_summary()

La fonction `tbl_summary`{data-pkg="gtsummary"} permets de réaliser des tris à plats de plusieurs variables, éventuellement croisés selon une variable catégorielle.

On lui passe en entrée un tableaux de données (*data.frame*) et par défaut toutes les variables sont résumées.

```{r}
trial %>%
  tbl_summary()
```

### Sélection des variables (include)

La paramètre `include` permets de spécifier les variables à inclure dans le tableau (et leur ordre). On peut lui passer un vecteur de noms de variables, ou bien utiliser des sélecteurs *tidyselect* (utiliser `c()` si plusieurs sélecteurs).

```{r}
trial %>%
  tbl_summary(include = c("age", "marker", "response"))

trial %>%
  tbl_summary(include = c(age:stage, starts_with("t")))
```


### En fonction d'une seconde variable (by, add_overall)

Le paramètre `by` permets de résumer chacune des variables inclues en fonction d'une variable catégorielle.

```{r}
trial %>%
  tbl_summary(
    include = c(age, stage, response),
    by = trt
  )
```

La fonction `add_overall`{data-pkg="gtsummary"}, appliquée après `tbl_summary`{data-pkg="gtsummary"}, permets, lorsqu'une variable `by` a été définie, de rajouter une colonne avec l'ensemble du fichier. L'option `last` permets de spécifier si l'on veut ajouter cette colonne à la droite du tableau et `col_label` permet de personnaliser le titre de la colonne (noter le recours aux `**` pour indiquer ce qui doit être affiché en gras et `{N}` qui sera remplacé par le nombre d'observations).

```{r}
trial %>%
  tbl_summary(
    include = c(age, stage, response),
    by = trt
  ) %>%
  add_overall(last = TRUE, col_label = "**Ensemble** (effectif total: {N})")
```

### Statistiques affichées (statistic, percent, sort)

Le paramètre `statistic` permets de sélectionner les statistiques à afficher pour chaque variable. On indiquera une chaîne de caractères dont les différentes statistiques seront indiquées entre accolades (`{}`).

Pour une **variable continue**, on pourra utiliser `{median}` pour la médiane, `{mean}` pour la moyenne, `{sd}` pour l'écart type, `{var}` pour la variance, `{min}` pour le minimum, `{max}` pour le maximum, ou encore `{p##}` (en remplacant `##` par un nombre entier entre 00 et 100) pour le percentile correspondant (par exemple `p25` et `p75` pour le premier et le troisième quartile). Utilisez `all_continous`{data-pkg="gtsummary"} pour sélectionner toutes les variables continues.

```{r}
trial %>%
  tbl_summary(
    include = c(age, marker),
    statistic = all_continuous() ~ "Moy. : {mean} [min-max : {min} - {max}]"
  )
```

Il est possible d'afficher des statistiques différentes pour chaque variable.

```{r}
trial %>%
  tbl_summary(
    include = c(age, marker),
    statistic = list(
      age ~ "Méd. : {median} [{p25} - {p75}]",
      marker ~ "Moy. : {mean} ({sd})"
    )
  )
```

Pour les variables continues, il est également possible d'indiquer le nom d'une fonction personnalisée qui prends un vecteur et renvoie une valeur résumé. Par exemple, pour afficher la moyenne des carrés :

```{r}
moy_carres <- function(x) {
  mean(x^2, na.rm = TRUE)
}
trial %>%
  tbl_summary(
    include = marker,
    statistic = ~ "MC : {moy_carres}"
  )
```

Pour une **variable catégorielle**, les statistiques possibles sont `{n}` le nombre d'observations, `{N}` le nombre total d'observations, et `{p}` le pourcentage correspondant. Utilisez `all_categorical`{data-pkg="gtsummary"} pour sélectionner toutes les variables catégorielles.

```{r}
trial %>%
  tbl_summary(
    include = c(stage, response),
    statistic = all_categorical() ~ "{p} % ({n}/{N})"
  )
```

Il est possible, pour une variable catégorielle, de trier les modalités de la plus fréquente à la moins fréquente avec le paramètre `sort`.

```{r}
trial %>%
  tbl_summary(
    include = c(stage, response),
    sort = all_categorical() ~ "frequency"
  )
```

Lorsqu'une variable `by` est définie, on peut utiliser `percent` pour indiquer le type de pourcentages : en ligne avec `"row"`, en colonne avec `"column"` et `"cell"` pour les pourcentages totaux.

```{r}
trial %>%
  tbl_summary(
    include = c(stage, response),
    by = grade,
    statistic = all_categorical() ~ "{p} % ({n}/{N})",
    percent = "row"
  ) %>%
  add_overall(last = TRUE)
```

Pour toutes les variables (catégorielles et continues), les statistiques suivantes sont également disponibles : `{N_obs}` le nombre total d'observations, `{N_miss}` le nombre d'observations manquantes (`NA`), `{N_nonmiss}` le nombre d'observations non manquantes, `{p_miss}` le pourcentage d'observations manquantes (i.e. `N_miss / N_obs`) et `{p_nonmiss}` le pourcentage d'observations non manquantes (i.e. `N_nonmiss / N_obs`).

### Affichage du nom des statistiques (add_stat_label)

Lorsque l'on affiche de multiples statistiques, la liste des statistiques est regroupée dans une note de tableau qui peut vite devenir un peu confuse.

```{r}
tbl <- trial %>%
  tbl_summary(
    include = c(age, marker, grade),
    by = trt,
    statistic = list(
      age ~ "{median} [{p25} - {p75}]",
      marker ~ "{mean} ({sd})"
    )
  )
tbl
```

La fonction `add_stat_label`{data-pkg="gtsummary"} permets d'indiquer le type de statistique à côté du nom des variables ou bien dans une colonne dédiée, plutôt qu'en note de tableau.

```{r}
tbl %>% add_stat_label()
tbl %>% add_stat_label(location = "column")
```

### Forcer le type de variable (type, value)

Comme [abordé plus haut](#type_variables), `gtsummary`{.pkg} détermine automatiquement le type de chaque variable. Par défaut, la variabe `age` est traitée comme variable continue, `death` comme dichotomique (seule la valeur 1 est affichée) et `grade` comme variable catégorielle.

```{r}
trial %>%
  tbl_summary(
    include = c(grade, age, death)
  )
```

Il est cependant possible de forcer un certain type avec l'argument `type`. Précision, lorsque l'on force une variable en dichotomique, il faut indiquer avec `value` la valeur à afficher (les autres sont alors masquées).

```{r}
trial %>%
  tbl_summary(
    include = c(grade, age, death),
    type = list(
      grade ~ "dichotomous",
      age ~ "categorical",
      death ~ "categorical"
    ),
    value = grade ~ "III",
    label = grade ~ "Grade III"
  )
```


### Afficher des statistiques sur plusieurs lignes (continuous2)

Pour les variables continues, `gtsummary`{.pkg} a introduit un type de variable `"continuous2"`, qui doit être attribué manuellement via `type`, et qui permets d'afficher plusieurs lignes de statistiques (en indiquant plusieurs chaînes de caractères dans `statistic`). À noter le sélecteur dédié `all_continuous2`{data-pkg="gtsummary"}.

```{r}
trial %>%
  tbl_summary(
    include = c(age, marker, ttdeath),
    type = c(age, marker) ~ "continuous2",
    statistic = all_continuous2() ~ c("{median} ({p25} - {p75}", "{mean} ({sd})", "{min} - {max}")
  )
```

### Mise en forme des statistiques (digits)

L'argument `digits` permet de spécifier comment mettre en forme les différentes statistiques. Le plus simple est d'indiquer le nombre de décimales à afficher. Il est important de tenir compte que plusieurs statistiques peuvent être affichées pour une même variable. On peut alors indiquer une valeur différente pour chaque statistique.

```{r}
trial %>%
  tbl_summary(
    include = c(age, stage),
    by = trt,
    digits = list(
      all_continuous() ~ 1,
      all_categorical() ~ c(0, 1)
    )
  )
```

Au lieu d'un nombre de décimales, on peut indiquer plutôt une fonction à appliquer pour mettre en forme le résultat. Par exemple, `gtsummary`{.pkg} fournit les fonctions suivantes : `style_number`{data-pkg="gtsummary"} pour les nombres de manière générale, `style_percent`{data-pkg="gtsummary"} pour les pourcentages (les valeurs sont multipliées par 100, mais le symbole % n'est pas ajouté), `style_pvalue`{data-pkg="gtsummary"} pour les p-valeurs, `style_sigfig`{data-pkg="gtsummary"} qui n'affiche (par défaut) que deux chiffres significatifs, ou encore `style_ratio`{data-pkg="gtsummary"} qui est une variante de `style_sigfig`{data-pkg="gtsummary"} pour les ratios (comme les *odds ratios*) que l'on compare à 1.

Il faiut bien noter que ce qui est attendu par `digits`, c'est une fonction et non le résultat d'une fonction. On indiquera donc le nom de la fonction sans parenthèse.

```{r}
trial %>%
  tbl_summary(include = marker)

trial %>%
  tbl_summary(
    include = marker,
    digits = all_continuous() ~ c(style_percent, style_pvalue, style_ratio)
  )
```

Comme `digits` attends à recevoir une fonction (et non le résultat) d'une fonction, on ne peut pas passer directement des arguments aux fonctions `style_*()` de `gtsummary`{.pkg}. Pour cela il faut créer une fonction à la levée :

```{r}
trial %>%
  tbl_summary(
    include = marker,
    statistic = ~ "{mean} pour 100",
    digits = ~ function(x){style_percent(x, digits = 1)}
  )
```

Une syntaxe alternative consiste à avoir recours à la fonction `partial`{data-pkg="purrr"} de `purrr`{.pkg} qui permet d'appeler <q>partiellement</q> une fonction et de renvoyer une nouvelle fonction.

```{r}
trial %>%
  tbl_summary(
    include = marker,
    statistic = ~ "{mean} pour 100",
    digits = ~ purrr::partial(style_percent, digits = 1)
  )
```

À noter dans l'exemple précédent que les fonctions `style_*()` de `gtsummary`{.pkg} tiennent compte du thème défini (ici la virgule comme séparateur de décimale). 

Pour une mise en forme plus avancée des nombres, il faut se tourner vers l'extension `scales`{.pkg} (choir le [chapitre dédié](formater-nombres.html)). ATTENTION : les fonctions de `scales`{.pkg} n'héritent pas des paramètres du thème gtsummary actif. Il faut donc personnaliser le séparateur de décimal dans l'appel à la fonction.

```{r}
trial %>%
  tbl_summary(
    include = marker,
    statistic = ~ "{mean}",
    digits = ~ scales::label_number(accuracy = .01, suffix = " ng/mL", decimal.mark = ",")
  )
```

### Données manquantes (missing, missing_text)

Le paramètre `missing` permets d'indiquer s'il faut afficher le nombre d'observations manquantes (c'est-à-dire égales à `NA`) : `"ifany"` (valeur par défaut) affiche ce nombre seulement s'il y en a, `"no"` masque ce nombre et `"always"` force l'affichage de ce nombre même s'il n'y pas de valeur manquante. Le paramètre `missing_text` permets de personnaliser le texte affiché.

```{r}
trial %>%
  tbl_summary(include = c(trt, age))
trial %>%
  tbl_summary(
    include = c(trt, age),
    missing = "always",
    missing_text = "Nbre observations manquantes"
  )
```

Il est à noter, pour les variables catégorielles, que les valeurs manquantes ne sont jamais pris en compte pour le calcul des pourcentages. Pour les inclure dans le calcul, il faut les transformer en valeurs explicites, par exemple avec `fct_explicit_na`{data-pkg="forcats"} de `forcats`{.pkg}.

```{r}
trial %>%
  tbl_summary(include = response, type = response ~ "categorical")
trial %>%
  mutate(response = response %>% as.factor() %>% forcats::fct_explicit_na(na_level = "non observé")) %>%
  tbl_summary(include = response)
```

### Étiquettes des variables (label)

`gtsummary`, par défaut, prends en compte les étiquettes de variables, si elles existent, et sinon utilisera le nom de chaque variable dans le tableau. Pour rappel, les étiquettes de variables peuvent être manipulées avec l'extension `labelled`{.pkg} et les fonctions `var_label`{data-pkg="labelled"} et `set_variable_labels`{data-pkg="labelled"}.

Il est aussi possible d'utiliser l'option `label` de `tbl_summary`{data-pkg="gtsummary"} pour indiquer des étiquettes personnalisées.

```{r}
iris %>%
  labelled::set_variable_labels(
    Petal.Length = "Longueur du pétale",
    Petal.Width = "Largeur du pétale"
  ) %>%
  tbl_summary(label = Species ~ "Espèce")
```

Pour modifier les modalités d'une variable catégorielle, il faut modifier en amont les niveaux du facteur correspondant.

### Afficher les effectifs (add_n)

La fonction `add_n`{data-pkg="gtsummary"} permets d'ajouter une colonne avec le nombre d'observations (non manquantes par défaut). Plusieurs options permettent de personnaliser le résultat : `col_label` pour modifier l'intitulé de la colonne; `statistic` pour personnaliser la ou les statistiques affichées (la liste des statistiques disponibles est disponible dans le fichier d'aide `add_n.tbl_summary`{data-pkg="gtsummary"}); `last` pour la positition de la colonne; `footnote` pour l'ajout d'une note de tableau.


```{r}
trial %>%
  tbl_summary(include = c(age, marker)) %>%
  add_n()
trial %>%
  tbl_summary(
    include = c(age, marker),
    by = trt,
    missing = "no"
  ) %>%
  add_n(
    statistic = "{n}/{N}",
    col_label = "**Effectifs** (observés / total)",
    last = TRUE,
    footnote = TRUE
  ) %>%
  add_overall(last = TRUE)
```


### Mise en forme du tableau (bold_labels, italicize_levels)

Les fonctions `bold_labels`{data-pkg="gtsummary"}, `bold_levels`{data-pkg="gtsummary"}, `italicize_labels`{data-pkg="gtsummary"} et `italicize_levels`{data-pkg="gtsummary"} permettent d'afficher les étiquettes de variables et les modalités des variables catégorielles en gras ou en italique.

```{r}
trial %>%
  tbl_summary(
    include = c(marker, grade, stage),
    by = trt
  ) %>%
  bold_labels() %>%
  italicize_levels()
```

### Modifer en-têtes et notes (modify_header, modify_spanning_header, modify_footnote)

La fonction `modify_header`{data-pkg="gtsummary"} permet de modifier les en-têtes des colonnes, `modify_spanning_header`{data-pkg="gtsummary"} d'ajouter un chapeau regroupant plusieurs colonnes et `modify_footnote`{data-pkg="gtsummary"}. On doit indiquer une formule ou une liste de formules indiquant les colonnes concernées et la modification souhaitée.

Il faut néanmoins connaître le nom interne des différentes colonnes. Ceux-ci peuvent âtre affichés avec la fonction `show_header_names`{data-pkg="gtsummary"} :

```{r}
tbl <- trial %>%
  tbl_summary(
    include = c(age, grade),
    by = trt
  ) %>%
  add_overall() %>%
  add_p()
tbl
show_header_names(tbl)
```

*label* est la colonne affichant le nom des variables, *stat_0* la colonne totale crée par `add_overall`{data-pkg="gtsummary"} (ou la colonne unique de statistiques en l'absence de paramètre `by`) et *p.value* la colonne crée par `add_p`{data-pkg="gtsummary"}. Lorsqu'il y a un paramètre `by`, des colonnes nommées *stat_1*, *stat_2*, etc. sont crées pour chaque valeur de `by`. La fonction `all_stat_cols`{data-pkg="gtsummary"} permets de sélectionner toutes les colonnes dont le nom commence par *stat_*. On peut également utiliser `all_stat_cols(stat_0 = FALSE)` sélectionner toutes les colonnes associées à `by` mais pas celle crée par `add_overall`{data-pkg="gtsummary"}.

Dans les étiquettes, on peut utiliser des doubles étoiles (`**`) pour indiquer du gras et des tirets simples (`_`) pour de l'italique (il s'agit de codes *markdown*). On peut utliser `{N}` pour afficher le nombre total d'observations. Pour les colonnes associées à `by`, `{level}`, `{n}` et `{p}` correspondent respectivement au niveau du facteur, au nombre d'observations et à la proportion de ce facteur dans l'échantillon total. La valeur `NA` peut être utilisée pour supprimer les notes associées aux colonnes concernées.

```{r}
tbl %>%
  modify_header(
    list(
      label ~ "**Variable**",
      all_stat_cols(stat_0 = FALSE) ~ "_{level}_ (n={n}, {style_percent(p)}%)",
      stat_0 ~ "**TOTAL** (n={N})",
      p.value ~ "**Test de comparaison** (p-valeur)"
    )
  ) %>%
  modify_footnote(everything() ~ NA) %>%
  modify_spanning_header(all_stat_cols() ~ "**Traitement**")
```



### Tests de comparaisons (add_p, separate_p_footnotes)

Lorsqu'une variable `by` est définie, la fonction `add_p`{data-pkg="gtsummary"} permets d'ajouter des tests de comparaisons entre les groupes et d'afficher les p-valeurs.

```{r}
trial %>%
  tbl_summary(
    include = c(trt, marker, age, response, stage),
    by = trt
  ) %>%
  add_p()
```

Par défaut, pour les **variables continues**, un <dfn>test de Kruskal-Wallis</dfn> calculé avec la fonction `kruskal.test`{data-pkg="stats"} est utilisé lorsqu'il y a trois groupes ou plus, et un <dfn>test de Wilcoxon-Mann-Whitney</dfn> calculé avec `wilcox.test`{data-pkg="stats"} (test de comparaison des rangs) lorsqu'il n'y a que deux groupes.

Si l'on affiche des moyennes, il serait plus juste d'utiliser un <dfn>test t de Student</dfn> (test de compairaison des moyennes) calculé avec `t.test`{data-pkg="stats"}.

Pour les **variables catégorielles**, un <dfn>test du Chi²</dfn> calculé avec `chisq.test`{data-pkg="stats"} est utilisé par défaut lorsque les effectifs théoriques sont supérieurs à 5, sinon un <dfn>test de Fosher</dfn> calculé avec `fisher.test`{data-pkg="stats"} est utilisé.

D'autres tests sont disponibles et sont détaillés dans le fichier d'aide `add_p.tbl_summary`{data-pkg="gtsummary"}. 

Le paramètre `test` permets de spécifier pour chaque variable le type de tests à utiliser. La fonction `separate_p_footnotes`{data-pkg="gtsummary"} peut être utilisée pour créer une note de tableau différente pour chaque test. Le paramètre `pvalue_fun` permet d'indiquer une fonction personnalisée pour la mise en forme des p-valeurs.

```{r}
trial %>%
  tbl_summary(
    include = c(trt, marker, age, response, stage),
    statistic = age ~ "{mean} ({sd})",
    by = trt
  ) %>%
  add_stat_label() %>%
  add_p(
    test = list(
      response ~ "fisher.test",
      age ~ "t.test"
    ),
    pvalue_fun = scales::label_pvalue(accuracy = .0001)
  ) %>%
  separate_p_footnotes()
```


### Intervalles de confiance (add_ci)

La fonction `add_ci`{data-pkg="gtsummary"} permets d'ajouter des intervalles de confiance dans des colonnes additionnelles. ATTENTION : par défaut, pour les variables continues, cela calcule les intervalles de confiance d'une moyenne et non d'une médiane. Le type d'intervalle peut être modifié avec `method` (par exemple `"wilcox.test"` pour l'intervalle de confiance d'une médiane). `statistic` permet de personnaliser la présentation de l'intervalle. `conf.level` permets de changer le niveau de confiance. `style_fun` permets de modifier la fonction de formatage des 


```{r}
trial %>%
  tbl_summary(
    include = c(age, stage),
    by = trt,
    statistic = all_continuous() ~ "{mean}"
  ) %>%
  add_overall() %>%
  add_ci()

trial %>%
  tbl_summary(
    include = c(age, marker), 
    statistic = ~ "{median}"
  ) %>%
  add_ci(
    method = ~ "wilcox.test",
    statistic = ~ "entre {conf.low} et {conf.high}",
    conf.level = .9,
    style_fun = ~ scales::label_number(accuracy = .01, decimal.mark = ",")
  )
```

### Différences entre groupes (add_difference)

Si la variable spécfiée dans `by` a exactement 2 niveaux, il est possible de calculer la différence entre deux moyennes (variable continue) ou entre deux proportions (variables dichotomiques uniquement, pas les variables catégorielles), d'afficher l'intervalle de confiance de cette différence et la p-valeur associée (la différence est-elle significativement différente de 0) avec `add_difference`{data-pkg="gtsummary"}.


```{r}
trial %>%
  tbl_summary(
    include = c(age, marker, response),
    by = trt,
    statistic = list(
      all_continuous() ~ "{mean}",
      all_categorical() ~ "{p}%"
    ),
    digits = list(
      all_continuous() ~ 2,
      all_categorical() ~ 1
    )
  ) %>%
  add_difference()
```

D'autres options sont disponibles (comme la possibilité de calculer des différences ajustées sur d'autres variables) et sont explicitées dans le fichier d'aide de `add_difference`{data-pkg="gtsummary"}.

## Tableau croisé avec tbl_cross()

La fonction `tbl_cross`{data-pkg="gtsummary"} est une variation de `tbl_summary`{data-pkg="gtsummary"} permettant de croiser deux variables spécfiées avec les arguments `row` et `col`. Le type de pourcentage peut-être précisé avec l'arguement `percent`. Il est possible d'ajouter le résultat d'un test du Chi² avec `add_p.tbl_cross`{data-pkg="gtsummary"}.

```{r}
trial %>%
  tbl_cross(
    row = grade,
    col = trt,
    percent = "row"
  ) %>%
  add_p(source_note = TRUE)
```


## Données pondérées et tbl_svysummary()

La fonction `tbl_svysummary`{data-pkg="gtsummary"} est similaire à `tbl_summary`{data-pkg="gtsummary"} à l'exception qu'elle prend en entrée un objet de type `survey`{.pkg} défini avec l'extension homonyme. Cela permet de définir une pondération des observations et un plan d'échantillonnage complexe. Les options de `tbl_svysummary`{data-pkg="gtsummary"} sont similaires et il est possible d'utiliser les autres fonctions de `gtsummary`{.pkg} telles que `add_overall`{data-pkg="gtsummary"}, `add_p`{data-pkg="gtsummary"}, `add_n`{data-pkg="gtsummary"}, `add_stat_label`{data-pkg="gtsummary"}, etc.

Il faut noter que les tests statistiques disponibles ne sont pas les mêmes et sont détaillés dans le fichier d'aide de `add_p.tbl_svysummary`{data-pkg="gtsummary"}.

```{r}
Titanic %>%
  as.data.frame() %>%
  survey::svydesign(~ 1, data = ., weights = ~Freq) %>%
  tbl_svysummary(
    by = Survived, 
    percent = "row"
  ) %>%
  add_stat_label(location = "column") %>%
  add_n() %>%
  add_overall(last = TRUE) %>%
  add_p() %>%
  separate_p_footnotes()
```

## Statistiques personnalisées avec tbl_continous() et tbl_custom_summary()

### tbl_continuous()

La fonction `tbl_continuous`{data-pkg="gtsummary"} permets de résumer une variable continue en fonction de deux ou plusieurs variables catégorielles.

Par exemple, pour afficher l'âge moyen de plusieurs sous-groupes :

```{r}
trial %>%
  tbl_continuous(
    variable = age,
    statistic = ~ "{mean}",
    include = c(stage, grade),
    by = trt,
    digits = ~ 1
  )
```


### tbl_custom_summary()

La fonction `tbl_custom_summary`{data-pkg="gtsummary"} permets encore plus de personnalisation que `tbl_continuous`{data-pkg="gtsummary"}.

Comme précédemment, un tableau va être créé avec les paramètres `include` et `by`. On doit également fournir via `stat_fns` une fonction personnalisée qui va recevoir un sous tableau de données (obtenu en croisant `include` et `by`), contenant toutes les variables du fichier, et qui renverra des statistiques personnalisées que l'on affichera avec `statistic`. La fonction peut-être différente pour chaque variable.

Il est également possible d'utiliser quelques fonctions dédiées fournies directement par `gtsummary`{.pkg}.

À noter que l'option `overall_raw` permets d'afficher une ligne total, `overall_raw_label` de personnaliser l'étiquette de cette ligne et `overall_raw_last` de choisir si on souhaite l'afficher en début ou en fin de tableau.

#### tbl_custom_summary() & continuous_summary()

La fonction `continuous_summary`{data-pkg="gtsummary"} permet de reproduire avec `tbl_custom_summary`{data-pkg="gtsummary"} le fonctionnement de `tbl_continuous`{data-pkg="gtsummary"}. `continuous_summary`{data-pkg="gtsummary"} prend un seul argument (le nom d'une variable du fichier). Les statistiques à afficher sont directement précisées avec `statistic`.

Ainsi, pour afficher l'âge moyen (avec l'écart-type) en fonction des variables *trt*, *grade* et *stage* :

```{r}
trial %>%
  tbl_custom_summary(
    include = c("grade", "stage"),
    by = "trt",
    stat_fns = ~ continuous_summary("age"),
    statistic = ~ "{mean} ({sd})",
    overall_row = TRUE,
    digits = ~ 1
  ) %>%
  add_overall() %>%
  modify_footnote(
    update = all_stat_cols() ~ "Âge moyen (ET)"
  )
```

Astuce : la fonction `modify_footnote`{data-pkg="gtsummary"} peut être utilisée pour mettre à jour la note de tableau.

#### tbl_custom_summary() & proportion_summary()

La fonction `proportion_summary`{data-pkg="gtsummary"} permets de calculer une proportion (et son intervalle de confiance). Elle prends en entrée la variable à partir de laquelle calculer la proportion et le ou les valeurs à inclure dans cette proportion. Il faut préciser l'affichage souhaité avec `statistic` et la mise enforme avec `digits`.

Par exemple, pour afficher la proportion de personnes étant à l'étape "T3" ou "T4" (variable *stage*) :

```{r}
trial %>%
  tbl_custom_summary(
    include = c("grade", "trt"),
    stat_fns = ~ proportion_summary(variable = "stage", value = c("T3", "T4")),
    statistic = ~ "{prop}% [{conf.low}-{conf.high}]",
    digits = ~ scales::label_percent(accuracy = .1, decimal.mark = ",", suffix = "")
  )
```

#### tbl_custom_summary() & ratio_summary()

La fonction `ratio_summary`{data-pkg="gtsummary"} calcule le ratio entre deux variables. Elle peut ainsi être utilisée pour produire un tableau d'incidence (nombre de cas / exposition exprimée en personnes-années). On lui indique le nom de la variable à prendre en compte pour le numérateur et celui de la variable pour le dénominateur. Pour chaque sous-groupe, la fonction renvoie `{num}` (somme de la variable définie pour le numérateur), `{denom}` (somme de la variable définie pour le dénominateur) et `{ratio}` (i.e. `{num}`/`{denom}`). Si `{num}` est un nombre entier, l'intervalle de confiance de `{ratio}` est calculé à l'aide de la fonction `poisson.test`{data-pkg="stats"} et accessible via `{conf.high}` et `{conf.high}`.

```{r}
trial %>%
  tbl_custom_summary(
    include = c("stage", "grade"),
    by = "trt",
    stat_fns = ~ ratio_summary("response", "ttdeath"),
    statistic = ~ "{ratio} [{conf.low}; {conf.high}] ({num}/{denom})",
    digits = ~ c(3, 2, 2, 0, 0),
    overall_row = TRUE,
    overall_row_label = "Total"
  ) %>%
  bold_labels() %>%
  modify_footnote(
    update = all_stat_cols() ~ "Ratio [95% CI] (n/N)"
  )
```

#### tbl_custom_summary() & écriture d'une fonction personnalisée

Il est également possible, et c'est là toute la puissance de `tbl_custom_summary`{data-pkg="gtsummary"}, de définir une fonction personnelle et de la passer via `stat_fns`.

Cette fonction sera appellée pour chaque cellule du tableau, chaque cellule étant calculée indépendamment.

Une telle fonction recevra les arguments suivants :

- `data` est un tableau de données contenant un sous-ensemble des données transmises à `tbl_custom_summary`{data-pkg="gtsummary"}, plus précisément le sous-ensemble défini par la valeur courante de `variable` et de `by`. Il faut noter que les valeurs manquantes (`NA`) de `variable` sont également exclues de `data`.
- `full_data` est le tableau de données complet transmis à `tbl_custom_summary`{data-pkg="gtsummary"}.
- `variable` est une valeur textuelle contenant le nom de la variable sur laquelle porte le calcul en cours.
- `by` est une valeur textuelle contenant le nom de la variable `by` s'il y en a une, `NULL` sinon.
- `type` est une valeur textuelle indiquant le type de variable (*continuous*, *categorical*, ...).
- `stat_display` est une valeur textuelle indiquant les statistiques qui seront affichées (i.e. la valeur indiquée dans l'argument `statistic` de `tbl_custom_summary`{data-pkg="gtsummary"}).

La plupart du temps, une fonction personnalisée n'aura pas besoin de tous ces éléments. C'est pourquoi il est recommandé d'inclure `...` dans la définition de la fonction, par exemple `ma_fonction <- function(data, ...){}`.

La fonction devra impérativement renvoyé un `tibble`{data-pkg="tibble"} composé d'une seule ligne et avec une colonne par statistique calculée, le nom de la colonne correspondant avec la statistique demandée dans `statistic`.

Voyons un premier exemple, avec une fonction calculant la somme de *marker* et l'âge moyen.

```{r}
ma_fonction <- function(data, ...) {
  marker_sum = sum(data$marker, na.rm = TRUE)
  mean_age = mean(data$age, na.rm = TRUE)
  dplyr::tibble(
    marker_sum = marker_sum,
    mean_age = mean_age
  )
}

ma_fonction(trial)
```

Construisons un tableau à partir de cette dernière.

```{r}
trial %>%
  tbl_custom_summary(
    include = c(stage, grade),
    by = trt,
    stat_fns = ~ ma_fonction,
    statistic = ~ "A: {mean_age} - M: {marker_sum}",
    digits = everything() ~ c(1, 0),
    overall_row = TRUE
  ) %>%
  add_overall(last = TRUE) %>%
  modify_footnote(
    update = all_stat_cols() ~ "A: âge moyen - M: somme de marker"
  ) %>%
  bold_labels()
```

Dans notre second exemple, nous souhaitons calculer la moyenne et l'intervalle de confiance de la variable affichée en ligne. Cette fois-ci, la variable en cours n'est pas connue à l'avance mais son nom est accessible via l'argument `variable`. On peut donc y accéder avec la syntaxe `data[[variable]]`.

```{r}
mean_ci <- function(data, variable, ...) {
  test <- t.test(data[[variable]])
  dplyr::tibble(
    mean = test$estimate,
    conf.low = test$conf.int[1],
    conf.high = test$conf.int[2]
  )
}

trial %>%
  tbl_custom_summary(
    include = c("marker", "ttdeath"),
    by = "trt",
    stat_fns = ~ mean_ci,
    statistic = ~ "{mean} [{conf.low}; {conf.high}]"
  ) %>%
  add_overall(last = TRUE) %>%
  modify_footnote(
    update = all_stat_cols() ~ "moyenne [IC 95%"
  )
```

Allons un peu plus loin avec notre troisième exemple. Nous nous intéressons non seulement à la moyenne de la variable *marker* pour une sous-catégorie donnée, mais également si cette moyenne est supérieure ou inférieuree à la grande moyenne (toutes catégories confondues). Nous aurons donc besoin de l'ensemble du jeu de données avec `full_data`. Cet exemple nous permets également de voir qu'il est possible de renvoyer une statistique textuelle.

```{r}
diff_to_great_mean <- function(data, full_data, ...) {
  mean <- mean(data$marker, na.rm = TRUE)
  great_mean <- mean(full_data$marker, na.rm = TRUE)
  diff <- mean - great_mean
  dplyr::tibble(
    mean = mean,
    great_mean = great_mean,
    diff = diff,
    level = ifelse(diff > 0, "haut", "bas")
  )
}

trial %>%
  tbl_custom_summary(
    include = c("grade", "stage"),
    by = "trt",
    stat_fns = ~ diff_to_great_mean,
    statistic = ~ "{mean} ({level}, diff: {diff})",
    digits = ~ list(1, as.character, 1),
    overall_row = TRUE
  ) %>%
  bold_labels()
```

<div class="note">
Il n'existe pas encore de fonction `tbl_custom_svysummary` acceptant un objet `survey`{.pkg} en entrée, mais une telle fonction devrait être disponible dans une future version de `gtsummary`{.pkg}.
</div>

### add_stat()

D'un usage plus avancé, `add_stat`{data-pkg="gtsummary"} permets de rajouter une colonne de statistiques personnalisées à un objet `gtsummary`{.pkg} existant. Le calcul ne se fait pas ici cellule par cellule mais variable par variable.

On pourra se référer à l'aide la fonction pour des exemples d'utilisation.

## Résultats d'un modèle avec tbl_regression()

Déjà abordé dans le chapitre sur la [régression logistique](regression-logistique.html), `tbl_regression`{data-pkg="gtsummary"} permets d'afficher les coefficients d'un modèle statistique, avec les intervalles de confiance et les p-valeurs.

`tbl_regression`{data-pkg="gtsummary"} utilise de manière sous-jacente l'extension `broom.helpers`{.pkg} et est donc compatible avec tous les [types de modèles compatibles](https://larmarange.github.io/broom.helpers/articles/tidy.html#supported-models-1).

```{r}
mod <- glm(
  response ~ grade * age + trt, 
  data = trial, 
  family = binomial
)
mod %>% tbl_regression()
```

### Afficher seulement certains coefficients (include)

Le paramètre `include` permets de choisir les variables / termes à afficher.

```{r}
mod %>%
  tbl_regression(include = c(trt, all_interaction()))
```

### Étiquettes des variables (label)

On peut personnaliser les étiquettes des variables avec `label`.

```{r}
mod %>%
  tbl_regression(label = list(
    trt ~ "Traitement",
    "grade:age" ~ "Interaction entre grade et âge"
  ))
```

### Exponentiation des coefficients (exponentiate)

Pour une régression logistique, il est d'usage d'afficher l'exponentiel des coefficients, ce que l'on peut faire en indiquant `exponentiate = TRUE`.

```{r}
mod %>%
  tbl_regression(exponentiate = TRUE)
```

### Changer l'intitulé des colonnes

Comme pour tout tableau `gtsummary`{.pkg}, l'intitulé des colonnes peut être modifié avec `modify_header`{data-pkg="gtsummary"}. On pourra avoir recours à  `show_header_names`{data-pkg="gtsummary"} pour connaître le nom de chaque colonne.

```{r}
tbl <- mod %>% tbl_regression(exponentiate = TRUE)
show_header_names(tbl)
tbl %>%
  modify_header(estimate ~ "**Odds Ratio**")
```

### Afficher des étoiles de signification (add_significance_stars)

La fonction `add_significance_stars`{data-pkg="gtsummary"} ajoute des étoiles de significativité à côté des coefficients. Les options `hide_ci`, `hide_p` et `hide_se` permettent de masquer/afficher les intervalles de confiance, les p-valeurs et les écarts-types.

```{r}
lm(time ~ ph.ecog + sex, survival::lung) %>%
  tbl_regression() %>%
  add_significance_stars(
    hide_ci = FALSE,
    hide_p = FALSE,
    hide_se = TRUE
  )
```

### Variables dichotomiques sur une ligne (show_single_row)

L'argument `show_single_row` permet d'indiquer une liste de variables dichotomiques que l'on souhaite afficher sur une seule ligne (la modalité de référence étant alors masquée). Il est possible d'indiquer `all_dichotomous`{data-pkg="gtsummary"}`()` pour appliquer cette option à toutes les variables dichotomiques.

```{r}
mod %>%
  tbl_regression(show_single_row = trt)
```

### Afficher l'intercept (intercept)

Par défaut, l'intercept n'est pas affiché. Mais on peut forcer son affichage avec `intercept = TRUE`.

```{r}
mod %>%
  tbl_regression(intercept = TRUE)
```

### Mise en forme des coefficients (estimate_fun, pvalue_fun)

L'argument `estimate_fun` permet de fournir une fonction qui sera utilisée pour mettre en forme les coefficients (et les intervalles de confiance) et `pvalue_fun` pour une fonction utilisée pour les p-valeurs. Voir le [chapitre dédié à la mise en forme des nombres](formater-nombres.html).

```{r}
mod %>%
  tbl_regression(
    estimate_fun = scales::label_number(accuracy = .001, decimal.mark = ","),
    pvalue_fun = scales::label_pvalue(accuracy = .001, decimal.mark = ",", add_p = TRUE)
  )
```

### Afficher les coefficients pour les références (add_estimate_to_reference_rows)

L'option `add_estimate_to_reference_rows = TRUE` ajoute la valeur du coefficient pour les modalités de références.

```{r}
mod %>%
  tbl_regression(add_estimate_to_reference_rows = TRUE, exponentiate = TRUE)
```

### P-valeurs globales (add_global_p)

La fonction `add_global_p`{data-pkg="gtsummary"} calcule une p-valeur globale pour chaque variable. On ajoutera `keep = TRUE` pour conserver les p-valeurs individuelles de chaque coefficient.

**Note :** par défaut, les p-valeurs globales calculées sont du type III. Voir la [note dédiée aux p-valeurs globales](regression-logistique.html#type_global_p) dans le chapitre sur la régression logistique.

```{r}
mod %>%
  tbl_regression() %>%
  add_global_p(keep = TRUE)
```

### Ajouter les VIF (add_vif)

Dans le [chapitre sur la multicolinéarité](multicolinearite.html), nous avons abordé les <dfn>facteurs d'inflation de la variance</dfn> (<dfn>FIV</dfn>) ou <dfn lang="en">variance inflation factor</dfn> (<dfn lang="en">VIF</dfn>) en anglais. Ils peuvent être facilement calculés avec `add_vif`{data-pkg="gtsummary"}.

```{r}
mod %>%
  tbl_regression() %>%
  add_vif()
```

### Représenter graphiquement le modèle (plot)

Nous avons déjà abordé dans d'autres chapitres la fonction `ggcoef_model`{data-pkg="gtsummary"} de `GGally`{.pkg} pour la représentation graphiques des coefficients. Pour un graphique rapide, on peut appliquer `plot()` à un tableau généré avec `tbl_regression`{data-pkg="gtsummary"} pour produire rapidement un graphique des coefficients.

```{r}
mod %>%
  tbl_regression(exponentiate = TRUE) %>%
  plot()
```

Cependant, si l'on souhaite plus d'options de personnalisation, on utilisera directement `ggcoef_model`{data-pkg="gtsummary"} de `GGally`{.pkg}.

```{r}
mod %>% 
  GGally::ggcoef_model(exponentiate = TRUE)
```

### Afficher des statistiques globales du modèle (add_glance_table, add_glance_source_note)

La méthode `glance`{data-pkg="broom"} de `broom`{.pkg} permets de calculer des statistiques globales sur un modèle (comme le R² ou l'AIC, les statistiques calculées dépendant de chaque modèle). 

```{r}
mod %>% broom::glance()
```

Ces statistiques globales peuvent être ajoutées au tableau avec `add_glance_table`{data-pkg="gtsummary"} ou en notes avec `add_glance_source_note`{data-pkg="gtsummary"}. Le paramètre `include` permets de choisir les éléments à afficher parmi les colonnes du tableau générés par `glance`{data-pkg="broom"}.

```{r}
mod %>%
  tbl_regression() %>%
  add_glance_table()

mod %>%
  tbl_regression() %>%
  add_glance_source_note(include = c("nobs", "AIC"))
```

## Combiner des tableaux

### tbl_stack() & tbl_merge()

La fonction `tbl_stack`{data-pkg="gtsummary"} permets de <q>coller</q> deux (ou plus) tableaux l'un au-dessus de l'autre tandis que `tbl_merge`{data-pkg="gtsummary"} les placera côte-à-côte, en s'assurant qu'une même variable sera bien affichée sur la même ligne. 


```{r}
t1 <-
  glm(response ~ trt, trial, family = binomial) %>%
  tbl_regression(exponentiate = TRUE)

t2 <-
  glm(response ~ grade + trt + stage + marker, trial, family = binomial) %>%
  tbl_regression(exponentiate = TRUE)

tbl_stack(
  list(t1, t2),
  group_header = c("Modèle bivarié", "Modèle multivarié")
)
tbl_merge(
  list(t1, t2),
  tab_spanner = c("Modèle bivarié", "Modèle multivarié")
)
```


### tbl_strata()

La fonction `tbl_strata`{data-pkg="gtsummary"} permet de calculer un tableau `gtsummary`{.pkg} pour chaque modalité d'une variable catégorielle définie via `strata`, puis de combiner les tableaux entre eux. Le paramètre `.tbl_fun` indique la fonction à utiliser pour le calcul du tableau. On peut utiliser la syntaxe rapide d'écritude de fonction propre au *tidyverse* en indiquant une formule (qui commence par `~`) et en utilisant `.x` pour indiquer où passer le sous-ensemble de données.

Par défaut les sous-tableaux produits sont combinés avec `tbl_merge`{data-pkg="gtsummary"}.


```{r}
trial %>%
  select(age, grade, stage, trt) %>%
  mutate(grade = paste("Grade", grade)) %>%
  tbl_strata(
    strata = grade,
    .tbl_fun =
      ~ .x %>%
        tbl_summary(by = trt, missing = "no") %>%
        add_n()
  )
```

Pour les combiner avec `tbl_stack`{data-pkg="gtsummary"}, on indiquera `.combine_with = "tbl_stack"`.

```{r}
trial %>%
  select(age, grade, stage, trt) %>%
  mutate(grade = paste("Grade", grade)) %>%
  tbl_strata(
    strata = grade,
    .tbl_fun =
      ~ .x %>%
        tbl_summary(by = trt, missing = "no") %>%
        add_n(),
    .combine_with = "tbl_stack"
  )
```

### tbl_split()

Lorsqu'un tableau est trop long et qu'on souhaite le couper en plusieurs tableaux, on pourra utiliser `tbl_spit`{data-pkg="gtsummary"} en indiquant le nom des variables après lesquelles le tableau doit être coupé.

```{r, eval=FALSE}
trial %>%
  tbl_summary() %>%
  tbl_split(variables = c(marker, grade))
```

## Régressions univariées multiples avec tbl_uvregression()

La fonction `tbl_uvregression`{data-pkg="gtsummary"} est utile pour réaliser plusieurs régressions univariées. Il faut lui passer un tableau ne contenant que la variable à expliquer et les variables explicatives. La variable à expliquer sera indiquée avec `y`. L'argument `method` indique la fonction à utiliser pour le calcul des modèles univariés, par exemple `glm`{data-pkg="stats"} pour une régression logistique ordinale. On pourra indiquer des paramètres à transmettre à cette fonction avec `method.args`, par exemple `list(family = binomial)` dans le cadre d'une régreession logistique binaire.


```{r}
tbl_uni <- tbl_uvregression(
    trial %>% select(response, age, grade, stage),
    method = glm,
    y = response,
    method.args = list(family = binomial),
    exponentiate = TRUE,
    hide_n = TRUE
  )
tbl_uni
```

On peut facilement présenter côte-à-côte l'analyse descriptive, l'analyse bivariée et l'analyse multivariée avec `tbl_merge`{data-pkg="gtsummary"}.

```{r}
tbl_desc <- trial %>%
  tbl_summary(
    by = response,
    include = c(age, grade, stage)
  )
tbl_multi <- trial %>%
  glm(
    response ~ age + grade + stage,
    data = .,
    family = binomial 
  ) %>%
  tbl_regression(exponentiate = TRUE)

tbl_merge(
  list(tbl_desc, tbl_uni, tbl_multi),
  tab_spanner = c("**Analyse descriptive**", "**Modèles bivariés**", "**Modèle multivarié**")
)
```

## Tables de survie avec tbl_survfit()

L'analyse de survie et les courbes de <dfn>Kaplan-Meier</dfn> sont abordées dans un [chapitre dédié](analyse-de-survie.html). La fonction `tbl_survfit`{data-pkg="gtsummary"} permets de représenter la probabilité encore en vie à différents points de temps définis avec `times`.

```{r}
library(survival)
km <- survfit(Surv(ttdeath, death) ~ trt, trial)
survminer::ggsurvplot(km)
km %>%
  tbl_survfit(
    times = c(0, 6, 12, 18, 24),
    label_header = "**Mois {time}**"
  )
```

On peut alternativement représenter la proportion ayant vécu l'évènement avec `reverse = TRUE`.

```{r}
km %>%
  tbl_survfit(
    times = c(6, 12),
    reverse = TRUE
  )
```

Au lieu d'indiquer des points de temps, on peut indiquer des quantiles avec `probs` et représenter le temps requis pour atteindre ces quantiles.

```{r}
km %>% 
  tbl_survfit(probs = c(.25, .5, .75))
```

Il est également possible de passer une liste d'objets `survfit`{data-pkg="survival"}.

```{r}
list(
  survfit(Surv(ttdeath, death) ~ 1, trial),
  survfit(Surv(ttdeath, death) ~ trt, trial),
  survfit(Surv(ttdeath, death) ~ grade, trial)
) %>%
  tbl_survfit(
    times = c(6, 12, 18),
    label_header = "**Mois {time}**"
  )
```

Dernière possibilité, il est possible de passer un tableau de données et d'indiquer les variables à analyser. Les tables de survie seront alors calculées à la volée.

```{r}
trial %>%
  tbl_survfit(
    y = Surv(ttdeath, death),
    include = c(trt, grade, stage),
    probs = 0.5,
    label_header = "**Survie médiane en mois** (IC 95%)",
    estimate_fun = scales::label_number(accuracy = .1)
  )
```


## Exporter un tableau

Les tableaux produits par `gtsummary`{.pkg} peuvent être rendus avec plusieurs moteurs de tableaux, grace aux fonctions `as_flex_table`{data-pkg="gtsummary"}, `as_hux_table`{data-pkg="gtsummary"}, `as_kable_extra`{data-pkg="gtsummary"}, et `as_kable`{data-pkg="gtsummary"}. Ils peuvent même être convertis en tableaux de données avec , `as_tibble`{data-pkg="gtsummary"}. 

Dans un [document R Markdown](rmarkdown-les-rapports-automatises.html), `gtsummary`{.pkg} utilisera le moteur de tableaux le plus adapté selon la sortie (HTML, PDF ou Word).

![Formats d'export d'un tableau gtsummary](images/gtsummary_output_formats.png)

```{r}
tbl <- trial %>%
  tbl_summary(
    include = c(age, grade),
    by = trt
  ) %>%
  add_p()

tbl %>% as_gt()
tbl %>% as_flex_table()
tbl %>% as_hux_table()
tbl %>% as_kable_extra()
tbl %>% as_tibble()
```

En dehors d'un fichier R markdown, pour exporter un tableau dans un fichier HTML, TeX ou RTF, on pourra utiliser `gtsave`{data-pkg="gt"} de `gt`{.pkg}.


```{r, eval=FALSE}
tbl %>%
  as_gt() %>%
  gt::gtsave(filename = ".") # use extensions .html .tex .ltx .rtf
```

Pour exporter un tableau dans un fichier Word, on pourra avoir recours à `save_as_docx`{data-pkg="flextable"} de `flextable`{.pkg}.

```{r, eval=FALSE}
tbl %>%
  as_flex_table() %>%
  flextable::save_as_docx()
```

## Plus d'options avec bstfun

L'extension `bstfun`{.pkg} est une petite sœur de `gtsummary`{.pkg}, développée par la même équipe. Cette extension n'est pas disponible sur CRAN mais seulement sur GitHub et elle permet, entre autres, de tester certaines fonctionnalités avant leur éventuelle intégration dans `gtsummary`{.pkg}.

Cette extension n'étant disponible que sur GitHub, elle s'installe avec la commande ci-après. ATTENTION : sous Windows, vous aurez besoin d'avoir installer en amont l'outil **R Tools** disponible sur <https://cran.r-project.org/bin/windows/Rtools/>.

```{r, eval=FALSE}
devtools::install_github("ddsjoberg/bstfun")
```

### tbl_likert()

En sciences sociales, il est fréquent de mesurer des connaissances ou des opinions selon une <dfn>échelle de Likert</dfn><dfn data-index="Likert, échelle"></dfn>. Dans cette situation, nous avons alors plusieurs variables catégorielles partageant les mêmes modalités.

Prenons les données utilisées dans le chapitre [Exemples de graphiques avancés](exemples-graphiques-avances.html#questions-de-connaissance).

```{r, eval=FALSE}
load(url("https://larmarange.github.io/analyse-R/data/connaissances.RData"))
```

```{r, echo=FALSE}
load("data/connaissances.RData")
```

```{r}
library(labelled)
quest %>% lookfor("conn")
```

Nous avons une série de 8 variables avec les mêmes modalités (Oui, Non et NSP). Un tri à plat peut-être un peu fastidieux à lire.

```{r}
quest %>%
  tbl_summary(include = starts_with("conn_"))
```

La fonction `tbl_likert`{data-pkg="bstfun"} de `bstfun`{.pkg} est plus adaptée pour présenter ce type de données.

```{r}
library(bstfun)
quest %>%
  tbl_likert(
    include = starts_with("conn_"),
    statistic = ~ "{p}%"
  ) %>%
  add_n()
```

### Ajouter un graphique de tendances (add_sparkline)

La fonction `add_sparkline`{data-pkg="bstfun"} ajoute une représentation graphique de la distribution d'une variable continue.

```{r eval=FALSE}
trial %>%
  tbl_summary(include = c(age, marker)) %>%
  add_sparkline(column_header = "**Distribution**")
```


### Représentation graphique des coefficients dans le tableau (add_inline_forest_plot)

La fonction `add_inline_forest_plot`{data-pkg="bstfun"} ajoute aux tableaux représentant les coefficients d'un modèle une représentation graphique de ces coefficients et de leur intervalle de confiance.

```{r, eval=FALSE}
mod %>%
  tbl_regression(exponentiate = TRUE) %>%
  add_inline_forest_plot()
```


### Forest plot (as_forest_plot)

La fonction `as_forest_plot`{data-pkg="bstfun"} permets d'afficher un graphique des coefficients utilisant la fonction `forestplot`{data-pkg="forestplot"} de l'extension homonyme `forestplot`{.pkg} à partir d'un tableau construit avec `tbl_regression`{data-pkg="gtsummary"}.

```{r fig.height=8, fig.width=12}
mod %>% 
  tbl_regression() %>%
  as_forest_plot()
```