_learnr_gradethis_interactive_tuto.Rmd

---
title: "Tutoriels avec R avec learnr et gradethis"
output: 
  learnr::tutorial:
    code_download: true
runtime: shiny_prerendered
---

## Démarrer: en tête `yaml` et `setup` chunk

Tout tutoriel doit débuter avec l'en tête yaml (voir `help(learnr::tutorial)` dans `R` pour les différentes options):

````markdown
---
title: "Tutoriels avec R avec learnr et gradethis"
output: 
  learnr::tutorial:
    code_download: true
runtime: shiny_prerendered
---
````

De plus, on peut régler des options du tutoriel dans le chunk `setup`.



```{r setup, message = FALSE, warning = FALSE}
# Setup chunk

## Packages

# L'utilisation de require semble à privilégier pour le déploiment sur shiny apps
library(tidyverse)
library(learnr)
# devtools::install_github("https://github.com/rstudio-education/gradethis")
library(gradethis)

# Options du tutoriel (voir l'aide)
tutorial_options(
  exercise.checker = gradethis::grade_learnr, # Pour checker
)

# Objets pour exercices
my_data <- tibble(x = 1:10, y = runif(10))
```

**Remarque importante:** Tout objet `R` qui est créé pour plusieurs exercices doit être créé dans ce chunk. En effet, les chunks exercices que nous verrons dans la section suivantes ne créé que des objets dans l'environnement du chunk, qui ne seront connus par aucun autre.


## Exercice simple (avec indice)

On peut faire des exercices simples, en ajoutant potentiellement indices et solutions.

*Faire une fonction `add` qui additionne deux nombres. Puis utiliser cette fonction pour calculer 4 + 6*


Le point clé est de spécifier dans le chunk `r` classique l'option `exercise = TRUE`.
Il est essentiel de **nommer** le chunk associé (ici, on a nommé le chunk `add`).

````markdown
`r ''````{r add, exercise=TRUE}
add <- function() {
}
```
````

Ce nommage permet d'ajouter ensuite des attributs à cet exercice, qui seront spécifiés dans de nouveaux chunks. 
Par exemple, on peut donner des indices via l'attribut `hint`. 
On créera un nouveau chunk lié au chunk `nom_chunk` sous la forme:
`nom_chunk-hint`. 

````markdown
`r ''````{r add-hint}
# La fonction prendra deux arguments, séparés par une virgule.
# La dernière ligne de la fonction renverra le résultat.
exemple_function <- function(argument1, argument2){
  # Code de la fonction
  # resultat <- ....
  resultat # On peut aussi mettre return(resultat)
}
```
````

Cet indice sera visible par le lecteur dans un onglet *Hint* sur lequel il pourra cliquer.

De même, on peut ajouter une solution, dans un chunk nommé `nom_chunk-solution`:

````markdown
`r ''````{r add-solution}
# SOLUTION
add <- function(argument1, argument2){
  resultat <- argument1 + argument2
  resultat # On peut aussi  mettre return(resultat)
}
add(4, 6)
```
````

Ceci crée un onglet *Solution* dans la fenêtre de code.

**Remarque:** Dans la version actuelle de `learnr`, il semblerait qu'ajouter une solution à un *hint* ne crée pas deux onglets, mais un seul onglet *Hints*, qui permet de défiler plusieurs fenêtres, dont la dernière sera la solution. On peut espérer que cela évolue dans l'avenir.

L'écriture de tous ces codes renvoie le chunk suivant, dans 


```{r add, exercise=TRUE}
add <- function() {
}
```


```{r add-hint}
# La fonction prendra deux arguments, séparés par une virgule.
# La dernière ligne de la fonction renverra le résultat.
exemple_function <- function(argument1, argument2){
  # Code de la fonction
  # resultat <- ....
  resultat # On peut aussi mettre return(resultat)
}
```

```{r add-solution}
# SOLUTION
add <- function(argument1, argument2){
  resultat <- argument1 + argument2
  resultat # On peut aussi  mettre return(resultat)
}
add(4, 6)
```

### Exercices faisant appel à des objets extérieurs.

Supposons qu'on ait deux exercices. Le premier est:

1. *Créer un vecteur `exemple` contenant les valeurs de 1 à 5:*

```{r exo_chunk_ex_data, exercise = TRUE}
# Afficher le vecteur ex_data
exemple <- 
```

Le second fait appel au résultat du premier:

2. *Calculer la somme des éléments du vecteur `exemple`:*

```{r exo_chunk_exemple_sum, exercise = TRUE}
# Afficher le vecteur ex_data
sum(exemple)
```

Malheureusement, l'objet n'est pas reconnu. Ceci est dû au fait que l'objet créé dans le premier exercice n'est créé que dans un environnement local.

