2 Comment utiliser la documentation `utilitR`

2.1 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. 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.

2.2 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…).

2.3 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 quatre 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.

Nom	Symbole	Signification
Recommandation	<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:30px;width:30px;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:rgba(220, 53, 69, 1);overflow:visible;position:relative;"><path d="M448 128l-177.6 0c1 5.2 1.6 10.5 1.6 16l0 16 32 0 144 0c8.8 0 16-7.2 16-16s-7.2-16-16-16zM224 144c0-17.7-14.3-32-32-32c0 0 0 0 0 0l-24 0c-66.3 0-120 53.7-120 120l0 48c0 52.5 33.7 97.1 80.7 113.4c-.5-3.1-.7-6.2-.7-9.4c0-20 9.2-37.9 23.6-49.7c-4.9-9-7.6-19.4-7.6-30.3c0-15.1 5.3-29 14-40c-8.8-11-14-24.9-14-40l0-40c0-13.3 10.7-24 24-24s24 10.7 24 24l0 40c0 8.8 7.2 16 16 16s16-7.2 16-16l0-40 0-40zM192 64s0 0 0 0c18 0 34.6 6 48 16l208 0c35.3 0 64 28.7 64 64s-28.7 64-64 64l-82 0c1.3 5.1 2 10.5 2 16c0 25.3-14.7 47.2-36 57.6c2.6 7 4 14.5 4 22.4c0 20-9.2 37.9-23.6 49.7c4.9 9 7.6 19.4 7.6 30.3c0 35.3-28.7 64-64 64l-64 0-24 0C75.2 448 0 372.8 0 280l0-48C0 139.2 75.2 64 168 64l24 0zm64 336c8.8 0 16-7.2 16-16s-7.2-16-16-16l-48 0-16 0c-8.8 0-16 7.2-16 16s7.2 16 16 16l64 0zm16-176c0 5.5-.7 10.9-2 16l2 0 32 0c8.8 0 16-7.2 16-16s-7.2-16-16-16l-32 0 0 16zm-24 64l-40 0c-8.8 0-16 7.2-16 16s7.2 16 16 16l48 0 16 0c8.8 0 16-7.2 16-16s-7.2-16-16-16l-24 0z"/></svg>	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.
Conseil	<svg aria-hidden="true" role="img" viewBox="0 0 384 512" style="height:30px;width:22.5px;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:rgba(255, 193, 7, 1);overflow:visible;position:relative;"><path d="M297.2 248.9C311.6 228.3 320 203.2 320 176c0-70.7-57.3-128-128-128S64 105.3 64 176c0 27.2 8.4 52.3 22.8 72.9c3.7 5.3 8.1 11.3 12.8 17.7l0 0c12.9 17.7 28.3 38.9 39.8 59.8c10.4 19 15.7 38.8 18.3 57.5H109c-2.2-12-5.9-23.7-11.8-34.5c-9.9-18-22.2-34.9-34.5-51.8l0 0 0 0c-5.2-7.1-10.4-14.2-15.4-21.4C27.6 247.9 16 213.3 16 176C16 78.8 94.8 0 192 0s176 78.8 176 176c0 37.3-11.6 71.9-31.4 100.3c-5 7.2-10.2 14.3-15.4 21.4l0 0 0 0c-12.3 16.8-24.6 33.7-34.5 51.8c-5.9 10.8-9.6 22.5-11.8 34.5H226.4c2.6-18.7 7.9-38.6 18.3-57.5c11.5-20.9 26.9-42.1 39.8-59.8l0 0 0 0 0 0c4.7-6.4 9-12.4 12.7-17.7zM192 128c-26.5 0-48 21.5-48 48c0 8.8-7.2 16-16 16s-16-7.2-16-16c0-44.2 35.8-80 80-80c8.8 0 16 7.2 16 16s-7.2 16-16 16zm0 384c-44.2 0-80-35.8-80-80V416H272v16c0 44.2-35.8 80-80 80z"/></svg>	Ce paragraphe détaille les bonnes pratiques à adopter.
Remarque	<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:30px;width:30px;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:rgba(0, 123, 255, 1);overflow:visible;position:relative;"><path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM216 336h24V272H216c-13.3 0-24-10.7-24-24s10.7-24 24-24h48c13.3 0 24 10.7 24 24v88h8c13.3 0 24 10.7 24 24s-10.7 24-24 24H216c-13.3 0-24-10.7-24-24s10.7-24 24-24zm40-208a32 32 0 1 1 0 64 32 32 0 1 1 0-64z"/></svg>	Ce paragraphe donne des informations supplémentaires ou formule une mise en garde.
Spécificité Insee	<svg aria-hidden="true" role="img" viewBox="0 0 576 512" style="height:30px;width:33.75px;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:rgba(81, 81, 81, 1);overflow:visible;position:relative;"><path d="M575.8 255.5c0 18-15 32.1-32 32.1h-32l.7 160.2c0 2.7-.2 5.4-.5 8.1V472c0 22.1-17.9 40-40 40H456c-1.1 0-2.2 0-3.3-.1c-1.4 .1-2.8 .1-4.2 .1H416 392c-22.1 0-40-17.9-40-40V448 384c0-17.7-14.3-32-32-32H256c-17.7 0-32 14.3-32 32v64 24c0 22.1-17.9 40-40 40H160 128.1c-1.5 0-3-.1-4.5-.2c-1.2 .1-2.4 .2-3.6 .2H104c-22.1 0-40-17.9-40-40V360c0-.9 0-1.9 .1-2.8V287.6H32c-18 0-32-14-32-32.1c0-9 3-17 10-24L266.4 8c7-7 15-8 22-8s15 2 21 7L564.8 231.5c8 7 12 15 11 24z"/></svg>	Ce paragraphe porte sur une spécificité de l'Insee qui a un impact sur l'usage de `R`.

2.4 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) :

[1] 2

Tip

Pour reproduire les exemples d’une fiche, il est important de les exécuter tous et dans l’ordre dans lequel ils apparaissent dans la fiche. Si vous ne le faites pas, vous rencontrerez très probablement des erreurs.

Voici un exemple : la fiche sur la manipulation de données textuelles commence par charger le package stringr avec la commande library(stringr). Si vous n’exécutez pas cette instruction, et que vous essayez d’exécuter le premier exemple de la fiche (str_to_lower("Hello world")), R renverra une erreur, car le package contenant la fonction str_to_lower() n’aura pas été chargé.

2.5 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 :

Table	Description
bpe_ens_2018	Base Permanente des Équipements 2018
cog_com_2019	Code Officiel Géographique 2019
data_iris_paris_2017	Données sociales sur les IRIS de Paris 2017
filosofi_com_2016	Données sur les revenus et la pauvreté en 2016, niveau communal
filosofi_epci_2016	Données sur les revenus et la pauvreté en 2016, niveau EPCI

Note

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.

2.5.1 Comment installer le package `doremifasolData`

Le package doremifasolData n’est pas disponible sur le répertoire central des packages R (le CRAN). Pour installer installer le package, il est nécessaire d’exécuter les deux commandes suivantes :

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

Spécificité Insee

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",
  type = "source"
)