Dans un précédent billet, je considérai que trouver un bon nom pour un package R était important et faisait partie de l’ergonomie du logiciel. Dans ce billet, je vais appliquer ceci à la recherche d’un nom pour mon prochain package. Ce package a comme objectif de créer des scripts permettant l’import rigoureux de variables à partir d’un cahier de variable dans le cadre d’une consultation méthodologique. Expliqué comme ceci en une phrase, ça ne doit pas sembler très clair. Raison de plus pour que le nom aide à sa compréhension!

À quoi sert ce package ?

Pour trouver un nom adéquat, il faut d’abord être au clair avec l’objectif principal du package et tenter d’en définir les limites. Pour ma part, j’en arrive à cette phase qu’une fois le package bien avancé et déjà en partie documenté. Un peu comme lorsque l’on écrit un article et l’on choisit un titre à la fin, je crois qu’il faut choisir le nom du package que juste avant sa publication.

Dans le cas de mon package, il sert à créer des scripts R à partir de définition de variables. L’idée centrale est d’être très explicite dans la description des variables afin d’éviter des erreurs d’analyses par la suite. Par exemple une variable définissant l’évènement décès d’un patient est une variable catégorielle à deux modalités Vivant ou Décédé. Elle peut être codée de manière variée selon la base de données : parfois v et d, ou d et a (dead or alive) ce qui est relativement explicite, mais parfois 0 et 1, ou 1 et 2 ce qui l’est beaucoup moins. L’idée est de définir dans un cahier de variable les caractéristiques de cette variable. Elle serait dans ce cas :

  • Nom de la variable dans R : death
  • Étiquette de la variable : Statut vital
  • Description : Statut vital du patient au moment du suivi
  • Type : Catégorielle
  • Modalités : 0 = mort, 1 = vivant
  • Commentaire : les données manquantes (“NA”) existent lorsque le statut vital n’a pas pu être vérifié. Ces cas doivent être écartés de l’analyse

En ayant ceci, je n’ai pas de doute sur la manière d’utiliser la variable. Je ne risque pas de perdre des heures à me lancer dans une analyse de survie en croyant que 1 = mort et en arrivant à des conclusions me laissant imaginer que je vais pouvoir faire un Lancet. Je comprends également tout de suite comment je vais devoir traiter les données manquantes pour cette variable. Enfin, l’étiquette va me permettre de créer proprement mes légendes sur mes tableaux et graphiques.

Pour importer toutes ces informations dans R, pour une variable, ça irait assez vite.

death <- factor(death, levels = c(0, 1), labels = c(“mort”, “vivant”))

Cependant, une base de données contient rarement une seule variable. Dans ma pratique, elles en contiennent plutôt quelques dizaines (souvent plus de cinquante), avec des noms assez peu explicites. L’idée initiale est donc de remplir un cahier de variable avec la personne qui me remet la base de données. Ce cahier de variable est un simple fichier tabulé (.csv, .odt ou .xlsx) contenant les colonnes suivantes :

  • Nom de la variable dans R : C’est le nom que je vais définir à utiliser dans R. Il suit les bonnes pratiques, à savoir il est raisonnablement court, explicite et ne contient que des caractères autorisés.
  • Étiquette de la variable : C’est ce qui apparaitra dans les graphiques et tableaux du rapport final. Il est défini par la personne qui me consulte et correspond souvent au nom initial de ses variables dans sa base de données.
  • Description : Une courte description de la variable qui pourra apparaitre dans le rapport final, permettant de comprendre la variable, son contexte.
  • Type : Le type de variable, quantitative (numérique ou entier), catégorielle (non ordonnée ou ordonnée), date, chaine de caractère
  • Unité : utilisé pour construire les légendes. Pour les dates, donne le format de date (par exemple %d/%m/%Y pour 10/06/2014)
  • Modalités : Définition des couples de clef (ou level) avec un nom de modalité (ou label).
  • Commentaire : Un commentaire pouvant guider l’analyse. Ne sera pas repris dans le rapport.

À partir de ce cahier de variable, j’ai l’habitude de revoir variable par variable l’importation dans R, afin de m’assurer que tout soit rigoureusement importé afin de gagner du temps par la suite. Je recode les catégorielles, fait toujours un petit summary pour chaque variable, ainsi qu’une petite représentation graphique pour voir les distributions. Souvent, je remets un fichier généré à partir du .Rmd sous la forme d’un HTML à la personne qui me consulte afin qu’il que le processus d’importation soit traçable et reproductible.

J’ai donc créé de petits scripts permettant de générer rapidement des squelettes de scripts en fonction du type de variable. J’ai étendu ces scripts sous forme de package.

Ceci donne actuellement pour une variable :

library(easydm)

# Créer une variable
vardeath <- Descvar(
       rname = "death", 
       varlabel = "État vital", 
       type = "factor", 
       comment = "Statut vital du patient au moment du suivi", 
       levels = 0:1, 
       names = c("mort", "vivant")
  )
vardeath
# rname = death 
# varlabel = État vital 
# type = factor 
# comment = Statut vital du patient au moment du suivi 
# levels = 0, 1 
# names = mort, vivant 
# Créer une sortie 
create_dm(vardeath, template = import_template())

# #- Start of the script in R -#
# ######### Datamanagement script ##########
# # import data
# 
# rep_rawdata <- read.csv( "rep_path_to_database", stringsAsFactors =F)
# 
# # Change headers
# variables_df <- read.csv( "rep_path_to_database")
# names(rep_rawdata) <- variables_df$var_name
# 
# # Make a copy
# rep_cleandata <- rep_rawdata
# 
# ####### Clean the variable death #####
# 
# # explore the raw data
# head(raw_data$death)
# str(raw_data$death)
# 
# # Set it as a factor
# clean_data$death <- factor(
#   x = raw_data$death,
#   levels = c('0', '1'),
#   labels = c('mort', 'vivant'),
#   ordered = FALSE
# )
# # set the label
# attr(clean_data$death, "label") <- "État vital"
# 
# head(clean_data$death)
# str(clean_data$death)
# summary(clean_data$death)
# 
# # number of NA
# 
# sum(is.na(clean_data$death))
# # Make a plot
# plot(clean_data$death)
# ##### watch all ######
# 
# str(rep_cleandata)
# 
# ####### Save the cleaned data ######
# save(rep_cleandata, file="produced_data/clean_data.Rdata"
#      #- End of the script in R -#

Et l’on peut faire la même chose à partir d’un cahier de variable complet que l’on importe avec la fonction import_vardef().

Quel nom ?

Pour l’instant mon package se nomme easydm pour easy datamanagement. Mais comme me l’a fait remarquer un de mes enseignants, ceci n’est pas du datamagement. Il s’agit plus de créer des squelettes de scripts à partir de définition de variable. Voici mes quelques recherches de noms :

  • importr
  • variable to script
    • vartoscript
    • vtos
    • vartos
    • vartors
    • vardeftors
  • description to script
    • desctor
    • descscript
  • description to program
  • program template
  • fast import script skeleton
  • importskeleton

Au final, je retiens vartors qui peut se titrer Variable definition To R Script skeleton. Il suit les règles de nommage d’un package et n’est pas encore utilisé sur le CRAN. De plus, c’est un mot-clé qui ne semble pas encore beaucoup utilisé lorsque l’on cherche sur Google donc il sera facilement trouvable.