Personnalisez vos rapports en pdf avec pagedreport
Cette semaine, j’ai testé le package pagedreport, développé par Thomas Vroylandt et David Keyes.
La promesse de ce package, c’est de nous permettre (nous qui ne maîtrisons ni le CSS ni LaTeX) de générer un rapport au format pdf, élégant et personnalisable, à partir d’un simple document Rmarkdown !
Si vous ne connaissez pas Rmarkdown, il s’agit simplement d’un format de script R dans lequel vous pouvez inclure du texte, des titres, des images, du code R, des tables de données, etc… et qui vous permet ensuite de générer automatiquement un document rendu (un rapport) en format word, html ou pdf, avec une table des matières, les titres, le texte, les images, le code R, les sorties du code R (un graph par exemple, ou un modèle de régression), etc….
Pour plus d’informations vous pouvez consulter mon guide de démarrage en Rmarkdown .
La promesse de ce nouveau package pagedreport est vraiment intéressante, parce qu’il existe des solutions pour personnaliser le rendu word , et le rendu html (notamment avec le package rmdformat) : mais peu, ou du moins de façon moins abordable, pour le rendu pdf.
Pour mes clients, je génère généralement un premier compte rendu en format word, car cela leur permet de l’annoter facilement. Et parfois, dans un second temps, je leur transmets une version définitive en pdf.
Ce document final au format pdf a plutôt un bel aspect, mais il n’est pas du tout personnalisé. Alors l’idée de pouvoir ajouter un logo, une image de couverture, de pouvoir facilement modifier les polices et les couleurs employées, est assez séduisante !
Je vous montre en pas à pas comment cela fonctionne.
Remarque : Pour tester ce package, j’ai utilisé le contenu d’un fichier Rmarkdown d’un de mes articles (celui sur les séries temporelles)
Table des matières
Installation de pagedreport pour vos rapports en pdf
Ce package n’est pas sur CRAN, pour l’installer, il est nécessaire d’aller le télécharger à partir d’un repo GitHub :
install.packages("remotes")
remotes::install_github("rfortherestofus/pagedreport", ref = "main")
library(pagedreport) Après avoir employé cette commande, R m’a proposé la mise à jour de nombreux packages. J’ai accepté de tous les mettre à jour. La première installation n’a pas fonctionné, car j’avais un problème avec la mise à jour du package xfun qui ne parvenait pas à se faire. Idem lors de la deuxième tentative. Je suis alors allée dans le dossier de mon ordinateur dans lequel sont stockés les packages. Pour moi, le chemin d’accès est : C:\Users\clair\Documents\R\win-library\4.0
Et j’ai supprimé le dossier xfun, puis j’ai relancé l’installation de pagedreport, et cette fois tout a bien fonctionné.
Fonctionnement de pagedreport
Les modèles de base
Le package pagedreport propose trois modèles de base, qui sont personnalisables (en termes de police, de couleurs, de logo, d’images de couverture, de traitements des images et logo (pour les assombrir afin que le texte soit plus lisible) :
paged_grid()paged_hazelnuts()paged_windmill()
Remarque : A priori, les trois modèles ne disposent pas de toutes les options de personnalisation possibles. Par exemple certains modèles n’utilisent pas d’images de couverture de fin de rapport, d’autres, pas de sommaire, etc… En tout cas je n’y suis pas parvenue !
Accéder à ces modèles
Une fois le package installé, le principe est d’aller ouvrir un fichier Rmarkdown spécifique à l’un de ces 3 modèles de base.
Pour cela : File –> Rmarkdown –> From Template –> windmill (par exemple).
Ce qui permet d’obtenir le template suivant :
Il faut ensuite l’enregistrer, à la racine de votre projet R, ou dans le dossier script de votre projet R par exemple.
Personnaliser les rendus pdf
Généralités
La personnalisation se déroule dans l’en-tête du template Rmd qui a été généré.
La première partie est identique à tous les fichiers Rmarkdown, avec le titre et sous-titre du document, l’auteur et la date (je l’ai amélioré pour qu’elle soit générée automatiquement).
Logo et images de couvertures
Dans la seconde partie de l’en-tête, se trouvent :
- le modèle utilisé : ici paged_windmill
- les options pour insérer des images de couverture (front_img pour la couverture avant et back_img pour la couverture arrière)
- l’option pour insérer un logo : logo
- les options pour modifier la couleur des images (img_to_dark : permet de les assombrir pour rendre le texte des couvertures plus lisibles) et du logo (logo_to_white : permet de rendre le logo blanc pour là encore le rendre plus visible).
Le modèle paged_hazelnuts emploie une image sur les couvertures de début et de fin de rapport, le modèle paged_windmill uniquement sur la couverture de début, et le modèle paged_grid n’emploie pas du tout d’image. Les images peuvent être stockées en format .jpg (ou .png sans doute) en local ou sur un serveur, idem pour le logo, mais il doit être au format.svg(vectoriel).
Voici les couvertures du modèle paged_windmill:
Celles du modèle paged_grid:
Et celles du modèle paged_hazelnuts:
Je n’ai pas compris comment modifier la taille du logo (la silhouette blanche avec la loupe), je pense qu’elle est liée à la taille du fichier svg.
Remarque : vous pouvez trouver des images sympa et libre de droit sur Flickr : Recherche–> Avancé –>Licence
Table des matières
La table des matières est gérée dans la troisième partie de l’entête, avec l’option toc_title. Ce qui se trouve dans les guillemets est le nom qui sera donné, dans le document généré, à la table des matières : ici “Sommaire”.
A priori, la génération d’une table des matières n’est possible qu’avec le modèle paged_hazelnuts. Je n’ai pas réussi à modifier la profondeur de la table (uniquement les titres de niveau 1 et 2).
Voici le rendu du modèle paged_hazelnuts:
Couleurs
En plus de la couleur noire utilisée pour le corps du texte (les paragraphes), les modèles emploient une ou deux autres couleurs. Elles peuvent être spécifiées avec les options :
main-color :secondary-color :
Le modèle paged_grid emploie une couleur principale qui est utilisée sur :
- la couverture de début (bandeau à gauche et motif de points en haut à droite),
- les pages de texte (motifs de points et grille de fin de page),
- la couverture de fin
Le modèle paged_windmill emploie également une seule couleur principale, au niveau de la mise en page (haut des pages et numéro des pages), ainsi que pour les titres, et la couverture de fin.
Le modèle paged_hazelnuts emploie, quant à lui, deux couleurs :
- une principale, employée au niveau des haut de page, numérotation, et table des matières
- une secondaire, employée, au niveau des titres.
Voici le rendu du modèle paged_hazelnuts:
Polices
Il est possible d’utiliser les polices de google en employant, dans l’en-tête, l’option google-font: true, puis en les spécifiant dans les options main-font ( pour les paragraphes), et header-font (pour les titres).
Les polices de google sont disponibles ici.
Remarques
Pour que les titres soient numérotés, il est nécessaire de supprimer les {-} derrière les titres.
Avec le modèle paged_hazelnuts, il faut faire attention à ne pas avoir des titres trop longs, car si c’est le cas, le début et la fin sont masqué par les barres horizontales.
Si ce sujet de la personnalisation des rendus pdf vous intéresse particulièrement, vous pouvez aussi consulter le package `pdfreport` de Sébastien Rochette. Je ne l’ai jamais essayé.
Conclusion
Après ce test, je trouve que les rendus pdf générés avec ce package sont plutôt satisfaisants !
Vous trouverez des exemples supplémentaires ici
Personnellement, j’aimerais qu’une table des matières soit insérable dans tous les modèles, et que les parties code et sorties de code ressortent plus, par exemple avec une option highlight comme dans les rmarkdown de base.
Et vous, qu’en pensez-vous ? Allez-vous, vous en servir ? Qu’est-ce que vous souhaiteriez comme amélioration? N’hésitez pas à me le dire en commentaire !
Suite à la publication de cet article Thomas Vroyland, le développeur du package, m’a fait parvenir ces précisions :
- “la taille du logo n’est pas personnalisable pour le moment, mais ça devrait venir, une issue a été ouverte sur le sujet github.com/rfortherestofu – tout n’est effectivement pas personnalisable partout. L’idée est que ces templates servent plutôt de première approche pour que les gens se mettent à pagedown ensuite si le besoin se fait sentir ou en reste là si ça leur suffit
- on peut mettre du .png pour les images
- les titres dépassent effectivement un peu, j’ai eu du mal à les régler =)
- pour l’instant la table des matières est bloquée car plus on rajoute d’options plus c’est difficile de garder la cohérence d’ensemble
- par rapport à {pdfreport} de Sebastien, l’approche est différente puisqu’ici on se passe de LaTeX et qu’on se repose sur {pagedown}, pagedjs et toutes les technos Web comme HTML et CSS. C’est un peu le point fort.
Si article vous a plu, ou vous a été utile, et si vous le souhaitez, vous pouvez soutenir ce blog en faisant un don libre sur sa page Tipeee.
2 réponses
Bonjour Claire!
j’ai installé ce package et comme bien détaillé dans votre article,le rendu est très joli en si peu de temps!🙉
Seulement ,je n’ai pas su affiché la liste des tableaux ,la liste des figures !
Bonjour,
Il me semble que la table des matières n’est possible que pour le modèle paged_hazelnuts.
Bonne continuation