Améliorons les tables en Rmarkdown

Dans l’article précédent, nous avons vu kable(), la fonction de knitr qui permet de générer des représentations de tables homogènes selon le mode de sortie PDF, HTML ou autre.

Cela nous donnait un seul modèle de table qui possiblement n’a pas votre préférence. Attention, kableExtra va faire son entrée pour améliorer tout ça.

Qu’est-ce que c’est ?

kableExtra est une librairie qui rajoute des fonctions permettant de personnaliser l’aspect final des kables destinés à HTML ou (PDF via) LaTeX. Il permet de très facilement rendre plus professionnel une sortie tout en laissant libre l’utilisateur pour ensuite personnaliser. Nous partirons du code .rmd de l’article précédent, en rajoutant le chargement de kableExtra en début de code (idéalement il faut charger knitr avant kableExtra et kableExtra avant dplyr pour éviter des conflits de noms de fonctions possibles) :

library(knitr)
library(kableExtra)
library(dplyr)

<...>

k <- GHS_N %>% inner_join(GHS_R,by="GHS", suffix=c(".N", ".R")) %>%
    mutate(CMD = substr(GHM.N, 1,2),
           CATGHM = substr(GHM.N,3,3),
           `variation%` = 100 * ((GHSPRIX.N / GHSPRIX.R)-1)) %>%
    select(GHS, CMD, CATGHM, `variation%`)%>% head(10) %>%
    kable

k

Ce qui nous donne sans personnalisation :

Fonctionnel mais pas super joli… Là arrive le pouvoir de base de kableExtra avec ses styles déjà tout prêt : kable_classic(), kable_classic_2(), kable_minimal(), kable_paper(), kable_material() et kable_material_dark(). Pour les appliquer, il suffit de les “piper” (%>%) depuis/après kable() ou comme dans le cas du code ci-dessus, appliquer les fonctions à l’objet knitr_kable que nous avons sauvegardé dans la variable k. Cela donne respectivement :

Tous ces styles sont compatibles HTML mais sortiront tous globalement comme kable_classic() en LaTeX/PDF. Il est possible de passer 2 paramètres : lightable= et html_font= pour personnaliser les fonctionnalités et l’aspect en HTML.

Comme vous pouvez le voir, le tableau est désormais ligné (“striped”) et la ligne survolée (“hover”) est mise en surbrillance. Par ailleurs, la police sans sérif par défaut est remplacée par du Times New Roman.

Le faire à la main

Outre ces styles préréglés, il existe la fonction kable_styling() permettant de paramétrer de nombreuses options.

kable_styling(
  kable_input,
  bootstrap_options = "basic",
  latex_options = "basic",
  full_width = NULL,
  position = "center",
  font_size = NULL,
  row_label_position = "l",
  repeat_header_text = "\\textit{(continued)}",
  repeat_header_method = c("append", "replace"),
  repeat_header_continued = FALSE,
  stripe_color = "gray!10",
  stripe_index = NULL,
  latex_table_env = NULL,
  protect_latex = TRUE,
  table.envir = "table",
  fixed_thead = FALSE,
  htmltable_class = NULL,
  html_font = NULL,
  wraptable_width = "0pt"
)

Notez, pour les techniciens du HTML et du CSS, que kable_styling() utilise la feuille de style “bootstrap” alors que ci-dessus, il s’agissait de “lightable”.

Les paramètres

Nous allons les prendre dans l’ordre :

kable_input= : dans la pure tradition du pipe (%>%), il s’agit de l’objet sur lequel nous allons travailler, il est obligatoire et obligatoirement de classe knitr_kable ou kableExtra soit un résultat de kable() ou kbl() (cf plus loin).

bootstrap_options= : il s’agit d’un vecteur d’options qui seront utilisées pour personnaliser l’aspect du style CSS hérité de bootstrap. Je ne vous en veux pas si vous ne comprenez pas ce que veut dire la phrase précédente. Sachez juste que les options sont nombreuses :

• "basic" : activant le fonctionnement par défaut
• "striped" : ajoutant une légère coloration alternative des lignes, pas trop visible, pour améliorer la lisibilité
• "bordered" : pour que le tableau, qui de base n’est pas fermé sur les côtés, le soit
• "hover" : ajoute la fonction de coloration au survol qui permet de repérer d’un seul coup d’oeil la
• "condensed" : change la police d’affichage pour condenser verticalement
• "responsive" : affiche un “ascenceur” horizontal si l’affichage le nécessite, permettant de naviguer en cas de nombre important de colonnes (franchement, évitez. C’est souvent que vous ne sélectionnez pas assez vos colonnes de données à afficher et risquez de noyer vos lecteurs).
• "none" : tout désactiver

latex_options= : c’est l’équivalent en cas de production de code LaTeX en vue, par exemple, d’une sortie PDF. Les valeurs possibles sont “basic”, “striped”, “hold_position”, “HOLD_position”, “scale_down”, “scale_up” et “repeat_header”. "basic" et "striped" font la même chose que ci-dessus, les autres valeurs sont liées à toute la particularité (et la puissance) de LaTeX :

