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 personnel avant de les publier sur le web. Cette section traite de 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 de données interactives. Si vis est un animint (liste de ggplots et d’options avec la 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 temporaire séparé, vous pouvez définir un dossier de sortie via l’argument out.dir de la commande animint. Si vous voulez 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 (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, il se peut que vous deviez 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 animint2dir afin de compiler la visualisation dans un nouveau dossier temporaire sur votre ordinateur personnel. 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 similaires dans le navigateur 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. R exécutera la méthode S3 knit_print.animint, qui compile l’animint dans un dossier local, nommé en fonction du nom du bloc de code R. Par exemple, un bloc de code nommé vis-facettes sera sauvegardé dans le dossier visfacettes. Veillez à placer chaque animint dans son propre morceau de code (ne mettez pas deux animints dans le même morceau de code).

5.3 Publier sur un serveur web

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

Par exemple, j’ai exécuté le code dans https://github.com/animint/animint2/blob/master/inst/examples/WorldBank-facets.R pour créer le WorldBank-facets dossier sur mon ordinateur personnel. 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/ et je peux ainsi 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. Aucun enregistrement ou connexion n’est nécessaire, mais si vous n’avez pas de compte enregistré, vos données seront supprimées après une heure. Vous pouvez souscrire à un compte gratuit si vous souhaitez que vos vis 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 et peut être utilisé pour publier des animints. Pour publier un animint sur GitHub Pages, vous avez besoin d’un compte GitHub et 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 obtiendra cette information à partir du stockage des identifiants de git). Un message devrait s’afficher vous indiquant 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.

Si vous voulez mettre à jour un animint qui a déjà été publié sur GitHub Pages, vous pouvez simplement lancer 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 100MB par fichier. Pour la plupart des visualisations, cette limite ne devrait pas poser de 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 fichiers plus petits.

5.6 Organiser des animints dans une galerie

Une galerie est une collection de méta-donné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 montre 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) et
index.Rmd (source de la page web avec des liens vers animints).

Pour ajouter un nouvel animint à la galerie qui est 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, et validez/poussez cette capture d’écran 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éta-donné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éta-donné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 devrait pouvoir être consultée 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 personnel avant de les publier sur le web.  Cette section traite de 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 de données interactives.  Si `vis` est un animint (liste de ggplots et d'options avec la 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 temporaire séparé, vous pouvez définir un dossier de sortie via l'argument `out.dir` de la commande `animint`.  Si vous voulez 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 (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, il se peut que vous deviez 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 `animint2dir` afin de compiler la visualisation dans un nouveau dossier temporaire sur votre ordinateur personnel.  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 similaires dans le navigateur 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.  R exécutera la méthode S3 `knit_print.animint`, qui compile l'animint dans un dossier local, nommé en fonction du nom du bloc de code R.  Par exemple, un bloc de code nommé `vis-facettes` sera sauvegardé dans le dossier `visfacettes`.  Veillez à placer chaque animint dans son propre morceau de code (ne mettez pas deux animints dans le même morceau de code).  ## Publier sur un serveur web {#web-server}  Comme les animints ne sont que des dossiers contenant des fichiers HTML, TSV et JavaScript, vous pouvez les publier sur n'importe quel serveur web en copiant simplement le dossier sur ce serveur.  Par exemple, j'ai exécuté le code dans <https://github.com/animint/animint2/blob/master/inst/examples/WorldBank-facets.R> pour créer le `WorldBank-facets` dossier sur mon ordinateur personnel.  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/` et je peux ainsi 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.  Aucun enregistrement ou connexion n'est nécessaire, mais si vous n'avez pas de compte enregistré, vos données seront supprimées après une heure.  Vous pouvez souscrire à un compte gratuit si vous souhaitez que vos vis 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 et peut être utilisé pour publier des animints.  Pour publier un animint sur GitHub Pages, vous avez besoin d'un compte GitHub et 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` obtiendra cette information à partir du stockage des identifiants de git).  Un message devrait s'afficher vous indiquant 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.  Si vous voulez mettre à jour un animint qui a déjà été publié sur GitHub Pages, vous pouvez simplement lancer `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 100MB par fichier.  Pour la plupart des visualisations, cette limite ne devrait pas poser de 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 fichiers plus petits.  ## Organiser des animints dans une galerie {#gallery}  Une galerie est une collection de méta-donné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` montre 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) et - `index.Rmd` (source de la page web avec des liens vers animints).  Pour ajouter un nouvel animint à la galerie qui est 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`, et validez/poussez cette capture d'écran 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éta-donné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éta-donné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 devrait pouvoir être consultée 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 {#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.