5 Partage

Traduction de l’anglais Ch05-sharing

Dans ce chapitre, nous expliquons plusieurs méthodes pour partager vos visualisations de données interactives sur le web. Après avoir lu ce chapitre, vous serez en mesure de visualiser des animints :

à partir d’un dossier local sur votre ordinateur personnel;
dans des documents R Markdown;
en utilisant n’importe quel serveur web, y compris NetlifyDrop;
publiés en utilisant GitHub Pages et organisés dans une galerie.

5.1 Compiler un animint dans un dossier local

Lorsque vous testez différentes visualisations de données interactives, il est utile de les prévisualiser sur votre ordinateur avant de les publier sur le web. Cette section présente deux méthodes pour compiler les animints dans un répertoire local.

Dans les chapitres précédents, nous n’avons abordé qu’une seule méthode pour créer des visualisations interactives. Si vis est un animint (liste de ggplots et d’options de classe animint), alors print(vis)va compiler cet animint dans un dossier temporaire, en utilisant un code comme celui-ci :

set.seed(1)
dix.points <- data.frame(x=0:9, y=rnorm(10))
library(animint2)
animint(
  point=ggplot()+
    geom_point(aes(
      x, y), 
      data=dix.points))

Le code ci-dessus sauvegarde l’animint dans un nouveau dossier temporaire. Plutôt que de sauvegarder chaque animint dans un dossier séparé, vous pouvez définir un dossier de sortie en utilisant l’argument out.dir de la commande animint. Pour sauvegarder l’animint dans le fichier "Ch05-partager-dix-points" utilisez :

animint(
  point=ggplot()+
    geom_point(aes(
      x, y), 
      data=dix.points),
  out.dir="Ch05-partager-dix-points")

Si le dossier parent d’out.dir n’existe pas, vous générerez une erreur (vous pouvez utiliser dir.create pour créer le parent si nécessaire). Si out.dir n’existe pas, il sera créé. Si out.dir existe déjà (et contient un fichier nommé animint.js), tous les fichiers de ce répertoire seront écrasés. Pour afficher la visualisation, il suffit d’aller à Ch05-partager-dix-points/index.html dans un navigateur web (ce qui devrait être fait automatiquement/par défaut). Si la page web est vide, vous devrez peut-être configurer votre navigateur pour autoriser l’exécution du code JavaScript local, comme expliqué dans notre FAQ.

En interne, R appelle la méthode S3 print.animint, laquelle appelle à son tour animint2dir pour compiler la visualisation dans un nouveau dossier temporaire sur votre ordinateur. En général, nous déconseillons d’appeler animint2dir directement, mais cela peut être utile si vous voulez éviter d’ouvrir plusieurs fenêtres lorsque vous révisez un animint. Vous pouvez empêcher l’ouverture par défaut d’une fenêtre du navigateur avec :

vis <- animint(
  point=ggplot()+
    geom_point(aes(
      x, y), 
      data=dix.points))
animint2dir(
  vis,
  out.dir="Ch05-partager-dix-points",
  open.browser=FALSE)

5.2 Publier en R Markdown

Pour inclure un animint dans un document R Markdown, utilisez animint(...) à l’intérieur d’un bloc de code R, ce qui déclenchera l’exécution de la méthode S3 knit_print.animint, qui compile l’animint dans un dossier local dont le nom suit celui du bloc R . Par exemple, un bloc de code nommé vis-facettes sera sauvegardé dans le dossier visfacettes. Veillez à placer chaque animint dans son propre bloc de code (ne mettez pas deux animints dans le même bloc).

5.3 Publier sur un serveur web

Les animints sont des dossiers contenant des fichiers HTML, TSV et JavaScript, vous pouvez donc les publier sur n’importe quel serveur web en y copiant simplement le dossier.

Par exemple, j’ai exécuté le code présenté dans https://github.com/animint/animint2/blob/master/inst/examples/WorldBank-facets.R pour créer le dossier WorldBank-facets sur mon ordinateur. J’ai copié ce dossier sur le serveur web de mon laboratoire à l’aide de la commande rsync -r WorldBank-facets/ monsoon.hpc.nau.edu:genomic-ml/WorldBank-facets/, ce qui me permet de le visualiser sur https://rcdata.nau.edu/genomic-ml/WorldBank-facets/

Si vous n’avez pas accès à un serveur web personnel ou par le biais d’un laboratoire, vous pouvez utiliser l’une des méthodes décrites ci-dessous; elles sont gratuites et accessibles à tous.

5.4 Publier sur Netlify Drop

