Données et exports

Ce guide explique comment les données d'une participation sont organisées une fois exportées, afin que vous puissiez les analyser en toute confiance. Pour la liste des fichiers d'un export et la façon de les télécharger, consultez Détails de la participation. Cette page se concentre sur les concepts sous-jacents : la base de temps, la forme de chaque type d'enregistrement et la manière de les relier.

Base de temps

Chaque horodatage d'un export est exprimé en temps d'enregistrement : des millisecondes comptées à partir de la première image de la caméra. C'est la même échelle que la tête de lecture sur la page de participation, donc une valeur de 12000 correspond à douze secondes après le début de l'enregistrement.

Chaque export indique aussi une qualité de synchronisation pour que vous sachiez à quel point cet alignement est fiable. Consultez Synchronisation et qualité des données pour la signification des niveaux precise, approximate et unavailable et la conduite à tenir pour chacun. Lorsque la qualité est unavailable, les colonnes en temps d'enregistrement restent vides plutôt que de contenir une valeur peu fiable.

Temps absolu sur l'horloge murale

Le temps d'enregistrement vous indique où se situe un événement à l'intérieur d'un enregistrement. Pour placer cet enregistrement sur le calendrier réel (l'aligner sur un appareil externe, ou comparer deux participations), le fichier metadata.json de l'export contient un bloc precise_times avec des horodatages absolus, ancrés sur l'horloge du serveur.

Ces horodatages sont ancrés sur une lecture unique de l'horloge du serveur effectuée près du consentement, et non sur l'horloge de la machine locale du participant. Cela les distingue des champs historiques session_started_at et session_ended_at, qui proviennent directement de l'horloge de la machine locale et ne comportent aucune borne d'erreur. Ne confondez pas les deux : precise_times est ancré sur le serveur et accompagné d'une incertitude déclarée, tandis que la famille session_started_at est une lecture de l'horloge locale. Le fait qu'une colonne temporelle soit proche d'une autre n'est pas une raison de supposer qu'elles partagent la même horloge.

precise_times contient trois événements :

• participation_start : l'instant où la page de participation s'est ouverte.
• record_time_0 : l'instant de la première image de la caméra, le moment même auquel le temps d'enregistrement 0 fait référence. Cet événement est dérivé au moment de l'export (il a besoin du décalage de départ de l'enregistrement) : il n'apparaît donc qu'ici, dans metadata.json, et non sur le document de participation.
• participation_end : l'instant où la participation s'est terminée.

Chaque événement est un objet doté des champs suivants :

Champ	Signification
epoch_ms	le temps absolu sous forme d'horodatage UTC en millisecondes
iso	le même instant sous forme de chaîne ISO-8601 UTC (se termine par Z)
error_ms	l'incertitude dans le pire des cas, en millisecondes, ou null lorsqu'aucune borne ne s'applique
bounded	true lorsque le temps comporte une borne d'erreur fiable, false sinon
clock_source	server_offset lorsqu'il est ancré sur la lecture de l'horloge du serveur, ou local_fallback lorsque cette lecture n'était pas disponible
recording_sync_source	sur record_time_0 uniquement : chirp_anchored pour un alignement audio inframillimétrique, ou approximate_sync lorsque le départ de l'enregistrement n'a pas pu être fixé

La valeur error_ms est une incertitude d'étalonnage : elle reflète l'aller-retour de l'unique lecture de l'horloge du serveur effectuée près du consentement, mesurée une seule fois. Ce n'est pas une mesure de la dérive de l'horloge au cours de la session. Lorsque l'horloge est fiable, un participation_start se lit bounded: true avec un petit error_ms ; si l'horloge de l'appareil fait un saut ou se met en veille pendant la session, les temps sont reportés bounded: false avec error_ms à null, car l'étalonnage unique ne peut plus être considéré comme fiable.

