library(vizsurvey)

Introduction

Cette vignette présente la préparation des données nécessaire pour utiliser {vizsurvey} via runVizsurvey_from_folder. L’objectif est un usage régulier et structuré de l’outil au sein d’une équipe gérant plusieurs enquêtes.

Dans ce contexte, lancer l’interface manuellement pour chaque base devient vite fastidieux. Surtout, le calcul des écarts — en particulier lorsqu’ils sont déclinés par vague et par filtre — est très long. {vizsurvey} sépare donc les deux temps : une préparation (prepa_survey()), qui calcule toutes les statistiques et enregistre le résultat dans un fichier global.rds, et l’ouverture de l’interface, qui ne fait que lire ce fichier et est donc immédiate.

La préparation peut être relancée à chaque mise à jour des données, par exemple par une tâche planifiée quotidienne : toutes les personnes qui ouvrent l’interface analysent alors les mêmes fichiers à jour.

Les données d’exemple

Pour tester la chaîne complète sans données réelles, la fonction create_eusilc_sim() génère un jeu d’exemple à partir de l’extrait SILC du package {laeken} : un numéro d’enquêteur·rice fictif (nr_itw), une vague fictive (db010), et des erreurs volontaires à retrouver dans l’interface (voir la vignette de prise en main).

On va créer cette jeu de données, et le placer dans un répertoire fictif “data/EUSILC”.

df <- create_eusilc_sim()

dir.create("data/EUSILC", recursive = TRUE)
readr::write_csv(df, "data/EUSILC/eusilc_sim.csv")

Configurer une enquête

Votre fichier de données doit être lisible par data.table::fread, qui reconnaît automatiquement les formats standards (CSV, TSV, etc.). Placez-le dans un dossier dédié, où il sera le seul fichier de ce format.

Si votre enquête est constituée de plusieurs fichiers (par exemple un fichier par année ou par pays), vous pouvez les placer dans le même dossier : ils sont alors empilés à la lecture. Tous doivent cependant contenir les mêmes variables et être au même format, et aucun autre fichier de ce type ne doit être présent dans le dossier.

Le fichier de configuration

Chaque dossier de données doit contenir un fichier de configuration nommé config.txt. Ce fichier indique à {vizsurvey} comment interpréter et structurer vos données. En voici la forme générale :

name_survey = EUSILC-SIM

vars_discretes =
vars_continuous =
vars_ignore =

prefix_discretes =
prefix_continuous =
prefix_ignore =

var_wave = DB010
var_filter = DB040
var_intvwr = NR_ITW
var_intv =

var_date =
var_info_geo =

Les clés se répartissent en trois groupes. D’abord les rôles des variables. Toutes ces variables sont facultatives, et activent les différents onglets de {vizsurvey} :

Clé	Rôle
`var_wave`	variable de vague, servant à décliner les calculs (exemple : l’année). Peut contenir deux variables séparées par une virgule : la seconde est alors un second niveau, emboîté dans le premier (exemple : `var_wave = YEAR, QUARTER`)
`var_filter`	variable de filtre, permettant une déclinaison supplémentaire (exemple : la région). Les calculs sont aussi produits sans distinction de filtre. Accepte également deux variables
`var_intvwr`	identifiant de l’enquêteur·rice
`var_intv`	identifiant de l’entretien (utilisé par l’audit trail et par l’archive)
`var_date`	date de l’entretien
`var_info_geo`	variable géographique, utilisée dans l’onglet Enquêteur pour situer les entretiens

Ensuite la configuration des variables, entièrement facultatif :

Clé	Rôle
`vars_discretes`	variables à traiter comme catégorielles (`VAR1,VAR2,...`)
`vars_continuous`	variables à traiter comme continues
`vars_ignore`	variables à exclure de l’analyse
`prefix_discretes`	préfixes de noms : toute variable commençant ainsi est catégorielle (exemple : `CD_,FL_`)
`prefix_continuous`	préfixes pour les variables continues (exemple : `MT_,NB_`)
`prefix_ignore`	préfixes des variables à exclure

Enfin les clés de l’audit trail (timers), décrites plus bas.

Toutes les valeurs sont traitées sans tenir compte de la casse. Le fichier peut être créé à la main, ou généré avec create_config :