• "HOLD/hold_position" force (fortement ou pas) la position de la table dans la page (LaTeX a un fonctionnement de base qui place les tables et autres figures en fonctions de règles de composition de document, celles-ci impliquent qu’une table peut parfois ne pas être placée là où elle est incluse dans le code source mais à un endroit plus adapté une page avant ou après).
• "scale_up/down" : adapte le contenu à la largeur de page
• "repeat_header" : sert à répéter les entêtes de la table en haut de page en cas de table trop longue et nécessitant une rupture.

full_width= : comme son nom l’indique précise si la table doit être étendue en largeur sur tout son contenant. La valeur par défaut (NULL) varie selon si on produit du HTML (valeur assumée = TRUE) ou du LaTeX (FALSE). Franchement, ces valeurs par défaut sont plutôt bien adaptées. Vous pourriez vouloir mettre FALSE en HTML si vous avez une table vraiment peu large.
position= : par défaut "center", qui fait ce que son nom indique en spécifiant le placement horizontal de la table. A noter qu’il est possible d’utiliser "float_left" et "float_right" pour que la table soit “habillée” par le texte
font_size= et html_font= : règlent la taille et la variété de police (la valeur par défaut NULL laisse le reste de la feuille de style décider).
row_label_position= : l’alignement par défaut de la colonne d’étiquettes si elle existe et est utilisée (par défaut, alignement à gauche via la valeur "l" (un L minuscule)). Les valeurs possibles sont “l”, “c”, “r”.
repeat_header_text= : (LaTeX uniquement) le code qui sera mis dans la légende en entête en cas de saut(s) de page (valeur par défaut : "\textit{(continued)}"). C’est du code LaTeX qui est attendu.
repeat_header_method= : spécifie ce qu’on doit fairre du contenu de l’option ci-dessus : "append" (par défaut) ajoute le texte au bout de la légende initiale, tandis que "replace" la remplace totalement.
repeat_header_continued= : (FALSE, par défaut) spécifie le texte à insérer, cette fois-ci en bas de table, si elle passe un saut de page.

stripe_color= : la couleur (en termes LaTeX) de la mise en alternance des lignes (par défaut "gray!10", ce qui signifie 10% de gris)
stripe_index= : (NULL par défaut) permet de définir “manuellement” quelles lignes du tableau mettre en couleur. Il s’agira alors d’un vecteur de nombre entiers

A partir d’ici, il s’agit VRAIMENT d’options dont le changement est rarissime et qui nécessite de maitriser la chaine de production en aval. On ne les modifiera que si l’aspect final est à modifier finement. Je ne ferai que les citer :
table.envir= (par défaut "table") et latex_table_env= (défaut : NULL qui correspond à \table{}) : permettent respectivement de forcer le type d’environnement HTML ou LaTeX qui va former la table (si vous ne comprenez pas, dites vous que ça n’a généralement pas d’intérêt de le modifier)
protect_latex= : par défaut TRUE
fixed_thead= : par défaut FALSE
htmltable_class= : par défaut NULL
wraptable_width= : par défaut "0pt"

La fonction kbl()

kableExtra amène aussi une fonction kbl() qui est un remplacement de la fonction kable(). Celle-ci permet de configurer de nombreux paramètres spécifiques permettant de reproduire ou s’inspirer des styles vus ci-dessus.

kbl(
  x,
  format,
  digits = getOption("digits"),
  row.names = NA,
  col.names = NA,
  align,
  caption = NULL,
  label = NULL,
  format.args = list(),
  escape = TRUE,
  table.attr = getOption("knitr.table.html.attr", ""),
  booktabs = FALSE,
  longtable = FALSE,
  tabular = if (longtable) "longtable" else "tabular",
  valign = if (tabular %in% c("tabularx", "xltabular")) "{\\linewidth}" else "[t]",
  position = "",
  centering = TRUE,
  vline = getOption("knitr.table.vline", if (booktabs) "" else "|"),
  toprule = getOption("knitr.table.toprule", if (booktabs) "\\toprule" else
    "\\hline"),
  bottomrule = getOption("knitr.table.bottomrule", if (booktabs) "\\bottomrule" else
    "\\hline"),
  midrule = getOption("knitr.table.midrule", if (booktabs) "\\midrule" else
    "\\hline"),
  linesep = if (booktabs) c("", "", "", "", "\\addlinespace") else "\\hline",
  caption.short = "",
  table.envir = if (!is.null(caption)) "table",
  ...
)

L’une de ses particularités est de produire directement le HTML ou LaTeX sans passer par l’interprétation par pandoc. Cela, assez logiquement permet ce surcroit de contrôle sur le résultat final (au prix bien sûr d’une limitation des formats de sortie supportés).

Par ailleurs, pour accéder à kable() et l’agrémenter de mise en forme, il faut charger explicitement la librairie knitr ET la librairie kableExtra. Tandis que passer par kbl() ne nécessite que de charger kableExtra.

Conclusion

Cet article est, je dois le reconnaitre, assez compact mais malheureusement (ou pas) kableExtra étant très puissant, il y a beaucoup de paramètres à lister et à comprendre.

Une prochaine fois nous continuerons d’explorer cette librairie en voyant comment personnaliser des colonnes ou des cases des tableaux.