clock_source (la façon dont l'horloge murale a été ancrée) et recording_sync_source (la façon dont le départ de l'enregistrement a été aligné) sont deux indicateurs de qualité indépendants. Une session peut disposer d'un ancrage d'horloge solide mais d'un départ d'enregistrement seulement approximatif, ou l'inverse.

Reconstituer le temps sur l'horloge murale pour n'importe quel événement

Comme record_time_0 est le temps absolu du temps d'enregistrement 0, vous pouvez convertir n'importe quelle valeur de temps d'enregistrement en temps absolu par une simple addition :

wall_clock_ms = record_time_0.epoch_ms + recording_ms

Ici, recording_ms est une valeur de temps d'enregistrement quelconque issue de l'export (un marqueur, une réponse, un échantillon de signal), et recording_ms = 0 correspond à la première image de la caméra. Lorsque record_time_0 est reporté bounded: false (par exemple sur une session approximate_sync), traitez comme approximatif tout temps sur l'horloge murale que vous reconstituez à partir de lui.

Enregistrements de réponses et granularité

Chaque tâche comportementale écrit un fichier de réponses par type de tâche (par exemple responses/csv/flanker.csv et un responses/json/flanker.json sans perte). La correspondance entre les lignes et la tâche dépend de la granularité de la tâche :

