U Time
1.0.0
Offizielle Umsetzung von
Dieses Repository kann verwendet werden, um sowohl die ursprünglichen U-Time- als auch die neueren U-Sleep-Modelle zu trainieren. Das Repository wurde jedoch seit [1] erheblich erweitert und kann allmählich von der in [2] beschriebenen Version abweichen. Frühere Versionen können unter:
In diesem Dokument wird das offizielle Softwarepaket beschrieben, das für das kostenlose und öffentliche Schlafstaging-System U-Sleeschlaf entwickelt wurde [2]. U-Sleep ist ein vollesendes nerviges, tiefes Neuralnetz für die automatisierte Schlafstaging. Eine einzelne Instanz des Modells kann geschult werden, um eine genaue und belastbare Schlafstagierung in einer Vielzahl von Erwerbsprotokollen für klinische Populationen und Polysomnographie (PSG) durchzuführen.
Diese Software ermöglicht das gleichzeitige Training von U-Sleep über eine beliebige Anzahl von PSG-Datensätzen über die zufällige Auswahl der Eingabekanalkonfigurationen. Es verfügt über eine Befehlszeilenschnittstelle zum Initialisieren, Training und Bewertung von Modellen, ohne die zugrunde liegende Codebasis zu ändern.
Im Folgenden werden wir die Software hinter U-Sleep ausführlicher vorstellen. Bitte beachten Sie::
Dieses Repository speichert Code für das Training und die Bewertung des U-Slee-Sleep -Schlaf-Staging-Modells. Es baut auf und erweitert unser U-Time-Repository, das bei Neurips 2019 veröffentlicht wurde [1]. Im Folgenden werden wir den Begriff U-Sleep verwenden, um das belastbare Hochfrequenz-Schlaf-Staging-Modell [2] zu bezeichnen, und die U-Time , um dieses Code-Repository zu bezeichnen, das zum Training und Bewertung des U-Sleep-Modells verwendet wird.
Sie können dieses Repository weiterhin verwenden, um das ältere U-Zeit-Modell zu trainieren. Siehe U-Time-Beispiel unten.
Minimale Hardwareanforderungen
Die Verwendung eines bereits geschulten U-Sleep-Modells für die Schlafstadium kann normalerweise an jedem modernen Laptop durchgeführt werden (vorbehaltlich der unten aufgeführten Softwareanforderungen).
Für das Training von U-Sleep-Modellen von Grund auf empfehlen wir jedoch dringend, einen Linux-basierten Computer mit mindestens den folgenden Hardwarespezifikationen zu verwenden:
Es ist möglich, das Modell auf kleineren Maschinen und ohne GPUs zu trainieren, aber dies kann eine beträchtliche Zeit in Anspruch nehmen. Ebenso beschleunigen mehr Ressourcen das Training. Wenn der betrachtete Datensatz den Systemspeicher überschreitet (z. B. der oben vorgeschlagene RAM -RAM), müssen die Daten vorverarbeitet und von der Festplatte gestreamt werden, wie im folgenden Demo -Abschnitt gezeigt. Bei größeren Maschinen kann man davon profitieren, dass ein größerer Datenpool im Speicher geladen wird. Zum Beispiel haben wir U-Sleep [2] mit 8 CPU-Kernen, 1 GPU und 40 Gib RAM trainiert. Weitere Informationen finden Sie in der vollständigen Reproduktion des U-Sleep-Abschnitts unten.
*Der erforderliche Festplattenraum hängt von der Anzahl und den Größen der betrachteten Datensätze ab. Für eine vollständige Reproduktion von U-Sleep sind ungefähr 4 TIB verfügbarer Speicher benötigt.
Softwareanforderungen:
Wenn Sie selbst ein U-Sleep-Modell von Grund auf selbst trainieren möchten, empfehlen wir es wärmstens auf einer GPU zu tun. Um das U-Time Paket mit einer GPU zu verwenden, ist die Bibliothek tensorflow ( v2.8.0 ) erforderlich. Hierzu ist die folgende zusätzliche Software für Ihr System erforderlich:
Weitere Informationen finden Sie unter https://www.tensorflow.org/install/gpu. Sie müssen TensorFlow nicht selbst installieren (siehe Installationshandbuch unten), aber die obige Software muss vor dem Fortfahren installiert werden.
Auf einer Linux-Maschine mit mindestens 1 CUDA-fähiger GPU verfügbar und anaconda oder miniconda installiert werden die folgenden Befehle zum Herunterladen der Software aus. Erstellen Sie eine Conda-Umgebung mit dem Namen u-sleep und richten Sie das neueste U-Time-Softwarepaket und ihre Abhängigkeiten ein:
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/
Alternativ können Sie das Paket von PYPI installieren (können weniger häufig aktualisiert werden):
pip install utime
In diesem folgenden werden wir demonstrieren, wie eine kurze Trainingseinheit mit U-Sleep in einer erheblich begrenzten Teilmenge der in [2] verwendeten Datensätze auf den Markt gebracht werden.
30 minutes um eine typische Computer- und Netzwerkverbindung zu vervollständigen. Der Großteil dieser Zeit ist es, die erforderlichen Daten aus öffentlichen Datenbanken herunterzuladen. Dieser Schritt kann je nach aktueller Datenbankverkehr erheblich dauern.11 GiB verfügbarer Scheibenraum auf Ihrem Computer. Zunächst erstellen wir ein Projektverzeichnis, in dem alle unsere Daten für diese Demo gespeichert werden. Der Befehl ut init erstellt einen Ordner und füllt ihn mit einer Reihe von Standard -Hyperparameterwerten aus:
ut init --name demo --model usleep_demo
Wenn wir das neu erstellte Projektverzeichnis eingeben, werden wir einen Ordner finden, in dem Hyperparameter gespeichert werden:
cd demo
ls
> hyperparameters
Wir werden 6 PSG-Studien aus den öffentlichen Schlafdatenbanken Sleep-EDF und DCSM unter Verwendung des Befehls ut fetch herunterladen. Sie benötigen ungefähr 10 GiB KOSTENLOSE Hartscheibenraum, um die heruntergeladenen Dateien zu speichern. Abhängig von Ihrer Internetgeschwindigkeit und der aktuellen Ladung jeder der beiden Server kann das Herunterladen zwischen 5 Minuten und mehreren Stunden dauern:
ut fetch --dataset sedf_sc --out_dir data/sedf_sc --N_first 6
ut fetch --dataset dcsm --out_dir data/dcsm --N_first 6
Die Rohdaten, die wir in dieser Demo berücksichtigen werden, wurden jetzt heruntergeladen. Unser demo -Projektordner hat jetzt ungefähr die folgende Struktur:
└─ demo
├─ hyperparameters
└─ data
├─ dcsm
│ ├─ tp005f7e68_a084_46bb_9f0a_b6a084155a1c
│ │ ├─ hypnogram.ids
│ │ └─ psg.h5
│ ├─ ...
└─ sedf_sc
├─ SC4001E0
│ ├─ SC4001E0-PSG.edf
│ └─ SC4001EC-Hypnogram.edf
├─ ...
Bevor Sie das U-Sleep-Modell trainieren, teilen wir jeden Datensatz mit dem Befehl ut cv_split in feste Zug-/Validierungs-/Testaufentsachen auf. Der Befehl muss zweimal mit einem eindeutigen Parametern aufgerufen werden, in dem die Namenskonventionen des Datensatzes angegeben sind:
# 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
Beachten Sie, dass die Aufteilung von SEDF-SC pro Subjektbasis durchgeführt wird. Alle PSG -Datensätze aus demselben Thema werden in denselben Datensatz geteilt. Dies ist für DCSM nicht erforderlich, da alle Aufnahmen einzigartige Themen sind.
Bitte beachten Sie, dass Sie, wenn Sie die oben genannten Befehle an die Verwendung verschiedener Ausgabeverzeichnisnamen ändern, Pfade in Dataset hyperparameters/dataset_configurations -Dateien ändern müssen, die unter den nächsten Schritten unter den nächsten Schritten unter den nächsten Schritten gespeichert sind, die gespeichert sind.
Führen Sie den folgenden Befehl aus, um die Daten für das Training vorzubereiten:
ut preprocess --out_path data/processed_data.h5 --dataset_splits train_data val_data
Das ut preprocess -Skript lädt und verarbeitet alle Datensätze, wie in den Parametern in hyperparameters/hparams.yaml und alle datensatzspezifischen Dateien im Ordner hyperparameters/dataset_configurations festgelegt. Insbesondere lädt es die benötigten Kanäle (ignorieren Sie den Rest), Samples, skaliert und klammern die Daten, Kartenhypnogrammstufen in intergere Darstellungen, die im Training intern verwendet werden, und speichert schließlich die verarbeiteten Daten in einem HDF5-Archiv. Beim Training können Daten direkt aus diesem Archiv gestreamt werden, um den erforderlichen Systemspeicher erheblich zu reduzieren.
Es ist auch möglich, diesen Schritt alle zusammen zu überspringen und entweder 1) alle für das Training benötigten Daten im Voraus oder 2) zu streamen und während des Trainings die Vorverarbeitung während des Trainings anzuwenden, wie in der vollständigen Reproduktion von U-Sleep-Abschnitt unten gezeigt.
Wir können jetzt mit dem Training beginnen, indem wir den Befehl ut train aufrufen. Ein Standard-Optimierungs-Hyperparameter wurde vorgegeben und befindet sich in der hyperparameters/hparams.yaml Datei Ihres Projektverzeichnisses. In dieser Demo werden wir nur eine sehr kurze Trainingseinheit durchführen, aber Sie können gerne alle Parameter in der hparams.yaml -Datei ändert, wie Sie es für richtig halten. Führen Sie den folgenden Befehl aus:
ut train --num_gpus=1 --preprocessed --seed 123
Sie können den Parameter --num_gpus=1 im obigen Befehl ersetzen durch --num_gpus=0 Wenn Sie keine GPU zur Verfügung haben und auf der CPU trainieren möchten. Das Training auf CPU kann bis zu 30 Minuten dauern.
Nach dem Training wird im model eine Reihe von Kandidatenmodellen verfügbar sein. Unter Verwendung des besten beobachteten (höchsten Validierungsmittelwerts F1-Score) können wir die Testsätze von SEDF-SC und DCSM unter Verwendung aller Kanalkombinationen vorhersagen und die Mehrheitsstimmen berechnen, indem sie den folgenden ut predict aufrufen:
ut predict --num_gpus=1
--data_split test_data
--strip_func strip_to_match
--one_shot
--save_true
--majority
--out_dir predictions
Die vorhergesagten Hypnogramme sind jetzt unter predictions/test_data verfügbar. Lassen Sie uns schließlich eine globale Verwirrungsmatrix (über alle Probanden über alle Probanden berechnet) für Dataset sedf_sc ( sedf_sc -> dcsm für die DCSM -Bewertung ersetzen) ausdrucken:
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
Wenn Sie eine ähnliche Ausgabe wie die oben genannten erhalten haben, herzlichen Glückwunsch! Sie haben ein U-Sleep-Modell auf zwei verschiedenen Datensätzen erfolgreich installiert, konfiguriert, trainiert und bewertet.
Bitte beachten Sie::
Wenn Sie den obigen Code auf einer GPU ausgeführt haben, erhalten Sie möglicherweise nicht die hier aufgeführten Nummern, auch wenn Sie die Argumente -SEED angegeben haben. Dies liegt daran, dass einige Berechnungen, die während des Trainings von U-Sleep verwendet werden, grundsätzlich nicht deterministisch sind, wenn sie an einer GPU bewertet werden. Die Vorhersage der Verwendung eines geschulten U-Sleep-Modells ergibt jedoch deterministische Ausgänge.
Die Leistung des erhaltenen Demo -Modells ist sehr niedrig und nicht für die tatsächliche Schlafstagung geeignet. Der Grund dafür ist, dass wir U-Sleep in sehr begrenzten Daten und sehr begrenzten Epochen geschult haben. In der vollständigen Reproduktion des U-Sleep-Abschnitts finden Sie Informationen zur Vorbereitung und Ausbildung einer vollständigen Version von U-Sleep.
Die im Prinzip oben genannte Demo beschreibt alle Schritte, die zur Reproduktion von U-Sleep wie in [2] erforderlich sind. Der Haupt- und signifikante Unterschied besteht darin, dass Sie zum Reproduzieren des vollständigen Modells 1) zugreifen müssen. Möglicherweise benötigen Sie auch einen Computer mit mehr Ressourcen, wie in den Systemanforderungen beschrieben.
Wir haben unser Bestes getan, um diesen Prozess so einfach wie möglich zu gestalten. Sie sollten die folgenden Schritte ausführen:
ut fetch heruntergeladen werden. Bitte rufen Sie ut fetch --help auf, um eine aktuelle Liste zu sehen, von der Datensätze auf diese Weise heruntergeladen werden können.[LOCAL_PATH] mit 1 Unterordner für jeden Datensatz.ut extract , ut extract_hypno und ut cv_split auf allen Datensätzen aus, wie für jeden Datensatz separat in Dateien unter den Ordner resources/usleep_dataset_pred dieses Repositorys (ebenfalls hier gefunden) angegeben. Diese Befehle extrahieren und platzieren Daten in eine Ordnerstruktur und Format, die U-Time akzeptiert, sowie die Daten in Teilmengen aufzuteilen.ut extract wählt die relevanten Kanäle aus, probiere sie wieder auf 128 Hz und speichere die Daten in HDF5-Archiven. Die ursprünglichen Daten werden standardmäßig nicht gelöscht. Wenn Sie einen begrenzten festen Speicherplatz haben, sollten Sie die alten Dateien vor der Verarbeitung des nächsten Datensatzes entfernen.ut init --name u-sleep --model usleep .u-sleep/hyperparameters/dataset_configurations/ Ersetzen Sie die Zeichenfolge [local_path] durch den [LOCAL_PATH] Ihrer Daten. Wenn Sie über mehr als 40 GIB-Systemspeicher verfügbar sind, trainieren Sie U-Sleep mit dem folgenden Befehl:
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
Bei Systemen mit weniger Speicher können Sie entweder 1) den Parameter --max_loaded_per_dataset aus dem aktuellen 40 auf einen niedrigeren Wert reduzieren (dies hält weniger PSG -Datensätze im aktiven Speicherpool, wodurch die Zufälligkeit bei der Auswahl von Datensätzen verringert wird) oder 2) oder 2) oder 2). Verarbeiten Sie die Daten und Stream -Daten während des Trainings (wie in der Demo oben gezeigt), indem Sie die folgenden zwei Befehle aufrufen (ersetzen Sie [local_path] nach zutreffend):
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
Dadurch wird alle Vorverarbeitung angewendet, ein zum Streaming geeignetes Datenarchiv erstellt und U-Sleep mit Proben trainiert, die auf die Fliege von der Festplatte geladen wurden.
Aufgrund der enormen Größe des in Betracht gezogenen Datensatzes kann das Training von U-Sleep mit den Standardparametern sehr lange dauern. Wir empfehlen, die Lernrate zu erhöhen (von dem aktuellen 1e-7 bis z. 1e-6 ), es sei denn, Sie möchten den U-Sleep unter den genauen Bedingungen in [2] neu erstellen.
Sie können dieses Repository weiterhin verwenden, um das ältere U-Zeit-Modell zu trainieren. Im Folgenden zeigen wir ein End-to-End-Beispiel. Die unten aufgeführten Befehle erstellen einen Projektordner, lädt den Sleep-EDF-153-Datensatz herunter, passt und bewertet ein U-Time-Modell in einem festen Zug-/Val/Test-Datensatz-Split-Setup. Bitte beachten Sie, dass der folgende Code das Sleep-EDF-153-Experiment von [1] nicht reproduziert, da der 10-fache Lebenslauf verwendet wurde. Um ein CV -Experiment auszuführen, lesen Sie bitte die Befehle ut cv_split --help und ut cv_experiment --help .
# Erhalten Sie einen Datensatz für die öffentliche Schlafstaging
UT -Fetch -Datenet Sedf_Sc -Out_Dir Datasets/Sedf_Sc
# Erstellen Sie ein Fixed-Split-Experiment
ut cv_split - -data_dir 'datasets/sedf_sc'
-Subject_dir_Pattern 'sc*'
-Cv 1
-Validation_Fraction 0.20
-Test_fraction 0.20
-Subject_matching_regex 'sc4 ( d {2}).*'
-file_list
# Initialisieren Sie ein U-Time-Projekt
ut init -name my_utime_project
-Model utime
-DATA_DIR-Datensätze/Sedf_Sc/Ansichten/Fixed_Split
# Training beginnen
CD my_utime_project
UT Train --Num_gpus = 1-Channels 'EEG FPZ-CZ' '
# Vorhersage und bewerten
ut evaluate -out_dir eval --on_shot
# Drucken Sie eine Verwirrungsmatrix aus
UT CM -TRUE 'eval/test_data/dataset_1/files/*/true.npz'
--Pred 'eval/test_data/dataset_1/files/*/pred.npz'
# Drucken Sie die Subjekt-Zusammenfassungsstatistik drucken
UT -Zusammenfassung - -csv_pattern 'eval/test_data/*/evaluation_dice.csv'
-PRINT_ALL
# Schlafstufen für alle 3 Sekunden von 128 Hz Signal ausgeben
# Hier übereinstimmt der 'order_regex' 2 Dateien im Datensatz
UT Predict-older_regex '../datasets/sedf_sc/sc400..1-2 weibliche 0' '
-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
