Nouveautés {learnr}

Auteur·rice·s

Pierre Barbillon

Marie-Pierre Etienne

Isabelle Sanchez

Date de publication

24 août 2023

Introduction

Nous allons ici présenter les nouveautés du package {learnr} qui permet de créer des tutoriaux interactifs. {learnr} avait déjà été discuté durant la semaine Finist’R 2020

{learnr} repose sur {shiny}. Le tutoriel est construit à partir d’un fichier Rmarkdown et peut être soit executé en local via le bouton run app soit en déployant le fichier sur un serveur Shiny.

Depuis 2020 environ, il est possible d’intégrer un tutoriel {learnr] dans un package, ce qui rend les classiques vignettes interactives. Les nouvelles versions de RStudio ont de plus inclus un bouton tutorial disponible dans le panel “Environnement, Git etc…”.

L’idée est de partager un tutoriel facilement à une large audience et pour cela il est maintenant possible de les intégrer dans un package. Cela peut être intéressant pour des tutoriaux à destination d’étudiants mais également pour des tutoriaux à intégrer dans les packages que vous développez pour rendre l’initiation aux méthodes développées plus interactives qu’une vignette.

L’avantage technique d’intégrer un tutoriel {learnr} dans un package est qu’il est alors possible, après avoir installé le package, d’exécuter le tutoriel en local sans avoir à le déployer sur un serveur Shiny. C’est donc gratuit et simple d’utilisation.

A noter qu’il n’est pas nécessaire que le package contenant le tutoriel soit déposé sur le CRAN ou autre, qu’il contienne d’autres fichiers que le tutoriel. Tout est donc possible.

Les étapes pour créer un package contenant un tutoriel:

  1. Si le package n’est pas déjà créé:
usethis::create_package("<path_to_folder/name_of_package>")
  1. Pour créer le fichier du tutoriel:
usethis::use_tutorial("<name-of-learnr-file>", "<Title You'd Like the User to See>")

  1. Puis dans RStudio, cliquer sur “Build > Install and Restart”.

  2. Si nécessaire, rajouter le package {gradethis} (noter la fonction de {usethis} spécifique pour les install de package en développement),

usethis::use_dev_package("gradethis")
  1. Si nécessaire, rajouter les packages présent sur le CRAN toujours avec {usethis}
usethis::use_package("palmerpenguins")

  1. Si nécessaire, éditer le fichier DESCRIPTION

  2. Exécuter usethis::use_readme_rmd() pour rajouter un fichier README. puis compiler le tout.

  3. Déposer le package sur gitlab ou github puis partager le repository qui peut être installé avec les lignes de code suivantes:

devtools::install_github("<your-repo>/<package-name>")
devtools::install_gitlab("<your-repo>/<package-name>")

  1. Lorsque le package est installé, aller dans le panel Tutorial dans RStudio et c’est parti…

  2. Quelques outils utiles.

Il est possible de chaîner des chunks en utilisant la fonctionnalité exercise.setup dans les chunks. Par exemple, nous pouvons effectuer

```{r exo1,exercise=TRUE}

```
```{r exo1-solution}
x = 2+1
```
```{r exo2,exercise=TRUE,exercise.setup="exo1-solution"}

```
```{r exo2-solution,exercise.setup="exo1-solution"}
y = x *3
```
```{r exo3,exercise=TRUE,exercise.setup="exo2-solution"}

```

etc.

Le package {gradethis} permet de vérifier les solutions proposées à un exercice. Par exemple,

L’exercice consiste à faire 2+3

```{r exo3}

```
```{r exo3-solution}
2+3
```

on ajoute un chunk pour vérifier que le code est le bon (mais cela demande que la solution proposée contienne le même code que dans la solution)

```{r exo3-code-check}
grade_this_code()
```

sinon on peut simplement vérifier la sortie du code proposé par l’utilisateur :

```{r exo3-check}
grade_result(
  pass_if(~identical(.result, 5))
)
```

Références

  1. https://rstudio.github.io/learnr/
  2. https://education.rstudio.com/blog/2020/09/delivering-learnr-tutorials-in-a-package/