Compétence splsleep-pipeline

Automatisez le nettoyage des données de journal de sommeil EMA à l'aide du package R splsleep. Cette compétence aide un agent IA à comprendre, exécuter et maintenir le pipeline de nettoyage des données.

Aperçu

Le pipeline splsleep traite les données brutes de journal de sommeil EMA (heure du coucher, heure de sommeil, heure d'éveil, heure de lever, SOL, WASO, consommation de substances) en 9 étapes séquentielles qui analysent, valident, corrigent et visualisent les données.

Entrée : Fichiers CSV + RDS bruts d'EMA avec les enregistrements de journal de sommeil des participants. Sortie : Ensemble de données nettoyé + 27 PNGs de contrôle qualité + rapports de correction.

Étapes du pipeline

Étapes 1-4 : Analyser les horodatages et les intervalles (process_timestamp, process_interval)
Étape 5   : Classifier les enregistrements (classification error_unusual)
Étape 5.75 : Deuxième révision (apply_second_review)
Étape 6   : Corriger les erreurs d'horodatage (error_unusual_sleep_time_corrections)
Étape 6.5 : Corriger les durées des siestes/exercices (apply_nap_exercise_corrections)
Étape 7   : Calculer les métriques de sommeil (TST, SOL, WASO, SE)
Étape 8   : Détection automatique des problèmes restants (checkforerrors_processing)
Étape 8.5 : Cohérence inter-participant (cross_participant_global_check)
Étape 9   : Générer les visualisations (sleep_visualization.R)

Fichiers clés

Fichier	Objectif
`00_MAIN_entry.R`	Orchestration principale (fonction `run_pipeline()`)
`00a_setup.R`	Chargement et validation des données
`process_timestamp_emadatarelease_cyra.R`	Analyser les horodatages bruts HH:MM AM/PM
`process_interval.R`	Analyser les chaînes de durée HH:MM
`normalize_sleep_time_sequence.R`	Corriger les mauvaises affectations AM/PM dans les horodatages
`calculate_sleep_time_end.R`	Calculer les métriques TST, SOL, WASO, SE
`error_unusual_sleep_time_corrections.R`	Classification principale + correction d'horodatage
`generate_correction_files.R`	Créer des modèles CSV de correction manuelle
`apply_second_review.R`	Révision en deuxième passage après la classification initiale
`apply_nap_exercise_corrections.R`	Corriger les durées de sieste/exercice auto-déclarées
`apply_sleep_metric_duration_corrections.R`	Corriger les entrées de durée SOL/WASO
`apply_metric_review_acceptances.R`	Appliquer les acceptations de métriques révisées par l'humain
`checkforerrors_processing.R`	Détection automatique des problèmes restants (3 parties : A/B/C)
`cross_participant_global_check.R`	Vérification de l'écart par rapport à la ligne de base par participant
`cross_participant_field_misentry_check.R`	Détection des mauvaises saisies de champ (ex. SOL=time_bed)
`sleep_visualization.R`	Générer 27 figures de contrôle qualité
`report_correction_status.R`	Rapporteur de points de contrôle + résumé final
`audit_review_propagation.R`	Vérifier la propagation de la révision manuelle
`generate_ai_review_csvs.R`	Générer des CSV de révision assistée par IA
`run.sh`	Point d'entrée shell (installe le package + exécute le pipeline)
`DESCRIPTION`	Métadonnées du package R
`R/pipeline.R`	Fonction `run_pipeline()` exportée par le package

Fichiers de données

Fichier	Format	Description
`deidentified_intervalvars_forCD_111325.rds`	RDS	Données principales du journal de sommeil (intervalles traités)
`sber_ema_anon_20260227.csv`	CSV	Réponses EMA brutes avec consommation de substances
`manual_error_corrections.csv`	CSV	Corrections d'erreurs manuelles (entrée de l'étape 6)
`manual_unusual_corrections.csv`	CSV	Corrections manuelles de valeurs inhabituelles
`manual_nap_exercise_corrections.csv`	CSV	Corrections manuelles des durées de sieste/exercice
`manual_sleep_metric_duration_corrections.csv`	CSV	Corrections manuelles des durées SOL/WASO
`manual_metric_review_acceptances.csv`	CSV	Anomalies de métriques acceptées par l'humain (supprimer de NEEDS_REVIEW)
`second_review_checklist.csv`	CSV	Décisions de la deuxième révision

Sorties

Chemin	Contenu
`output/correction_status.csv`	Instantanés de points de contrôle par exécution (A-E)
`output/correction_status_final.csv`	Résumés des écarts inter-points de contrôle
`output/flagged_records_self_reported.csv`	Enregistrements SELF-REPORTED FLAG
`latest_visualization/`	Tous les PNG de la dernière exécution
`latest_visualization/pipeline_cleaning/`	Progression du pipeline et figures de contrôle qualité
`latest_visualization/research_ready/`	Métriques de sommeil et figures de consommation de substances

Catalogue de figures

