In InseeFrLab/utilitr-template: Templates for the utilitR Project

Comment utiliser la documentation utilitR {#presentation-utilitr}

Contenu de la documentation

Cette documentation vise à aider les agents à réaliser des traitements statistiques usuels avec R et à produire des sorties (graphiques, cartes, documents). Cette documentation présente succinctement les outils les plus adaptés à ces tâches, et oriente les agents vers les ressources documentaires pertinentes. Elle veille en outre à être cohérente avec les recommandations émises par le comité de certification des packages R (COPS). En revanche, elle n'aborde pas les outils les plus avancés, notamment ceux utilisés dans un cadre de développement logiciel.

Trois points importants sont à noter :

• Cette documentation recommande les outils et les packages les plus adaptés au contexte d'utilisation de R à l'Insee. Ces recommandations ne sont pas nécessairement adaptées à d'autres contextes, et pourront évoluer lorsque ce contexte évoluera.
• Cette documentation ne prétend pas être exhaustive ou sans erreurs. Elle doit être vue comme une mise en commun des connaissances sur R que les agents de la statistique publique ont accumulées dans le cadre de leurs activités.
• 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.

Structure de la documentation

La documentation utilitR est composée de fiches regroupées en deux grandes parties :

• La première partie explique comment utiliser R et RStudio et les outils associés (git, Gitlab) dans les environnements informatiques proposés à l'Insee (AUSv3 et SSP Cloud).
• La seconde partie est constituée de fiches thématiques expliquant comment réaliser des tâches standards avec R (importation et manipulation de données, exploitation d'enquêtes, réalisation de graphiques, rédaction de documents...).

Contenu des fiches

Chaque fiche porte sur une tâche précise, décrite dans le titre et éventuellement dans les premières lignes. Elle indique quels sont les packages adaptés pour réaliser la tâche en question, et en présente en détail les principales fonctions. Les fiches n'ont toutefois pas la prétention d'être exhaustives ; c'est pourquoi des références figurent à la fin de chaque fiche de façon à orienter le lecteur vers des ressources plus détaillées.

Par ailleurs, les fiches comportent trois types de paragraphes mis en évidence par une icône et une couleur, afin de faciliter la lecture et le repérage des informations importantes.

library(fontawesome)
library(magrittr)

texte_recommandation <- "Ce paragraphe présente succinctement les outils et les approches les plus adaptés à la tâche concernée. Chaque fiche ne comprend qu'un seul paragraphe de ce type, au début de la fiche."
texte_conseil        <- "Ce paragraphe détaille les bonnes pratiques à adopter."
texte_remarque       <- "Ce paragraphe donne des informations supplémentaires ou formule une mise en garde."
texte_specificite    <- "Ce paragraphe porte sur une spécificité de l'Insee qui a un impact sur l'usage de `R`."

symb <-
  c(fa("hand-point-right", fill = "rgba(220, 53, 69, 1)", height = "40px"),
    fa("lightbulb", fill = "rgba(255, 193, 7, 1)", height = "40px"),
    fa("info-circle", fill = "rgba(0, 123, 255, 1)", height = "40px"),
    fa("home", fill = "rgba(81, 81, 81, 1)", height = "40px"))

dt <- 
  as.data.frame(list(
    Nom = c("Recommandation", 
            "Conseil", 
            "Remarque",
            "Spécificité Insee"), 
    Symbole = symb,
    Signification = c(texte_recommandation, 
                      texte_conseil, 
                      texte_remarque,
                      texte_specificite)
  )
  )


output <- 
  dt %>% 
  knitr::kable(escape = F, position = "center", full_width = F, align="ccl") %>%
  kableExtra::column_spec(1, width = "3cm", bold = TRUE) %>%
  kableExtra::column_spec(2, width = "2cm") %>% 
  kableExtra::column_spec(3, width = "10cm") %>% 
  kableExtra::row_spec(0,bold=TRUE, align = "c")
output

Des exemples reproductibles

Même si certains lecteurs ont uniquement besoin de parcourir une fiche pour s'en imprégner, d'autres éprouveront le besoin d'exécuter des exemples de code pour se les approprier. C'est pourquoi la documentation utilitR propose un grand nombre d'exemples reproductibles. Cela signifie qu'en chargeant les packages indiqués dans chaque fiche, le lecteur pourra exécuter le code des exemples présentés et reproduire le même résultat.

Les exemples sont facilement repérables par leur mise en page. Voici un exemple :

resultat <- 1 + 1
resultat

Le résultat de l'exécution d'un exemple est également facile à repérer. Voici le résultat de l'exemple précédent (qui s'affichera dans la console) :

resultat <- 1 + 1
resultat

Le package doremifasolData

Afin de se rapprocher le plus possible des situations de travail rencontrées par les agents de l'Insee, la plupart des exemples de la documentation utilitR reposent sur des données produites par l'Insee. Ces données sont soit directement disponibles sur le site de l'Insee, soit construites à partir de données disponibles sur le site de l'Insee.

Ces jeux de données sont mis à disposition par l'intermédiaire d'un package nommé doremifasolData développé par les contributeurs du projet utilitR. La documentation détaillée de ce package est disponible sur GitHub.

Voici la liste des tables disponibles dans doremifasolData :

tables <- data(package = "doremifasolData")$result

output <- 
  knitr::kable(
  as.data.frame(list("Table" = tables[, "Item"], "Description" = tables[, "Title"])),
  format = "html",
  escape = F, position = "center", full_width = F, align="cl") %>%
  kableExtra::column_spec(1, width = "4cm") %>%
  kableExtra::column_spec(2, width = "13cm") %>% 
  kableExtra::row_spec(0, bold=TRUE, align = "c")
output

::: {.remarque}

Le package tire son nom de son "grand frère", le package doremifasol. Ce package a pour finalité de charger dans R des données disponibles sur le site de l'Insee, sans que l'utilisateur n'ait ni à naviguer sur ce site, ni à effectuer l'import des données. Tous les jeux de données présents dans doremifasolData ont été téléchargés avec doremifasol. :::

Comment installer le package doremifasolData

Le package doremifasolData n'est pas disponible sur le répertoire central des packages R (le CRAN). Voici comment installer le package :

Si vous utilisez R sur un autre ordinateur ou sur le SSP Cloud, il faut exécuter la commande suivante :

remotes::install_github("InseeFrLab/doremifasolData", ref = "main")

::: {.specificite}

Si vous utilisez R sur un poste Insee (y compris en télétravail) ou dans l'environnement de travail AUS, il faut exécuter la commande suivante :

install.packages("doremifasolData", 
                 repos = "https://nexus.insee.fr/repository/r-public")

:::

InseeFrLab/utilitr-template documentation built on Oct. 21, 2022, 11:42 p.m.