create_config(
  folder_path = "data/EUSILC",
  name_survey = "EUSILC-SIM",
  var_wave    = "db010",
  var_filter  = "db040",
  var_intvwr  = "nr_itw"
)

Le typage automatique des variables

Vous n’avez à renseigner vars_discretes et vars_continuous (et prefix_discretes et prefix_continuous) que si le classement automatique se trompe. La fonction classify_df détermine le type de chaque variable à partir de son format et de son nombre de modalités ; le seuil pour classer une variable comme catégorielle est de 15 modalités par défaut.

classify_df(iris)
#> # A tibble: 5 × 2
#>   variable     type      
#>   <chr>        <chr>     
#> 1 Petal.Length Continuous
#> 2 Petal.Width  Continuous
#> 3 Sepal.Length Continuous
#> 4 Sepal.Width  Continuous
#> 5 Species      Modal

En pratique, le typage se résout dans cet ordre : les préfixes (prefix_*), puis les listes explicites (vars_*), puis le classement automatique pour tout le reste. Les variables listées dans vars_ignore ou correspondant à prefix_ignore sont écartées. En cas d’incohérence (variable en double, variable inclassable), un avertissement est émis et un fichier log.txt est écrit dans le dossier de l’enquête.

Une vague ou un filtre à deux niveaux

Quand var_wave (ou var_filter) contient deux variables, {vizsurvey} construit une clé complète en concaténant les niveaux (2024 / T1) et calcule les statistiques deux fois : une fois pour le premier niveau seul (l’année), une fois pour la clé complète (l’année et le trimestre). La préparation est donc plus longue, à peu près proportionnellement au nombre de modalités ajoutées.

Dans l’interface, le premier niveau est un choix obligatoire et le second est facultatif (All par défaut), affiché en cascade sous le premier. Choisir seulement l’année donne l’analyse au niveau de l’année ; ajouter le trimestre restreint l’analyse, et les comparaisons entre vagues se font alors aussi au niveau année-trimestre.

Les valeurs manquantes

Par défaut, les valeurs manquantes sont comptées comme une modalité à part entière dans le calcul des distances de chi² : une hausse de non-réponse est ainsi détectée au même titre qu’un déplacement de distribution. L’argument na.rm = TRUE de prepa_survey les écarte au contraire du calcul.

Préparer l’enquête

Structure simple : un seul dossier

Une fois la configuration en place, prepa_survey utilise le dossier — données plus config.txt — pour produire :

par vague, les statistiques descriptives de chaque variable ;
par vague, pour chaque variable, les écarts de chaque enquêteur·rice à la population (au sein de la vague) ;
par vague et par filtre, les mêmes écarts au sein du filtre.

Pour l’analyse par enquêteur·rice, les variables continues sont préalablement découpées en cinq classes (par quantiles), de sorte que toutes les variables se comparent avec la même distance de chi² (voir la vignette de méthodes).

Par défaut, prepa_survey cherche les fichiers CSV du dossier ; l’argument file_pattern permet d’adapter ce comportement. Un fichier global.rds est alors généré dans le même dossier : c’est le seul fichier que lira l’interface.

prepa_survey(
  folder_path  = "data/EUSILC",
  file_pattern = "*.csv")

L’application se lance ensuite simplement :

runVizsurvey_from_folder("data/EUSILC", depth_folder = 1)

Structure double : plusieurs dossiers

Si vous gérez plusieurs enquêtes, créez les dossiers côte à côte :

data/
  ├── ENQ1/
  │   ├── *.csv
  │   └── config.txt
  └── ENQ2/
      ├── *.csv
      └── config.txt

prepa_surveys (au pluriel) applique alors la préparation à tous les sous-dossiers. Indiquez depth_folder = 2, à la préparation comme au lancement :

prepa_surveys("data", depth_folder = 2)
runVizsurvey_from_folder("data", depth_folder = 2)

Structure triple : plusieurs niveaux de dossiers

Il est enfin possible de gérer une arborescence complète : un premier niveau par enquête, un second par type de fichier produit par l’enquête. Par exemple, l’enquête SILC comporte des fichiers ménages et des fichiers individus ; l’enquête HBS un fichier d’enquête et un fichier de carnets de dépenses.

data/
  ├── ENQ1/
  │   ├── ENQ1-A/
  │   │   └── ...
  │   └── ENQ1-B/
  │       └── ...
  └── ENQ2/
      ├── ENQ2-A/
      │   └── ...
      └── ENQ2-B/
          └── ...

