42  Tableaux de bord avec R Markdown

Cette page couvre l’utilisation base du paquet flexdashboard. Ce paquet vous permet de formater facilement la sortie R Markdown comme un tableau de bord avec des panneaux et des pages. Le contenu du tableau de bord peut être du texte, des figures/tableaux statiques ou des graphiques interactifs.

Avantages de flexdashboard :

Inconvénients de flexdashboard :

Des tutoriels assez complets sur l’utilisation de flexdashboard qui ont informé cette page se trouvent dans la section Ressources (fin de la page). Nous décrivons ci-dessous les fonctionnalités de base et donnons un exemple de construction d’un tableau de bord pour explorer une épidémie, en utilisant les données du cas linelist.

42.1 Préparation

Charger les paquets

Dans ce manuel, nous mettons l’accent sur p_load() de pacman, qui installe le paquet si nécessaire et le charge pour l’utiliser. Vous pouvez aussi charger les paquets installés avec library() de base R. Voir la page sur bases de R pour plus d’informations sur les paquets R.

pacman::p_load(
  rio, # import/export de données     
  here, # localisation des fichiers
  tidyverse, # gestion et visualisation des données
  flexdashboard, # versions tableaux de bord des rapports R Markdown
  shiny, # figures interactives
  plotly # figures interactives
)

Importer des données

Nous importons le jeu de données des cas d’une épidémie d’Ebola simulée. Si vous voulez suivre, cliquez pour télécharger la liste de lignes “propre” (en tant que fichier .rds). Importez des données avec la fonction import() du paquet rio (elle gère de nombreux types de fichiers comme .xlsx, .csv, .rds - voir la page Importation et exportation pour plus de détails).

# Importez la liste de cas
linelist <- import("linelist_cleaned.rds")

Les 50 premières lignes de la linelist sont affichées ci-dessous.

42.2 Créer un nouveau R Markdown

Après avoir installé le package, créez un nouveau fichier R Markdown en cliquant sur Fichier > Nouveau fichier > R Markdown.

Dans la fenêtre qui s’ouvre, sélectionnez “From Template” et choisissez le modèle “Flex Dashboard”. Vous serez ensuite invité à nommer le document. Dans l’exemple de cette page, nous allons nommer notre R Markdown “outbreak_dashboard.Rmd”.

42.3 Le script

Le script est un script R Markdown, et a donc les mêmes composants et la même organisation que les scripts décrits dans la page sur les Rapports avec R Markdown. Nous allons brièvement les revoir et souligner les différences avec les autres formats de sortie R Markdown.

YAML

En haut du script se trouve l’en-tête “YAML”. Il doit commencer par trois tirets --- et doit se terminer par trois tirets ---. Les paramètres YAML sont présentés par paires key: value. L’indentation et le placement des deux points dans YAML sont importants: les paires key: value sont séparées par des deux points (pas par des signes égaux !).

Le fichier YAML doit commencer par les métadonnées du document. L’ordre de ces paramètres YAML primaires (non indentés) n’a pas d’importance. Par exemple :

tite: "Mon document"
author: "Moi"
date: "`r Sys.Date()`"

Vous pouvez utiliser du code R dans des valeurs YAML en le mettant comme du code en ligne (précédé de r entre guillemets) mais aussi entre guillemets (voir ci-dessus pour Date).

Un paramètre YAML obligatoire est output:, qui spécifie le type de fichier à produire (par exemple, html_document, pdf_document, word_document, ou powerpoint_presentation). Pour flexdashboard, la valeur de ce paramètre est un peu confuse - elle doit être définie comme output:flexdashboard::flex_dashboard. Notez les deux-points simples et doubles, et le trait de soulignement. Ce paramètre de sortie YAML est souvent suivi par un deux-points supplémentaire et des sous-paramètres indentés (voir les paramètres orientation: et vertical_layout: ci-dessous).