Granularité	Un enregistrement par	Exemples
trial	essai	Stroop, Flanker, N-back
event	événement distinct (sans numéro d'essai)	tracé de pistes, certaines tâches d'oculométrie
single	tâche entière (un seul enregistrement)	questionnaire, dessin
sequence	étape ordonnée, avec une réponse finale	test des jetons, échelle sociale

La granularité détermine également la façon dont les essais sont comptés dans study_summary.json : les tâches de granularité trial rapportent un nombre réel d'essais, tandis que les tâches de granularité event ou single laissent ces comptes vides car la notion ne s'applique pas. La granularité de chaque tâche est précisée dans le README.md de l'export.

Le CSV plat contient une ligne de champs scalaires pour un usage tableur ; le JSON conserve l'enregistrement complet, y compris les champs imbriqués que le CSV omet. Les champs dont le nom se termine par un suffixe temporel sont convertis en temps d'enregistrement à l'export ; le data_dictionary.csv et le codebook.json décrivent chaque champ.

Fichiers de synthèse

Les tâches qui produisent des statistiques agrégées écrivent aussi un fichier de synthèse, un par tâche (par exemple summaries/flanker_0.json). Chaque synthèse suit une enveloppe versionnée commune :

• schema_version : la version de l'enveloppe (actuellement 1), afin que votre code d'analyse puisse détecter les changements de structure entre les versions de la plateforme.
• task : un bloc d'identité qui indique à quelle tâche appartient cette synthèse. Il contient le type de tâche, la version, l'indice d'exécution et les clés de jointure (task_id, display_order, task_name) qui relient ce fichier aux autres fichiers de l'export. Utilisez task.task_id pour relier une synthèse aux lignes de réponses correspondantes ou aux échantillons de signaux.
• measures : une carte plate des valeurs calculées principales pour l'ensemble de la tâche : nombre d'essais, temps de réaction moyen, exactitude, et tout score dérivé propre à la tâche comme les effets d'interférence ou les indices de théorie de détection du signal. Ce sont les mêmes valeurs que celles affichées dans la section « Mesures calculées » de l'onglet Notation.
• breakdowns (optionnel) : les mêmes mesures ventilées selon un facteur comme la condition, le bloc ou la catégorie. Structure : breakdowns.<facteur>.<niveau>.<mesure>.
• meta (optionnel) : contexte propre à la tâche qui n'est pas lui-même une mesure, comme le mode d'exécution, la liste de mots présentée ou l'indication que la tâche a été interrompue.
• practice (optionnel) : un bloc parallèle contenant measures et breakdowns pour la phase d'entraînement, présent lorsque la tâche comprenait une telle phase.

Les lignes par essai ne sont pas dupliquées dans la synthèse. Toutes les données au niveau de l'essai se trouvent dans les fichiers de réponses (responses/csv/<type>.csv et responses/json/<type>.json) ; la synthèse est construite à partir de ces lignes et ne rapporte que les agrégats calculés. Les mesures exactes rapportées pour chaque tâche sont documentées sur la page de la tâche concernée.

Marqueurs et événements

markers.csv liste chaque marqueur système et de tâche sur la ligne de temps d'enregistrement. À côté de chaque marqueur, une catégorie décrit le type d'événement enregistré, ce qui vous permet de filtrer ou de regrouper sans mémoriser chaque nom de marqueur :

Catégorie	Enregistre
lifecycle	points de début et de fin de session et de tâche
instruction	écrans d'instructions et d'aide
phase	limites de blocs (phase d'entraînement, phase principale, etc.)
trial onset	le début et la fin de chaque essai
stimulus	événements de stimulus, de fixation, d'amorce et de cible
feedback	retour présenté au participant
per item	interactions par item (un toucher, un tracé, un clic)
task specific	événements propres à une seule tâche

Les marqueurs que vous ajoutez vous-même lors de la revue d'une participation sont exportés séparément dans researcher_markers.csv, avec l'indication de chaque marqueur saisi manuellement ou copié depuis la frise système.

Notations du chercheur

Les métriques personnalisées que vous consignez dans l'onglet Notation de la page de participation sont exportées dans scores/researcher_scores.csv, accompagné d'un fichier compagnon scores/researcher_scores.json qui regroupe les mêmes lignes par tâche. Les fichiers n'apparaissent que lorsque vous avez saisi au moins une métrique personnalisée.

Chaque ligne contient une métrique pour une tâche : la tâche concernée, le nom de la métrique, la valeur et vos notes. La valeur et les notes sont du texte libre que vous avez rédigé, et non des nombres calculés : traitez-les donc comme des chaînes de caractères. Une valeur peut être un nombre, une étiquette, une cotation ou une courte phrase, exactement telle que vous l'avez saisie. Convertissez-la vous-même en nombre lorsque votre analyse l'exige.

Reliez les notations du chercheur au reste de l'export par tâche, de la même manière que vous reliez les autres fichiers (voir Tout relier). Comme les noms de métriques sont les vôtres, gardez-les cohérents d'une participation à l'autre afin que la même métrique s'aligne lorsque vous combinez les sessions.

Flux de signaux

Lorsque les données correspondantes ont été collectées, un export inclut des flux de signaux continus :

• signals/gaze.csv : une ligne par échantillon de regard (position dans la fenêtre d'affichage, en pourcentage).
• signals/interaction.csv : événements de pointeur, de défilement, de clavier et de focus.

Les deux flux sont étiquetés à l'export avec l'essai et la phase dans lesquels chaque échantillon est tombé (trial_index, practice_trial_index, is_practice), afin que vous puissiez aligner le regard ou l'interaction sur l'essai affiché. Un échantillon porte un indicateur incomplete_trial lorsque l'essai auquel il appartient n'avait pas de marqueur de fin explicite et que sa fenêtre a été close au début de l'essai suivant ; traitez ces fenêtres comme approximatives.

Le catalogue de champs

Deux fichiers décrivent les données pour vous éviter d'en déduire le sens des champs :

• data_dictionary.csv : un dictionnaire plat à six colonnes (nom, type, signification, unité, valeurs, tâche) couvrant chaque colonne de l'export.
• codebook.json : le même catalogue sous forme exploitable par machine, adapté au chargement dans un script d'analyse.

Les deux sont générés à partir des définitions de tâches de la plateforme : ils correspondent donc toujours aux données du lot avec lequel ils sont livrés.

Tout relier

Utilisez study_summary.json comme index de ce que le participant a réellement exécuté, dans l'ordre. À partir de là, reliez les autres fichiers par la clé task_id (et, au sein d'une tâche, par le numéro d'essai). Le README.md inclus dans chaque export détaille la procédure de jointure pour ce lot précis.