U Time
1.0.0
공식 구현
이 저장소는 원래 U-Time 및 새로운 U-Sleep 모델을 모두 훈련시키는 데 사용될 수 있습니다. 그러나 저장소는 [1] 이후 크게 확장되었으며 [2]에 설명 된 버전에서 점차 분기 될 수 있습니다. 이전 버전은 다음에서 찾을 수 있습니다.
이 문서는 무료 및 공개 수면 준비 시스템 U-Sleep 를 위해 개발되고 사용되는 공식 소프트웨어 패키지를 설명합니다 [2]. U-Sleep은 자동화 된 수면 준비를위한 완전 컨볼 루션 깊은 신경망입니다. 모델의 단일 인스턴스는 광범위한 임상 집단 및 PSG (Polysomnography) 획득 프로토콜에 걸쳐 정확하고 탄력적 인 수면 준비를 수행하도록 훈련 될 수 있습니다.
이 소프트웨어를 사용하면 입력 채널 구성의 온라인 임의 선택을 사용하여 수많은 PSG 데이터 세트에서 U-Sleep을 동시에 교육 할 수 있습니다. 기본 코드베이스를 수정할 필요없이 모델을 초기화, 교육 및 평가하기위한 명령 줄 인터페이스가 특징입니다.
다음에서는 U-Sleep 뒤에있는 소프트웨어를 더 자세히 소개합니다. 참조하십시오 :
이 저장소는 U-Sleep Sleep Staging 모델 교육 및 평가를위한 코드를 저장합니다. Neurips 2019 [1]에 게시 된 U- 시간 저장소를 기반으로하고 확장합니다. 다음에서, 우리는 U-Sleep 라는 용어를 사용하여 탄력적 인 고주파 수면 준비 모델 [2]을 나타내고 U-time을 사용하여 U-Sleep 모델을 훈련하고 평가하는 데 사용되는이 코드 저장소를 나타냅니다.
이 저장소를 사용하여 이전 U- 시간 모델을 훈련시킬 수 있습니다. 아래 U- 시간 예제를 참조하십시오.
최소 하드웨어 요구 사항
수면 준비를 위해 이미 훈련 된 U-Sleep 모델을 사용하는 것은 일반적으로 현대 랩톱에서 수행 될 수 있습니다 (아래 나열된 소프트웨어 요구 사항에 따라).
그러나 U-Sleep 모델을 처음부터 교육하려면 다음과 같은 하드웨어 사양이있는 Linux 기반 컴퓨터를 사용하는 것이 좋습니다.
소규모 기계에서 모델을 훈련시킬 수 있으며 GPU가 없지만 그렇게하는 데 상당한 시간이 걸릴 수 있습니다. 마찬가지로, 더 많은 자원이 교육 속도를 높일 것입니다. 고려 된 데이터 세트가 시스템 메모리를 초과하는 경우 (예 : 위에서 제안한 RAM의 8 gib), 아래 데모 섹션에 표시된대로 데이터를 전처리하고 디스크에서 스트리밍해야합니다. 더 큰 기계에서는 메모리에로드 된 더 큰 데이터 풀을 유지하는 것이 좋습니다. 예를 들어, 우리는 8 개의 CPU 코어, 1 GPU 및 40 개의 gib를 사용하여 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를 사용할 수 있고 anaconda 또는 miniconda 설치된 Linux 시스템에서 다음 명령을 실행하여 소프트웨어를 다운로드하고 u-sleep 이라는 콘다 환경을 만들고 최신 U- 타임 소프트웨어 패키지 및 해당 종속성을 설정하십시오.
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 명령을 사용하여 공개 수면 데이터베이스 Sleep-EDF 및 DCSM에서 6 개의 PSG 연구를 다운로드 할 것입니다. 다운로드 된 파일을 저장하려면 약 10 GiB 무료 하드 디스크 공간이 필요합니다. 인터넷 속도와 두 서버 각각의 현재로드에 따라 다운로드에는 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 에는 필요하지 않습니다.
위의 명령 중 하나를 예를 들어 다른 출력 디렉토리 이름을 사용하도록 위의 명령을 수정하면 다음 단계로 절차하기 전에 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 의 모든 데이터 세트 별 파일에 의해 설명 된 모든 데이터 세트를로드하고 처리합니다. 구체적으로, 필요한 채널 (나머지 무시), 리 샘플, 스케일링 및 클립을로드하고 최면 단계를 훈련 중에 내부적으로 사용하는 중간 표현에 hypnogram 단계를 맵핑하고 처리 된 데이터를 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
위와 비슷한 출력을 받았다면 축하합니다! 두 개의 다른 데이터 세트에 U-Sleep 모델을 성공적으로 설치, 구성, 교육 및 평가했습니다.
참조하십시오 :
GPU에서 위 코드를 실행 한 경우 -seed 인수를 지정하더라도 여기에 나열된 숫자를 얻지 못할 수 있습니다. U-Sleep 훈련 중에 사용 된 일부 계산은 GPU에서 평가 될 때 근본적으로 비 결정적이기 때문입니다. 그러나 훈련 된 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 (여기에서도 찾을 수 있음). 이러한 명령은 데이터를 폴더 구조와 UTIE가 허용하는 형식으로 추출하고 배치 할뿐만 아니라 데이터를 서브 세트로 분할합니다.ut extract 명령은 관련 채널을 선택하고 128Hz로 다시 샘플링하고 데이터를 HDF5 아카이브에 저장합니다. 원래 데이터는 기본적으로 삭제되지 않습니다. 하드 드라이브 공간이 제한된 경우 다음 데이터 세트를 처리하기 전에 이전 파일을 제거하는 것이 좋습니다.ut init --name u-sleep --model usleep .u-sleep/hyperparameters/dataset_configurations/ 의 각 데이터 세트 구성 파일에 대해 문자열 [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을 훈련하는 데 매우 오래 걸릴 수 있습니다. [2]에서 고려 된 정확한 조건에서 U-Sleep을 다시 만들려고하지 않는 한 (현재 1e-7 에서 예를 들어 1e-6 으로 학습 속도를 증가시키는 것이 좋습니다.
이 저장소를 사용하여 이전 U- 시간 모델을 훈련시킬 수 있습니다. 다음에서는 엔드 투 엔드 예제를 보여줍니다. 아래에 나열된 명령은 프로젝트 폴더를 준비하고 Sleep-EDF-153 데이터 세트를 다운로드하고 고정 된 Train/VAL/Test DataSet 분할 설정에서 U- 시간 모델을 맞추고 평가합니다. 아래 코드는 10 배 CV가 사용되었으므로 [1]의 수면 -EDF-153 실험을 재현하지 않습니다. CV 실험을 실행하려면 ut cv_split --help 및 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}).*'
-파일 _list
# u-time 프로젝트 초기화
ut init---- 이름 my_utime_project
-모델 utime
---data_dir 데이터 세트/sedf_sc/views/고정 _split
# 훈련 시작
cd my_utime_project
UT Train ---NUM_GPUS = 1-채널 'EEG FPZ-CZ'
# 예측 및 평가
UT 평가 -out_dir eval -one_shot
# 혼란 매트릭스를 인쇄하십시오
ut cm -true 'atal/test_data/dataset_1/files/*/true.npz'
-pred 'Eval/test_data/dataset_1/files/*/pred.npz'
# 개체 당 요약 통계를 인쇄합니다
UT 요약 -CSV_PATTERN 'EVAT/TEST_DATA/*/EVATUATION_DICE.CSV'
--print_all
# 128 Hz 신호의 3 초마다 출력 수면 단계
# 여기, 'folder_regex'는 데이터 세트의 2 개의 파일과 일치합니다.
UT 예측-folder_regex '../datasets/sedf_sc/sc400] 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
