Code source pour le projet utilitR, documentation collaborative R
faite par des agents de l'Insee et du Système Statistique Public.
Elle a vocation à être validée annuellement afin de produire un guide des bonnes pratiques et des fiches techniques.
Elle prend la forme suivante :
- la documentation principale qui est déployée à l'adresse https://www.book.utilitr.org/ ;
- un guide des bonnes pratiques en
Rdéployé à l'adresse https://www.pratiques.utilitr.org/
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
avec une mise en page agréable grâce à un bouton dédié sur le site web.
Les exemples sont construits sur des données ouvertes, disponibles sur www.insee.fr.
Le package doremifasolData facilite
l'import de ces données dans la documentation. Le modèle de document est
encapsulé dans un package R dédié: https://github.com/InseeFrLab/utilitr-template
L'ensemble des ressources du projet utilitR sont disponibles sur https://www.utilitr.org
Cette documentation s'adresse à tous utilisateur de R dans le cadre d'un usage courant d'analyse de données.
Elle est conçue pour aider les utilisateurs à 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 utilisateurs 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.
La documentation présentée dans www.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
RetRstudiode 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
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
RavecRstudio, qui apparaît comme la solution la plus simple et la plus complète pour un usage courant deR, et qui est par ailleurs le choix effectué par l'Insee et de nombreuses institutions.
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. Les objectifs et l'approche collaborative du projet utilitR sont détaillés dans ce document.
Toute personne qui le souhaite peut modifier ou compléter la documentation en fonction de ses connaissances et de ses expériences, et toutes les contributions sont les bienvenues: compléments, corrections d'erreur, améliorations, questions... Il n'y a aucun prérequis, et aucun niveau minimal en R n'est demandé. Le dépôt de la documentation est situé ici. Toute personne intéressée à contribuer au projet est invité à consulter le guide des contributeurs (CONTRIBUTING.md).
Le projet utilitR a pour objectif de favoriser la reproductibilité et
la pérennité des traitements statistiques avec R.
Ces principes s'appliquent également à la documentation produite: l'ensemble
des exemples sont construits à partir de données
disponibles sur le site www.insee.fr et les morceaux de code présents
sont faits pour être reproductibles. Pour rendre la documentation plus
reproductible, un certain nombre d'éléments de formattage ont été intégrés
dans un package R proposant des modèles de documents standardisés. Il
peut être installé de la manière suivante:
# install.packages("remotes")
remotes::install_github("https://github.com/InseeFrLab/utilitr-template")Les éléments présents dans la documentation visent à être cohérents avec
les recommandations émises par le comité de certification des packages R (COPS),
organe interne visant à prescrire ou proscrire certains packages dans le cadre
de la production statistique.
Plus d'éléments pour faire tourner les codes sont disponibles dans ce document