pipeline_cleaning/ (Contrôle qualité et progression)

01_Final_Data_Quality_Dashboard — diagramme circulaire data_category + métriques clés
06_Sleep_Duration_Post_Correction — densité par statut de correction
07_Flag_Composition_Stacked — flag_severity × sleep_duration
08_Sleep_Duration_by_Category — violon par data_category
10_Extreme_Sleep_Duration — valeurs extrêmes avec efficacité
11_Flag_Cooccurrence_Heatmap — co-occurrence de paires de flags
12_Pipeline_Correction_Progress — diagramme à barres des points de contrôle A→E
19_Unified_Quality_Status — classification checkforerrors_summary
P26_PerParticipant_Flag_Rate — % Clean/Minor/Major par participant

research_ready/ (Analyse du sommeil)

02_Distribution_Sleep_Variables — histogrammes TST/SOL/WASO/SE
03_Sleep_Duration_Distribution — histogramme TST avec statistiques
04_Sleep_Duration_vs_Time_in_Bed — nuage de points avec corrélation
04B_SOL_vs_Sleep_Duration — nuage de points SOL × TST
05_Variability_Sleep_Variables — diagrammes en violon (free_y)
09_Bedtime_vs_Getup_Distribution — schémas circadiens
20_SOL_Perception_Bias — SOL subjectif vs objectif
20B_WASO_Perception_Bias — WASO subjectif vs objectif
21_Substance_Use_Availability, 22-24 — consommation de substances

Non générées lorsque la détection automatique ne trouve aucun problème :

Figures 13-18 (détails de la détection automatique)

Système de classification

data_category (de l'étape 5, classification temporelle)

clean — aucun problème temporel détecté
error — ordre temporel impossible à corriger automatiquement (ex. lever avant coucher)
unusual — schéma plausible mais inhabituel (ex. sommeil très court)
equal_time_ok — coucher == lever (accepté automatiquement)
skipped_na — aucune donnée de sommeil enregistrée
reasonable_unusual — inhabituel mais dans des limites raisonnables

flag_severity (des métriques corrigées, étape 7)

Clean — 0 flags
Minor — 1 flag parmi {SE < 70%, SOL > 1h, WASO > 1.5h}
Major — 2+ flags du même ensemble

checkforerrors_summary (de l'étape 8 de détection automatique)

TIMESTAMP_ISSUE — erreurs de format horodatage
DURATION_ISSUE — erreurs d'intervalle/format
AMOUNT_FLAG — anomalies de saisie de substance
SELF_REPORTED_FLAG — anomalies des métriques SOL/WASO (PAS des erreurs de données)
CLEAN — aucun problème
CLEAN (Manually Fixed) — avait des problèmes, corrigé à l'étape 6

Métriques clés (exécution actuelle)

Enregistrements totaux : 13 990
Skipped NA (aucune donnée de sommeil) : 11 142
Clean : 1 908 | Error : 7 | Unusual : 31 | Equal Time : 902
Corrigés manuellement : 82
SELF-REPORTED FLAG : 72 (61 SOL excessif + 11 TST/TIB très bas)
Enregistrements métriques valides : 1 729 | TST moyen : 7,71 h | SOL moyen : 28,8 min
Problèmes TIMESTAMP/DURATION/AMOUNT : 0 (tous résolus par le pipeline)

Tâches courantes

Exécuter le pipeline (configuration par défaut)

library(splsleep)
run_pipeline()

Exécuter avec une configuration personnalisée (nouvel ensemble de données)

# 1. Générer un modèle de configuration
file.copy(system.file("config_default.yaml", package = "splsleep"),
          "my_study_config.yaml")

# 2. Modifier my_study_config.yaml :
#    - column_mapping : mapper vos noms de colonnes aux variables du pipeline
#    - classification : ajuster les seuils (SOL, SE, ratio TST/TIB)
#    - timestamp : format de l'heure d'entrée

# 3. Exécuter
run_pipeline(config = "my_study_config.yaml")

Point d'entrée shell

cd /chemin/vers/splsleep
bash run.sh

Exécuter sans installation du package (hérité)

Rscript -e 'splsleep_loaded <- TRUE; source("00_MAIN_entry.R")'

Regénérer les figures uniquement

source("sleep_visualization.R")

Vérifier le dernier statut de correction

# Depuis output/correction_status_final.csv
read.csv("output/correction_status_final.csv")

Ajouter une correction manuelle

Ajouter une ligne à manual_error_corrections.csv (ou autre CSV de correction)
Relancer le pipeline
Vérifier dans le rapport et la Figure 7

Ajouter une nouvelle figure

Ajouter le code dans sleep_visualization.R
Ajouter save_png() avec subdir = "pipeline_cleaning" ou " research_ready"
Mettre à jour le catalogue de figures dans le script
Relancer

cyracaid/sleepdiary-cleaner

Qu'est-ce que sleepdiary-cleaner ?

Demander à votre IA préférée

Documentation