U Time
1.0.0
Официальная реализация
Этот репозиторий может быть использован для обучения оригинальных моделей U-времени и более новых U-Sleep. Тем не менее, репозиторий был значительно расширен с тех пор, как [1] и может постепенно расходиться с версией, описанной в [2]. Более ранние версии можно найти по адресу:
В этом документе описывается официальный программный пакет, разработанный для создания бесплатной и публичной системы постановки сна и Sleep Sleep [2]. U-Sleep-это полностью сверточная глубокая нейронная сеть для автоматической постановки сна. Один экземпляр модели может быть обучен для выполнения точной и устойчивой постановки сна в широком спектре клинических популяций и протоколов приобретения полисомнографии (PSG).
Это программное обеспечение позволяет одновременно обучать U-Sleep по любому количеству наборов данных PSG, используя случайный выбор конфигураций входных каналов. Он имеет интерфейс командной строки для инициализации, обучения и оценки моделей без необходимости изменения базовой кодовой базы.
Далее мы представим программное обеспечение более подробно. Обратите внимание, что:
Этот репозиторий хранит код для обучения и оценки модели постановки сна . Он опирается и значительно расширяет наш репозиторий U-времени, опубликованный на Neurips 2019 [1]. Далее мы будем использовать термин U-Sleep для обозначения устойчивой высокочастотной модели постановки сна [2] и U-времени для обозначения этого хранилища кода, используемого для обучения и оценки модели U-Sleep.
Вы все еще можете использовать этот репозиторий для обучения более старой модели U-времени, см. Пример U-времени ниже.
Минимальные требования к оборудованию
Использование уже обученной модели U-Sleep для постановки сна, как правило, можно выполнять на любом современном ноутбуке (в соответствии с требованиями программного обеспечения, перечисленными ниже).
Однако для обучения моделей U-Sleep с нуля мы настоятельно рекомендуем использовать компьютер на основе Linux, по крайней мере, со следующими характеристиками оборудования:
Можно обучить модель на небольших машинах и без графических процессоров, но это может занять значительное время. Кроме того, больше ресурсов ускорит обучение. Если рассматриваемый набор данных превышает системную память (например, 8 Gib of RAM, предложенные выше), данные должны быть предварительно обработаны и транслированы из диска, как показано в демо -разделе ниже. На более крупных машинах можно выиграть от поддержания большего пула данных, загруженных в памяти. Например, мы обучили U-Sleep [2], используя 8 ядер ЦП, 1 графический процессор и 40 Gib of Ram, пожалуйста, см. В полном размножении раздела U-Sleep ниже.
*Требуемое пространство жесткого диска зависит от числа и размеров рассмотренных наборов данных. Для полного воспроизведения U-Sleep примерно 4 Tib доступного хранилища необходимо.
Требования к программному обеспечению:
Если вы собираетесь тренировать модель U-Sleep самостоятельно с нуля, мы настоятельно рекомендуем сделать это на графическом процессоре. Чтобы использовать пакет U-Time с помощью графического процессора, требуется библиотека tensorflow ( v2.8.0 ). Для этого в вашей системе требуется следующее дополнительное программное обеспечение:
Пожалуйста, обратитесь к https://www.tensorflow.org/install/gpu для получения дополнительной информации. Вам не нужно устанавливать TensorFlow самостоятельно (см. Руководство по установке ниже), но вышеуказанное программное обеспечение должно быть установлено перед продолжением.
На машине Linux с доступным графическим процессором, по крайней мере, 1 CUDA, а также установлена anaconda или miniconda , запустите следующие команды для загрузки программного обеспечения, создайте среду Conda с именем 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
В этом следующем мы продемонстрируем, как запустить короткую тренировку U-Sleep на значительно ограниченном подмножестве наборов данных, используемых в [2].
30 minutes на типичное соединение компьютера и сети. Большая часть этого времени - тратить загрузку необходимых данных из общедоступных баз данных. Этот шаг может занять значительно дольше в зависимости от текущего трафика базы данных.11 GiB доступного дискового пространства на вашем компьютере. Во -первых, мы создаем каталог проектов, который будет хранить все наши данные для этой демонстрации. Команда ut init создаст папку и заполнит ее набором значений гиперпараметра по умолчанию:
ut init --name demo --model usleep_demo
Ввод в недавно созданный каталог проектов, мы найдем папку, хранящую гиперпараметры:
cd demo
ls
> hyperparameters
Мы скачаем 6 исследований PSG из баз данных общего сна и DCSM, используя команду ut fetch . Вам понадобится приблизительно 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 . В частности, он загружает необходимые каналы (игнорируя остальные), повторно складывает, масштабирует и зажигает данные, отображает стадии гипнограммы в межпречные представления, используемые внутри, во время обучения, и, наконец, сохраняет обработанные данные в архив HDF5. При обучении данные могут транслироваться непосредственно из этого архива, чтобы значительно уменьшить необходимую системную память.
Также можно пропустить этот шаг вместе и либо 1) загрузить все данные, необходимые для обучения вперед, или 2) потока и применять предварительную обработку на лету во время обучения, как показано в полном размножении раздела U-Sleep ниже.
Теперь мы можем начать обучение, вызывая команду ut train . Набор гиперпараметров оптимизации по умолчанию был предварительно определен и расположен в файле hyperparameters/hparams.yaml вашего каталога проекта. В этой демонстрации мы собираемся запустить только очень короткую учебную сессию, но не стесняемся изменять любые параметры в файле hparams.yaml , как вы считаете нужным. Запустите следующую команду:
ut train --num_gpus=1 --preprocessed --seed 123
Вы можете заменить параметр --num_gpus=1 в вышеуказанной команде на --num_gpus=0 , если у вас нет доступного графического процессора, и хотите тренироваться на процессоре. Обучение на процессоре может занять до 30 минут.
После обучения набор моделей кандидатов будет доступен в model папки. Используя лучший наблюдаемый (средний показатель F1 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 (замените 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-Sleep на двух разных наборах данных.
Обратите внимание, что:
Если вы запустили приведенный выше код на графическом процессоре, вы не можете получить точно такие же числа, перечисленные здесь, даже если вы указали аргументы -seed. Это связано с тем, что некоторые вычисления, используемые во время обучения U-Sleep, принципиально нетерминированы при оценке на GPU. Тем не менее, прогнозирование с использованием обученной модели U-Sleep даст детерминированные выходы.
Производительность полученной демонстрационной модели очень низкая и не подходит для реальной постановки сна. Причина в том, что мы обучили U-Sleep на очень ограниченном наборе данных и для очень ограниченного числа эпох. Пожалуйста, обратитесь к полному размножению раздела U-Sleep для получения подробной информации о том, как подготовить и обучить полную версию U-Sleep.
Демонстрация выше в принципе описывает все этапы, необходимые для воспроизведения U-Sleep, как сообщается в [2]. Основная - и значимая - разница в том, что для воспроизведения полной модели вам нужно будет 1) иметь возможность получить доступ 2) загрузить и 3) предварительно предварительно обработать все необходимые наборы данных. Вам также может понадобиться компьютер с большим количеством ресурсов, как описано в системных требованиях.
Мы сделали все возможное, чтобы сделать этот процесс максимально простым. Вы должны предпринять следующие шаги:
ut fetch . Пожалуйста, вызовите ut fetch --help , чтобы увидеть обновленный список, в котором наборы данных могут быть загружены таким образом.[LOCAL_PATH] с 1 субсолдером для каждого набора данных.ut extract , ut extract_hypno и ut cv_split на всех наборах данных, как указано для каждого набора данных отдельно в файлах в resources/usleep_dataset_pred этого репозитория (также найдено здесь). Эти команды будут извлекать и помещать данные в структуру папки и формат, который принимает U-Time, а также разделяет данные на подмножества.ut extract выберет соответствующие каналы, заново выбрать их до 128 Гц и сохранить данные в архиве 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 с параметрами по умолчанию может занять очень много времени. Мы предлагаем увеличить скорость обучения (от текущего 1e-7 до EG 1e-6 ), если вы не хотите воссоздать U-Sleep в точных условиях, рассматриваемых в [2].
Вы все еще можете использовать этот репозиторий для обучения более старой модели U-времени. Далее мы показываем сквозное пример. Команды, перечисленные ниже, готовит папку проекта, загружает набор данных Sleep-EDF-153, подходит и оценивает модель U-времени в фиксированной настройке набора данных Train/Val/Test. Обратите внимание, что приведенный ниже код не воспроизводит эксперимент Sleep-EDF-153 [1], как использовался в 10 раз CV. Чтобы запустить эксперимент CV, пожалуйста, обратитесь к командам ut cv_split --help и ut cv_experiment --help .
# Получить набор данных об общедоступном сна
UT Fetch -Dataset SEDF_SC -OUT_DIR DATATS/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 DATATS/SEDF_SC/SIVEST/FILTER_SPLIT
# Начните обучение
CD my_utime_project
UT Train-num_gpus = 1-каналы '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 Сводка -CSV_PATTERN 'eval/test_data/*/evaluation_dice.csv'
--print_all
# Выходные стадии сна на каждые 3 секунды сигнала 128 Гц
# Здесь, «folder_regex» соответствует 2 файлам в наборе данных
UT прогнозирует-folder_regex '../datasets/sedf_sc/sc400=-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