Netlify Drop est un service d’hébergement de sites web statiques. Pour y publier votre visualisation de données, il suffit de faire glisser un dossier sur cette page web (il peut s’agir d’un dossier issu de animint2dir ou de rmarkdown::render si votre animint est à l’intérieur de Rmd, comme décrit ci-dessus). Une fois le téléversement terminé, vous obtiendrez un lien qui vous permettra de visualiser les fichiers contenus dans ce dossier. Il n’est pas nécessaire de s’inscrire, mais sans connexion à un compte enregistré, vos données seront supprimées après une heure. Vous pouvez souscrire à un compte gratuit si vous souhaitez que vos visualisations de données soient disponibles pour une plus longue période.

5.5 Publier sur GitHub Pages

GitHub Pages est un service d’hébergement de sites web statiques sur lequel on peut publier des animints. Pour publier un animint sur GitHub Pages, vous avez besoin d’un compte GitHub ainsi que des packages gert (pour exécuter git à partir de R), gh (pour utiliser l’API GitHub à partir de R), et gitcreds (pour interagir avec le stockage des identifiants de git et faciliter l’authentification lors de l’envoi à GitHub). Tout d’abord, installez ces packages. Si vous n’avez pas de compte GitHub, vous pouvez vous inscrire gratuitement. Ensuite, assurez-vous d’indiquer à R le nom et le courriel à utiliser pour la publication des commits git :

gert::git_config_global_set("user.name", "<votre_identifiant>")
gert::git_config_global_set("user.email", "<votre_courriel>")

Vous pouvez ensuite utiliser animint2pages(vis, "nouveau_dépôt") pour publier votre visualisation dans la branche gh-pages de votre_identifiant_github/nouveau_dépôt (à noter que votre_identifiant_github n’est pas écrit dans le code, puisque gitcreds récupère cette information à partir du stockage des identifiants de git). Un message affichera l’URL ou le lien pour accéder à votre visualisation de données. Il faut compter quelques minutes (généralement pas plus de cinq) entre le moment où vous lancez animint2pages et celui où la visualisation est publiée sur GitHub Pages.

Pour mettre à jour un animint déjà publié sur GitHub Pages, lancez simplement animint2pages(nouvelle_version, "dépôt_existant") qui mettra à jour la branche gh-pages du dépôt spécifié.

Attention, GitHub Pages impose une limite de 100 Mo par fichier. Pour la plupart des visualisations, cette limite ne pose aucun problème. Si votre visualisation de données contient un fichier TSV de plus de 100 Mo, vous pouvez utiliser l’option chunk_vars pour convertir ce grand fichier en plusieurs plus petits.

5.6 Organiser des animints dans une galerie

Une galerie est une collection de métadonnées pour un ensemble de visualisations publiées sur GitHub Pages. Par exemple, la galerie principale des animints https://animint.github.io/gallery/ (en anglais) est une page web contenant des liens vers divers animints, organisés en tableau de contingence. Nous avons aussi une galerie en français.

Il y a une ligne pour chaque animint.
La première colonne viz.link présente une capture d’écran de l’animint, qui renvoie à la page web de l’animint.
La deuxième colonne title indique le nom de la visualisation (extrait de l’option title de chaque animint).
La troisième colonne links contient des liens vers son dépôt sur GitHub, ainsi que son code source et éventuellement une vidéo.

Une galerie est un dépôt sur GitHub qui doit avoir deux fichiers sources dans la branche gh-pages :

repos.txt (liste des dépôts sur GitHub qui contiennent des animints, un propriétaire/dépôt par ligne).
index.Rmd (source de la page web avec des liens vers animints).

Pour ajouter un nouvel animint à la galerie publiée sur la branche gh-pages de votre_identifiant_github/galerie vous pouvez utiliser la méthode suivante :

créez un nouveau animint dans le code R, et assurez-vous de définir les options source et title;
utilisez animint2pages(vis, "dépôt_de_vis") pour publier cet animint sur la branche gh-pages de votre_identifiant_github/dépôt_de_vis;
prenez une capture d’écran de cet animint2 qu’il vous faudra valider/pousser dans un fichier nommé Capture.PNG (sensible à la casse), dans la branchegh-pages de votre_identifiant_github/dépôt_de_vis;
ajoutez votre_identifiant_github/dépôt_de_vis au fichier repos.txt dans la branche gh-pages de votre_identifiant_github/galerie;
exécutez le code R animint2::update_gallery("path/to/galerie") (notez qu’un clone du dossier de la galerie doit être présent sur le système où vous exécutez cette fonction, et que le GitHub distant doit être nommé origin). Le code R lira galerie/repos.txt, puis les métadonnées (title, source, Capture.PNG) de chaque dossier qui n’est pas déjà présent dans galerie/meta.csv, il écrira ensuite les fichiers de métadonnées mis à jour dans la galerie, affichera les fichiers de galerieo/index.Rmd dans galerie/index.html, validera les fichiers et les poussera vers origin.
la galerie mise à jour sera consultable sur le web, à l’adresse https://votre_identifiant_github.github.io/galerie après quelques minutes (généralement pas plus de cinq).