title: "Mon tableau de bord"
author: "Moi"
date: "`r Sys.Date()`"
output:
  flexdashboard::flex_dashboard:
    orientation: rows
    vertical_layout: scroll

Comme indiqué ci-dessus, des indentations (2 espaces) sont utilisées pour les sous-paramètres. Dans ce cas, n’oubliez pas de mettre un deux-points supplémentaire après le primaire, comme key:value:.

Le cas échéant, les valeurs logiques doivent être données dans YAML en minuscules (true, false, null). Si un deux-points fait partie de votre valeur (par exemple, dans le titre), mettez la valeur entre guillemets. Voir les exemples dans les sections ci-dessous.

Morceaux de code

Un script R Markdown peut contenir plusieurs “chunks” de code - il s’agit de zones du script dans lesquelles vous pouvez écrire du code R sur plusieurs lignes et qui fonctionnent comme des mini-scripts R.

Les morceaux de code sont créés à l’aide de trois crochets arrière et de parenthèses avec un “r” minuscule à l’intérieur. Le chunk est fermé par trois crochets arrière. Vous pouvez créer un nouveau chunk en le tapant vous-même, en utilisant le raccourci clavier “Ctrl + Alt + i” (ou Cmd + Shift + r sur Mac), ou en cliquant sur l’icône verte “insérer un nouveau chunk de code” en haut de votre éditeur de script. De nombreux exemples sont donnés ci-dessous.

Texte narratif

En dehors d’un “chunk” de code R, vous pouvez écrire un texte narratif. Comme décrit dans la page Rapports avec R Markdown, vous pouvez mettre du texte en italique en l’entourant d’un astérisque (texte italique), ou en gras en l’entourant de deux astérisques (texte gras). Rappelez-vous que les puces et les schémas de numérotation sont sensibles aux nouvelles lignes, à l’indentation et au fait de terminer une ligne par deux espaces.

Vous pouvez également insérer du code R en ligne dans du texte, comme décrit à la page Rapports avec R Markdown, en entourant le code de barres obliques inversées et en commençant la commande par “r” : 2 (voir l’exemple avec la date ci-dessus).

Titres

Différents niveaux de titres sont établis avec différents nombres de symboles de hachage, comme décrit dans la page Rapports avec R Markdown.

