U Time
1.0.0
Mise en œuvre officielle de
Ce référentiel peut être utilisé pour former à la fois les modèles d'origine U-Time et U-Sleep. Cependant, le référentiel a été considérablement étendu depuis [1] et peut progressivement diverger à partir de la version décrite dans [2]. Des versions antérieures peuvent être trouvées à:
Ce document décrit le progiciel officiel développé et utilisé pour créer le système de stadification de sommeil gratuit et public U-Sleep [2]. U-Sleep est un réseau neuronal profond entièrement convolutionnel pour la mise en scène automatisée du sommeil. Une seule instance du modèle peut être formée pour effectuer une mise en scène précise et résiliente du sommeil à travers un large éventail de populations cliniques et de protocoles d'acquisition de polysomnographie (PSG).
Ce logiciel permet une formation simultanée de U-Sleep sur n'importe quel nombre d'ensembles de données PSG à l'aide de sélection aléatoire à la volant des configurations de canaux d'entrée. Il dispose d'une interface de ligne de commande pour initialiser, former et évaluer les modèles sans avoir à modifier la base de code sous-jacente.
Dans ce qui suit, nous présenterons le logiciel derrière U-Sleep plus en détail. Veuillez noter que:
Ce référentiel stocke le code pour la formation et l'évaluation du modèle de mise en scène de sommeil en U-Sleep . Il s'appuie sur et étend considérablement notre référentiel U-Time, publié chez Nerips 2019 [1]. Dans ce qui suit, nous utiliserons le terme U-Sleep pour désigner le modèle de stadification de sommeil haute fréquence résilient [2], et U-Time pour désigner ce référentiel de code utilisé pour former et évaluer le modèle U-Sleep.
Vous pouvez toujours utiliser ce référentiel pour former l'ancien modèle U-Time, voir l'exemple U-Time ci-dessous.
Exigences matérielles minimales
L'utilisation d'un modèle U-Sleep déjà formé pour la mise en scène du sommeil peut généralement être effectuée sur n'importe quel ordinateur portable moderne (sous réserve des exigences logicielles énumérées ci-dessous).
Pour la formation de modèles de sommeil U à partir de zéro, cependant, nous vous recommandons fortement d'utiliser un ordinateur basé sur Linux avec au moins les spécifications matérielles suivantes:
Il est possible de former le modèle sur des machines plus petites, et sans GPU, mais cela peut prendre un temps considérable. De même, plus de ressources accéléreront l'entraînement. Si l'ensemble de données considéré dépasse la mémoire système (par exemple, le 8 GIB de RAM suggéré ci-dessus), les données doivent être prétraitées et diffusées à partir du disque comme démontré dans la section de démonstration ci-dessous. Sur les grandes machines, on peut bénéficier de la maintenance d'un plus grand pool de données chargées en mémoire. Par exemple, nous avons formé U-Sleep [2] en utilisant 8 cœurs de processeur, 1 GPU et 40 Gib de RAM, veuillez vous référer à la reproduction complète de la section U-Sleep ci-dessous.
* L'espace à disque dur requis dépend du nombre et des tailles des ensembles de données considérés. Pour une reproduction complète de U-Sleep, environ 4 tib de stockage disponible sont nécessaires.
Exigences logicielles:
Si vous allez vous entraîner à un modèle U-Sleep à partir de zéro, nous vous recommandons fortement de le faire sur un GPU. Afin d'utiliser le package U-Time avec un GPU, la bibliothèque tensorflow ( v2.8.0 ) est requise. Pour cela, le logiciel supplémentaire suivant est requis sur votre système:
Veuillez vous référer à https://www.tensorflow.org/install/gpu pour plus de détails. Vous n'avez pas besoin d'installer TensorFlow vous-même (voir le guide d'installation ci-dessous), mais le logiciel ci-dessus doit être installé avant de continuer.
Sur une machine Linux avec au moins 1 GPU compatible CUDA disponible et anaconda ou miniconda installé, exécutez les commandes suivantes pour télécharger le logiciel, créer un environnement conda nommé u-sleep et configurer le dernier progiciel U-TIME et ses dépendances:
git clone https://github.com/perslev/U-Time.git
conda env create --file U-Time/environment.yaml
conda activate u-sleep
pip install U-Time/
Alternativement, vous pouvez installer le package à partir de PYPI (peut être mis à jour moins fréquemment):
pip install utime
Dans ce qui suit, nous montrerons comment lancer une courte session de formation en U-Sleep sur un sous-ensemble considérablement limité des ensembles de données utilisés dans [2].
30 minutes pour terminer sur une connexion informatique et réseau typique. La majorité de ce temps consiste à télécharger les données requises des bases de données publiques. Cette étape peut prendre beaucoup plus de temps en fonction du trafic actuel de la base de données.11 GiB d'espace disque disponible sur votre ordinateur. Tout d'abord, nous créons un répertoire de projet qui stockera toutes nos données pour cette démo. La commande ut init créera un dossier et le remplira avec un ensemble de valeurs d'hyperparamètre par défaut:
ut init --name demo --model usleep_demo
En entrant dans le répertoire de projet nouvellement créé, nous trouverons un dossier stockant des hyperparamètres:
cd demo
ls
> hyperparameters
Nous téléchargerons 6 études PSG à partir des bases de données du sommeil publics Sleep-EDF et DCSM en utilisant la commande ut fetch . Vous aurez besoin d'environ 10 GiB d'espace à disque dur gratuit pour stocker les fichiers téléchargés. Selon votre vitesse Internet et la charge actuelle sur chacun des deux serveurs, le téléchargement peut prendre de 5 minutes à plusieurs heures:
ut fetch --dataset sedf_sc --out_dir data/sedf_sc --N_first 6
ut fetch --dataset dcsm --out_dir data/dcsm --N_first 6
Les données brutes que nous considérerons dans cette démo ont maintenant été téléchargées. Notre dossier de projet demo a maintenant à peu près la structure suivante:
└─ demo
├─ hyperparameters
└─ data
├─ dcsm
│ ├─ tp005f7e68_a084_46bb_9f0a_b6a084155a1c
│ │ ├─ hypnogram.ids
│ │ └─ psg.h5
│ ├─ ...
└─ sedf_sc
├─ SC4001E0
│ ├─ SC4001E0-PSG.edf
│ └─ SC4001EC-Hypnogram.edf
├─ ...
Avant de procéder à la formation du modèle U-Sleep, nous divisons chaque ensemble de données en train de train / validation / test / test fixe à l'aide de la commande ut cv_split . La commande doit être invoquée deux fois chacune avec un ensemble unique de paramètres spécifiant les conventions de dénomination de l'ensemble de données:
# Split dataset SEDF-SC
ut cv_split --data_dir data/sedf_sc/
--subject_dir_pattern 'SC*'
--CV 1
--validation_fraction 0.10
--test_fraction 0.25
--subject_matching_regex 'SC4(d{2}).*'
--seed 123
# Split dataset DCSM
ut cv_split --data_dir data/dcsm/
--subject_dir_pattern 'tp*'
--CV 1
--validation_fraction 0.10
--test_fraction 0.25
--seed 123
Notez que le fractionnement de SEDF-SC est effectué sur une base par sujet. Tous les enregistrements PSG du même sujet seront placés dans le même division d'ensemble de données. Ce n'est pas nécessaire pour DCSM car tous les enregistrements sont de sujets uniques.
Veuillez noter que si vous modifiez l'une des commandes ci-dessus pour utiliser différents noms de répertoire de sortie, vous devrez modifier des chemins de temps dans des fichiers d'hyperparamètre de données stockés sous hyperparameters/dataset_configurations , le cas échéant avant de procéder avec les étapes suivantes.
Exécutez la commande suivante pour préparer les données pour la formation:
ut preprocess --out_path data/processed_data.h5 --dataset_splits train_data val_data
Le script ut preprocess charge et traite tous les ensembles de données tels que décrits par les paramètres définis dans hyperparameters/hparams.yaml et tous les fichiers spécifiques à l'ensemble de données dans le dossier hyperparameters/dataset_configurations . Plus précisément, il charge les canaux nécessaires (en ignorant le reste), rééchantillonne, échelle et coupe les données, cartographie les étapes d'hypnogramme pour interger les représentations utilisées en interne pendant la formation et enregistre enfin les données traitées dans une archive HDF5. Lors de la formation, les données peuvent être diffusées directement à partir de ces archives pour réduire considérablement la mémoire système requise.
Il est également possible de sauter cette étape ensemble et 1) Chargez toutes les données nécessaires pour l'entraînement à l'avance, ou 2) Stream et appliquez le prétraitement à la volée pendant la formation comme indiqué dans la reproduction complète de la section U-Sleep ci-dessous.
Nous pouvons maintenant commencer à nous entraîner en invoquant la commande ut train . Un ensemble par défaut d'hyperparamètres d'optimisation a été pré-spécifié et est situé dans le fichier hyperparameters/hparams.yaml de votre répertoire de projet. Dans cette démo, nous allons exécuter une session de formation très courte, mais n'hésitez pas à modifier tous les paramètres dans le fichier hparams.yaml comme bon vous semble. Exécutez la commande suivante:
ut train --num_gpus=1 --preprocessed --seed 123
Vous pouvez remplacer le paramètre --num_gpus=1 dans la commande ci-dessus par --num_gpus=0 si vous n'avez pas de GPU disponible et que vous souhaitez vous entraîner sur le CPU. La formation sur le processeur peut prendre jusqu'à 30 minutes.
Après la formation, un ensemble de modèles de candidats sera disponible dans le model de dossier. En utilisant le meilleur observé (score F1 moyen de validation la plus élevée), nous pouvons prédire sur les ensembles de tests de SEDF-SC et DCSM en utilisant toutes les combinaisons de canaux ainsi que de calculer les votes majoritaires en invoquant la commande ut predict suivante:
ut predict --num_gpus=1
--data_split test_data
--strip_func strip_to_match
--one_shot
--save_true
--majority
--out_dir predictions
Les hypnogrammes prévus sont désormais disponibles sous predictions/test_data . Enfin, imprimons une matrice de confusion globale (calculée sur tous les sujets) pour l'ensemble de données sedf_sc (Remplacez sedf_sc -> dcsm pour l'évaluation DCSM):
ut cm --true 'predictions/test_data/sedf_sc/*TRUE.npy'
--pred 'predictions/test_data/sedf_sc/majority/*PRED.npy'
--ignore 5
--round 2
--wake_trim_min 30
>>> Looking for files...
>>> Loading 2 pairs...
>>> OBS: Wake trimming of 30 minutes (period length 30 sec)
>>> OBS: Ignoring class(es): [5]
>>>
>>> Raw Confusion Matrix:
>>>
>>> Pred 0 Pred 1 Pred 2 Pred 3 Pred 4
>>> True 0 0 0 17 234 0
>>> True 1 0 0 132 146 0
>>> True 2 0 0 790 157 0
>>> True 3 0 0 25 189 0
>>> True 4 0 0 243 99 0
>>>
>>> Raw Metrics:
>>>
>>> F1 Precision Recall/Sens.
>>> Class 0 0.00 0.00 0.00
>>> Class 1 0.00 0.00 0.00
>>> Class 2 0.73 0.65 0.83
>>> Class 3 0.36 0.23 0.88
>>> Class 4 0.00 0.00 0.00
>>> mean 0.22 0.18 0.34
Si vous avez reçu une sortie similaire à ce qui précède, félicitations! Vous avez réussi à installer, configuré, formé et évalué un modèle U-Sleep sur deux ensembles de données différents.
Veuillez noter que:
Si vous avez exécuté le code ci-dessus sur un GPU, vous ne pouvez pas obtenir exactement les mêmes numéros répertoriés ici, même si vous avez spécifié les arguments --seed. En effet, certains calculs utilisés lors de la formation de U-Sleep sont fondamentalement non déterministes lorsqu'ils sont évalués sur un GPU. Cependant, la prévision de l'utilisation d'un modèle en U entraîné donnera des sorties déterministes.
Les performances du modèle de démonstration obtenues sont très faibles et ne conviennent pas à la mise en scène réelle du sommeil. La raison en est que nous avons formé U-Sleep sur un ensemble de données très limité et pour un nombre très limité d'époches. Veuillez vous référer à la reproduction complète de la section U-Sleep pour plus de détails sur la façon de préparer et de former une version complète de U-Sleep.
La démo ci-dessus en principe décrit toutes les étapes nécessaires pour reproduire U-Sleep comme indiqué dans [2]. La différence principale - et significative - est que pour reproduire le modèle complet, vous devrez 1) pouvoir accéder 2) télécharger et 3) prétraitement tous les ensembles de données requis. Vous pouvez également avoir besoin d'un ordinateur avec plus de ressources comme décrit dans les exigences du système.
Nous avons fait de notre mieux pour rendre ce processus aussi simple que possible. Vous devriez prendre les mesures suivantes:
ut fetch . Veuillez invoquer ut fetch --help pour voir une liste à jour dont les ensembles de données peuvent être téléchargés de cette façon.[LOCAL_PATH] avec 1 sous-dossier pour chaque ensemble de données.ut extract , ut extract_hypno et ut cv_split sur tous les ensembles de données spécifiés pour chaque ensemble de données séparément dans des fichiers sous les resources/usleep_dataset_pred de ce référentiel (également trouvé ici). Ces commandes extraire et placeront des données dans une structure de dossier et un format que U-Time accepte, ainsi que diviser les données en sous-ensembles.ut extract sélectionnera les canaux pertinents, les rééchantillonnera à 128 Hz et stockera les données dans les archives HDF5. Les données d'origine ne seront pas supprimées par défaut. Si vous avez un espace à disque dur limité, envisagez de supprimer les anciens fichiers avant de traiter le prochain ensemble de données.ut init --name u-sleep --model usleep .u-sleep/hyperparameters/dataset_configurations/ Remplacez la chaîne [local_path] par le [LOCAL_PATH] de vos données. Si vous avez plus de 40 ans de mémoire système GIB, formez U-Sleep en utilisant la commande suivante:
ut train --num_gpus 1 --max_loaded_per_dataset 40 --num_access_before_reload 32 --train_queue_type limitation --val_queue_type lazy --max_train_samples_per_epoch 1000000
Sur les systèmes avec moins de mémoire, vous pouvez soit 1) réduire le paramètre --max_loaded_per_dataset du 40 actuel à une valeur inférieure (cela conservera moins d'enregistrements PSG dans le pool de mémoire actif, ce qui réduira le hasard lors de la sélection des enregistrements), ou 2) Prétraitez les données et les données du flux pendant la formation (comme démontré dans la démo ci-dessus) en invoquant les deux commandes suivantes (remplaçant [local_path] le cas échéant):
ut preprocess --out_path '[LOCAL_PATH]/processed_data.h5' --dataset_splits train_data val_data
ut train --num_gpus 1 --preprocessed --max_train_samples_per_epoch 1000000
Cela appliquera tous les prétraitements, créera une archive de données adaptée à la diffusion en streaming et s'entraînera en U-Sleep à l'aide d'échantillons chargés à la volée à partir du disque.
En raison de la grande taille de l'ensemble de données considéré, la formation en U-Sleep avec les paramètres par défaut peut prendre très longtemps. Nous suggérons d'augmenter le taux d'apprentissage (du 1e-7 actuel à EG 1e-6 ), sauf si vous cherchez à recréer U-Sleep dans les conditions exactes considérées dans [2].
Vous pouvez toujours utiliser ce référentiel pour former l'ancien modèle U-Time. Dans ce qui suit, nous montrons un exemple de bout en bout. Les commandes répertoriées ci-dessous préparent un dossier de projet, télécharge l'ensemble de données Sleep-EDF-153, s'adapte et évalue un modèle U-TIME dans une configuration de fraction de données Train / Val / Test / test fixe. Veuillez noter que le code ci-dessous ne reproduit pas l'expérience du sommeil-EDF-153 de [1] en tant que CV à 10 fois a été utilisé. Pour exécuter une expérience CV, veuillez vous référer aux commandes ut cv_split --help et ut cv_experiment --help .
# Obtenir un ensemble de données de mise en scène du sommeil public
ut fetch - dataset sedf_sc --out_dir Datasets / sedf_sc
# Préparez une expérience de split fixe
UT CV_SPLIT --DATA_DIR 'DatasetSets / Sedf_sc'
--subject_dir_pattern 'sc *'
--Cv 1
--Validation_Fraction 0.20
--Test_Fraction 0.20
--subject_matching_regex 'sc4 ( d {2}). *'
--file_list
# Initialiser un projet U-Time
ut init --name my_utime_project
--model utime
--Data_dir DataSets / Sedf_sc / Views / Fixed_split
# Commencer la formation
cd my_utime_project
ut Train --num_gpus = 1 - Channels 'EEG FPZ-CZ'
# Prédire et évaluer
ut evaluate --out_dir eval --one_shot
# Imprimez une matrice de confusion
ut cm --true 'eval / test_data / dataset_1 / files / * / true.npz'
--pred 'eval / test_data / dataset_1 / files / * / pred.npz'
# Impression par sursal Sommaire Statistiques
Ut Résumé --CSV_PATTERN 'EVAL / TEST_DATA / * / EVAMUATION_DICE.CSV'
--print_all
# Sortie des étapes de sommeil pour toutes les 3 secondes de signal 128 Hz
# Ici, le 'Folder_regex' correspond à 2 fichiers dans l'ensemble de données
ut prédire --folder_regex '../datasets/sedf_sc/sc400[1-2
--out_dir high_res_pred
--data_per_prediction 384
--one_shot
@incollection{NIPS2019_8692,
title = {U-Time: A Fully Convolutional Network for Time Series Segmentation Applied to Sleep Staging},
author = {Perslev, Mathias and Jensen, Michael and Darkner, Sune and Jennum, Poul Jo rgen and Igel, Christian},
booktitle = {Advances in Neural Information Processing Systems 32},
editor = {H. Wallach and H. Larochelle and A. Beygelzimer and F. dtextquotesingle Alch'{e}-Buc and E. Fox and R. Garnett},
pages = {4415--4426},
year = {2019},
publisher = {Curran Associates, Inc.},
url = {http://papers.nips.cc/paper/8692-u-time-a-fully-convolutional-network-for-time-series-segmentation-applied-to-sleep-staging.pdf}
}
U-Sleep: Resilient High-Frequency Sleep Staging
Mathias Perslev (1), Sune Darkner (1), Lykke Kempfner (2), Miki Nikolic (2), Poul Jørgen Jennum (2) & Christian Igel (1)
npj Digital Medicine, 4, 72 (2021)
https://doi.org/10.1038/s41746-021-00440-5
(1) Department of Computer Science, University of Copenhagen, Denmark
(2) Danish Center for Sleep Medicine, Rigshospitalet, Glostrup, Denmark
