U Time
1.0.0
の公式実装
このリポジトリは、元のU-Timeと新しいU-Sleepモデルの両方をトレーニングするために使用できます。ただし、[2]で説明されているバージョンから徐々に分岐する可能性がある[1]以来、リポジトリは大幅に拡張されています。以前のバージョンは、次のように見つけることができます。
このドキュメントでは、無料および公共の睡眠ステージングシステムのために開発され、使用される公式ソフトウェアパッケージについて説明します[2]。 U-Sleepは、自動化された睡眠のステージングのための完全に畳み込み深い神経ネットワークです。モデルの単一のインスタンスは、幅広い臨床集団とポリソムノグラフィ（PSG）の獲得プロトコルにわたって正確で回復力のある睡眠のステージングを実行するようにトレーニングすることができます。
このソフトウェアにより、入力チャネル構成のオンザフライランダム選択を使用して、任意の数のPSGデータセットにわたってUスリープの同時トレーニングが可能になります。基礎となるコードベースを変更する必要なく、モデルを初期化、トレーニング、評価するためのコマンドラインインターフェイスを備えています。
以下では、U-Sleepの背後にあるソフトウェアを詳細に紹介します。注意してください：
このリポジトリは、 U-Sleep Sleepステージングモデルをトレーニングおよび評価するためのコードを保存します。 Neurips 2019 [1]で公開されているU-Timeリポジトリの上に構築され、大幅に拡張されています。以下では、 U-Sleepという用語を使用して、回復力のある高周波睡眠段階モデル[2]を示し、U-Sleepモデルのトレーニングと評価に使用されるこのコードのリポジトリを示すためにU-Timeを示します。
このリポジトリを使用して、古いU-Timeモデルをトレーニングすることができます。以下のU-Timeの例を参照してください。
最小限のハードウェア要件
睡眠段階のために既に訓練されたU-Sleepモデルを使用することは、通常、最新のラップトップで行われる場合があります（以下にリストされているソフトウェア要件の対象となります）。
ただし、U-Sleepモデルをゼロからトレーニングするには、少なくとも次のハードウェア仕様でLinuxベースのコンピューターを使用することを強くお勧めします。
小規模なマシンでモデルを訓練することは可能ですが、GPUなしでは可能ですが、そうすることにはかなりの時間がかかる場合があります。同様に、より多くのリソースがトレーニングをスピードアップします。考慮されたデータセットがシステムメモリ（上記の提案された8ギブのRAMなど）を超える場合、以下のデモセクションで示されているように、データをディスクから前処理およびストリーミングする必要があります。大規模なマシンでは、メモリにロードされたより大きなデータプールを維持することで恩恵を受けることができます。たとえば、8つのCPUコア、1つのGPU、40 GIBのRAMを使用してU-Sleep [2]を訓練しました。以下のU-Sleepセクションの完全な複製を参照してください。
*必要なハードディスクスペースは、考慮されるデータセットの数とサイズに依存します。 U-Sleepの完全な複製には、約4つのTIBの利用可能なストレージが必要です。
ソフトウェア要件：
自分でU-Sleepモデルをゼロから訓練する場合は、GPUでそうすることを強くお勧めします。 GPUでU-Timeパッケージを使用するには、 tensorflow （ v2.8.0 ）ライブラリが必要です。このために、システムには次の追加ソフトウェアが必要です。
詳細については、https：//www.tensorflow.org/install/gpuを参照してください。 Tensorflowを自分でインストールする必要はありません（以下のインストールガイドを参照）が、上記のソフトウェアを進める前にインストールする必要があります。
少なくとも1つのCUDA対応GPUを使用できるLinuxマシンで、 anacondaまたはminicondaがインストールされている場合、次のコマンドを実行してソフトウェアをダウンロードし、 u-sleepという名前のコンドラ環境を作成し、最新のU-Timeソフトウェアパッケージとその依存関係をセットアップします。
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/
または、Pypiからパッケージをインストールすることもできます（更新頻度が低下する場合があります）。
pip install utime
このフォローでは、[2]で使用されているデータセットの大幅に限られたサブセットでU-Sleepの短いトレーニングセッションを開始する方法を示します。
30 minutesかかります。この時間の大部分は、パブリックデータベースから必要なデータをダウンロードするのに費やすことです。このステップは、現在のデータベーストラフィックに応じて大幅に時間がかかる場合があります。11 GiB 。 まず、このデモのためにすべてのデータを保存するプロジェクトディレクトリを作成します。 ut initコマンドは、フォルダーを作成し、デフォルトのハイパーパラメーター値のセットでそれを入力します。
ut init --name demo --model usleep_demo
新しく作成されたプロジェクトディレクトリに入力すると、ハイパーパラメーターを保存するフォルダーがあります。
cd demo
ls
> hyperparameters
ut fetchコマンドを使用して、Public SleepデータベースSleep-EDFおよびDCSMから6つのPSG研究をダウンロードします。ダウンロードしたファイルを保存するには、約10 GiBの無料のハードディスクスペースが必要です。インターネットの速度と2つのサーバーのそれぞれの現在の負荷に応じて、ダウンロードは5分から複数時間かかる場合があります。
ut fetch --dataset sedf_sc --out_dir data/sedf_sc --N_first 6
ut fetch --dataset dcsm --out_dir data/dcsm --N_first 6
このデモで考慮する生データがダウンロードされました。 demoプロジェクトフォルダーには、ほぼ次の構造があります。
└─ demo
├─ hyperparameters
└─ data
├─ dcsm
│ ├─ tp005f7e68_a084_46bb_9f0a_b6a084155a1c
│ │ ├─ hypnogram.ids
│ │ └─ psg.h5
│ ├─ ...
└─ sedf_sc
├─ SC4001E0
│ ├─ SC4001E0-PSG.edf
│ └─ SC4001EC-Hypnogram.edf
├─ ...
U-Sleepモデルのトレーニングに進む前に、 ut cv_splitコマンドを使用して、各データセットを固定トレーニング/検証/テストスプリットに分割します。コマンドは、データセットの命名規則を指定する一意のパラメーターセットを使用して、それぞれ2回呼び出す必要があります。
# 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
SEDF-SCの分割は、被験者ごとに実行されることに注意してください。同じ主題からのすべてのPSGレコードは、同じデータセット分割に配置されます。すべての録音はユニークな主題であるため、これはDCSMには必要ありません。
上記のコマンドのいずれかを変更して、異なる出力ディレクトリ名を使用するように変更する場合は、次のステップで手順を処理する前に、必要に応じてhyperparameters/dataset_configurations下に保存されているデータセットハイパーパラメーターファイルのパスを変更する必要があることに注意してください。
次のコマンドを実行して、トレーニング用のデータを準備します。
ut preprocess --out_path data/processed_data.h5 --dataset_splits train_data val_data
ut preprocessスクリプトは、 hyperparameters/hparams.yamlおよびFolder hyperparameters/dataset_configurationsのすべてのデータセット固有のファイルで設定されたパラメーターで説明されているように、すべてのデータセットをロードおよび処理します。具体的には、必要なチャネル（残りを無視する）、再サンプリング、スケール、およびクリップをロードし、トレーニング中に内部で使用されるインターガー表現に誇張されたステージをマップし、最後に処理されたデータをHDF5アーカイブに保存します。トレーニングの場合、必要なシステムメモリを大幅に削減するために、このアーカイブからデータを直接ストリーミングできます。
また、このステップをすべてスキップし、 1）前にトレーニングに必要なすべてのデータをロードするか、 2）以下のU-Sleepセクションの完全な複製に示すように、トレーニング中にプリプロシングをフライでストリーミングして適用することもできます。
ut trainコマンドを呼び出すことで、トレーニングを開始することがあります。最適化ハイパーパラメーターのデフォルトセットが事前に指定されており、プロジェクトディレクトリのhyperparameters/hparams.yamlファイルにあります。このデモでは、非常に短いトレーニングセッションのみを実行しますが、 hparams.yamlファイルのパラメーターを自由に変更してください。次のコマンドを実行します。
ut train --num_gpus=1 --preprocessed --seed 123
上記のコマンドの--num_gpus=1パラメーターを、GPUを使用できない場合は--num_gpus=0で置き換えて、CPUでトレーニングしたい場合があります。 CPUでのトレーニングには最大30分かかる場合があります。
トレーニングに続いて、候補モデルのセットがフォルダーmodelで利用可能になります。観察された最良のもの（最高の検証平均F1スコア）を使用して、すべてのチャネルの組み合わせを使用してSEDF-SCとDCSMの両方のテストセットと、次のut predictコマンドを呼び出して多数票を計算することを予測することができます。
ut predict --num_gpus=1
--data_split test_data
--strip_func strip_to_match
--one_shot
--save_true
--majority
--out_dir predictions
予測された催眠術は、ディレクトリpredictions/test_dataで利用可能になりました。最後に、データセットsedf_sc （DCSM評価のためにsedf_sc > 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
上記と同様の出力を受け取った場合は、おめでとうございます！ 2つの異なるデータセットでU-Sleepモデルをインストール、構成、トレーニング、評価に成功しました。
注意してください：
上記のコードをGPUで実行した場合、-seedの引数を指定したとしても、ここにリストされているまったく同じ数字を取得できない場合があります。これは、Uスリープのトレーニング中に使用される一部の計算は、GPUで評価された場合、基本的に非決定論的であるためです。ただし、訓練されたUスリープモデルを使用して予測すると、決定論的な出力が得られます。
取得したデモモデルのパフォーマンスは非常に低く、実際の睡眠のステージングには適していません。その理由は、私たちが非常に限られたデータセットでU-Sleepを訓練し、非常に限られた数の時代のために訓練したからです。 U-Sleepの完全なバージョンの準備とトレーニングの方法の詳細については、U-Sleepセクションの完全な複製を参照してください。
上記のデモは、[2]で報告されているように、Uスリープを再現するために必要なすべての手順を説明しています。主な違いは、完全なモデルを再現するには、1）アクセスできる必要があることです。また、システム要件に記載されているように、より多くのリソースを備えたコンピューターが必要になる場合があります。
このプロセスを可能な限り簡単にするために最善を尽くしました。次の手順を実行する必要があります。
ut fetchコマンドを使用して簡単にダウンロードできます。 ut fetch --helpを呼び出して、この方法でダウンロードできるデータセットの最新リストを確認してください。[LOCAL_PATH]に配置します。resources/usleep_dataset_predの下のファイルで各データセットに個別に指定されているすべてのデータセットでut extract 、 ut extract_hypno 、およびut cv_splitを実行します（ここにもあります）。これらのコマンドは、データをUT-Timeが受け入れるフォルダー構造と形式に抽出して配置し、データをサブセットに分割します。ut extractコマンドは、関連するチャネルを選択し、それらを128 Hzに再サンプリングし、HDF5アーカイブにデータを保存します。元のデータはデフォルトで削除されません。ハードドライブスペースが限られている場合は、次のデータセットを処理する前に古いファイルを削除することを検討してください。ut init --name u-sleep --model usleep 。u-sleep/hyperparameters/dataset_configurations/文字列[local_path]をデータの[LOCAL_PATH]に置き換えます。 40個以上のGIBシステムメモリを利用できる場合は、次のコマンドを使用してUスリープを訓練します。
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
メモリが少ないシステムでは、1） --max_loaded_per_datasetパラメーターを現在の40から低い値に減らすことができます（これにより、アクティブメモリプールのPSGレコードが少なくなり、レコードを選択するとランダム性が低下します）、または2）次の2つのコマンドを呼び出すことにより（上記のデモで示されているように）、トレーニング中にデータとストリーミングのデータを事前に処理します（該当する場合は[local_path]を置き換えます）。
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
これにより、すべての前処理が適用され、ストリーミングに適したデータアーカイブが作成され、ディスクからオンザフライでロードされたサンプルを使用してUスリープをトレーニングします。
考慮されるデータセットのサイズが膨大であるため、デフォルトのパラメーターでUスリープをトレーニングするには非常に時間がかかる場合があります。 [2]で検討されている正確な条件下でu-sleepを再現しようとしない限り、学習率を（現在の1e-7からEg 1e-6に）増加させることをお勧めします。
このリポジトリを使用して、古いU-Timeモデルをトレーニングできます。以下では、エンドツーエンドの例を示します。以下にリストされているコマンドは、プロジェクトフォルダーを準備し、Sleep-EDF-153データセットをダウンロードし、固定列車/VAL/テストデータセットの分割セットアップでU-Timeモデルに適合して評価します。以下のコードでは、[1]の睡眠EDF-153の実験が10倍のCVを使用したことに注意してください。 CV実験を実行するには、 ut cv_split --help and ut cv_experiment --helpコマンドを参照してください。
＃公開睡眠ステージングデータセットを取得します
ut fetch - dataset sedf_sc -out_dir datasets/sedf_sc
＃固定分割実験を準備します
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
＃U-Timeプロジェクトを初期化します
ut init -name my_utime_project
- モデルutime
-data_dirデータセット/sedf_sc/views/sixt_split
＃トレーニングを開始します
CD my_utime_project
UTトレイン-NUM_GPUS = 1 -Channels 'EEG FPZ-CZ'
＃予測と評価
UT Evaluate -out_dir eval -one_shot
＃混乱マトリックスを印刷します
ut cm -true 'eval/test_data/dataset_1/files/*/true.npz'
-pred 'eval/test_data/dataset_1/files/*/pred.npz'
＃被験者ごとの概要統計を印刷します
ut summary - csv_pattern 'eval/test_data/*/evaluation_dice.csv'
-print_all
＃128 Hz信号の3秒ごとに出力睡眠段階
＃ここで、「Folder_Regex」はデータセット内の2つのファイルと一致します
UT PREDICE -FOLDER_REGEX '../DATASETS/SEDF_SC/SC400 [1-2] e0'
-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
