U Time
1.0.0
Implementasi resmi
Repositori ini dapat digunakan untuk melatih model U-Sleep u-time dan yang lebih baru. Namun, repositori telah diperpanjang secara signifikan sejak [1] dan secara bertahap dapat menyimpang dari versi yang dijelaskan dalam [2]. Versi sebelumnya dapat ditemukan di:
Dokumen ini menjelaskan paket perangkat lunak resmi yang dikembangkan dan digunakan untuk membuat sistem pementasan tidur gratis dan publik U-Sleep [2]. U-Sleep adalah jaringan saraf dalam yang sepenuhnya konvolusional untuk pementasan tidur otomatis. Satu contoh model dapat dilatih untuk melakukan pementasan tidur yang akurat dan tangguh di berbagai populasi klinis dan protokol akuisisi polisomnografi (PSG).
Perangkat lunak ini memungkinkan pelatihan simultan U-Sleep di sejumlah dataset PSG menggunakan pemilihan acak konfigurasi saluran input secara acak. Ini fitur antarmuka baris perintah untuk menginisialisasi, melatih dan mengevaluasi model tanpa perlu memodifikasi basis kode yang mendasarinya.
Berikut ini kami akan memperkenalkan perangkat lunak di belakang U-Sleep secara lebih rinci. Harap dicatat bahwa:
Repositori ini menyimpan kode untuk melatih dan mengevaluasi model pementasan tidur tidur-U . Ini dibangun di atas dan secara signifikan memperluas repositori U-time kami, yang diterbitkan di Neurips 2019 [1]. Berikut ini, kami akan menggunakan istilah u-sleep untuk menunjukkan model pementasan tidur frekuensi tinggi yang tangguh [2], dan waktu-U untuk menunjukkan repositori kode yang digunakan untuk melatih dan mengevaluasi model tidur-U.
Anda masih dapat menggunakan repositori ini untuk melatih model U-time yang lebih tua, lihat contoh U-time di bawah ini.
Persyaratan perangkat keras minimal
Menggunakan model U-Sleep yang sudah terlatih untuk pementasan tidur biasanya dapat dilakukan pada laptop modern apa pun (tergantung pada persyaratan perangkat lunak yang tercantum di bawah).
Untuk melatih model u-sleep dari awal, kami sangat merekomendasikan menggunakan komputer berbasis Linux dengan setidaknya spesifikasi perangkat keras berikut:
Dimungkinkan untuk melatih model pada mesin yang lebih kecil, dan tanpa GPU, tetapi melakukannya mungkin membutuhkan waktu yang cukup lama. Demikian juga, lebih banyak sumber daya akan mempercepat pelatihan. Jika dataset yang dipertimbangkan melebihi memori sistem (misalnya 8 GIB RAM yang disarankan di atas), data harus diproses dan dialirkan dari disk seperti yang ditunjukkan pada bagian demo di bawah ini. Pada mesin yang lebih besar, orang dapat mengambil manfaat dari mempertahankan kumpulan data yang lebih besar yang dimuat dalam memori. Misalnya, kami melatih U-Sleep [2] menggunakan 8 core CPU, 1 GPU dan 40 GIB RAM, silakan merujuk ke reproduksi lengkap bagian U-Sleep di bawah ini.
*Ruang disk keras yang diperlukan tergantung pada jumlah dan ukuran dataset yang dipertimbangkan. Untuk reproduksi penuh U-Sleep sekitar 4 tib penyimpanan yang tersedia diperlukan.
Persyaratan Perangkat Lunak:
Jika Anda akan melatih model U-Sleep sendiri dari awal, kami sangat menyarankan melakukannya pada GPU. Untuk menggunakan paket U-Time dengan GPU, pustaka tensorflow ( v2.8.0 ) diperlukan. Untuk ini, perangkat lunak tambahan berikut diperlukan pada sistem Anda:
Silakan merujuk ke https://www.tensorflow.org/install/gpu untuk detail tambahan. Anda tidak perlu menginstal sendiri TensorFlow (lihat Panduan Instalasi di bawah), tetapi perangkat lunak di atas harus diinstal sebelum melanjutkan.
Pada mesin Linux dengan setidaknya 1 GPU yang diaktifkan CUDA tersedia dan anaconda atau miniconda diinstal, jalankan perintah berikut untuk mengunduh perangkat lunak, buat lingkungan Conda bernama u-sleep dan setup paket perangkat lunak U-Time terbaru dan ketergantungannya:
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/
Atau, Anda dapat menginstal paket dari PYPI (mungkin lebih jarang diperbarui):
pip install utime
Dalam berikut ini kami akan mendemonstrasikan cara meluncurkan sesi pelatihan singkat U-Sleep pada subset yang terbatas secara signifikan dari dataset yang digunakan dalam [2].
30 minutes untuk menyelesaikan pada komputer dan koneksi jaringan yang khas. Sebagian besar waktu ini adalah pengeluaran mengunduh data yang diperlukan dari database publik. Langkah ini mungkin memakan waktu lebih lama tergantung pada lalu lintas basis data saat ini.11 GiB ruang disk yang tersedia di komputer Anda. Pertama, kami membuat direktori proyek yang akan menyimpan semua data kami untuk demo ini. Perintah ut init akan membuat folder dan mengisinya dengan satu set nilai hyperparameter default:
ut init --name demo --model usleep_demo
Memasuki direktori proyek yang baru dibuat, kami akan menemukan folder yang menyimpan hyperparameters:
cd demo
ls
> hyperparameters
Kami akan mengunduh 6 studi PSG dari database tidur publik Sleep-EDF dan DCSM menggunakan perintah ut fetch . Anda akan membutuhkan sekitar 10 GiB ruang disk keras gratis untuk menyimpan file yang diunduh. Tergantung pada kecepatan internet Anda dan beban saat ini pada masing -masing dari dua server, unduhan mungkin memakan waktu dari 5 menit hingga beberapa jam:
ut fetch --dataset sedf_sc --out_dir data/sedf_sc --N_first 6
ut fetch --dataset dcsm --out_dir data/dcsm --N_first 6
Data mentah yang akan kami pertimbangkan dalam demo ini sekarang telah diunduh. Folder proyek demo kami sekarang memiliki kira -kira struktur berikut:
└─ demo
├─ hyperparameters
└─ data
├─ dcsm
│ ├─ tp005f7e68_a084_46bb_9f0a_b6a084155a1c
│ │ ├─ hypnogram.ids
│ │ └─ psg.h5
│ ├─ ...
└─ sedf_sc
├─ SC4001E0
│ ├─ SC4001E0-PSG.edf
│ └─ SC4001EC-Hypnogram.edf
├─ ...
Sebelum melanjutkan untuk melatih model U-Sleep, kami membagi setiap dataset menjadi kereta api tetap/validasi/uji split menggunakan perintah ut cv_split . Perintah harus dipanggil masing -masing dua kali dengan set parameter unik yang menentukan konvensi penamaan dataset:
# 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
Perhatikan bahwa pemisahan SEDF-SC dilakukan berdasarkan per subjek. Semua catatan PSG dari subjek yang sama akan ditempatkan ke dalam perpecahan dataset yang sama. Ini tidak diperlukan untuk DCSM karena semua rekaman adalah subjek yang unik.
Perlu diketahui bahwa jika Anda memodifikasi salah satu perintah di atas untuk EG menggunakan nama direktori output yang berbeda, Anda perlu memodifikasi jalur dalam file hyperparameter dataset yang disimpan di bawah hyperparameters/dataset_configurations yang sesuai sebelum proseding dengan langkah selanjutnya.
Jalankan perintah berikut untuk menyiapkan data untuk pelatihan:
ut preprocess --out_path data/processed_data.h5 --dataset_splits train_data val_data
Skrip ut preprocess memuat dan memproses semua dataset seperti yang dijelaskan oleh parameter yang diatur dalam hyperparameters/hparams.yaml dan semua file khusus dataset di folder hyperparameters/dataset_configurations . Secara khusus, memuat saluran yang dibutuhkan (mengabaikan sisanya), sampel ulang, skala dan klip data, memetakan tahapan hipnogram untuk mengganggu representasi yang digunakan secara internal selama pelatihan dan akhirnya menyimpan data yang diproses ke arsip HDF5. Saat pelatihan, data dapat dialirkan langsung dari arsip ini untuk secara signifikan mengurangi memori sistem yang diperlukan.
Dimungkinkan juga untuk melewatkan langkah ini bersama-sama dan salah satu 1) memuat semua data yang diperlukan untuk pelatihan di muka, atau 2) streaming dan menerapkan preprocessing on-the-lalat selama pelatihan seperti yang ditunjukkan dalam reproduksi penuh bagian tidur-u di bawah ini.
Kita sekarang dapat memulai pelatihan dengan memohon perintah ut train . Satu set default optimasi hyperparameters telah ditentukan sebelumnya dan terletak di file hyperparameters/hparams.yaml dari direktori proyek Anda. Dalam demo ini, kami hanya akan menjalankan sesi pelatihan yang sangat singkat, tetapi jangan ragu untuk memodifikasi parameter apa pun dalam file hparams.yaml sesuai keinginan Anda. Jalankan perintah berikut:
ut train --num_gpus=1 --preprocessed --seed 123
Anda dapat mengganti parameter --num_gpus=1 dalam perintah di atas dengan --num_gpus=0 jika Anda tidak memiliki GPU yang tersedia, dan ingin berlatih di CPU. Pelatihan CPU dapat memakan waktu hingga 30 menit.
Setelah pelatihan, satu set model kandidat akan tersedia dalam model folder. Menggunakan yang terbaik yang diamati (skor f1 validasi tertinggi), kami dapat memprediksi pada set pengujian kedua SEDF-SC dan DCSM menggunakan semua kombinasi saluran serta menghitung suara mayoritas dengan memanggil perintah ut predict berikut:
ut predict --num_gpus=1
--data_split test_data
--strip_func strip_to_match
--one_shot
--save_true
--majority
--out_dir predictions
Hipnogram yang diprediksi sekarang tersedia di bawah predictions/test_data . Akhirnya, mari kita mencetak matriks kebingungan global (dihitung di semua subjek) untuk dataset sedf_sc (ganti sedf_sc -> dcsm untuk evaluasi 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
Jika Anda menerima output yang mirip dengan yang di atas, selamat! Anda telah berhasil menginstal, dikonfigurasi, dilatih, dan mengevaluasi model tidur-U pada dua dataset yang berbeda.
Harap dicatat bahwa:
Jika Anda menjalankan kode di atas pada GPU, Anda mungkin tidak mendapatkan nomor yang sama persis yang tercantum di sini, bahkan jika Anda menentukan argumen -leed. Ini karena beberapa perhitungan yang digunakan selama pelatihan U-Sleep pada dasarnya non-deterministik ketika dievaluasi pada GPU. Namun, memprediksi menggunakan model tidur-U yang terlatih akan memberikan output deterministik.
Kinerja model demo yang diperoleh sangat rendah dan tidak cocok untuk pementasan tidur yang sebenarnya. Alasannya adalah bahwa kami melatih U-Sleep pada set data yang sangat terbatas dan untuk jumlah zaman yang sangat terbatas. Silakan merujuk ke reproduksi lengkap bagian U-Sleep untuk detail tentang cara menyiapkan dan melatih versi lengkap U-Sleep.
Demo di atas pada prinsipnya menggambarkan semua langkah yang diperlukan untuk mereproduksi tidur-U seperti yang dilaporkan dalam [2]. Perbedaan utama - dan signifikan adalah bahwa untuk mereproduksi model lengkap, Anda harus 1) dapat mengakses 2) unduh dan 3) preprocess semua set data yang diperlukan. Anda juga mungkin memerlukan komputer dengan lebih banyak sumber daya seperti yang dijelaskan dalam persyaratan sistem.
Kami melakukan yang terbaik untuk membuat proses ini semudah mungkin. Anda harus mengambil langkah -langkah berikut:
ut fetch . Silakan memohon ut fetch --help untuk melihat daftar terkini dari dataset mana yang dapat diunduh dengan cara ini.[LOCAL_PATH] dengan 1 sub-folder untuk setiap dataset.ut extract , ut extract_hypno , dan ut cv_split pada semua dataset sebagaimana ditentukan untuk setiap dataset secara terpisah dalam file di bawah Folder resources/usleep_dataset_pred dari repositori ini (juga ditemukan di sini). Perintah-perintah ini akan mengekstraksi dan menempatkan data ke dalam struktur-folder dan format yang diterima U-Time, serta membagi data menjadi subset.ut extract akan memilih saluran yang relevan, sampel ulang ke 128 Hz dan menyimpan data di arsip HDF5. Data asli tidak akan dihapus secara default. Jika Anda memiliki ruang hard-drive yang terbatas, pertimbangkan untuk menghapus file lama sebelum memproses dataset berikutnya.ut init --name u-sleep --model usleep .u-sleep/hyperparameters/dataset_configurations/ ganti string [local_path] dengan [LOCAL_PATH] data Anda. Jika Anda memiliki 40+ memori sistem Gib yang tersedia, latih u-sleep menggunakan perintah berikut:
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
Pada sistem dengan lebih sedikit memori, Anda dapat 1) mengurangi parameter --max_loaded_per_dataset dari 40 saat ini ke nilai yang lebih rendah (ini akan menyimpan lebih sedikit catatan PSG di kumpulan memori aktif, yang akan mengurangi keacakan saat memilih catatan), atau 2) Preprocess data dan stream data selama pelatihan (seperti yang ditunjukkan dalam demo di atas) dengan memohon dua perintah berikut (mengganti [Local_path] sebagaimana berlaku):
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
Ini akan menerapkan semua preprocessing, membuat arsip data yang cocok untuk streaming, dan melatih U-Sleep menggunakan sampel yang dimuat secara langsung dari disk.
Karena ukuran besar dari dataset yang dipertimbangkan, pelatihan u-sleep dengan parameter default mungkin memakan waktu sangat lama. Kami menyarankan untuk meningkatkan tingkat pembelajaran (dari 1e-7 saat ini ke misalnya 1e-6 ) kecuali Anda ingin membuat kembali tidur-u dalam kondisi yang tepat yang dipertimbangkan dalam [2].
Anda masih dapat menggunakan repositori ini untuk melatih model U-time yang lebih tua. Berikut ini kami menunjukkan contoh ujung ke ujung. Perintah yang tercantum di bawah ini menyiapkan folder proyek, mengunduh dataset tidur-edf-153, cocok dan mengevaluasi model U-time dalam pengaturan split train/val/test dataset tetap. Harap dicatat bahwa kode di bawah ini tidak mereproduksi eksperimen tidur-EDF-153 [1] karena 10 kali lipat CV digunakan. Untuk menjalankan eksperimen CV, silakan merujuk ke ut cv_split --help dan ut cv_experiment --help .
# Dapatkan dataset pementasan tidur publik
UT fetch --Cataset SEDF_SC -O -OUT_DIR Dataset/SEDF_SC
# Siapkan eksperimen tetap-split
UT CV_SPLIT --Data_Dir 'Datasets/Sedf_sc'
---ubject_dir_pattern 'sc*'
--Cv 1
--Validation_fraction 0.20
---test_fraction 0.20
--subject_matching_regex 'sc4 ( d {2}).*'
--File_list
# Inisialisasi proyek U-time
UT init --Name my_utime_project
-Model Utime
--Data_dir Dataset/SEDF_SC/Views/Fixed_split
# Mulai pelatihan
CD my_utime_project
UT Train ---Mum_GPUS = 1-saluran 'EEG FPZ-CZ'
# Prediksi dan evaluasi
UT EVALUASI -UJ
# Cetak matriks kebingungan
ut cm --true 'eval/test_data/dataset_1/file/*/true.npz'
--pred 'eval/test_data/dataset_1/file/*/pred.npz'
# Cetak statistik ringkasan per subjek
Ringkasan UT --CSV_PATER 'EVAL/TEST_DATA/*/EVALUASI_DICE.CSV'
--print_all
# Keluaran tahap tidur untuk setiap 3 detik dari sinyal 128 Hz
# Di sini, 'folder_regex' cocok dengan 2 file dalam dataset
UT prediksi --folder_regex '../datasets/sedf_sc/sc400uarkan
--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
