Ajout d'une mention sur les sous-requêtes (#436)

* complète fiche bdd (#435)

* droits pour écrire dans base
* id et pwd dans .Renviron

* petite correction de la hiérarchie des titres

* Relecture rmarkdown (#428)

* correction coquille orthographe

* Correction §27.4.2

* Déplacement logo Latex

* Modification éditeur markdown RStudio

* Correction coquille sur lien gif

* Changement url lancement du service utilitr dans CONTRIBUTING (#405)

* Changement url lancement du service utilitr dans CONTRIBUTING
* Update CONTRIBUTING.md

Co-authored-by: Pierre-Yves Berrard <[email protected]>

* ajout exemples de sous-requetes SQL

Co-authored-by: Pierre-Yves Berrard <[email protected]>
Co-authored-by: Lino Galiana <[email protected]>
Co-authored-by: Damien Dotta <[email protected]>

03_Fiches_thematiques/Fiche_connexion_bdd.Rmd

@@ -150,22 +150,38 @@ Pour lancer des requêtes sur la base de données, l'utilisateur a la possibilit
 Ainsi, pour un utilisateur qui est connecté à la base de données PostgreSQL qui contient le schéma de diffusion - une sorte de librairie SAS - de Fidéli (`s_diff_2018`) et qui souhaite requêter la table des logements (`d_logement`) pour compter le nombre de logements par commune et selon le critère du type de local (critère n°2 dans la documentation utilisateur), on peut lancer les requêtes SQL suivantes :
 
 ```{r, eval = FALSE}
-dbSendQuery(conn, 
-            "create temp table count_log as 
-             select csdep, cne, 
-             case when natloc in ('MA', 'ME', 'AP') then 1 else 0 end as logement 
-             from s_diff_2018.d_logement")
+q <- dbSendQuery(conn, 
+                 "create temp table count_log as 
+                  select csdep, cne, 
+                  case when natloc in ('MA', 'ME', 'AP') then 1 else 0 end as logement 
+                  from s_diff_2018.d_logement")
+dbClearResult(q)
 
 count_log <- dbGetQuery(conn, 
                         "select distinct concat(csdep, cne) as code_com,
                          sum(logement) as nb_logement 
                          from count_log")
 ```
 
-La première requête crée une table temporaire `count_log` qui contient le département et la commune de chaque local, ainsi qu'une variable indicatrice indiquant s'il s'agit d'un logement. Cette requête est envoyée au serveur avec `dbSendQuery` et ne renvoie donc aucun résultat vers `R`. La création de cette table temporaire nécessite d'avoir les droits en écriture dans la base.
+La première requête crée une table temporaire `count_log` qui contient le département et la commune de chaque local, ainsi qu'une variable indicatrice indiquant s'il s'agit d'un logement. Cette requête est envoyée au serveur avec `dbSendQuery` et ne renvoie donc aucun résultat vers `R`. La création de cette table temporaire nécessite d'avoir les droits minimaux en écriture dans la base.
 
 La seconde requête compte le nombre de logements par commune à partir de la table temporaire et renvoie vers `R` un objet de type `data.frame` appelé `count_log` donnant le nombre de logements (`nb_logement`) par commune (`code_com`).
 
+Dans le cas où l'utilisateur n'a pas les droits pour créer des tables temporaires, il est toujours possible de procéder à des sous-requêtes (**sub-query**) en SQL. Cela consiste à enchasser la première requête dans la seconde sans passer par la création d'une table temporaire, de la manière suivante :
+
+```{r, eval = FALSE}
+q <- dbSendQuery(conn, 
+            "select distinct concat(csdep, cne) as code_com,
+                         sum(logement) as nb_logement 
+                         from (select csdep, cne, 
+                         case when natloc in ('MA', 'ME', 'AP') then 1 else 0 end as logement 
+                         from s_diff_2018.d_logement) as a")
+
+dbFetch(q)
+dbClearResult(q)
+
+```
+
 ::: {.remarque}
 Il est fréquent que les bases de données contiennent des données volumineuses, dont le téléchargement et le traitement peuvent dépasser les capacités de votre poste local. C'est pourquoi **il est recommandé d'éviter de télécharger les données brutes et de réaliser les traitements en `R`.** Dans la mesure du possible, **il vaut mieux faire exécuter les traitements par la base de données, et ne récupérer en `R` qu'un résultat agrégé.** 
 
@@ -186,20 +202,32 @@ Une fois la référence créée, on peut manipuler les données de la table `d_l
 
 ```{r, eval = FALSE}
 count_log <- d_logement %>%
-    mutate(logement = ifelse(natloc %in% c('MA', 'ME', 'AP'), 1, 0)) %>%
-    select(csdep, cne, logement) %>%
-    compute()
+  mutate(logement = ifelse(natloc %in% c('MA', 'ME', 'AP'), 1, 0)) %>%
+  select(csdep, cne, logement) %>%
+  compute()
 
 count_log <- count_log %>%
-    group_by(csdep, cne) %>%
-    summarise(nb_logement = sum(logement)) %>%
-    collect()
+  group_by(csdep, cne) %>%
+  summarise(nb_logement = sum(logement)) %>%
+  collect()
 ```
 
 Dans cet exemple, la nature de l'objet `count_log` change entre la première et la seconde instruction. Au départ, il s'agit d'une interprétation de l'instruction sous forme `dplyr` en requête SQL (un objet `sql_tbl`) stockée dans une table temporaire grâce à la commande `compute`, qui ensuite devient un objet `data.frame` suite à la commande `collect` (qui peut se voir comme un équivalent de la commande `dbGetQuery`, en plus large puisqu'elle déclenche la soumission de la requête SQL).
 
 Le _package_ `dbplyr` présente l'avantage d'offrir une syntaxe très proche de celle de `dplyr`. Cette syntaxe peut néanmoins, comme indiqué dans la documentation, présenter des limites dans l'interprétation des commandes en requêtes SQL. L'utilisateur devra être particulièrement attentif à ce point.
 
+L'enchâssement d'une sous-requête dans une requête SQL est très adapté au _pipe_ de la syntaxe `dplyr`, et se traduit très naturellement ainsi :
+
+```{r, eval = FALSE}
+count_log <- d_logement %>%
+  mutate(logement = ifelse(natloc %in% c('MA', 'ME', 'AP'), 1, 0)) %>%
+  select(csdep, cne, logement) %>%
+  group_by(csdep, cne) %>%
+  summarise(nb_logement = sum(logement)) %>%
+  collect()
+```
+
+
 ::: {.conseil}
 Comme indiqué ci-dessus, le _package_ `dbplyr` convertit automatiquement vos instructions en requête SQL. Il est possible d'afficher cette requête avec la fonction `show_query`. Cela vous permet de vous familiariser avec le langage SQL, et de voir que la requête SQL générée par `dbplyr` est souvent loin d'être optimale.
 :::

03_Fiches_thematiques/Fiche_rmarkdown.Rmd

@@ -152,7 +152,7 @@ Un document `R Markdown` comprend deux parties principales :
 
 #### L'en-tête
 
-L'en-tête d'un document `R Markdown` (arfois appelé `YAML header`) est délimité par deux lignes de pointillés et contient les métadonnées du document (titre, auteurs, options générales de mise en page...). Il contient au minimum le titre du document et le format de sortie. Il peut être enrichi d'autres champs pour modifier certaines métadonnées (par exemple la date) ou le style du document compilé. Voici un exemple d'en-tête :
+L'en-tête d'un document `R Markdown` (parfois appelé `YAML header`) est délimité par deux lignes de pointillés et contient les métadonnées du document (titre, auteurs, options générales de mise en page...). Il contient au minimum le titre du document et le format de sortie. Il peut être enrichi d'autres champs pour modifier certaines métadonnées (par exemple la date) ou le style du document compilé. Voici un exemple d'en-tête :
 
 ```yaml
 --- 
@@ -235,19 +235,21 @@ Prendra la forme suivante, une fois compilé :
 
 Dans RStudio, le menu `Help > Markdown quick reference` donne un aperçu plus complet de la syntaxe.
 
-::: {.conseil}
-La version 1.4 de ` RStudio` qui devrait devenir version officielle d'ici peu, 
-propose de nombreux outils pour faciliter l'édition de fichiers `R Markdown`.
+À partir de [la version 1.4](https://www.rstudio.com/blog/announcing-rstudio-1-4/), ` RStudio` propose de nombreux outils pour faciliter l'édition de fichiers `R Markdown`.
 La principale innovation est 
-[l'éditeur visuel de Markdown](https://rstudio.github.io/visual-markdown-editing/#/)
-qui propose une pré-visualisation du document compilé en *live* mais aussi 
-des fonctionnalités qui facilitent l'écriture de `Markdown`
+[l'éditeur visuel de Markdown](https://rstudio.github.io/visual-markdown-editing/#/), accessible grâce au bouton
+```{r, out.extra='style="display: inline-block; padding: 0; width: 30px;"', echo = FALSE}
+utilitr::include_image("./pics/rmarkdown/inline_pics/bouton_visual_rmarkdown.png", compression = FALSE)
+```
+\ situé en haut à droite de l'éditeur, qui propose une pré-visualisation du document compilé en *live* mais aussi des fonctionnalités qui facilitent l'écriture de `Markdown`
 (correcteur orthographique amélioré, ajout de citations bibliographiques
 facilité, plus de raccourcis claviers, etc.).
 
-En attendant l'officialisation de cette version,
-l'*addin* `Remedy` facilite l'écriture de fichiers `R Markdown` grâce à un
-menu qui permet de cliquer directement sur le type de balise désiré :
+`r if(knitr::is_html_output()){"![Présentation de l'éditeur visuel de RStudio](https://www.rstudio.com/blog/rstudio-v1-4-preview-visual-markdown-editing/images/visualmode-demo.gif)"}`
+
+::: {.conseil}
+L'*addin* `Remedy` est également pratique et facilite l'écriture de fichiers `R Markdown` 
+grâce à un menu qui permet de cliquer directement sur le type de balise désiré :
 
 `r if(knitr::is_html_output()){"![Présentation de l'addin disponible sur github](https://raw.githubusercontent.com/ThinkR-open/remedy/master/reference/figures/remedy_example.gif)"}`
 
@@ -418,7 +420,11 @@ La liste complète des options possibles est présente sur le site de la documen
 
 ### Gestion automatique de la bibliographie
 
-Parmi les tâches les plus pénibles dans un document *WYSIWYG* [**mettre un mouseover pour rappeler la def**], la bibliographie tient une place de premier choix. Les utilisateurs de `LaTeX` [mettre logo plutôt] connaissent le temps que peut faire gagner un module adapté de gestion des ressources bibliographiques, à savoir `bibtex`. Un module adapté de bibliographie repose sur des métadonnées avec un système ressemblant au format `JSON`, c'est-à-dire des champs (par exemple `author`) associé à des valeurs au format prédéfini (par exemple `Dumas, Alexandre`).
+Parmi les tâches les plus pénibles dans un document *WYSIWYG* (*What you see is what you get*), la bibliographie tient une place de premier choix. Les utilisateurs de 
+```{r, out.extra='style="display: inline-block; padding: 0; width: 30px;"', echo = FALSE}
+utilitr::include_image("./pics/rmarkdown/inline_pics/LaTeX_logo.png", compression = FALSE)
+```
+\ connaissent le temps que peut faire gagner un module adapté de gestion des ressources bibliographiques, à savoir `bibtex`. Un module adapté de bibliographie repose sur des métadonnées avec un système ressemblant au format `JSON`, c'est-à-dire des champs (par exemple `author`) associé à des valeurs au format prédéfini (par exemple `Dumas, Alexandre`).
 
 Le format `bibtex` constitue un standard dans le domaine. Il s'agit de définir le type de publication (livre, article, rapport, etc.) qui déterminera la manière dont sera citée le document dans la norme bibliographique adoptée et les champs informatifs (auteur, année, etc.). Le principal avantage d'une gestion bibliographique avec `bibtex` est que formattage de la référence bibliographique n'est pas fait par l'utilisateur mais est fait automatiquement en fonction d'une norme qui met en forme les champs de la référence bibliographique. Ce sont ainsi des heures pénibles de travail économisées. Une référence bibliographique prend la forme suivante :
 

03_Fiches_thematiques/Fiche_targets.Rmd

@@ -397,7 +397,7 @@ de la chaîne de traitement, directement depuis le fichier `RMarkdown`.
 Dans ce cas, le fichier `.Rmd` n'est plus exécuté depuis le `_targets.R`
 mais au contraire sert à l'exécuter.
 
-## Concevoir un rapport en sortie de chaîne de traitement
+### Concevoir un rapport en sortie de chaîne de traitement
 
 Le *package* `tarchetypes` est un complément utile.
 Ce *package* permet d'intégrer simplement des rapports `Rmarkdown`
@@ -428,7 +428,7 @@ list(
 
 ```
 
-## Utiliser des objets issus d'une chaîne de traitement dans un R Markdown
+### Utiliser des objets issus d'une chaîne de traitement dans un `R Markdown`
 
 Cette méthode est particulièrement appropriée lorsqu'on 
 désire prototyper un rapport en utilisant un ou plusieurs
@@ -636,3 +636,4 @@ Etc...
 * https://docs.ropensci.org/tarchetypes/ 
 * Un exemple https://github.com/InseeFrLab/lockdown-maps-R/ 
 * Les "target factories": https://wlandau.github.io/targetopia/contributing.html 
+* Un tutoriel de Noam Ross présentant l'usage de `targets` avec un système de stockage de type AWS (similaire au principe du `SSPCloud`): https://github.com/noamross/targets-minio-versioning

CONTRIBUTING.md

@@ -269,7 +269,7 @@ de la manière suivante :
 
 ![](./pics/contributing/mes_secrets_utilitr.png)
 
-On peut ensuite lancer le [service configuré dans ce lien](https://datalab.sspcloud.fr/launcher/inseefrlab-helm-charts-datascience/rstudio?onyxia.friendlyName=%C2%AButilitr-contrib%C2%BB&init.personalInit=%C2%ABhttps%3A%2F%2Fraw.githubusercontent.com%2FInseeFrLab%2FutilitR%2Fmaster%2Finit_utilitr.sh%C2%BB&service.image.version=%C2%ABinseefrlab%2Futilitr%3A0.8.0%C2%BB&vault.secret=%C2%AButilitr%2Futilitr%C2%BB) pour obtenir un service avec une identification persistante.
+On peut ensuite lancer le [service configuré dans ce lien](https://datalab.sspcloud.fr/launcher/inseefrlab-helm-charts-datascience/rstudio?autoLaunch=true&onyxia.friendlyName=«utilitr-contrib»&init.personalInit=«https%3A%2F%2Fraw.githubusercontent.com%2FInseeFrLab%2FutilitR%2Fmaster%2Finit_utilitr.sh»&service.image.version=«inseefrlab%2Futilitr%3A0.8.0»&vault.secret=«utilitr%2Futilitr»&git.token=«») pour obtenir un service avec une identification persistante.
 
 ### :one: Forker le dépôt `utilitR`