Pour que cet objet soit reconnu, il faudra le créer dans le chunk setup initial (voir la première section de ce document), ou le crééer dans un chunk associé à cet exercice (ici, l'exercice 2), dont le nom fera référence à l'exercice,, auquel on ajoutera le suffixe `setup`: i.e. `exercice2-setup`

Par exemple, on peut imprimer l'objet `my_data` créé dans la première section

```{r print_my_data, exercise = TRUE}
# Imprimer my_data
print(my_data)
```

On peut ensuite passer à la section suivante avec le `## Quiz (QCM)`.

## Quiz (QCM)

*On peut faire des quiz à l'aide des fonctions `quiz` et `question`*.

La fonction `quiz` regroupe différentes fonctions `question`, dans lesquelles des QCM 
peuvent être très facilement intégrés (voir Help).


```{r quiz, echo = TRUE}
library(learnr)
quiz(
  question(text = "La méthode des k-means est une méthode de classification:",
    answer("Supervisée"),
    answer("Non-supervisée", correct = TRUE),
    answer("C'est des stats, ça?",
           message = "Donne n'importe quel nom à une rose, elle sentira toujours bon"),
    submit_button = "Valider la réponse"
  ),
  question(text = "R est:",
    answer("Une lettre de l'alphabet", correct = TRUE),
    answer("Un des quatre éléments"),
    answer("Un logiciel de statistiques", correct = TRUE)
  )
)
```

## Exercice avec "vérification"

Dans cette section, on utilise le package `gradethis` qui permet de vérifier la validité d'un code donné dans un exercice:

### Vérification du résultat


Dans un exercice sur du code, si on veut vérifier le résultat, on peut ajouter à un exercice un chunk de vérification, qui sera sous la forme `nom_chunk-check`. 
En incluant dans ce chunk la fonction `gradethis::grade_result`, on pourra passer une liste de tests pour voir si le résultat donné est correct.

Par exemple, pour l'exercice suivant, on commence par créer un chunk d'exercice, comme précedemment:


````markdown
`r ''```{r puissance, exercise=TRUE, exercise.lines = 5}
function(x, y) {
  # Rentrer le code de la fonction ici
}
```
````

On passera alors les tests dans le chunk:

````markdown
`r ''```{r puissance-check}
grade_result(
  fail_if(~ !is.function(.result), "I expected a function."),
  pass_if(~ identical(.result(1.4, 2.3), 1.4^2.3), 
          message = "Bravo!"),
  glue_incorrect = glue::glue("Pour x = 1.4 et y = 2.3, votre fonction devrait renvoyer {1.4^2.3}. En R, la puissance se fait avec ^"))
```
````

Ici, on passe  deux tests, un sur la nature de l'objet rendu, un sur le résultat pour deux arguments donnés.

En pratique, cela donne l'exempl;e suivant (essayez différentes valeurs dans le chunk!).

*Faites une fonction qui prend un nombre `x` et un nombre `y` et renvoie 
$x^y$. Vous n'assignerez pas cette fonction à un objet*


```{r puissance, exercise=TRUE, exercise.lines = 5}
function(x, y) {
  # Rentrer le code de la fonction ici
}
```

```{r puissance-check}
grade_result(
  pass_if(~ identical(.result(1.4, 2.3), 1.4^2.3), 
          message = "Bravo!"),
  glue_incorrect = glue::glue("Pour x = 1.4 et y = 2.3, votre fonction devrait renvoyer {1.4^2.3}. En R, la puissance se fait avec ^"))
```

### Vérification du code

Mais aussi du code!

Pour cela, on procède comme précedemment, sauf que l'on utilise désormais la fonction `grade_code` dans le chunk `-check`

````markdown
`r ''```{r code_verif-check}
grade_code("Bah ça alors") # Message d'ajout.
```
````

En une seule ligne, tirez un échantillon de taille 1 dans une uniforme, en prend le logarithme, 
puis la valeur absolue.

*Dans le code suivant, essayez d'écrire `abs(log(runif(1)))`, puis `abs(exp(runif(1)))`, et constatez le résultat.*

```{r code_verif, exercise=TRUE, exercise.lines = 10}
# Rentrer la solution
```

```{r code_verif-solution}
abs(log(runif(1)))
```

```{r code_verif-check}
grade_code(correct = "Très bon", incorrect = "Essaye encore!") # Message circonstancié
```

## Publication sur `shinyapps`

Un tutorial `learnr` peut être déployé sur `shinyapps`. Il faut pour cela avoir un compte sur shinyapps.io. Ensuite, on peut publier directement depuis Rstudio (ongle `Publish` en haut à droite de `Run`.)