U Time
1.0.0
官方實施
該存儲庫可用於培訓原始的U時間和更新的U-Sleep型號。但是，自[1]以來，存儲庫已顯著擴展，並且可能逐漸與[2]中描述的版本逐漸不同。可以找到早期版本：
本文檔介紹了為免費和公共睡眠期的系統U-Sleep開發和用於創建的官方軟件包[2]。 U-Sleep是一個完全卷積的深度神經網絡，用於自動睡眠階段。該模型的一個實例可以訓練，以在廣泛的臨床人群和多個術語（PSG）採集方案中進行準確且有彈性的睡眠分期。
該軟件允許使用輸入通道配置的隨機選擇在任意數量的PSG數據集中同時培訓U-Sleep。它具有用於初始化，培訓和評估模型的命令行接口，而無需修改基礎代碼庫。
在下文中，我們將更詳細地介紹U-Sleep背後的軟件。請注意：
該存儲庫存儲用於培訓和評估U-Sleep睡眠分期模型的代碼。它基於並大大擴展了我們的U時間存儲庫，該存儲庫在2019年Neurips [1]上發表。在下文中，我們將使用u-Sleep一詞來表示彈性的高頻睡眠分期模型[2]，並表示u Time表示該存儲庫，用於訓練和評估U-Sleep模型。
您仍然可以使用此存儲庫來訓練較舊的U時間模型，請參見下面的U時間示例。
最小的硬件要求
使用已經訓練的U-Sleep模型進行睡眠分期，通常可以在任何現代筆記本電腦上完成（遵守下面列出的軟件要求）。
但是，對於從頭開始培訓U-Sleep模型，我們強烈建議使用至少具有以下硬件規格的基於Linux的計算機：
可以在較小的機器上訓練模型，而沒有GPU，但是這樣做可能需要大量時間。同樣，更多的資源將加快培訓。如果考慮的數據集超過了系統內存（例如上面建議的8個RAM的GIB），則必須從磁盤進行預處理並流從磁盤進行流，如下面的演示部分所示。在較大的計算機上，可以通過維護內存中加載的較大數據池受益。例如，我們使用8個CPU內核，1 GPU和40 GIB RAM訓練了U-Sleep [2]，請參閱下面的U-Sleep部分的完整復製品。
*所需的硬盤空間取決於所考慮的數據集的數量和大小。為了完全複製U-Sleep，需要大約4個可用的存儲空間。
軟件要求：
如果您要自己從頭開始訓練U-Sleep模型，我們強烈建議您在GPU上這樣做。為了將U-Time軟件包與GPU一起使用，需要tensorflow （ v2.8.0 ）庫。為此，您的系統需要以下其他軟件：
有關更多詳細信息，請參閱https://www.tensorflow.org/install/gpu。您不需要自己安裝TensorFlow（請參閱下面的安裝指南），但是上述軟件必須在繼續之前安裝。
在具有至少1個CUDA啟用GPU的Linux計算機上，安裝了anaconda或miniconda ，請運行以下命令以下載軟件，創建一個名為u-sleep的Conda環境，並設置了最新的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命令從公共睡眠數據庫和DCSM下載6個PSG研究。您將需要大約10 GiB的免費硬盤空間來存儲下載的文件。根據您的Internet速度和兩個服務器中每個服務器的當前負載，下載可能需要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命令將每個數據集分為固定的火車/驗證/測試拆分。必須使用一組唯一的參數調用命令，以指定數據集的命名約定：
# 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不需要這，因為所有錄音都是獨特的主題。
請注意，如果您將上述任何命令修改為EG使用不同的輸出目錄名稱，則需要修改數據集超參數文件中存儲在hyperparameters/dataset_configurations中的數據集超參數文件中的路徑，然後再處理下一步。
運行以下命令準備培訓數據：
ut preprocess --out_path data/processed_data.h5 --dataset_splits train_data val_data
ut preprocess腳本加載和處理所有數據集，如hyperparameters/hparams.yaml中設置的參數所述，以及文件夾hyperparameters/dataset_configurations中的所有數據集特定文件。具體而言，它加載了所需的通道（忽略其餘的），重新示例，縮放和剪輯數據，映射催眠階段到訓練期間內部使用的Interger表示，並最終將處理的數據保存到HDF5存檔中。當培訓時，數據可能直接從該存檔流傳輸，以大大減少所需的系統內存。
也可以整個步驟都跳過此步驟，然後加載前面訓練所需的所有數據，或者2）流媒體並在訓練過程中進行預處理，如下面的U-Sleep部分的完整復制所示。
現在，我們可以通過調用ut train命令開始培訓。一組默認的優化超參數已預先指定，並位於項目目錄的hyperparameters/hparams.yaml文件中。在此演示中，我們將僅進行一個非常簡短的培訓課程，但可以隨意修改hparams.yaml文件中的任何參數。運行以下命令：
ut train --num_gpus=1 --preprocessed --seed 123
如果您沒有GPU，則可以用--num_gpus=0替換上述命令中的--num_gpus=1參數，並希望在CPU上訓練。對CPU的培訓可能需要長達30分鐘。
訓練後，文件夾model將提供一組候選模型。使用觀察到的最佳一個（最高驗證平均F1得分），我們可以使用所有頻道組合以及通過調用以下ut predict命令來預測SEDF-SC和DCSM的測試集：計算多數票。
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打印一個全局混亂矩陣（跨所有主題計算）（替換sedf_sc > dcsm用於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
如果您收到的輸出與上述類似，請恭喜！您已經成功安裝，配置，訓練和評估了兩個不同數據集上的U-腿模型。
請注意：
如果您在GPU上運行了上述代碼，即使您指定了-seed參數，也可能無法獲得此處列出的完全相同的數字。這是因為在GPU上進行評估時，在U-Sleep訓練期間使用的某些計算是非確定性的。但是，預測使用訓練有素的U-Sleep模型將提供確定性的輸出。
獲得的演示模型的性能非常低，不適合實際睡眠分期。原因是我們在一組非常有限的數據和非常有限的時期訓練了U-Sleep。有關如何準備和培訓U-Sleep的完整版本的詳細信息，請參閱U-Sleep部分的完整復制。
上面的演示原則上描述了[2]中報導的重現U-Sleep所需的所有步驟。主要和重要的區別是，要重現完整的模型，您將需要1）能夠訪問2）下載和3）預處理所有所需的數據集。您可能還需要一台具有更多資源的計算機，如係統需求中所述。
我們盡力使這個過程盡可能容易。您應該採取以下步驟：
ut fetch命令輕鬆下載一些數據集。請調用ut fetch --help以查看可以通過這種方式下載哪些數據集的最新列表。[LOCAL_PATH]中。ut extract ， ut extract_hypno和ut cv_split在所有數據集上在文件夾resources/usleep_dataset_pred的文件中分別為每個數據集指定的所有數據集（也可以在此處找到）。這些命令將提取並將數據放入U Time接受的文件夾結構和格式中，並將數據分為子集。ut extract命令將選擇相關的頻道，將它們重新樣本為128 Hz，然後將數據存儲在HDF5檔案中。默認情況下不會刪除原始數據。如果您的硬盤驅動空間有限，請在處理下一個數據集之前考慮刪除舊文件。ut init --name u-sleep --model usleep 。u-sleep/hyperparameters/dataset_configurations/ instry [local_path]中的每個數據集配置文件，用數據的[LOCAL_PATH]替換。 如果您有40多個GIB系統內存，請使用以下命令訓練U-Sleep：
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）通過調用以下兩個命令（適用替換[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-Sleep。
由於考慮了數據集的巨大尺寸，因此使用默認參數的U-Sleep可能需要很長時間。我們建議提高學習率（從當前的1e-7增加到例如1e-6 ），除非您希望在[2]中考慮的確切條件下重新創建U-Sleep。
您仍然可以使用此存儲庫來訓練較舊的U時間模型。在下文中，我們將顯示一個端到端示例。下面列出的命令準備了一個項目文件夾，下載Sheep-ed-dyf-153數據集，在固定的火車/Val/test數據集拆分設置中擬合和評估U-Time模型。請注意，以下代碼不會重現[1]的Sleep-EDF-153實驗，因為使用了10倍CV。要運行簡歷實驗，請參閱ut cv_split --help和ut cv_experiment --help命令。
＃獲取公共睡眠分期數據集
ut提取-dataset sedf_sc -out_dir數據集/sedf_sc
＃準備固定切割實驗
ut cv_split -data_dir'數據集/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時間項目
ut init -name my_utime_project
- 模型utime
-data_dir數據集/sedf_sc/views/fixed_split
＃開始培訓
CD my_utime_project
UT火車-num_gpus = 1-通道'eeg fpz-cz'
＃預測和評估
UT評估 - OUT_DIR評估-One_shot
＃打印混亂矩陣
UT CM - true'eval/test_data/dataset_1/files/*/true.npz'
- pred'eval/test_data/dataset_1/files/*/pred.npz'
＃打印人數摘要統計數據
UT摘要-CSV_PATTERN'eval/test_data/*/evaluation_dice.csv'
-print_all
＃每3秒的128 Hz信號輸出睡眠階段
＃在這裡，“ folder_regex”匹配數據集中的2個文件
UT預測-folder_regex'../ datasets/sedf_sc/sc400 [1-2] e0'
-out_dir High_res_pred
-data_per_prediction 384
- 一個_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