Chaque sous-dossier doit contenir son propre config.txt et ses propres données. La préparation et le lancement se font avec depth_folder = 3 :

prepa_surveys("data", depth_folder = 3)
runVizsurvey_from_folder("data", depth_folder = 3)

Si les données sont mises à jour, par exemple en cours de collecte, il suffit de relancer prepa_surveys pour obtenir une version à jour des global.rds, donc de l’interface.

Les fichiers transverses

Trois fichiers facultatifs, communs à toutes les enquêtes, se déclarent au lancement de l’interface — pas dans config.txt. La vignette de métadonnées détaille leur utilité et leur création. Voici un bref aperçu.

Le dictionnaire (`path_dict`)

Un fichier .rds contenant un data.frame de documentation des variables : libellés, descriptions, modalités… Sa structure est libre ; il est affiché tel quel dans un onglet Dictionnaire, avec recherche et filtres.

Deux colonnes ont toutefois un rôle particulier : si une colonne VARIABLE est présente, l’onglet Croisé affiche les entrées du dictionnaire correspondant à la variable sélectionnée ; si une colonne TX_LANG est présente (valeurs FR, EN, NL), seules les entrées de la langue courante de l’interface sont montrées.

La nomenclature (`path_nomen`)

Un fichier plat (lisible par fread) donnant un libellé court par variable, dans chaque langue :

VARIABLE,FR,EN,NL
AGE,Âge de la personne,Age of the person,Leeftijd van de persoon
EQINCOME,Revenu équivalent,Equivalised income,Equivalent inkomen

Quand ce fichier est fourni, les libellés s’affichent sous les noms de variables dans les tableaux de l’onglet Enquêteur, dans la langue de l’interface.

L’archive (`path_archive`)

Un fichier CSV où l’interface enregistre les observations consignées par les utilisateur·rices (date, personne, enquête, vague, enquêteur·rice, entretien, variable, commentaire). Il est créé au premier enregistrement s’il n’existe pas. Pointez toutes les personnes de l’équipe vers le même chemin, sur un emplacement partagé et inscriptible : l’archive est justement faite pour mutualiser les vérifications.

runVizsurvey_from_folder("data", depth_folder = 2,
                         path_dict    = "meta/dictionnaire.rds",
                         path_nomen   = "meta/nomenclature.csv",
                         path_archive = "meta/archive.csv")

L’audit trail (timers)

Si votre outil de collecte produit des traces horodatées (un enregistrement par item de questionnaire), {vizsurvey} peut en tirer une analyse des durées : durée des entretiens et des sessions, entretiens trop courts ou trop rapprochés, travail de nuit, entretiens qui se chevauchent.

Les clés correspondantes de config.txt :

Clé	Rôle
`var_timer`	horodatage du début de l’item
`var_itm_duration`	durée de l’item
`var_session`	identifiant de la session de collecte
`duration_min_during`	durée (minutes) en dessous de laquelle un entretien est signalé (défaut : 15)
`duration_min_inter`	écart (minutes) entre deux entretiens en dessous duquel ils sont signalés (défaut : 15)
`night_start`, `night_end`	heures de début et de fin de la nuit (défaut : 21 et 6)

L’interface attend, dans le dossier de l’enquête, un fichier timers.rds contenant les synthèses par entretien et par session, ainsi qu’un fichier timers_<vague>.parquet par vague pour le détail item par item. Les fonctions de préparation de ces fichiers sont en cours de refonte : si vous souhaitez utiliser ce volet dès maintenant, ouvrez une issue sur le dépôt du package et nous vous accompagnerons.

Conclusion

La préparation des données est une étape essentielle avant une utilisation en routine de {vizsurvey} dans une organisation qui conduit des enquêtes au quotidien. Elle optimise la réactivité de l’application et garantit que toutes les personnes analysent les mêmes fichiers à jour.

Une fois les fichiers structurés, configurés et préparés, chaque ouverture de l’interface est immédiate : toutes les statistiques sont déjà calculées dans global.rds. Cette approche facilite aussi le travail collaboratif : chaque membre de l’équipe peut explorer les résultats sans connaître R, et l’archive partagée conserve la mémoire des vérifications déjà faites.

Préparer les données