From ffadb8e70d59ef68e9084f2612c21d12b4c46adc Mon Sep 17 00:00:00 2001 From: Tanguy BARTHELEMY Date: Tue, 25 Feb 2025 13:41:27 +0100 Subject: [PATCH 1/2] Github --> GitHub Rstudio --> RStudio --- 01_R_Insee/Fiche_installer_packages.qmd | 2 +- .../Fiche_utiliser_Rstudio_SSPCloud.qmd | 10 +-- 01_R_Insee/Travail_avec_R_Insee.qmd | 26 ++++---- 01_R_Insee/presentation_utilitr.qmd | 8 +-- 02_Bonnes_pratiques/02-structure-code.qmd | 2 +- 03_Fiches_thematiques/Fiche_datatable.qmd | 6 +- .../Fiche_donnees_spatiales.qmd | 2 +- .../Fiche_git_utilisation.qmd | 16 ++--- .../Fiche_import_tableurs.qmd | 4 +- .../Fiche_joindre_donnees.qmd | 20 +++--- 03_Fiches_thematiques/Fiche_targets.qmd | 4 +- 03_Fiches_thematiques/Fiche_tidyverse.qmd | 6 +- CONTRIBUTING.md | 64 +++++++++---------- DocumentationR.Rproj | 1 + Manifeste.md | 2 +- README.md | 4 +- index.qmd | 4 +- 17 files changed, 91 insertions(+), 90 deletions(-) diff --git a/01_R_Insee/Fiche_installer_packages.qmd b/01_R_Insee/Fiche_installer_packages.qmd index 04434162..00bdf41f 100644 --- a/01_R_Insee/Fiche_installer_packages.qmd +++ b/01_R_Insee/Fiche_installer_packages.qmd @@ -27,7 +27,7 @@ D'un point de vue technique, un _package_ est constitué d'objets `R` (la plupar Les _packages_ `R` sont disponibles sur des sites spécialisés appelés dépôts (_repositories_ ou _repo_ en anglais). Le principal dépôt est le dépôt officiel du projet `R`, le [CRAN](https://cran.r-project.org) (_Comprehensive R Archive Network_). -Les _packages_ peuvent également être mis à disposition par leurs auteurs sur les forges logicielles (telles que Github et Gitlab), mais il s'agit alors la plupart du temps de versions expérimentales dont l'usage est principalement destiné aux utilisateurs avancés de `R`. +Les _packages_ peuvent également être mis à disposition par leurs auteurs sur les forges logicielles (telles que GitHub et Gitlab), mais il s'agit alors la plupart du temps de versions expérimentales dont l'usage est principalement destiné aux utilisateurs avancés de `R`. ::: {.callout-note} Le CRAN dispose de plusieurs copies, appelées _miroirs_, dont la plupart sont hébergés sur des [serveurs d'universités ou d'établissements de recherche](https://cran.r-project.org/mirrors.html). Télécharger un _package_ sur un miroir ou un autre est strictement équivalent. L'intérêt de choisir un miroir proche de sa localisation permet simplement de gagner en vitesse et de réduire les flux sur le réseau. diff --git a/01_R_Insee/Fiche_utiliser_Rstudio_SSPCloud.qmd b/01_R_Insee/Fiche_utiliser_Rstudio_SSPCloud.qmd index 576d5721..0c8d32d1 100644 --- a/01_R_Insee/Fiche_utiliser_Rstudio_SSPCloud.qmd +++ b/01_R_Insee/Fiche_utiliser_Rstudio_SSPCloud.qmd @@ -149,18 +149,18 @@ Les principales options sont les suivantes : - L'**option `cpu`** (dans l'onglet `Resources`) définit le nombre minimal de processeurs alloués à votre service RStudio, c'est un minimum garanti. Il est conseillé d'utiliser 2 comme valeur par défaut si vos traitements nécessitent de la parallélisation et laisser l'option par défaut sinon. - L'**option `Enable IP protection`** (dans l'onglet `Security`) est une option de sécurité informatique assez contraignante, qui est activée par défaut. Il est conseillé de la laisser activée. Toutefois, vous pouvez éventuellement la désactiver, notamment si vous savez que vous allez devoir accéder à l'environnement RStudio depuis des adresses IP différentes (exemple : au bureau puis en télétravail). - L'**option `version`** (dans l'onglet `Service`) détermine l'environnement dans lequel RStudio va s'ouvrir. Il s'agit d'un environnement contenant une version donnée de `R` ainsi que des packages pré-installés. Par exemple, l'image `utilitR` disponible propose l'ensemble des dépendances (elles sont nombreuses...) nécessaires pour reproduire tous les exemples présents dans cette documentation. -- L'**option `PersonalInit`** (dans l'onglet `Init`) permet de référencer un script d'initialisation qui exécutera une série d'actions prédéfinies avant de lancer le service, par exemple copier localement des données, lancer un projet RStudio ou définir des paramètres d'affichage de l'interface. Un exemple d'un tel fichier Init utilisé pour des formations peut être trouvé [ici](https://github.com/InseeFrLab/formation-r-lissage-spatial/blob/f3258469513cabd2de328dc92165641f8f452bca/utils/init.sh). C'est l'URL du fichier sur github.com qui doit être référencé, **dans sa version *Raw*** (afficher le fichier dans Github et cliquer sur `Raw` en haut à droite pour obtenir cette URL). +- L'**option `PersonalInit`** (dans l'onglet `Init`) permet de référencer un script d'initialisation qui exécutera une série d'actions prédéfinies avant de lancer le service, par exemple copier localement des données, lancer un projet RStudio ou définir des paramètres d'affichage de l'interface. Un exemple d'un tel fichier Init utilisé pour des formations peut être trouvé [ici](https://github.com/InseeFrLab/formation-r-lissage-spatial/blob/f3258469513cabd2de328dc92165641f8f452bca/utils/init.sh). C'est l'URL du fichier sur github.com qui doit être référencé, **dans sa version *Raw*** (afficher le fichier dans GitHub et cliquer sur `Raw` en haut à droite pour obtenir cette URL). ::: {.callout-note} **Les options d'un service RStudio ne peuvent être définies qu'au moment de la création du service.** Si vous vous rendez compte qu'une option du service ne convient pas au traitement que vous voulez faire, vous devez supprimer votre service RStudio et en lancer un nouveau avec les bonnes options. Lorsqu'un ensemble d'options vous conviennent, il est possible de l'enregistrer pour les retrouver lors du prochain lancement d'un service. Pour cela, cliquez sur l'icône de marque-page en haut à droite du panneau de paramétrage. La liste des configurations ainsi définies comme favorites apparaîtront dans SSP Cloud dans la rubrique `Mes services`, dans la colonne `Enregistrés`. ::: -### Utiliser Github et Gitlab sur le SSP Cloud +### Utiliser GitHub et Gitlab sur le SSP Cloud Les services ouverts sur le SSPCloud ont une durée de vie limitée. Pour conserver les codes afin de pouvoir les réutiliser ultérieurement ou les rendre disponibles à d'autres personnes, il est nécessaire d'utiliser une -plateforme type Gitlab et Github. +plateforme type Gitlab et GitHub. Dans le catalogue des services, une plateforme Gitlab est disponible. Son adresse est (c'est un [`Service partagé`](https://datalab.sspcloud.fr/services)). Cependant, elle n'apporte pas un niveau de sécurité @@ -202,13 +202,13 @@ suivre en temps réel l'usage mémoire et CPU d'un service RStudio. C'est utile Le SSP Cloud propose des environnements (comme les services ` RStudio`, `Jupyter`, etc.) pour exécuter des programmes informatiques. Ces environnements sont **temporaires par définition** (quelques heures ou quelques jours), et ne peuvent donc pas servir à stocker des données ou des programmes informatiques. Cela a pour conséquence que les programmes informatiques et les données doivent être stockés dans d'autres espaces : -* *stockage des codes* : il est nécessaire d'utiliser une plate-forme de développement pour stocker des programmes informatiques, telles que [Gitlab](www.gitlab.com) ou [Github](www.github.com). +* *stockage des codes* : il est nécessaire d'utiliser une plate-forme de développement pour stocker des programmes informatiques, telles que [Gitlab](www.gitlab.com) ou [GitHub](www.github.com). * *stockage des données* : la plateforme SSP Cloud propose un système de stockage de données nommé S3. Depuis votre service RStudio, vous pourrez facilement accéder à des données stockées sur S3 grâce au _package_ `aws.s3`. ::: {.callout-note} Voici deux règles à respecter pour faire un bon usage de ces deux espaces de stockage : -* Les plate-formes telles que Gitlab ou Github ne doivent **jamais** être utilisées pour stocker des données (uniquement des codes). +* Les plate-formes telles que Gitlab ou GitHub ne doivent **jamais** être utilisées pour stocker des données (uniquement des codes). * Le système de stockage S3 ne doit **jamais** être utilisé pour stocker des données confidentielles. ::: diff --git a/01_R_Insee/Travail_avec_R_Insee.qmd b/01_R_Insee/Travail_avec_R_Insee.qmd index 65300473..07edf198 100644 --- a/01_R_Insee/Travail_avec_R_Insee.qmd +++ b/01_R_Insee/Travail_avec_R_Insee.qmd @@ -2,11 +2,11 @@ ## Démarrage rapide de `R` à l'Insee -- où clique-t-on pour accéder à Rstudio? Description rapide des environnements: local, AUS, PF innovation. +- où clique-t-on pour accéder à RStudio? Description rapide des environnements: local, AUS, PF innovation. - Comment on installe un _package_? - - Comment on crée un projet Rstudio? + - Comment on crée un projet RStudio? - ## Utiliser `R` et `Rstudio` à l'Insee? + ## Utiliser `R` et `RStudio` à l'Insee? ### Les différents environnements d'usage de `R` à l'Insee @@ -16,20 +16,20 @@ #### Utiliser `R` en local -- Comment on installe `R` et Rstudio. -- Comment on lance Rstudio. +- Comment on installe `R` et RStudio. +- Comment on lance RStudio. #### Utiliser `R` sous AUS - Comment on se connecte à AUS; -- Comment on lance Rstudio. +- Comment on lance RStudio. #### Utiliser `R` sur la PF innovation - Comment on se crée un compte sur la PF innovation; -- Comment on lance un container Rstudio. +- Comment on lance un container RStudio. -### Utiliser les projets Rstudio pour structurer son travail +### Utiliser les projets RStudio pour structurer son travail Reprendre (en version très allégée) la partie 3 de la formation Travail Collaboratif sous `R`. @@ -42,7 +42,7 @@ Parler du fichier `.Rprofile`, et dire ce qui peut être configuré. ### Installer des _packages_ -- Quelles sont les sources pour les _packages_? CRAN, Github... +- Quelles sont les sources pour les _packages_? CRAN, GitHub... - Expliquer qu'il y a des miroirs pour AUS; - Expliquer comment installer un _package_ (et aussi *binary* _versus_ *source*). @@ -53,16 +53,16 @@ Cette partie peut être ici, ou transférée dans la partie Fiches thématiques. ## La gestion de version -### Utiliser Git et Rstudio +### Utiliser Git et RStudio #### Introduction à Git - Des bases de `Git`: Reprendre la partie 4.2 de la formation Travail Collaboratif sous R. -#### Git dans Rstudio +#### Git dans RStudio - Où mettre son dépôt local `Git` (en local et dans AUS) -- Utiliser `Git` avec l'interface `Rstudio` +- Utiliser `Git` avec l'interface `RStudio` ### Le Gitlab interne @@ -70,4 +70,4 @@ Cette partie peut être ici, ou transférée dans la partie Fiches thématiques. - Configurer son accès à Gitlab (SSH, Putty etc.) - Comment travailler à plusieurs avec Gitlab? Reprendre la partie 4.4 de la formation Travail Collaboratif sous R. -## Se former à `R` à l'Insee \ No newline at end of file +## Se former à `R` à l'Insee diff --git a/01_R_Insee/presentation_utilitr.qmd b/01_R_Insee/presentation_utilitr.qmd index 88b1b195..47146526 100644 --- a/01_R_Insee/presentation_utilitr.qmd +++ b/01_R_Insee/presentation_utilitr.qmd @@ -11,12 +11,12 @@ Les contributeurs du projet `utilitR` se sont fixés pour objectif de **rassembl **Le projet `utilitR` est un projet collaboratif, évolutif, *open source* et ouvert à tous, porté par des agents de l'Insee et du Service Statistique Public (SSP).** Toute personne qui le souhaite peut modifier la documentation ou la compléter en fonction de ses connaissances et de ses expériences (voir [Comment contribuer au projet `utilitR`](#contribuer)). -Le code source de cette documentation est hébergé sous `Github` et est accessible en cliquant sur [ce lien](https://github.com/InseeFrLab/utilitR). +Le code source de cette documentation est hébergé sous `GitHub` et est accessible en cliquant sur [ce lien](https://github.com/InseeFrLab/utilitR). ## Comment contribuer à `utilitR`? {#contribuer} **Le projet `utilitR` est un projet collaboratif, évolutif, *open source* et ouvert à tous, auquel tous les agents peuvent contribuer.** Le projet est mené par un groupe de contributeurs qui en définissent eux-mêmes le contenu, la structure et le calendrier. -Le dépôt de la documentation est situé sur le compte `InseeFrLab` sur la plateforme `Github` et peut +Le dépôt de la documentation est situé sur le compte `InseeFrLab` sur la plateforme `GitHub` et peut facilement être retrouvé à [cette adresse](https://github.com/InseeFrLab/utilitR). Les objectifs et l'approche collaborative du projet `utilitR` sont détaillés dans le document [`Manifeste.md`](https://github.com/InseeFrLab/utilitR/blob/master/Manifeste.md). @@ -25,7 +25,7 @@ Les objectifs et l'approche collaborative du projet `utilitR` sont détaillés d Tout agent intéressé à contribuer au projet est invité à consulter le guide des contributeurs [`CONTRIBUTING.md`](https://github.com/InseeFrLab/utilitR/blob/master/CONTRIBUTING.md). [Ce guide](https://github.com/InseeFrLab/utilitR/blob/master/CONTRIBUTING.md) donne également quelques astuces pour les personnes n'étant pas familières -avec `Github`. +avec `GitHub`. ## Contributeurs du projet @@ -65,5 +65,5 @@ pour l'adapter à un contexte différent. Les conditions de réutilisation sont dans la [licence](https://github.com/InseeFrLab/utilitR/blob/master/LICENSE.md). Bien que ce ne soit en rien obligatoire, -si vous êtes réutilisateurs de la documentation, n'hésitez pas à vous signaler sur notre [`Github`](https://github.com/InseeFrLab), +si vous êtes réutilisateurs de la documentation, n'hésitez pas à vous signaler sur notre [`GitHub`](https://github.com/InseeFrLab), vos retours pourraient permettre d'améliorer la documentation, au bénéfice de tous. diff --git a/02_Bonnes_pratiques/02-structure-code.qmd b/02_Bonnes_pratiques/02-structure-code.qmd index 38582f5e..e7240698 100644 --- a/02_Bonnes_pratiques/02-structure-code.qmd +++ b/02_Bonnes_pratiques/02-structure-code.qmd @@ -212,7 +212,7 @@ détecter lors de l'exécution de scripts `R`. Le fichier `README.md`, situé à la racine du projet, est à la fois la carte d'identité et la vitrine du projet. En effet, comme il s'agit du fichier qui fait office de point d'entrée -d'un projet sur `Github` ou `Gitlab`, il s'agit de la première source +d'un projet sur `GitHub` ou `Gitlab`, il s'agit de la première source d'information pour comprendre l'objet du projet. Idéalement, ce fichier contient : diff --git a/03_Fiches_thematiques/Fiche_datatable.qmd b/03_Fiches_thematiques/Fiche_datatable.qmd index 8e52ddd7..ffbd83c7 100644 --- a/03_Fiches_thematiques/Fiche_datatable.qmd +++ b/03_Fiches_thematiques/Fiche_datatable.qmd @@ -200,17 +200,17 @@ dt[y > 3, newvar := 1] -```{asis, eval=TRUE, echo=TRUE} +```{asis, eval = TRUE, echo=TRUE} **Signification** ``` -```{asis, eval=TRUE, echo=TRUE} +```{asis, eval = TRUE, echo=TRUE} Partir de `dt`, conserver uniquement les observations pour lesquelles `x > 3`, et créer une nouvelle variable `newvar` qui vaut 1 partout ``` -```{asis, eval=TRUE, echo=TRUE} +```{asis, eval = TRUE, echo=TRUE} Partir de `dt`, créer une nouvelle variable `newvar` qui vaut 1 pour les observations pour lesquelles `x > 3` et `NA` ailleurs ``` diff --git a/03_Fiches_thematiques/Fiche_donnees_spatiales.qmd b/03_Fiches_thematiques/Fiche_donnees_spatiales.qmd index fdcb2996..9eca1a5b 100644 --- a/03_Fiches_thematiques/Fiche_donnees_spatiales.qmd +++ b/03_Fiches_thematiques/Fiche_donnees_spatiales.qmd @@ -256,7 +256,7 @@ Contrairement à ce qui pourrait être pensé, la géographie et le COG sont ré Le *package* [COGugaison](https://antuki.github.io/COGugaison/) fournit un ensemble d'outils répondant à ce besoin. Il permet de réaliser de nombreuses modifications utiles au chargé d'études (remplacement des codes arrondissements dans Paris, Lyon, Marseille, identification du millésime géographique des données, visualisation des changements de géographie, transformation d'un millésime à un autre pour les communes, les zonages standards d'études de l'Insee, et les zonages à façon, etc.) sans avoir à mobiliser le COG. ::: {.callout-note} -Ce package n'étant pas disponible sur le CRAN, dans un environnement connecté à internet, il est nécessaire de l'installer depuis `Github`: +Ce package n'étant pas disponible sur le CRAN, dans un environnement connecté à internet, il est nécessaire de l'installer depuis `GitHub`: ```{r, eval=FALSE} remotes::install_github("antuki/COGugaison") diff --git a/03_Fiches_thematiques/Fiche_git_utilisation.qmd b/03_Fiches_thematiques/Fiche_git_utilisation.qmd index 0c682a37..47c3bcf5 100644 --- a/03_Fiches_thematiques/Fiche_git_utilisation.qmd +++ b/03_Fiches_thematiques/Fiche_git_utilisation.qmd @@ -21,13 +21,13 @@ Vous pouvez utiliser `Git` _via_ la ligne de commande si vous le souhaitez. En r **Recommandations sur l'initialisation de `Git`** * Il est recommandé d'utiliser `Git` dès le lancement de votre projet, même s'il est possible de commencer à suivre un projet déjà existant avec `Git`. -* Il est recommandé de commencer par créer un dépôt distant sur une forge (`Gitlab`, `Github`...), puis de `r with_def("cloner")` ce dépôt pour travailler sur votre poste local. +* Il est recommandé de commencer par créer un dépôt distant sur une forge (`Gitlab`, `GitHub`...), puis de `r with_def("cloner")` ce dépôt pour travailler sur votre poste local. * Il est recommandé de renseigner immédiatement le fichier `.gitignore` afin d'exclure certains fichiers du suivi des modifications (notamment les fichiers de données). **Recommandations sur l'usage des branches** * Utiliser RStudio pour créer une branche ou naviguer entre les `r with_def("branches")` ; -* Utiliser les interfaces `Github` ou `Gitlab` pour fusionner deux `r with_def("branches")`. +* Utiliser les interfaces `GitHub` ou `Gitlab` pour fusionner deux `r with_def("branches")`. Sur ce point, vous pouvez consulter la formation [Travail collaboratif avec R](https://linogaliana.gitlab.io/collaboratif/git.html). ::: @@ -102,7 +102,7 @@ avec vos collègues ou stocker vos codes personnels. Deux points sont importants La marche à suivre pour créer un dépôt distant est -très similaire dans `Gitlab` et dans `Github`. Les seules différences entre les deux plateformes portent sur la dénomination (un dépôt s'appelle `r with_def('repository')` sur `Github` et `project` sur `Gitlab`) et sur l'endroit où il faut cliquer pour créer un dépôt : +très similaire dans `Gitlab` et dans `GitHub`. Les seules différences entre les deux plateformes portent sur la dénomination (un dépôt s'appelle `r with_def('repository')` sur `GitHub` et `project` sur `Gitlab`) et sur l'endroit où il faut cliquer pour créer un dépôt : * Sur `Gitlab`, il suffit de cliquer sur `New project` dans la partie supérieure de la fenêtre : @@ -110,7 +110,7 @@ très similaire dans `Gitlab` et dans `Github`. Les seules différences entre le utilitr::include_image("../pics/git/repo-create2.png", compression = FALSE) ``` -* Sur `Github`, il suffit de cliquer sur l'icône `+` en haut à droite (cadre rouge), puis sur `New repository` (flèche noire) : +* Sur `GitHub`, il suffit de cliquer sur l'icône `+` en haut à droite (cadre rouge), puis sur `New repository` (flèche noire) : ```{r, echo = FALSE, out.width = '75%'} utilitr::include_image("../pics/git/repo-create.png", compression = FALSE) @@ -126,13 +126,13 @@ Dans les deux cas, vous devez préciser quelques caractéristiques du dépôt : **La deuxième étape consiste à récupérer l'adresse du dépôt distant.** Cette adresse se termine toujours par `.git`. Par exemple, l'adresse du dépôt de la documentation `utilitR` est `https://github.com/InseeFrLab/utilitR.git`. -Pour récupérer cette adresse, vous devez d'abord vous rendre sur la page du projet sur la forge (comme `Gitlab` ou `Github`). Pour afficher l'adresse du dépôt, il faut ensuite cliquer sur un bouton déroulant à droite. Sur `Gitlab`, il s'agit du bouton `Clone` (bouton bleu) : +Pour récupérer cette adresse, vous devez d'abord vous rendre sur la page du projet sur la forge (comme `Gitlab` ou `GitHub`). Pour afficher l'adresse du dépôt, il faut ensuite cliquer sur un bouton déroulant à droite. Sur `Gitlab`, il s'agit du bouton `Clone` (bouton bleu) : ```{r, echo = FALSE, out.width = '100%'} utilitr::include_image("../pics/git/create_project_0b.png", compression = FALSE) ``` -Sur `Github`, il s'agit du bouton `Code` (bouton vert) : +Sur `GitHub`, il s'agit du bouton `Code` (bouton vert) : ```{r, echo = FALSE, out.width = '100%'} utilitr::include_image("../pics/git/create_project_0.png", compression = FALSE) @@ -473,7 +473,7 @@ Cette interface offre principalement deux fonctions : - **Naviguer parmi les branches** (cadre bleu) : le menu déroulant affiche d'abord la liste des branches disponibles dans votre dépôt local (`LOCAL BRANCHES`) puis la liste des branches existantes sur le dépôt distant (`REMOTE: ORIGIN`). Pour afficher le contenu d'une `r with_def("branche")`, il suffit de cliquer sur le nom de cette `r with_def("branche")`. L'instruction correspondante en ligne de commande est `git checkout ma-branche`, où `ma-branche` est le nom de la `r with_def("branche")` dont vous souhaitez afficher le contenu. ::: {.callout-note} -L'interface graphique de RStudio ne permet pas de réaliser toutes les opérations possibles sur les branches. En particulier, il n'est pas possible de fusionner des branches avec cette interface. Les interfaces des forges (telles que `Gitlab`, `Github`...) sont beaucoup plus adaptées pour mener ce type d'opération. Vous pouvez en apprendre davantage en consultant la [formation Travail collaboratif avec `R`](https://linogaliana.gitlab.io/collaboratif/). +L'interface graphique de RStudio ne permet pas de réaliser toutes les opérations possibles sur les branches. En particulier, il n'est pas possible de fusionner des branches avec cette interface. Les interfaces des forges (telles que `Gitlab`, `GitHub`...) sont beaucoup plus adaptées pour mener ce type d'opération. Vous pouvez en apprendre davantage en consultant la [formation Travail collaboratif avec `R`](https://linogaliana.gitlab.io/collaboratif/). ::: ## Utiliser le terminal {#terminal-git} @@ -503,4 +503,4 @@ Vous pouvez en apprendre davantage sur l'utilisation de la ligne de commande dan * [Travailler avec Git via RStudio et versionner son code (thinkr.fr)](https://thinkr.fr/travailler-avec-git-via-rstudio-et-versionner-son-code) * [*Happy Git with R*](https://happygitwithr.com/) * [Une présentation vidéo d'une utilisation `Git` pour débutants faite à l'Insee](https://www.youtube.com/watch?v=lyzWU43DJ9I) -* [Formation à l'utilisation de Git avec RStudio (SSM Agriculture)](https://ssm-agriculture.github.io/formation-git) \ No newline at end of file +* [Formation à l'utilisation de Git avec RStudio (SSM Agriculture)](https://ssm-agriculture.github.io/formation-git) diff --git a/03_Fiches_thematiques/Fiche_import_tableurs.qmd b/03_Fiches_thematiques/Fiche_import_tableurs.qmd index 16db3853..1b46973d 100644 --- a/03_Fiches_thematiques/Fiche_import_tableurs.qmd +++ b/03_Fiches_thematiques/Fiche_import_tableurs.qmd @@ -32,7 +32,7 @@ chemin_xls <- "C:/Users/mon_IDEP_Insee/Dossier_utilitR/mes_donnees/mes_donnees. chemin_xlsx <- "C:/Users/mon_IDEP_Insee/Dossier_utilitR/mes_donnees/mes_donnees.xlsx" ``` -```{r, eval=TRUE, echo = FALSE} +```{r, eval = TRUE, echo = FALSE} # Définir le chemin du fichier chemin_xls <- "./import_donnees_tabulees_tests/mes_donnees.xls" chemin_xlsx <- "./import_donnees_tabulees_tests/mes_donnees.xlsx" @@ -227,7 +227,7 @@ Le _package_ `readODS` propose deux fonctions d'importation de fichiers `ods` : chemin_ods <- "C:/Users/mon_IDEP_Insee/Dossier_utilitR/mes_donnees/mes_donnees.ods" ``` -```{r, eval=TRUE, echo = FALSE} +```{r, eval = TRUE, echo = FALSE} # Définir le chemin du fichier chemin_ods <- "./import_donnees_tabulees_tests/mes_donnees.ods" ``` diff --git a/03_Fiches_thematiques/Fiche_joindre_donnees.qmd b/03_Fiches_thematiques/Fiche_joindre_donnees.qmd index 6470da13..c6f883b7 100644 --- a/03_Fiches_thematiques/Fiche_joindre_donnees.qmd +++ b/03_Fiches_thematiques/Fiche_joindre_donnees.qmd @@ -226,7 +226,7 @@ INNER JOIN y ON x.var1 = y.var1 Par exemple, pour faire une jointure interne, on pourrait écrire `merge(x = filosofi_com_2016_dt, y = cog_com_2019_dt, by.x = "CODGEO", by.y = "com", all = FALSE)`. Avec la syntaxe alternative, on peut écrire : -```{r, eval=TRUE} +```{r, eval = TRUE} filosofi_com_2016_dt[cog_com_2019_dt, on = c("CODGEO" = "com"), nomatch=NULL] ``` @@ -234,7 +234,7 @@ L'argument `nomatch` sert à définir le comportement pour les valeurs des obser Pour effectuer une anti-jointure, il faut sélectionner les clés de `x` qui n'ont pas de contrepartie dans `y`, ce qui s'écrit de manière générale `x[!y]`. Dans notre exemple, cela donne : -```{r, eval=TRUE} +```{r, eval = TRUE} filosofi_com_2016_dt[!cog_com_2019_dt, on = c("CODGEO" = "com")] ``` @@ -266,14 +266,14 @@ Avant de procéder à une jointure, il est essentiel de **vérifier la qualité Une première approche consiste à rechercher les valeurs manquantes (`NA`) dans les variables de jointure. Le code suivant permet de calculer le nombre d'observations pour lesquelles l'identifiant est manquant : - ```{r, eval=TRUE} + ```{r, eval = TRUE} sum(is.na(filosofi_com_2016$CODGEO)) sum(is.na(cog_com_2019$com)) ``` On voit ici que les variables de jointure ne contiennent aucun `NA` dans les deux tables. Toutefois, les valeurs manquantes peuvent prendre des formes plus complexes que `NA` : `0`, `.`, `999`... c'est pourquoi il est important de procéder à une inspection visuelle des variables de jointure. Pour ce faire, vous pouvez utilisez la fonction `unique()`, qui permet d'afficher la liste des valeurs qui apparaissent dans une variable. - ```{r, eval=TRUE} + ```{r, eval = TRUE} unique(filosofi_com_2016$CODGEO) ``` @@ -281,7 +281,7 @@ Avant de procéder à une jointure, il est essentiel de **vérifier la qualité Si les variables de jointure contiennent un grand nombre de fois les mêmes valeurs, la jointure peut devenir très gourmande en ressources, voire irréalisable. Il est donc indispensable de repérer les doublons, et de les traiter si nécessaire. Les deux codes suivants calculent le nombre d'observations dans la table pour chaque valeur des variables de jointure, et affichent les premières lignes par nombre d'observations décroissant. Si la variable `nb_obs` est supérieure ou égale à 2, alors il y a des doublons. Le premier code est adapté si vous utilisez `tidyverse` pour manipuler des données, le second si vous utilisez `data.table`. - ```{r, eval=TRUE} + ```{r, eval = TRUE} # Approche dplyr/tidyverse doublons <- filosofi_com_2016_tbl %>% group_by(CODGEO) %>% @@ -300,7 +300,7 @@ Avant de procéder à une jointure, il est essentiel de **vérifier la qualité On voit ici qu'il n'y a aucun doublon sur les identifiants dans la table issue du répertoire Filosofi. En revanche, on constate qu'il y a un grand grand nombre de doublons sur les identifiants dans la table du code officiel géographique. Cette présence de doublons rend nécessaire une analyse de cette table avant de réaliser la jointure. - ```{r, eval=TRUE} + ```{r, eval = TRUE} # Approche dplyr/tidyverse doublons <- cog_com_2019_tbl %>% group_by(com) %>% @@ -323,7 +323,7 @@ Le fait que les variables de jointure contiennent des valeurs manquantes ou des - **Une jointure ne peut être réalisée avec `R` que si les variables de jointure sont de même type.** Il faut donc vérifier que c'est le cas. Les types de variables les plus fréquemment utilisées pour des jointures avec `R` sont `integer` (nombre entier), `character` (chaîne de caractères) et `factor` (catégorie). Vous pouvez utiliser la fonction `class` pour connaître le type d'une variable. Dans l'exemple suivant, on voit que les deux variables de jointure sont de type `character`. - ```{r, eval=TRUE} + ```{r, eval = TRUE} # Type de la variable de jointure dans la table Filosofi class(filosofi_com_2016$CODGEO) # Type de la variable de jointure dans le COG 2019 @@ -335,7 +335,7 @@ Le fait que les variables de jointure contiennent des valeurs manquantes ou des Le premier code affiche le nombre d'identifiants distincts dans chaque table, et le nombre d'identifiants communs aux deux tables. On voit que tous les identifiants de la table issue de Filosofi figurent dans le COG 2019, mais que l'inverse n'est pas vrai. - ```{r, eval=TRUE} + ```{r, eval = TRUE} # Nombre d'identifiants distincts dans la table Filosofi length(unique(filosofi_com_2016$CODGEO)) # Nombre d'identifiants distincts dans le COG 2019 @@ -346,7 +346,7 @@ Le fait que les variables de jointure contiennent des valeurs manquantes ou des Le second code donne la liste des identifiants de la table du COG 2019 qui ne figurent pas parmi les identifiants de la table issue de Filosofi. - ```{r, eval=TRUE} + ```{r, eval = TRUE} unique(cog_com_2019$com)[!(unique(cog_com_2019$com) %in% unique(filosofi_com_2016$CODGEO))] ``` @@ -371,7 +371,7 @@ Après une jointure, il est essentiel de **vérifier que la jointure a bien prod Vous pouvez par exemple utiliser la fonction `is.na()` qui permet de repérer les observations manquantes dans les variables provenant de la table de droite. S'il y a des valeurs manquantes, cela peut indiquer que cette variable contient des valeurs manquantes dans la table de droite, ou que certaines observations de la table de gauche n'ont pas de correspondances dans la table de droite. Dans l'exemple qui suit, on voit que le département est manquant pour plusieurs centaines d'observations de la table jointe. - ```{r, eval=TRUE} + ```{r, eval = TRUE} table_jointe_tbl %>% filter(is.na(dep)) ``` diff --git a/03_Fiches_thematiques/Fiche_targets.qmd b/03_Fiches_thematiques/Fiche_targets.qmd index 5d51aab7..5127dc0a 100644 --- a/03_Fiches_thematiques/Fiche_targets.qmd +++ b/03_Fiches_thematiques/Fiche_targets.qmd @@ -5,7 +5,7 @@ knitr::opts_knit$set(root.dir = '..') ``` -```{r entree_fiche_targets, message=FALSE, warning=FALSE, echo=FALSE, cache=FALSE, eval=TRUE} +```{r entree_fiche_targets, message=FALSE, warning=FALSE, echo=FALSE, cache=FALSE, eval = TRUE} library(targets) ``` @@ -60,7 +60,7 @@ _pipelines_ de données en `R` et en `Python`. Les premiers éléments du débat sont disponibles sur [l'issue #388](https://github.com/InseeFrLab/utilitR/issues/388) -dans le dépôt `Github` d'`utilitR`. +dans le dépôt `GitHub` d'`utilitR`. ::: diff --git a/03_Fiches_thematiques/Fiche_tidyverse.qmd b/03_Fiches_thematiques/Fiche_tidyverse.qmd index 163676d0..03a0619d 100644 --- a/03_Fiches_thematiques/Fiche_tidyverse.qmd +++ b/03_Fiches_thematiques/Fiche_tidyverse.qmd @@ -662,7 +662,7 @@ La fonction `pivot_wider` permet de restructurer des données en transformant de Par ailleurs, l'option `names_prefix` permet de définir le préfixe du nom des nouvelles colonnes, ce qui est utile pour avoir des noms explicites. -```{r, eval=TRUE, message = FALSE} +```{r, eval = TRUE, message = FALSE} bpe_ens_2018_tbl %>% group_by(REG, TYPEQU) %>% summarise(NB_EQUIP_TOT = sum(NB_EQUIP)) %>% @@ -727,7 +727,7 @@ L'évaluation, standard ou non-standard, repose donc sur l'idée que `R` doit sa Pour réussir à créer des fonctions facilement compatibles avec le `tidyverse`, il faut faire appel à un opérateur spécifique, appelé *curly-curly* ou *doublestache* : `{{ }}`. Il s'agit de l'équivalent `tidyverse` de la fonction `get` présentée dans le chapitre [Manipuler ses données avec data.table](#datatable). Son utilisation est particulièrement simple, car il suffit d'entourer la variable par ces accolades. -```{r,eval=TRUE} +```{r,eval = TRUE} selectionner_colonne <- function(donnees,colonne) { retour <- donnees %>% select({{colonne}}) @@ -755,7 +755,7 @@ Il peut arriver que vous trouviez sur internet une page recommandant l'usage de Lorsqu'on souhaite définir une nouvelle colonne dans le tidyverse, une légère modification est nécessaire, avec l'utilisation de l'opérateur `:=`, comme dans l'exemple suivant. -```{r,eval=TRUE} +```{r,eval = TRUE} selectionner_et_renommer <- function(donnees,colonne, nouveau_nom = "nouveau_nom") { retour <- donnees %>% select({{colonne}}) %>% diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ee8ab37a..4a281da0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,12 +5,12 @@ Il est possible de contribuer au projet `utilitR` de différentes manières, détaillées dans ce document. Les contributions peuvent prendre différentes formes, d'un avis argumenté suite à une relecture à des propositions de modification en passant par des propositions d'intégrations de nouveaux éléments dans le livre ou le site. **Il n'est pas nécessaire d'être un expert en `R` pour contribuer au projet `utilitR`.** En revanche, il est nécessaire de s'inscrire dans le fonctionnement -des contributeurs actuels, fonctionnement qui est orchestré autour de `Github` et de ses différents outils. +des contributeurs actuels, fonctionnement qui est orchestré autour de `GitHub` et de ses différents outils. Il est possible d'en acquérir très rapidement les bases à partir de ce document présentant le [Travail collaboratif avec `R`](https://linogaliana.gitlab.io/collaboratif/git.html#des-bases-de-git), ou à partir d'échanges avec les contributeurs actuels. Un environnement prêt à l'emploi pour l'exécution des scripts est disponible sur le `SSPCloud`. En cliquant sur le lien suivant, un service `RStudio` avec l'ensemble des dépendances nécessaires pour utiliser la documentation est disponible: [![SSPcloud](https://img.shields.io/badge/SSPcloud-Tester%20via%20SSP--cloud-informational?logo=R)](https://datalab.sspcloud.fr/launcher/ide/rstudio?autoLaunch=false&init.personalInit=%C2%ABhttps%3A%2F%2Fgithub.com%2FInseeFrLab%2FutilitR%2Fblob%2Fmaster%2Finit_utilitr.sh%C2%BB&service.image.custom.enabled=true&service.image.custom.version=%C2%ABinseefrlab%2Futilitr%3Alatest%C2%BB) -Pour les relecteurs quelques notions de l'environnement `Github` suffisent +Pour les relecteurs quelques notions de l'environnement `GitHub` suffisent (ou peuvent s'acquérir facilement) pour apporter sa pierre à l'édifice. Les mainteneurs et développeurs du projet `utilitR` sont en effet disponibles @@ -23,7 +23,7 @@ Le document apporte une réponse aux questions suivantes: - [:arrow_down: Comment proposer des modifications d'une fiche?](#two-comment-proposer-des-modifications-dune-fiche) - [:arrow_down: Comment participer aux discussions collectives?](#three-comment-participer-aux-discussions-collectives) - [:arrow_down: Comment effectuer la relecture d'une fiche?](#four-comment-effectuer-la-relecture-dune-fiche) - - Comment suggérer des remarques sur une fiche via Github? + - Comment suggérer des remarques sur une fiche via GitHub? - Comment ouvrir une issue si la fiche pose un réel problème? - [:arrow_down: Comment ajouter en tant que contributeur une nouvelle fiche?](#five-comment-ajouter-une-nouvelle-fiche-à-la-documentation) - Comment faire un `fork` du dépôt `utilitR`? @@ -43,13 +43,13 @@ Pour effectuer exclusivement une relecture, vous pouvez vous rendre directement [:arrow_up: Retour à l'introduction](#one-introduction) -Pré-requis: avoir un compte Github. +Pré-requis: avoir un compte GitHub. Pour ce type de modifications, il est demandé d'utiliser directement -l'outil de suggestions de changements de `Github`. +l'outil de suggestions de changements de `GitHub`. Le livre déployé sur https://book.utilitr.org comprend un bouton `Edit` qui permet de proposer, automatiquement, des modifications via l'interface de -`Github`. +`GitHub`. Dans le menu du document, il faut d'abord se placer dans la fiche à relire et ensuite cliquer sur le bouton `Edit`, en haut à gauche : @@ -57,7 +57,7 @@ relire et ensuite cliquer sur le bouton `Edit`, en haut à gauche : ![](../pics/contributing/edit_bs4.png) Un lien s'ouvre automatiquement sur la fiche `.Rmd` et permet d'éditer le -contenu depuis `Github`. Cette fonctionnalité est utilisable même +contenu depuis `GitHub`. Cette fonctionnalité est utilisable même lorsque vous n'avez pas les droits en écriture sur le dépôt (droits attachés au statut de *mainteneur* sur le projet), grâce à la notion de [*fork*](https://github.com/InseeFrLab/utilitr-bonnes-pratiques/edit/master/CONTRIBUTING.md#one-forker-le-d%C3%A9p%C3%B4t-utilitr). @@ -68,7 +68,7 @@ de visualiser et de proposer des modifications du fichier source. ![](../pics/contributing/edit2.png) -La documentation officielle de Github sur cette manière de procéder est +La documentation officielle de GitHub sur cette manière de procéder est disponible [ici](https://docs.github.com/en/free-pro-team@latest/github/managing-files-in-a-repository/editing-files-in-another-users-repository). @@ -117,7 +117,7 @@ en cliquant sur l'onglet `Files changed`: L'équipe du projet `utilitR` dispose d'un espace de discussion collective sur les problèmes techniques et les développements futurs du projet. -Cet espace de discussion est stocké sur le dépôt `Github` du projet et est +Cet espace de discussion est stocké sur le dépôt `GitHub` du projet et est structuré sous forme d'_issues_. Une *issue* est un fil de discussion permettant aux contributeurs du projet (mais aussi aux personnes extérieures) d'échanger sur un sujet précis (défini par le titre de l'*issue*). Vous @@ -154,20 +154,20 @@ son organisation globale. Il est recommandé de lire la partie [:arrow_up: Comment proposer des modifications d'une fiche?](#two-comment-proposer-des-modifications-dune-fiche) -avant de proposer des commentaires sur une fiche via Github. +avant de proposer des commentaires sur une fiche via GitHub. ### Où faire des retours sur une fiche ? Le lieu idéal de retour de la part d'un relecteur ou d'une relectrice dépend du type de modification envisagée : * Proposer des corrections mineures (faute d'orthographes, formulations peu claires) : ce travail de modification est décrit dans [:arrow_up: Comment proposer des modifications d'une fiche?](#two-comment-proposer-des-modifications-dune-fiche). Les suggestions de modification sont dès lors associées à une `pull request` pour laquelle il convient d'adopter la convention proposée de nommer la branche `typo-XXX`. Lorsque la `pull request` est ouverte, il est possible de renseigner, dans la description de celle-ci, des commentaires génériques. Les commentaires relatifs à une ligne peuvent être faits sous forme de commentaire en cliquant sur l'onglet `Files changed` puis, sur la fiche en question, en ouvrant un commentaire en cliquant sur le signe `+` dans la marge ; -* Faire des commentaires sans suggestion de modifications (exemple: je ne parviens pas à reproduire cet exemple): ce travail de modification est décrit dans __Comment faire des commentaires sur une fiche via Github?__; +* Faire des commentaires sans suggestion de modifications (exemple: je ne parviens pas à reproduire cet exemple): ce travail de modification est décrit dans __Comment faire des commentaires sur une fiche via GitHub?__; * Des signalements de problèmes: si le relecteur pense que l'organisation d'ensemble ou le déroulement de la fiche soulève une difficulté sérieuse, ou que des points importants n'ont pas été abordés, il est invité à le signaler en suivant la procédure décrite dans la partie __Comment ouvrir une _issue_ si la fiche soulève un problème?__. -### Comment faire des commentaires sur une fiche via Github? +### Comment faire des commentaires sur une fiche via GitHub? -La démarche est un peu fastidieuse mais est possible directement depuis `Github`. +La démarche est un peu fastidieuse mais est possible directement depuis `GitHub`. Dans le menu du site web book.utilitr.org, il faut d'abord se placer dans la fiche à relire et ensuite cliquer sur le bouton `View source`, dans le menu à droite. @@ -210,7 +210,7 @@ majorité des contributeurs du projet. ### Comment proposer et élaborer une nouvelle fiche? La première étape consiste à __ouvrir une *issue*__ dans le -dépôt `Github`. L'_issue_ doit avoir: +dépôt `GitHub`. L'_issue_ doit avoir: - un titre explicite indiquant sur quel sujet vous voulez proposer une fiche (toutes suggestions bienvenues); - un contenu détaillant l'objet de la fiche et les grandes lignes de son contenu. @@ -224,7 +224,7 @@ de la documentation `utilitR`. ### Utiliser un environnement de travail entièrement configuré pour disposer de l'ensemble des librairies nécessaires à la génération de la documentation -Plutôt que d'utiliser un environnement en local dont la configuration peut différer de manière parfois significative avec l'environnement canonique qui sert à générer la documentation `utilitR` sous Github, il est recommandé d'utiliser le service RStudio du SSP Cloud. +Plutôt que d'utiliser un environnement en local dont la configuration peut différer de manière parfois significative avec l'environnement canonique qui sert à générer la documentation `utilitR` sous GitHub, il est recommandé d'utiliser le service RStudio du SSP Cloud. #### Lancer le service RStudio configuré @@ -236,9 +236,9 @@ Pour contribuer à `utilitR`, il est possible de créer un service RStudio enti Une autre solution consiste à lancer le service directement via [ce lien](https://datalab.sspcloud.fr/launcher/inseefrlab-helm-charts-datascience/rstudio?onyxia.friendlyName=%C2%AButilitr%C2%BB&service.image.version=%C2%ABinseefrlab%2Futilitr%3A0.8.0%C2%BB). -#### Configurer l'accès au dépôt distant Github : la méthode simple et sécurisée +#### Configurer l'accès au dépôt distant GitHub : la méthode simple et sécurisée -Pour accéder au dépôt distant Github (très généralement un _fork_ du dépôt officiel d'`utilitR`, comme expliqué plus bas), il faut que l'identifiant du compte corresponde à celui configuré dans l'image (dont on peut voir la valeur prise par défaut dans l'onglet Git de la configuration du service, à l'item _user.email_). Dans l'éventualité où cet identifiant ne correspondrait, il est possible de le reconfigurer une fois le service lancé en soumettant dans un terminal la commande suivante : +Pour accéder au dépôt distant GitHub (très généralement un _fork_ du dépôt officiel d'`utilitR`, comme expliqué plus bas), il faut que l'identifiant du compte corresponde à celui configuré dans l'image (dont on peut voir la valeur prise par défaut dans l'onglet Git de la configuration du service, à l'item _user.email_). Dans l'éventualité où cet identifiant ne correspondrait, il est possible de le reconfigurer une fois le service lancé en soumettant dans un terminal la commande suivante : ``` shell git config --global user.name "Prénom Nom" @@ -247,22 +247,22 @@ git config --global user.email "mon.adresse@mail.com" Il est également possible, pour les utilisateurs avancés, d'incorporer cette commande dans un script d'initialisation qui se lance au démarrage du service, en utilisant également la commande `runuser` de manière à lancer la commande git pour le _user_ `rstudio` et non en _root_ comme cela se fait par défaut. -Enfin, comme montré dans la capture d'écran ci-dessous, il est possible de configurer le mot de passe associé au compte Github de manière à ce qu'il soit conservé dans le cache du service pendant une durée limitée (dans l'exemple ci-dessous, une heure). Une fois le temps écoulé, l'utilisateur devra de nouveau entrer son mot de passe. +Enfin, comme montré dans la capture d'écran ci-dessous, il est possible de configurer le mot de passe associé au compte GitHub de manière à ce qu'il soit conservé dans le cache du service pendant une durée limitée (dans l'exemple ci-dessous, une heure). Une fois le temps écoulé, l'utilisateur devra de nouveau entrer son mot de passe. ![](../pics/contributing/configurer_git_cache.png) -#### Configurer l'accès au dépôt distant Github : la méthode à vos risques et périls +#### Configurer l'accès au dépôt distant GitHub : la méthode à vos risques et périls La méthode présentée ci-dessus a l'inconvénient qu'elle oblige l'utilisateur à insérer son mot de passe de façon régulière, et quoi qu'il en soit, pour chaque nouveau service RStudio créé sur le SSP Cloud. Il est ainsi possible d'insérer le mot de passe en question dans les variables d'environnement insérées au moment de la création du service, via l'interface `Mes secrets` du SSP Cloud. L'utilisateur intéressé pourra s'il le souhaite consulter la [vidéo de démonstration](https://github.com/InseeFrLab/onyxia-ui/releases/download/assets/Demo_My_Secrets.mp4) explicitant l'usage de ce service. -**ATTENTION : cette méthode comporte des risques car dans l'éventualité où un attaquant parvient à accéder à votre compte sur le SSP Cloud, il récupère des identifiants lui permettant d'accéder, de manière plus ou moins limitée selon la solution retenue, à votre compte Github et à interagir avec vos dépôts. À ce stade, ce n'est pas une méthode recommandée et si elle est utilisée, il convient d'utiliser un jeton d'accès aux droits limités. La fiche `utilitR` [Configurer Git](https://book.utilitr.org/03_fiches_thematiques/fiche_configurer_git) présente plus de détails sur la question des jetons d'accès à Github +**ATTENTION : cette méthode comporte des risques car dans l'éventualité où un attaquant parvient à accéder à votre compte sur le SSP Cloud, il récupère des identifiants lui permettant d'accéder, de manière plus ou moins limitée selon la solution retenue, à votre compte GitHub et à interagir avec vos dépôts. À ce stade, ce n'est pas une méthode recommandée et si elle est utilisée, il convient d'utiliser un jeton d'accès aux droits limités. La fiche `utilitR` [Configurer Git](https://book.utilitr.org/03_fiches_thematiques/fiche_configurer_git) présente plus de détails sur la question des jetons d'accès à GitHub -Ainsi, il est possible de récupérer, de manière systématique, son mot de passe ou, de manière un peu plus sécurisée, le token créé sous Github pour communiquer avec le dépôt. La configuration de l'accès de manière automatique peut se configurer en définissant les secrets ci-dessous dans un dossier `utilitr` : +Ainsi, il est possible de récupérer, de manière systématique, son mot de passe ou, de manière un peu plus sécurisée, le token créé sous GitHub pour communiquer avec le dépôt. La configuration de l'accès de manière automatique peut se configurer en définissant les secrets ci-dessous dans un dossier `utilitr` : * `PROTOCOL` : prend la valeur `https` -* `USERNAME` : l'identifiant du compte Github ou Gitlab avec lequel on souhaite interagir sur le dépôt +* `USERNAME` : l'identifiant du compte GitHub ou Gitlab avec lequel on souhaite interagir sur le dépôt * `TOKEN` : il s'agit du token mentionné précédemment -* `HOST` : pour un accès à Github, la valeur à insérer est `github.com` +* `HOST` : pour un accès à GitHub, la valeur à insérer est `github.com` * `FORK` : une variable optionnelle (qui peut donc être omise) qui, dans le cas où elle prend la valeur `TRUE`, permet de clôner le dépôt _fork_ d'`utilitR` de l'utilisateur. Si elle prend toute autre valeur non vide, elle permet de clôner le dépôt `utilitR`, sur lesquel l'utilisateur, s'il n'est pas identifié comme mainteneur, ne pourra pas réaliser de _push_. Dans le cas où la variable n'est pas spécifiée, ou mise à vide, aucun clônage de dépôt n'est réalisé. de la manière suivante : @@ -288,7 +288,7 @@ il faudra mettre à jour sa copie personnelle. C'est expliqué dans la [partie dédiée](#two-mettre-a-jour-son-fork). -Pour forker le dépôt, il est nécessaire d'avoir un compte `Github`. Une fois +Pour forker le dépôt, il est nécessaire d'avoir un compte `GitHub`. Une fois connecté sur ce compte, on fork le dépôt en cliquant à droite de la page: ![](../pics/contributing/fork1.png) @@ -308,7 +308,7 @@ La [documentation officielle](https://docs.github.com/en/free-pro-team@latest/gi manipulations à faire pour garder un `fork` à jour. Nous allons un peu développer cela. -Généralement, `Github` indique au propriétaire d'un `fork` que sa version +Généralement, `GitHub` indique au propriétaire d'un `fork` que sa version est en retard, ou au contraire en avance, par rapport à la version copiée. Pour mettre à jour son `fork`, le plus simple est d'utiliser une copie @@ -332,7 +332,7 @@ origin https://github.com/{GITHUB_USERNAME}/utilitR.git (push) ``` L'adresse porte normalement le nom `origin`. `{GITHUB_USERNAME}` est -votre nom d'utilisateur sur `Github`. +votre nom d'utilisateur sur `GitHub`. Ajouter l'adresse du dépôt officiel `utilitr` avec le nom `upstream` : @@ -416,7 +416,7 @@ prévisualiser en local le livre: > > Pour prévisualiser la version web de l'ouvrage: > -> * Option 1: utiliser l'onglet 'Build' dans Rstudio; +> * Option 1: utiliser l'onglet 'Build' dans RStudio; > * Option 2: taper dans la commande R: > ```r > bookdown::render_book("index.Rmd", output_dir = "_public", output_format = "utilitr::bs4_utilitr") @@ -458,12 +458,12 @@ git merge master S'il y a des conflits les régler. S'il n'y en a pas, la branche est prête à être proposée au dépôt officiel: la `pull request` peut-être ouverte. -Vérifier que le code est bien fonctionnel. `Github` indique par une +Vérifier que le code est bien fonctionnel. `GitHub` indique par une croix verte :heavy_check_mark: le succès de la compilation, c'est-à-dire la compilation de l'ensemble des fichiers `R Markdown` en un site HTML et un fichier PDF. -Si tout va bien, `Github` nous indique le succès +Si tout va bien, `GitHub` nous indique le succès ![](../pics/contributing/fork3.png) @@ -507,7 +507,7 @@ contributeur corrige sa proposition. * Les extensions des images doivent être en minuscules. Cela veut dire qu'il faut éviter l'extension `.PNG` que `Windows` génère parfois (notamment via l'outil capture). Si un ou plusieurs fichiers `.PNG` ont été générés, -`Github` vous enverra une informera d'une erreur de la manière suivante: +`GitHub` vous enverra une informera d'une erreur de la manière suivante: ![](../pics/contributing/PR1.png) @@ -516,7 +516,7 @@ et appuyer sur `CTRL`+ `Entrée` pour exécuter le code. Cela vous donnera la liste des fichiers incriminés. Avec la fonction `convert_extension("PNG")` ces fichiers seront renommés avec la bonne extension. Ne pas oublier de faire un commit et un push pour envoyer ces -modifications sur `Github`. +modifications sur `GitHub`. ### Bonnes pratiques de codage en `R` @@ -551,7 +551,7 @@ liste des `Imports`. ### Gérer les jeux de données utilisés dans les exemples * Il est recommandé d'utiliser autant que possible les jeux de données figurant dans le _package_ [`doremifasolData`](https://github.com/InseeFrLab/DoReMIFaSolData), qui contient exclusivement des données téléchargées sur le site de l'Insee. -* Il est évidemment possible d'ajouter un nouveau *dataset* à `doremifasolData` si vous pensez qu'aucun des _datasets_ du _package_ ne convient pour vos exemples; pour ce faire il suffit d'ouvrir une _issue_ dans le dépôt Gitlab d'`utilitR` ou dans le dépôt Github de `doremifasolData`, puis de discuter avec les contributeurs; +* Il est évidemment possible d'ajouter un nouveau *dataset* à `doremifasolData` si vous pensez qu'aucun des _datasets_ du _package_ ne convient pour vos exemples; pour ce faire il suffit d'ouvrir une _issue_ dans le dépôt Gitlab d'`utilitR` ou dans le dépôt GitHub de `doremifasolData`, puis de discuter avec les contributeurs; * Si vous souhaitez utiliser un jeu de données provenant d'un autre _package_, voici la marche à suivre: - demander systématiquement l'approbation des autres contributeurs du projet avant de le faire; - préciser systématiquement le *package* d'origine. Par exemple on écrit `data("World", package = "sf")` pour utiliser la table `World` du *package* `sf`. diff --git a/DocumentationR.Rproj b/DocumentationR.Rproj index 9eddaec0..62c18403 100644 --- a/DocumentationR.Rproj +++ b/DocumentationR.Rproj @@ -1,4 +1,5 @@ Version: 1.0 +ProjectId: ae1c2706-6a55-482b-8a91-796e1568c6a0 RestoreWorkspace: No SaveWorkspace: No diff --git a/Manifeste.md b/Manifeste.md index 238b2610..8fad82ac 100644 --- a/Manifeste.md +++ b/Manifeste.md @@ -26,7 +26,7 @@ Cette documentation ne prétend pas être exhaustive ou sans erreurs. **Elle doi **Le projet `utilitR` repose sur cinq principes: transparence, ouverture, bienveillance, exigence, reproductibilité.** -- Transparence: l'ensemble du projet est librement accessible sur le [dépôt Github](https://github.com/InseeFrLab/utilitR), sous licence libre; +- Transparence: l'ensemble du projet est librement accessible sur le [dépôt GitHub](https://github.com/InseeFrLab/utilitR), sous licence libre; - Ouverture: **tout agent de l'Insee qui le souhaite peut rejoindre le projet à tout moment**. Les modalités de contribution peuvent prendre différentes formes, détaillées dans le [guide des contributeurs](CONTRIBUTING.md); - Bienveillance: toutes les idées, initiatives et propositions sont les bienvenues, et les contributeurs veillent à se soutenir les uns les autres; - Exigence: les modifications de la documentation sont systématiquement soumises à une revue par les contributeurs du projet et ne sont acceptées que lorsqu'elles rencontrent une large approbation; diff --git a/README.md b/README.md index 1c9a82a7..73dde303 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ Cette documentation présente succinctement les outils les plus adaptés à ces La documentation présentée dans book.utilitr.org a pour ambition de répondre à deux questions générales: * Comment réaliser des tâches standards avec `R` (importation et manipulation de données, exploitation d'enquêtes, graphiques...)? -* Comment configurer `R` et `Rstudio` de manière à bénéficier de la richesse de cet écosystème ? +* Comment configurer `R` et `RStudio` de manière à bénéficier de la richesse de cet écosystème ? A ces deux sujets s'ajoute une documentation sur les bonnes pratiques de développement avec `R`. Ce guide des bonnes pratiques est disponible sur www.pratiques.utilitr.org @@ -59,7 +59,7 @@ Ce guide des bonnes pratiques est disponible sur www.pratiques.utilitr.org Deux points importants sont à noter: * **Cette documentation recommande les outils et les *packages* les plus adaptés au contexte d'utilisation de `R` à l'Insee**. Dans certains cas, ces recommandations peuvent ne pas être adaptées à d'autres contextes ou être amenées à changer lorsque le contexte interne évoluera. Une grande partie des recommandations sont néanmoins suffisamment générales pour ne pas être spécifiques au contexte Insee. Elles peuvent ainsi servir à de nombreux utilisateurs de données. -* **Cette documentation recommande d'utiliser `R` avec `Rstudio`**, qui apparaît comme la solution la plus simple et la plus complète pour un usage courant de `R`, et qui est par ailleurs le choix effectué par l'Insee et de nombreuses institutions. +* **Cette documentation recommande d'utiliser `R` avec `RStudio`**, qui apparaît comme la solution la plus simple et la plus complète pour un usage courant de `R`, et qui est par ailleurs le choix effectué par l'Insee et de nombreuses institutions.
diff --git a/index.qmd b/index.qmd index 8dcb9f15..3eda081c 100644 --- a/index.qmd +++ b/index.qmd @@ -15,7 +15,7 @@ Une documentation collaborative sur {{< fa brands r-project >}} ```{=html} -Star this website on Github +Star this website on GitHub ```
@@ -25,7 +25,7 @@ logiciel {{< fa brands r-project >}}, née à l'__Insee__, destinée à tout utilisateur intéressé par la manipulation de données __sans pré-requis de niveau__. -Le contenu d'`utilitR` est entièrement disponible en _open source_ sur `Github` {{< fa brands github >}}. +Le contenu d'`utilitR` est entièrement disponible en _open source_ sur `GitHub` {{< fa brands github >}}.
From fd7d7b1f5710382799abb9d7cffb6b24f7d343d6 Mon Sep 17 00:00:00 2001 From: Tanguy BARTHELEMY Date: Tue, 25 Feb 2025 13:47:12 +0100 Subject: [PATCH 2/2] remove pratiques.utilitr.org from utilitr documentation --- 03_Fiches_thematiques/Fiche_targets.qmd | 2 +- 03_Fiches_thematiques/Fiche_tidyverse.qmd | 2 +- README.md | 2 -- 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/03_Fiches_thematiques/Fiche_targets.qmd b/03_Fiches_thematiques/Fiche_targets.qmd index 5127dc0a..5efdd3d5 100644 --- a/03_Fiches_thematiques/Fiche_targets.qmd +++ b/03_Fiches_thematiques/Fiche_targets.qmd @@ -54,7 +54,7 @@ dans le code lui-même. ::: {.callout-note} -Le [guide des bonnes pratiques `utilitR`](https://www.pratiques.utilitr.org/) +Le [guide des bonnes pratiques `utilitR`](https://book.utilitr.org/02_Bonnes_pratiques/02-structure-code.html) devrait prochainement s'enrichir d'éléments concernant la gestion de _pipelines_ de données en `R` et en `Python`. diff --git a/03_Fiches_thematiques/Fiche_tidyverse.qmd b/03_Fiches_thematiques/Fiche_tidyverse.qmd index 03a0619d..7a1d727d 100644 --- a/03_Fiches_thematiques/Fiche_tidyverse.qmd +++ b/03_Fiches_thematiques/Fiche_tidyverse.qmd @@ -683,7 +683,7 @@ bpe_ens_2018_tbl %>% ## Programmer des fonctions avec le `tidyverse` -Lorsqu'une suite d'opérations est amenée à être effectuée plusieurs fois, une bonne pratique consiste à *factoriser* son code, notamment grâce à des fonctions définies par l'utilisateur. Le site internet [pratiques.utilitr.org](https://www.pratiques.utilitr.org/) présente notamment quelques recommandations de cet ordre. +Lorsqu'une suite d'opérations est amenée à être effectuée plusieurs fois, une bonne pratique consiste à *factoriser* son code, notamment grâce à des fonctions définies par l'utilisateur. La section sur [les bonnnes pratiques](https://book.utilitr.org/02_Bonnes_pratiques/01-qualite-code.html) présente notamment quelques recommandations de cet ordre. ### Présentation de la difficulté à fonctionnaliser diff --git a/README.md b/README.md index 73dde303..0e32d2fb 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,6 @@ Elle a vocation à être validée annuellement afin de produire un guide des bon Elle prend la forme suivante : * la documentation principale qui est déployée à l'adresse ; -* un guide des bonnes pratiques en `R` déployé à l'adresse Lorsqu'une version `PDF` sera mise à disposition, un lien direct de téléchargement sera disponible. Chaque fiche, disponible sur le site web, peut être imprimée @@ -52,7 +51,6 @@ La documentation présentée dans book.utilitr.org a pour ambition de répondre * Comment configurer `R` et `RStudio` de manière à bénéficier de la richesse de cet écosystème ? A ces deux sujets s'ajoute une documentation sur les bonnes pratiques de développement avec `R`. -Ce guide des bonnes pratiques est disponible sur www.pratiques.utilitr.org ### Remarques