5.7 Résumé du chapitre et exercices

Ce chapitre explique comment partager des animints sur le web.

Exercices :

Créez un animint en utilisant les options mentionnées dans ce chapitre : out.dir (nom du dossier où sauvegarder l’animint sur votre ordinateur), source (lien vers le code source R utilisé pour créer l’animint), title (description de l’animint).
Utilisez Netlify Drop pour publier cette animation sur le web.
Utilisez animint2pages pour publier cet animint dans un nouveau dépôt GitHub. Faites une capture d’écran et enregistrez-la en tant que Capture.PNG dans la branche gh-pages de ce dépôt. Ajoutez ce dépôt à la galerie principale de l’animint repos.txt en soumettant une Pull Request sur GitHub.
Créez votre propre galerie animint, et ajoutez y au moins deux de vos propres animints.

Dans le chapitre 6 nous vous expliquerons les différentes options qui peuvent être utilisées pour personnaliser un animint.

--- title: Partage layout: default output: bookdown::html_chapter --- Traduction de l'[anglais](https://github.com/tdhock/animint-book/) [Ch05-sharing](https://raw.githubusercontent.com/tdhock/animint-book/master/Ch05-sharing.Rmd)  ```{r} #| echo: FALSE knitr::opts_chunk$set(fig.path="Ch05-figures/") ```  Dans ce chapitre, nous expliquons plusieurs méthodes pour partager vos visualisations de données interactives sur le web.  Après avoir lu ce chapitre, vous serez en mesure de visualiser des animints :  - à partir d'un dossier local sur votre ordinateur personnel;  - dans des documents [R Markdown](http://rmarkdown.rstudio.com/);  - en utilisant n'importe quel serveur web, y compris [NetlifyDrop](https://app.netlify.com/drop);  - publiés en utilisant [GitHub Pages](https://pages.github.com/) et organisés dans une galerie.  ## Compiler un animint dans un dossier local {#animint2dir}  Lorsque vous testez différentes visualisations de données interactives, il est utile de les prévisualiser sur votre ordinateur avant de les publier sur le web.  Cette section présente deux méthodes pour compiler les animints dans un répertoire local.  Dans les chapitres précédents, nous n'avons abordé qu'une seule méthode pour créer des visualisations interactives.  Si `vis` est un animint (liste de ggplots et d'options de classe animint), alors `print(vis)`va compiler cet animint dans un dossier temporaire, en utilisant un code comme celui-ci :  ```{r Ch05-viz-dix-points} set.seed(1) dix.points <- data.frame(x=0:9, y=rnorm(10)) library(animint2) animint( point=ggplot()+ geom_point(aes( x, y), data=dix.points)) ```  Le code ci-dessus sauvegarde l'animint dans un nouveau dossier temporaire.  Plutôt que de sauvegarder chaque animint dans un dossier séparé, vous pouvez définir un dossier de sortie en utilisant l'argument `out.dir` de la commande `animint`.  Pour sauvegarder l'animint dans le fichier `"Ch05-partager-dix-points"` utilisez :  ```{r Ch05-viz-partager-dix-points} animint( point=ggplot()+ geom_point(aes( x, y), data=dix.points), out.dir="Ch05-partager-dix-points") ```  Si le dossier parent d'`out.dir` n'existe pas, vous générerez une erreur (vous pouvez utiliser `dir.create` pour créer le parent si nécessaire).  Si `out.dir` n'existe pas, il sera créé.  Si `out.dir` existe déjà (et contient un fichier nommé `animint.js`), tous les fichiers de ce répertoire seront écrasés.  Pour afficher la visualisation, il suffit d'aller à `Ch05-partager-dix-points/index.html` dans un navigateur web (ce qui devrait être fait automatiquement/par défaut).  Si la page web est vide, vous devrez peut-être configurer votre navigateur pour autoriser l'exécution du code JavaScript local, comme expliqué dans notre [ FAQ](https://github.com/tdhock/animint2/wiki/FAQ#web-browser-on-local-indexhtml-file-is-blank).  En interne, R appelle la méthode S3 `print.animint`, laquelle appelle à son tour `animint2dir` pour compiler la visualisation dans un nouveau dossier temporaire sur votre ordinateur.  En général, nous déconseillons d'appeler `animint2dir` directement, mais cela peut être utile si vous voulez éviter d'ouvrir plusieurs fenêtres lorsque vous révisez un animint. Vous pouvez empêcher l'ouverture par défaut d'une fenêtre du navigateur avec :  ```{r, eval=F} vis <- animint( point=ggplot()+ geom_point(aes( x, y), data=dix.points)) animint2dir( vis, out.dir="Ch05-partager-dix-points", open.browser=FALSE) ```  ## Publier en R Markdown {#Rmd}  Pour inclure un animint dans un document R Markdown, utilisez `animint(...)` à l'intérieur d'un bloc de code R, ce qui déclenchera l'exécution de la méthode S3 `knit_print.animint`, qui compile l'animint dans un dossier local dont le nom suit celui du bloc R .  Par exemple, un bloc de code nommé `vis-facettes` sera sauvegardé dans le dossier `visfacettes`.  Veillez à placer chaque animint dans son propre bloc de code (ne mettez pas deux animints dans le même bloc).  ## Publier sur un serveur web {#web-server}  Les animints sont des dossiers contenant des fichiers HTML, TSV et JavaScript, vous pouvez donc les publier sur n'importe quel serveur web en y copiant simplement le dossier.  Par exemple, j'ai exécuté le code présenté dans <https://github.com/animint/animint2/blob/master/inst/examples/WorldBank-facets.R> pour créer le dossier `WorldBank-facets` sur mon ordinateur.  J'ai copié ce dossier sur le serveur web de mon laboratoire à l'aide de la commande `rsync -r WorldBank-facets/ monsoon.hpc.nau.edu:genomic-ml/WorldBank-facets/`, ce qui me permet de le visualiser sur <https://rcdata.nau.edu/genomic-ml/WorldBank-facets/>  Si vous n'avez pas accès à un serveur web personnel ou par le biais d'un laboratoire, vous pouvez utiliser l'une des méthodes décrites ci-dessous; elles sont gratuites et accessibles à tous.  ## Publier sur Netlify Drop {#netlifydrop}  [Netlify Drop](https://app.netlify.com/drop) est un service d'hébergement de sites web statiques. Pour y publier votre visualisation de données, il suffit de faire glisser un dossier sur cette page web (il peut s'agir d'un dossier issu de `animint2dir` ou de `rmarkdown::render` si votre animint est à l'intérieur de Rmd, comme décrit ci-dessus).  Une fois le téléversement terminé, vous obtiendrez un lien qui vous permettra de visualiser les fichiers contenus dans ce dossier.  Il n'est pas nécessaire de s'inscrire, mais sans connexion à un compte enregistré, vos données seront supprimées après une heure.  Vous pouvez souscrire à un compte gratuit si vous souhaitez que vos visualisations de données soient disponibles pour une plus longue période.  ## Publier sur GitHub Pages {#pages}  [GitHub Pages](https://pages.github.com/) est un service d'hébergement de sites web statiques sur lequel on peut publier des animints.  Pour publier un animint sur GitHub Pages, vous avez besoin d'un compte GitHub ainsi que des packages `gert` (pour exécuter git à partir de R), `gh` (pour utiliser l'API GitHub à partir de R), et `gitcreds` (pour interagir avec le stockage des identifiants de git et faciliter l'authentification lors de l'envoi à GitHub).  Tout d'abord, installez ces packages. Si vous n'avez pas de compte GitHub, vous pouvez [vous inscrire gratuitement](https://github.com/join).  Ensuite, assurez-vous d'indiquer à R le nom et le courriel à utiliser pour la publication des commits git :  ```r gert::git_config_global_set("user.name", "<votre_identifiant>") gert::git_config_global_set("user.email", "<votre_courriel>") ```  Vous pouvez ensuite utiliser `animint2pages(vis, "nouveau_dépôt")` pour publier votre visualisation dans la branche `gh-pages` de `votre_identifiant_github/nouveau_dépôt` (à noter que `votre_identifiant_github` n'est pas écrit dans le code, puisque `gitcreds` récupère cette information à partir du stockage des identifiants de git).  Un message affichera l'URL ou le lien pour accéder à votre visualisation de données.  Il faut compter quelques minutes (généralement pas plus de cinq) entre le moment où vous lancez `animint2pages` et celui où la visualisation est publiée sur GitHub Pages.  Pour mettre à jour un animint déjà publié sur GitHub Pages, lancez simplement `animint2pages(nouvelle_version, "dépôt_existant")` qui mettra à jour la branche `gh-pages` du dépôt spécifié.  Attention, GitHub Pages impose une limite de 100 Mo par fichier.  Pour la plupart des visualisations, cette limite ne pose aucun problème.  Si votre visualisation de données contient un fichier TSV de plus de 100 Mo, vous pouvez utiliser l'option [chunk_vars](https://rcdata.nau.edu/genomic-ml/animint2-manual/Ch06-other.html#geom-options) pour convertir ce grand fichier en plusieurs plus petits.  ## Organiser des animints dans une galerie {#gallery}  Une galerie est une collection de métadonnées pour un ensemble de visualisations publiées sur GitHub Pages.  Par exemple, la galerie principale des animints [https://animint.github.io/gallery/](https://animint.github.io/gallery/) (en anglais) est une page web contenant des liens vers divers animints, organisés en tableau de contingence. Nous avons aussi [une galerie en français](https://animint.github.io/gallery-fr/).  - Il y a une ligne pour chaque animint.  - La première colonne `viz.link` présente une capture d'écran de l'animint, qui renvoie à la page web de l'animint.  - La deuxième colonne `title` indique le nom de la visualisation (extrait de l'option `title` de chaque animint).  - La troisième colonne `links` contient des liens vers son dépôt sur GitHub, ainsi que son code source et éventuellement une vidéo.  Une galerie est un dépôt sur GitHub qui doit avoir deux fichiers sources dans la branche `gh-pages` :  - `repos.txt` (liste des dépôts sur GitHub qui contiennent des animints, un propriétaire/dépôt par ligne). - `index.Rmd` (source de la page web avec des liens vers animints).  Pour ajouter un nouvel animint à la galerie publiée sur la branche `gh-pages` de `votre_identifiant_github/galerie` vous pouvez utiliser la méthode suivante :  - créez un nouveau animint dans le code R, et assurez-vous de définir les options `source` et `title`;  - utilisez `animint2pages(vis, "dépôt_de_vis")` pour publier cet animint sur la branche `gh-pages` de `votre_identifiant_github/dépôt_de_vis`;  - prenez une capture d'écran de cet `animint2` qu'il vous faudra valider/pousser dans un fichier nommé `Capture.PNG` (sensible à la casse), dans la branche`gh-pages` de `votre_identifiant_github/dépôt_de_vis`;  - ajoutez `votre_identifiant_github/dépôt_de_vis` au fichier `repos.txt` dans la branche `gh-pages` de `votre_identifiant_github/galerie`;  - exécutez le code R `animint2::update_gallery("path/to/galerie")` (notez qu'un clone du dossier de la galerie doit être présent sur le système où vous exécutez cette fonction, et que le GitHub distant doit être nommé `origin`). Le code R lira `galerie/repos.txt`, puis les métadonnées (`title`, `source`, `Capture.PNG`) de chaque dossier qui n'est pas déjà présent dans `galerie/meta.csv`, il écrira ensuite les fichiers de métadonnées mis à jour dans la galerie, affichera les fichiers de `galerieo/index.Rmd` dans `galerie/index.html`, validera les fichiers et les poussera vers `origin`.  - la galerie mise à jour sera consultable sur le web, à l'adresse `https://votre_identifiant_github.github.io/galerie` après quelques minutes (généralement pas plus de cinq).  ## Résumé du chapitre et exercices {#ch05-exercises}  Ce chapitre explique comment partager des animints sur le web.  Exercices :  - Créez un animint en utilisant les options mentionnées dans ce chapitre : `out.dir` (nom du dossier où sauvegarder l'animint sur votre ordinateur), `source` (lien vers le code source R utilisé pour créer l'animint), `title` (description de l'animint).  - Utilisez Netlify Drop pour publier cette animation sur le web.  - Utilisez `animint2pages` pour publier cet animint dans un nouveau dépôt GitHub. Faites une capture d'écran et enregistrez-la en tant que `Capture.PNG` dans la branche `gh-pages` de ce dépôt. Ajoutez ce dépôt à la galerie principale de l'animint [repos.txt](https://github.com/animint/gallery/blob/gh-pages/repos.txt) en soumettant une Pull Request sur GitHub.  - Créez votre propre galerie animint, et ajoutez y au moins deux de vos propres animints.  Dans le [chapitre 6](Ch06-other.html) nous vous expliquerons les différentes options qui peuvent être utilisées pour personnaliser un animint.