Dans flexdashboard, un titre primaire (#) crée une “page” du tableau de bord. Les titres de deuxième niveau (##) créent une colonne ou une ligne en fonction de votre paramètre orientation: (voir les détails ci-dessous). Les titres de troisième niveau (###) créent des panneaux pour les graphiques, les tableaux, le texte, etc.

# Titre de premier niveau (page)

## En-tête de deuxième niveau (ligne ou colonne)  

### En-tête de troisième niveau (panneau pour le graphique, le tableau, etc.)

42.4 Attributs de section

Comme dans un markdown R normal, vous pouvez spécifier des attributs à appliquer aux parties de votre tableau de bord en incluant des options key=value après un titre, entre des accolades { }. Par exemple, dans un rapport HTML R Markdown typique, vous pouvez organiser les sous-titres en onglets avec ## Ma rubrique {.tabset}.

Notez que ces attributs sont écrits après un titre dans une partie texte du script. Ils sont différents des options knitr insérées en haut des morceaux de code R, telles que out.height =.

Les attributs de section spécifiques à flexdashboard comprennent :

  • {data-orientation=} Défini à rows ou columns. Si votre tableau de bord comporte plusieurs pages, ajoutez cet attribut à chaque page pour indiquer l’orientation (expliqué plus en détail dans la section de mise en page).
  • {data-width=} et {data-height=} définissent la taille relative des graphiques, colonnes, lignes disposés dans la même dimension (horizontale ou verticale). Les tailles absolues sont ajustées pour remplir au mieux l’espace sur n’importe quel dispositif d’affichage grâce au moteur flexbox.
    • La hauteur des graphiques dépend également de la définition du paramètre YAML vertical_layout: fill ou vertical_layout: scroll. S’il est défini sur scroll, la hauteur des figures reflétera l’option traditionnelle fig.height = dans le chunk de code R.
    • Voir la documentation complète sur la taille sur le flexdashboard website
  • {.hidden} Utilisez cette option pour exclure une page spécifique de la barre de navigation.
  • {data-navbar=} Utilisez ceci dans un titre de niveau page pour l’imbriquer dans un menu déroulant de la barre de navigation. Indiquez le nom (entre guillemets) du menu déroulant. Voir l’exemple ci-dessous.

42.5 Mise en page

Ajustez la mise en page de votre tableau de bord de la manière suivante :

  • Ajoutez des pages, des colonnes/lignes et des graphiques avec des titres R Markdown (par exemple, #, ## ou ###).
  • Ajustez l’orientation: de paramètre YAML à rangees ou colonnes.
  • Spécifiez si la mise en page remplit le navigateur ou permet le défilement.
  • Ajouter des onglets à un titre de section particulier

Pages

Les titres de premier niveau (#) dans le R Markdown représentent les “pages” du tableau de bord. Par défaut, les pages apparaissent dans une barre de navigation en haut du tableau de bord.

Vous pouvez regrouper des pages en un “menu” dans la barre de navigation supérieure en ajoutant l’attribut {data-navmenu=} au titre de la page. Attention, n’incluez pas d’espaces autour du signe égal, sinon cela ne fonctionnera pas !

Voici ce que produit le script :

Vous pouvez également convertir une page ou une colonne en une “barre latérale” sur le côté gauche du tableau de bord en ajoutant l’attribut {.sidebar}. Elle peut contenir du texte (visible de n’importe quelle page) ou, si vous avez intégré l’interactivité shiny, elle peut être utile pour contenir des commandes d’entrée utilisateur telles que des curseurs ou des menus déroulants.

Voici ce que produit le script :

Orientation

Définissez le paramètre YAML orientation: pour indiquer comment vos titres Markdown de second niveau (##) doivent être interprétés - comme orientation: colonnes ou orientation: lignes.

Les titres de second niveau (##) seront interprétés comme de nouvelles colonnes ou lignes en fonction de ce paramètre orientation.

Si vous définissez orientation: colonnes, les titres de second niveau créeront de nouvelles colonnes dans le tableau de bord. Le tableau de bord ci-dessous comporte une page, contenant deux colonnes, avec un total de trois panneaux. Vous pouvez ajuster la largeur relative des colonnes avec {data-width=} comme indiqué ci-dessous.

Voici ce que produit le script :

Si vous définissez orientation: lignes, les en-têtes de second niveau créeront de nouvelles lignes au lieu de colonnes. Voici le même script que ci-dessus, mais avec orientation: lignes pour que les en-têtes de second niveau produisent des lignes au lieu de colonnes. Vous pouvez ajuster la hauteur relative des lignes avec {data-height=} comme indiqué ci-dessous.

Voici ce que produit le script :

Si votre tableau de bord comporte plusieurs pages, vous pouvez désigner l’orientation pour chaque page spécifique en ajoutant l’attribut {data-orientation=} à l’en-tête de chaque page (spécifiez soit lignes soit colonnes sans les guillemets).

Onglets

Vous pouvez diviser le contenu en onglets avec l’attribut {.tabset}, comme dans les autres sorties HTML R Markdown.

Il suffit d’ajouter cet attribut après le titre souhaité. Les sous-titres sous ce titre seront affichés sous forme d’onglets. Par exemple, dans l’exemple de script ci-dessous, la colonne 2 à droite (##) est modifiée de manière à ce que les volets de la courbe épidémique et du tableau (###) soient affichés sous forme d’onglets.

Vous pouvez faire de même avec les lignes si votre orientation est celle des lignes.

Voici ce que produit le script :

42.6 Ajout de contenu

Commençons à construire un tableau de bord. Notre tableau de bord simple aura 1 page, 2 colonnes, et 4 panneaux. Nous allons construire les panneaux pièce par pièce pour la démonstration.

Vous pouvez facilement inclure des sorties R standard telles que du texte, des ggplots et des tableaux (voir la page Tableaux pour la présentation). Il suffit de les coder dans un chunk de code R comme vous le feriez pour tout autre script R Markdown.

Remarque : vous pouvez télécharger le script Rmd terminé et la sortie du tableau de bord HTML - voir la page Télécharger le manuel et les données.

Texte

Vous pouvez saisir du texte Markdown et inclure du code en ligne comme pour toute autre sortie R Markdown. Voir la page Rapports avec R Markdown pour plus de détails.

Dans ce tableau de bord, nous incluons un panneau de texte récapitulatif qui comprend un texte dynamique indiquant la dernière date d’hospitalisation et le nombre de cas signalés dans l’épidémie.

Tableaux

Vous pouvez inclure des morceaux de code R qui impriment des sorties telles que des tableaux. Mais la sortie sera plus belle et s’adaptera mieux à la taille de la fenêtre si vous utilisez la fonction kable() de knitr pour afficher vos tableaux. Les fonctions flextable peuvent produire des tableaux qui sont raccourcis / coupés.

Par exemple, ci-dessous, nous faisons passer la fonction linelist() par une commande count() pour produire un tableau récapitulatif des cas par hôpital. Finalement, le tableau est envoyé à knitr::kable() et le résultat a une barre de défilement sur la droite. Vous pouvez en savoir plus sur la personnalisation de votre tableau avec kable() et kableExtra ici.

Voici ce que produit le script :

Si vous voulez afficher un tableau dynamique qui permet à l’utilisateur de filtrer, trier et/ou cliquer sur les “pages” du cadre de données, utilisez le package DT et sa fonction datatable(), comme dans le code ci-dessous.

Dans l’exemple de code ci-dessous, le cadre de données linelist est imprimé. Vous pouvez définir rownames = FALSE pour conserver l’espace horizontal, et filter = "top" pour avoir les filtres en haut de chaque colonne. Une liste d’autres spécifications peut être fournie à options =. Ci-dessous, nous avons défini pageLength = pour que 5 lignes apparaissent et scrollX = pour que l’utilisateur puisse utiliser une barre de défilement en bas pour faire défiler horizontalement. L’argument class = 'white-space: nowrap' garantit que chaque ligne ne comporte qu’une seule ligne (et non plusieurs). Vous trouverez d’autres arguments et valeurs possibles ici ou en entrant ?datatable.

DT::datatable(linelist, 
              rownames = FALSE, 
              options = liste(pageLength = 5, scrollX = TRUE), 
              class = 'white-space: nowrap' )

Tracés

Vous pouvez imprimer les graphiques dans un tableau de bord comme vous le feriez dans un script R. Dans notre exemple, nous utilisons le paquet incidence2 pour créer une “courbe épidémique” par groupe d’âge avec deux commandes simples (voir la page Courbes épidémiques). Cependant, vous pourriez utiliser ggplot() et imprimer un graphique de la même manière.

Voici ce que produit le script :

Graphiques interactifs

Vous pouvez également passer un ggplot standard ou un autre objet de tracé à ggplotly() du paquet plotly (voir la page Graphiques interactifs). Cela rendra votre graphique interactif, permettra au lecteur de “zoomer” et affichera en surimpression la valeur de chaque point de données (dans ce scénario, le nombre de cas par semaine et le groupe d’âge dans la courbe).

age_outbreak <- incidence(linelist, date_onset, "week", groups = age_cat)
plot(age_outbreak, fill = age_cat, col_pal = muted, title = "") %>% 
  plotly::ggplotly()

Voici à quoi cela ressemble dans le tableau de bord (gif). Cette fonctionnalité interactive fonctionnera même si vous envoyez le tableau de bord par courriel sous forme de fichier statique (pas en ligne sur un serveur).

Widgets HTML

Les widgets HTML pour R sont une classe spéciale de paquets R qui augmentent l’interactivité en utilisant des bibliothèques JavaScript. Vous pouvez les intégrer dans les sorties Markdown de R (comme un flexdashboard) et dans les tableaux de bord Shiny.

Voici quelques exemples courants de ces widgets :

  • Plotly (utilisé dans cette page du manuel et dans la page Graphiques interactifs).
  • visNetwork (utilisé dans la page Chaînes de transmission de ce manuel)
  • Leaflet (utilisé dans la page bases de GIS de ce manuel)
  • digraphs (utile pour montrer de manière interactive des séries de données temporelles)
  • DT (datatable()) (utilisé pour afficher des tableaux dynamiques avec des filtres, des tris, etc.)

Ci-dessous, nous démontrons l’ajout d’une chaîne de transmission d’épidémie qui utilise visNetwork au tableau de bord. Le script ne montre que le nouveau code ajouté à la section “Column 2” du script R Markdown. Vous pouvez trouver le code dans la page Chaînes de transmission de ce manuel.

Voici ce que produit le script :

42.7 Organisation du code

Vous pouvez choisir d’avoir tout le code dans le script R Markdown flexdashboard. Alternativement, pour avoir un script de tableau de bord plus propre et concis, vous pouvez choisir de faire appel à du code/figures qui sont hébergés ou créés dans des scripts R externes. Ceci est décrit plus en détail dans la page Rapports avec R Markdown.

42.8 Shiny

L’intégration du paquet R shiny peut rendre vos tableaux de bord encore plus réactifs aux entrées de l’utilisateur. Par exemple, vous pouvez demander à l’utilisateur de sélectionner une juridiction ou une plage de dates, et faire réagir les panneaux à son choix (par exemple, filtrer les données affichées). Pour intégrer la réactivité shiny dans flexdashboard, il vous suffit d’apporter quelques modifications à votre script Markdown R flexdashboard.

Vous pouvez également utiliser shiny pour produire des applications ou des tableaux de bord sans flexdashboard. La page du manuel sur les tableaux de bord avec Shiny donne un aperçu de cette approche, y compris des conseils sur la syntaxe shiny, la structure des fichiers d’application et les options de partage et de publication (y compris les options de serveur libre). Ces conseils syntaxiques et généraux s’appliquent également au contexte flexdashboard.

L’intégration de shiny dans flexdashboard constitue cependant un changement fondamental pour votre flexdashboard. Il ne produira plus une sortie HTML que vous pouvez envoyer par courriel et que tout le monde peut ouvrir et visualiser. Il s’agira plutôt d’une “application”. Le bouton “Knit” en haut du script sera remplacé par une icône “Run document”, qui ouvrira une instance du tableau de bord interactif localement sur votre ordinateur.

Le partage de votre tableau de bord nécessitera maintenant que vous.. :

  • Envoyer le script Rmd au spectateur, qu’il l’ouvre dans R sur son ordinateur et qu’il exécute l’application, ou bien…
  • L’application/le tableau de bord est hébergé sur un serveur accessible à l’observateur.

L’intégration de shiny présente donc des avantages, mais aussi des complications. Si le partage facile par email est une priorité et que vous n’avez pas besoin des capacités réactives de shiny, considérez l’interactivité réduite offerte par ggplotly() comme démontré ci-dessus.

Nous donnons ci-dessous un exemple très simple utilisant le même “outbreak_dashboard.Rmd” que ci-dessus. Une documentation complète sur l’intégration de Shiny dans flexdashboard est disponible en ligne ici.

Paramètres

Activez shiny dans un flexdashboard en ajoutant le paramètre YAML runtime: shiny au même niveau d’indentation que output:, comme ci-dessous :

---
title: "Tableau de bord d'épidémie (Démo Shiny)".
output: 
  flexdashboard::flex_dashboard :
    orientation: columns
    vertical_layout : fill
runtime: shiny
---

Il est également pratique d’activer une “barre latérale” pour contenir les widgets de saisie shiny qui collecteront les informations de l’utilisateur. Comme expliqué ci-dessus, créez une colonne et indiquez l’option {.sidebar} pour créer une barre latérale sur le côté gauche. Vous pouvez ajouter du texte et des morceaux de R contenant les commandes input shiny dans cette colonne.

Si votre application/ tableau de bord est hébergé sur un serveur et peut avoir plusieurs utilisateurs simultanés, nommez le premier morceau de code R comme global. Incluez les commandes pour importer/charger vos données dans ce chunk. Ce chunk au nom spécial est traité différemment, et les données qui y sont importées ne le sont qu’une fois (et non en continu) et sont disponibles pour tous les utilisateurs. Cela améliore la vitesse de démarrage de l’application.

Exemple travaillé

Ici, nous adaptons le script flexdashboard “outbreak_dashboard.Rmd” pour inclure shiny. Nous allons ajouter la possibilité pour l’utilisateur de sélectionner un hôpital dans un menu déroulant, et de faire en sorte que la courbe épidémique ne reflète que les cas de cet hôpital, avec un titre de graphique dynamique. Nous faisons ce qui suit :

  • Ajouter runtime: shiny à la YAML.
  • Re-nommer le chunk de configuration comme global.
  • Créer une barre latérale contenant :
    • Du code pour créer un vecteur de noms d’hôpitaux uniques
    • Une commande selectInput() (menu déroulant shiny) avec le choix des noms d’hôpitaux. La sélection est sauvegardée sous le nom de hospital_choice, qui peut être référencé dans le code suivant comme input$hospital_choice.
  • Le code de la courbe d’épidémie (colonne 2) est enveloppé dans renderPlot({ }), incluant :
    • Un filtre sur l’ensemble de données qui restreint la colonne hospital à la valeur actuelle de input$hospital_choice.
    • Un titre dynamique du tracé qui incorpore input$hospital_choice.

Notez que tout code faisant référence à une valeur input$ doit se trouver dans une fonction render({}) (pour être réactif).

Voici le haut du script, incluant YAML, le chunk global, et la barre latérale :

Voici la colonne 2, avec le tracé de l’épicurve réactive :

Et voici le tableau de bord :

Autres exemples

Pour lire un exemple de tableau de bord Shiny-flexdashboard lié à la santé et utilisant l’interactivité shiny et le widget de cartographie leaflet, consultez ce chapitre du livre en ligne Geospatial Health Data : Modeling and Visualization with R-INLA and Shiny.

42.9 Partage

Les tableaux de bord qui ne contiennent pas d’éléments Shiny produisent un fichier HTML (.html), qui peut être envoyé par courriel (si la taille le permet). Ceci est utile, car vous pouvez envoyer le rapport du “tableau de bord” sans avoir à configurer un serveur pour l’héberger en tant que site web.

Si vous avez intégré shiny, vous ne pourrez pas envoyer une sortie par e-mail, mais vous pouvez envoyer le script lui-même à un utilisateur R, ou héberger le tableau de bord sur un serveur comme expliqué ci-dessus.

42.10 Ressources

Les excellents tutoriels qui ont informé cette page se trouvent ci-dessous. Si vous les consultez, vous pourrez probablement créer votre propre tableau de bord en moins d’une heure.

https://bookdown.org/yihui/rmarkdown/dashboards.html

https://rmarkdown.rstudio.com/flexdashboard/

https://rmarkdown.rstudio.com/flexdashboard/using.html

https://rmarkdown.rstudio.com/flexdashboard/examples.html