U Time
1.0.0
Implementación oficial de
Este repositorio puede usarse para entrenar tanto los modelos originales de U y más nuevos en U-Sleep. Sin embargo, el repositorio se ha extendido significativamente desde [1] y puede divergir gradualmente de la versión descrita en [2]. Se pueden encontrar versiones anteriores en:
Este documento describe el paquete de software oficial desarrollado y utilizado para crear el sistema de puesta en escena del sueño gratuita y pública U-Sleep [2]. U-Sleep es una red neuronal profunda totalmente convolucional para la estadificación automatizada del sueño. Se puede capacitar una sola instancia del modelo para realizar una estadificación de sueño precisa y resistente en una amplia gama de poblaciones clínicas y protocolos de adquisición de polisomnografía (PSG).
Este software permite la capacitación simultánea de U-Sleep en cualquier cantidad de conjuntos de datos de PSG utilizando la selección aleatoria de configuraciones de canales de entrada. Cuenta con una interfaz de línea de comandos para inicializar, capacitar y evaluar modelos sin necesidad de modificar la base de código subyacente.
A continuación, presentaremos el software detrás de U-Sleep con mayor detalle. Tenga en cuenta que:
Este repositorio almacena código para capacitar y evaluar el modelo de estadificación de sueño U-sleep . Se basa y extiende significativamente nuestro repositorio de U-Time, publicado en Neurips 2019 [1]. A continuación, utilizaremos el término U-Sleep para denotar el modelo de estadificación de sueño de alta frecuencia resistente [2], y en U-Time para denotar este repositorio de código utilizado para entrenar y evaluar el modelo U-Sleep.
Todavía puede usar este repositorio para entrenar el modelo más antiguo de U-Time, vea el ejemplo de U-Time a continuación.
Requisitos mínimos de hardware
El uso de un modelo U-Sleep ya entrenado para la puesta en escena del sueño generalmente puede realizarse en cualquier computadora portátil moderna (sujeto a los requisitos de software que se enumeran a continuación).
Sin embargo, para entrenar modelos U-Sleep desde cero, recomendamos que utilice una computadora basada en Linux con al menos las siguientes especificaciones de hardware:
Es posible entrenar el modelo en máquinas más pequeñas y sin GPU, pero hacerlo puede tomar un tiempo considerable. Del mismo modo, más recursos acelerarán la capacitación. Si el conjunto de datos considerado excede la memoria del sistema (por ejemplo, el 8 GIB de RAM sugerido anteriormente), los datos deben estar preprocesados y transmitidos desde el disco como se demuestra en la sección de demostración a continuación. En máquinas más grandes, uno puede beneficiarse de mantener un conjunto más grande de datos cargados en la memoria. Por ejemplo, entrenamos U-Sleep [2] usando 8 núcleos de CPU, 1 GPU y 40 GIB de RAM, consulte la reproducción completa de la sección U-Sleep a continuación.
*El espacio de disco duro requerido depende del número y los tamaños de los conjuntos de datos considerados. Para una reproducción completa de U-Sleep, se necesitan aproximadamente 4 TIB de almacenamiento disponible.
Requisitos de software:
Si va a entrenar a un modelo U-Sleep desde cero, le recomendamos que lo haga en una GPU. Para usar el paquete U-Time con una GPU, se requiere la biblioteca tensorflow ( v2.8.0 ). Para esto, se requiere el siguiente software adicional en su sistema:
Consulte https://www.tensorflow.org/install/gpu para obtener detalles adicionales. No necesita instalar tensorflow usted mismo (consulte la guía de instalación a continuación), pero el software anterior debe instalarse antes de continuar.
En una máquina de Linux con al menos 1 GPU habilitado para CUDA disponible y instalada anaconda o miniconda , ejecute los siguientes comandos para descargar el software, crear un entorno de conda llamado u-sleep y configurar el último paquete de software de U-Time y sus dependencias:
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/
Alternativamente, puede instalar el paquete desde PYPI (puede actualizarse con menos frecuencia):
pip install utime
En lo siguiente, demostraremos cómo lanzar una breve sesión de entrenamiento de U-Sleep en un subconjunto significativamente limitado de los conjuntos de datos utilizados en [2].
30 minutes en completarse en una computadora típica y conexión de red. La mayor parte de este tiempo es gastar descargando los datos requeridos de las bases de datos públicas. Este paso puede tardar significativamente más dependiendo del tráfico actual de la base de datos.11 GiB de espacio de disco disponible en su computadora. Primero, creamos un directorio de proyectos que almacenará todos nuestros datos para esta demostración. El comando ut init creará una carpeta y la llenará con un conjunto de valores predeterminados de hiperparameter:
ut init --name demo --model usleep_demo
Al ingresar al directorio de proyectos recién creado, encontraremos una carpeta que almacena hiperparámetros:
cd demo
ls
> hyperparameters
Descargaremos 6 estudios de PSG de las bases de datos de sueño público Sleep-EDF y DCSM utilizando el comando ut fetch . Necesitará aproximadamente 10 GiB de espacio gratuito de disco duro para almacenar los archivos descargados. Dependiendo de su velocidad de Internet y la carga actual en cada uno de los dos servidores, la descarga puede tomar entre 5 minutos y varias horas:
ut fetch --dataset sedf_sc --out_dir data/sedf_sc --N_first 6
ut fetch --dataset dcsm --out_dir data/dcsm --N_first 6
Los datos sin procesar que consideraremos en esta demostración ahora se han descargado. Nuestra carpeta de proyecto demo ahora tiene aproximadamente la siguiente estructura:
└─ demo
├─ hyperparameters
└─ data
├─ dcsm
│ ├─ tp005f7e68_a084_46bb_9f0a_b6a084155a1c
│ │ ├─ hypnogram.ids
│ │ └─ psg.h5
│ ├─ ...
└─ sedf_sc
├─ SC4001E0
│ ├─ SC4001E0-PSG.edf
│ └─ SC4001EC-Hypnogram.edf
├─ ...
Antes de proceder a entrenar el modelo U-Sleep, dividimos cada conjunto de datos en divisiones fijas de trenes/validación/prueba utilizando el comando ut cv_split . El comando debe invocarse dos veces cada uno con un conjunto único de parámetros que especifiquen las convenciones de nomenclatura del conjunto de datos:
# 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
Tenga en cuenta que la división de SEDF-SC se realiza por sujeto. Todos los registros de PSG del mismo tema se colocarán en la misma división del conjunto de datos. Esto no es necesario para DCSM , ya que todas las grabaciones son de temas únicos.
Tenga en cuenta que si modifica alguno de los comandos anteriores a EG Use diferentes nombres de directorio de salida, deberá modificar las rutas en los archivos de hiperparameter del conjunto de datos almacenados en hyperparameters/dataset_configurations según corresponda antes de proceder con los siguientes pasos.
Ejecute el siguiente comando para preparar los datos para la capacitación:
ut preprocess --out_path data/processed_data.h5 --dataset_splits train_data val_data
El script ut preprocess carga y procesa todos los conjuntos de datos descritos por los parámetros establecidos en hyperparameters/hparams.yaml y todos los archivos específicos de datos en la carpeta hyperparameters/dataset_configurations . Específicamente, carga los canales necesarios (ignorando el resto), vuelve a muestrear, escala y recorta los datos, mapea las etapas de hipnograma a las representaciones de Interger utilizadas internamente durante el entrenamiento y finalmente guarda los datos procesados a un archivo HDF5. Cuando se capacita, los datos pueden transmitirse directamente de este archivo para reducir significativamente la memoria del sistema requerida.
También es posible omitir este paso todos juntos y 1) cargar todos los datos necesarios para capacitar por adelantado, o 2) transmitir y aplicar preprocesamiento sobre la marcha durante la capacitación como se muestra en la reproducción completa de la sección U-Sleep a continuación.
Ahora podemos comenzar a entrenar invocando el comando ut train . Un conjunto predeterminado de hiperparámetros de optimización se ha especificado previamente y se encuentran en el archivo hyperparameters/hparams.yaml de su directorio de proyecto. En esta demostración, vamos a ejecutar solo una sesión de entrenamiento muy corta, pero no dude en modificar los parámetros en el archivo hparams.yaml como mejor le parezca. Ejecute el siguiente comando:
ut train --num_gpus=1 --preprocessed --seed 123
Puede reemplazar el parámetro --num_gpus=1 en el comando anterior con --num_gpus=0 si no tiene una GPU disponible y desea entrenar en la CPU. El entrenamiento en CPU puede tomar hasta 30 minutos.
Después de la capacitación, un conjunto de modelos candidatos estará disponible en el model de carpeta. Utilizando el mejor observado (puntaje F1 medio de validación más alto), podemos predecir en los conjuntos de pruebas de SEDF-SC y DCSM utilizando todas las combinaciones de canales, así como calcular los votos de la mayoría invocando el siguiente comando ut predict :
ut predict --num_gpus=1
--data_split test_data
--strip_func strip_to_match
--one_shot
--save_true
--majority
--out_dir predictions
Los hipnogramas predichos ahora están disponibles bajo predictions/test_data . Finalmente, imprimamos una matriz de confusión global (calculada en todos los sujetos) para el conjunto de datos sedf_sc (reemplace sedf_sc -> dcsm para la evaluación 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
Si recibió una salida similar a la anterior, ¡felicidades! Ha instalado, configurado, capacitado y evaluado con éxito un modelo U-Sleep en dos conjuntos de datos diferentes.
Tenga en cuenta que:
Si ejecutó el código anterior en una GPU, no puede obtener exactamente los mismos números enumerados aquí, incluso si especificó los argumentos -SEED. Esto se debe a que algunos cálculos utilizados durante el entrenamiento de U-Sleep son fundamentalmente no deterministas cuando se evalúan en una GPU. Sin embargo, la predicción del uso de un modelo de sueño U entrenado dará salidas deterministas.
El rendimiento del modelo de demostración obtenido es muy bajo y no es adecuado para la estadificación real del sueño. La razón es que entrenamos U-Sleep en un conjunto de datos muy limitado y para un número muy limitado de épocas. Consulte la sección de reproducción completa de U-Sleep para obtener detalles sobre cómo preparar y entrenar una versión completa de U-Sleep.
La demostración anterior en principio describe todos los pasos necesarios para reproducir U-Sleep como se informó en [2]. La diferencia principal y significativa es que para reproducir el modelo completo, deberá 1) poder acceder a 2) Descargar y 3) Preprocesar todos los conjuntos de datos requeridos. También puede necesitar una computadora con más recursos como se describe en los requisitos del sistema.
Hicimos todo lo posible para que este proceso sea lo más fácil posible. Debe dar los siguientes pasos:
ut fetch . Invoca ut fetch --help para ver una lista actualizada de los conjuntos de datos que se pueden descargar de esta manera.[LOCAL_PATH] con 1 subcarpelo para cada conjunto de datos.ut extract , ut extract_hypno y ut cv_split en todos los conjuntos de datos como se especifica para cada conjunto de datos por separado en archivos en la carpeta resources/usleep_dataset_pred de este repositorio (también se encuentra aquí). Estos comandos extraerán y colocarán datos en una estructura de carpeta y formato que acepta U-Time, así como dividir los datos en subconjuntos.ut extract seleccionará los canales relevantes, los volverá a mostrar a 128 Hz y almacenará los datos en los archivos HDF5. Los datos originales no se eliminarán de forma predeterminada. Si tiene un espacio de tracción dura limitada, considere eliminar los archivos antiguos antes de procesar el siguiente conjunto de datos.ut init --name u-sleep --model usleep .u-sleep/hyperparameters/dataset_configurations/ Reemplace la cadena [local_path] con el [LOCAL_PATH] de sus datos. Si tiene más de 40 Memoria del sistema GIB disponible, entrene U-Sleep utilizando el siguiente comando:
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
En los sistemas con menos memoria, puede 1) reducir el parámetro --max_loaded_per_dataset del 40 actual a un valor más bajo (esto mantendrá menos registros de PSG en el grupo de memoria activa, lo que reducirá la aleatoriedad al seleccionar registros) o 2), o 2) Preprocese los datos y los datos de transmisión durante la capacitación (como se demuestra en la demostración anterior) invocando los siguientes dos comandos (reemplazando [local_path] según corresponda):
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
Esto aplicará todo el preprocesamiento, creará un archivo de datos adecuado para la transmisión y entrenará el sueño U con muestras cargadas sobre la marcha del disco.
Debido al gran tamaño del conjunto de datos considerado, el entrenamiento de U-Sleep con los parámetros predeterminados puede llevar mucho tiempo. Sugerimos aumentar la tasa de aprendizaje (desde el 1e-7 actual a EG 1e-6 ) a menos que esté buscando recrear el sueño U bajo las condiciones exactas consideradas en [2].
Todavía puede usar este repositorio para capacitar al modelo más antiguo de U-Time. A continuación mostramos un ejemplo de extremo a extremo. Los comandos que se enumeran a continuación preparan una carpeta de proyecto, descarga el conjunto de datos Sleep-EDF-153, se ajusta y evalúa un modelo de U-Time en una configuración de división de conjunto de datos de tren/Val fijo. Tenga en cuenta que el siguiente código no reproduce el experimento Sleep-EDF-153 de [1] ya que se usó CV de 10 veces. Para ejecutar un experimento CV, consulte el ut cv_split --help y ut cv_experiment --help Commands.
# Obtener un conjunto de datos de estadificación de sueño público
UT Fetch --Dataset SEDF_SC --out_dir DataSets/SEDF_SC
# Prepare un experimento de división fija
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
# Inicializar un proyecto de U-Time
UT Init - -Name my_utime_project
-Modelo UTIME
--data_dir dataSets/sedf_sc/vistas/fijo_split
# Comienza el entrenamiento
CD my_utime_project
UT Train--Num_gpus = 1-Channels 'EEG FPZ-CZ'
# Predecir y evaluar
UT Evaluate --out_dir eval --one_shot
# Imprimir una matriz de confusión
UT CM --true 'eval/test_data/dataSet_1/files/*/true.npz'
--pred 'eval/test_data/dataSet_1/files/*/pred.npz'
# Estadísticas de resumen de impresión por sujeto
Resumen UT - -CSV_PTERTN 'EVALL/TEST_DATA/*/EVALUACIÓN_DICE.CSV'
--print_all
# Etapas de sueño de salida por cada 3 segundos de señal de 128 Hz
# Aquí, la 'carpeta_regex' coincide con 2 archivos en el conjunto de datos
UT Predicte --folder_regex '../datasets/sedf_sc/sc400§-2font>E0'
--out_dir high_res_pred
--data_per_predicción 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
