U Time
1.0.0
Implementação oficial de
Esse repositório pode ser usado para treinar os modelos originais do tempo de U e mais recentes. No entanto, o repositório tem sido significativamente estendido desde [1] e pode divergir gradualmente da versão descrita em [2]. As versões anteriores podem ser encontradas em:
Este documento descreve o pacote oficial de software desenvolvido e usado para criar o sistema U gratuito e público do sistema de estadiamento do sono [2]. O sono em U é uma rede neural profunda totalmente convolucional para encenação automatizada do sono. Uma única instância do modelo pode ser treinada para executar o estadiamento preciso e resiliente do sono em uma ampla gama de protocolos de aquisição de populações clínicas e polissomnografia (PSG).
Este software permite o treinamento simultâneo do sono em U em qualquer número de conjuntos de dados PSG usando a seleção aleatória de configurações de canal de entrada. Possui uma interface de linha de comando para inicializar, treinar e avaliar modelos sem precisar modificar a base de código subjacente.
A seguir, apresentaremos o software por trás do sono U com mais detalhes. Observe que:
Este repositório armazena código para treinamento e avaliação do modelo de estadiamento do sono no sono em U. Ele se baseia e estende significativamente nosso repositório de tempo de U, publicado no Neurips 2019 [1]. A seguir, usaremos o termo sono em U para denotar o modelo de estadiamento do sono resiliente de alta frequência [2] e o tempo de U para denotar este repositório de código usado para treinar e avaliar o modelo de sono em U.
Você ainda pode usar este repositório para treinar o modelo mais antigo do tempo de U, veja o exemplo do tempo de U abaixo.
Requisitos mínimos de hardware
O uso de um modelo de sono U já treinado para encenação do sono pode ser feito em qualquer laptop moderno (sujeito aos requisitos de software listados abaixo).
Para treinar modelos de sono em U do zero, no entanto, é altamente recomendável usar um computador baseado em Linux com pelo menos as seguintes especificações de hardware:
É possível treinar o modelo em máquinas menores e sem GPUs, mas isso pode levar um tempo considerável. Da mesma forma, mais recursos acelerarão o treinamento. Se o conjunto de dados considerado exceder a memória do sistema (por exemplo, o 8 Gib of RAM sugerido acima), os dados devem ser pré -processados e transmitidos do disco, conforme demonstrado na seção de demonstração abaixo. Em máquinas maiores, pode -se se beneficiar da manutenção de um conjunto maior de dados carregados na memória. Por exemplo, treinamos o sono U [2] usando 8 núcleos de CPU, 1 GPU e 40 GIB de RAM, consulte a reprodução completa da seção de sono em U abaixo.
*O espaço de disco rígido necessário depende do número e tamanhos dos conjuntos de dados considerados. Para uma reprodução completa do sono U, é necessário aproximadamente 4 TIB do armazenamento disponível.
Requisitos de software:
Se você vai treinar um modelo de sono em U do zero, é altamente recomendável fazê-lo em uma GPU. Para usar o pacote U-Time com uma GPU, é necessária a biblioteca tensorflow ( v2.8.0 ). Para isso, é necessário o seguinte software adicional no seu sistema:
Consulte https://www.tensorflow.org/install/gpu para obter detalhes adicionais. Você não precisa instalar o TensorFlow (consulte o guia de instalação abaixo), mas o software acima deve ser instalado antes de prosseguir.
Em uma máquina Linux com pelo menos 1 GPU habilitado para CUDA disponível e anaconda ou miniconda instalados, execute os seguintes comandos para baixar o software, criar um ambiente CONDA chamado u-sleep e configurar o mais recente pacote de software de tempo de U e suas dependências:
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/
Como alternativa, você pode instalar o pacote da Pypi (pode ser atualizado com menos frequência):
pip install utime
Neste seguinte, demonstraremos como iniciar uma curta sessão de treinamento do sono U em um subconjunto significativamente limitado dos conjuntos de dados usados em [2].
30 minutes para ser concluída em uma conexão típica de computador e rede. A maior parte desse tempo é gastar baixando os dados necessários de bancos de dados públicos. Esta etapa pode levar significativamente mais tempo, dependendo do tráfego atual do banco de dados.11 GiB do espaço disco disponível no seu computador. Primeiro, criamos um diretório de projetos que armazenará todos os nossos dados para esta demonstração. O comando ut init criará uma pasta e o preencherá com um conjunto de valores de hiperparameter padrão:
ut init --name demo --model usleep_demo
Digitando o diretório de projetos recém -criado, encontraremos uma pasta que armazena hiperparâmetros:
cd demo
ls
> hyperparameters
Faremos o download de 6 estudos PSG dos bancos de dados do Sleep Public Sleep-EDF e DCSM usando o comando ut fetch . Você precisará de aproximadamente 10 GiB de espaço de disco rígido gratuito para armazenar os arquivos baixados. Dependendo da velocidade da sua Internet e da carga atual em cada um dos dois servidores, o download pode levar de 5 minutos a várias 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
Os dados brutos que consideraremos nesta demonstração foram baixados. Nossa pasta de projeto demo agora tem aproximadamente a seguinte estrutura:
└─ demo
├─ hyperparameters
└─ data
├─ dcsm
│ ├─ tp005f7e68_a084_46bb_9f0a_b6a084155a1c
│ │ ├─ hypnogram.ids
│ │ └─ psg.h5
│ ├─ ...
└─ sedf_sc
├─ SC4001E0
│ ├─ SC4001E0-PSG.edf
│ └─ SC4001EC-Hypnogram.edf
├─ ...
Antes de prosseguir para treinar o modelo de sono em U, dividimos cada conjunto de dados em divisões de trem/validação/teste fixo usando o comando ut cv_split . O comando deve ser invocado duas vezes cada um com um conjunto exclusivo de parâmetros especificando as convenções de nomeação do conjunto de dados:
# 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
Observe que a divisão do SEDF-SC é realizada por sujeito. Todos os registros do PSG do mesmo assunto serão colocados no mesmo divisão do conjunto de dados. Isso não é necessário para DCSM , pois todas as gravações são de assuntos únicos.
Esteja ciente de que, se você modificar algum dos comandos acima para usar nomes de diretórios de saída diferentes, precisará modificar os caminhos nos arquivos hiperparâmetro do conjunto de dados armazenados em hyperparameters/dataset_configurations conforme apropriado, antes do procedimento com as próximas etapas.
Execute o seguinte comando para preparar os dados para treinamento:
ut preprocess --out_path data/processed_data.h5 --dataset_splits train_data val_data
O script ut preprocess carrega e processa todos os conjuntos de dados, conforme descrito pelos parâmetros definidos em hyperparameters/hparams.yaml e todos os arquivos específicos de dados nos hyperparameters/dataset_configurations da pasta. Especificamente, ele carrega os canais necessários (ignorando o restante), re-amostras, escala e prende os dados, mapeia os estágios do hipnograma para representações intergeradas usadas internamente durante o treinamento e, finalmente, salva os dados processados em um arquivo HDF5. Ao treinar, os dados podem ser transmitidos diretamente desse arquivo para reduzir significativamente a memória do sistema necessária.
Também é possível pular esta etapa juntos e 1) carregar todos os dados necessários para treinamento antecipadamente, ou 2) fluir e aplicar o pré-processamento on-the-fly durante o treinamento, como mostrado na reprodução completa da seção de sono em U abaixo.
Agora podemos começar a treinar invocando o comando ut train . Um conjunto padrão de hiperparâmetros de otimização foi pré-especificado e está localizado no arquivo hyperparameters/hparams.yaml do diretório do seu projeto. Nesta demonstração, vamos executar apenas uma sessão de treinamento muito curta, mas sinta -se à vontade para modificar quaisquer parâmetros no arquivo hparams.yaml como você achar melhor. Execute o seguinte comando:
ut train --num_gpus=1 --preprocessed --seed 123
Você pode substituir o parâmetro --num_gpus=1 no comando acima com --num_gpus=0 se não tiver uma GPU disponível e desejar treinar na CPU. O treinamento na CPU pode levar até 30 minutos.
Após o treinamento, um conjunto de modelos candidatos estará disponível no model de pasta. Usando o melhor observado (pontuação média de validação mais alta), podemos prever os conjuntos de testes de SEDF-SC e DCSM usando todas as combinações de canais, bem como computam votos majoritários, invocando o seguinte 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
Os hipnogramas previstos estão agora disponíveis em predictions/test_data . Por fim, vamos imprimir uma matriz de confusão global (calculada em todos os assuntos) para o conjunto de dados sedf_sc (substitua sedf_sc -> dcsm para avaliação 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
Se você recebeu uma produção semelhante ao acima, parabéns! Você instalou, configurou, treinou e avaliou um modelo de sono em U em dois conjuntos de dados diferentes.
Observe que:
Se você executou o código acima em uma GPU, não poderá obter exatamente os mesmos números listados aqui, mesmo se você especificar os argumentos -sementes. Isso ocorre porque alguns cálculos usados durante o treinamento do sono U são fundamentalmente não determinísticos quando avaliados em uma GPU. No entanto, prever o uso de um modelo de sono U treinado fornecerá saídas determinísticas.
O desempenho do modelo de demonstração obtido é muito baixo e não é adequado para a encenação real do sono. O motivo é que treinamos o sono em U em um conjunto de dados muito limitado e para um número muito limitado de épocas. Consulte a reprodução completa da seção de sono em U para obter detalhes sobre como preparar e treinar uma versão completa do sono em U.
A demonstração acima, em princípio, descreve todas as etapas necessárias para reproduzir o sono U, conforme relatado em [2]. A diferença principal - e significativa - é que, para reproduzir o modelo completo, você precisará 1) poder acessar 2) Download e 3) pré -processar todos os conjuntos de dados necessários. Você também pode precisar de um computador com mais recursos, conforme descrito nos requisitos do sistema.
Fizemos o nosso melhor para facilitar esse processo. Você deve tomar as seguintes etapas:
ut fetch . Invoque ut fetch --help para ver uma lista atualizada de quais conjuntos de dados podem ser baixados dessa maneira.[LOCAL_PATH] com 1 sub-folder para cada conjunto de dados.ut extract , ut extract_hypno e ut cv_split em todos os conjuntos de dados, conforme especificado para cada conjunto de dados separadamente em arquivos sob a pasta resources/usleep_dataset_pred deste repositório (também encontrado aqui). Esses comandos extrairão e colocarão dados em uma estrutura de pastas e formato que o tempo de U aceita, além de dividir os dados em subconjuntos.ut extract selecionará os canais relevantes, novamente os exemplará para 128 Hz e armazenará os dados nos arquivos HDF5. Os dados originais não serão excluídos por padrão. Se você possui espaço limitado de tração rígida, considere remover os arquivos antigos antes de processar o próximo conjunto de dados.ut init --name u-sleep --model usleep .u-sleep/hyperparameters/dataset_configurations/ Substitua a String [LOCAL_PATH] pelo [LOCAL_PATH] dos seus dados. Se você tiver mais de 40 anos de memória do sistema Gib, treine o sono em U usando o seguinte 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
Em sistemas com menos memória, você pode 1) reduzir o parâmetro --max_loaded_per_dataset do atual 40 para um valor mais baixo (isso manterá menos registros do PSG no pool de memória ativa, o que reduzirá a aleatoriedade ao selecionar registros) ou 2) Pré -processo os dados e os dados do fluxo durante o treinamento (como demonstrado na demonstração acima), invocando os dois comandos a seguir (substituindo [local_path] conforme aplicável):
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
Isso aplicará todo o pré-processamento, criará um arquivo de dados adequado para streaming e treinar o sono em U usando amostras carregadas no disco.
Devido ao vasto tamanho do conjunto de dados considerado, o treinamento em U com os parâmetros padrão pode demorar muito. Sugerimos aumentar a taxa de aprendizado (do atual 1e-7 para o por exemplo, 1e-6 ), a menos que você esteja procurando recriar o sono U nas condições exatas consideradas em [2].
Você ainda pode usar este repositório para treinar o modelo mais antigo do tempo de U. A seguir, mostramos um exemplo de ponta a ponta. Os comandos listados abaixo preparam uma pasta de projeto, baixam o conjunto de dados Sleep-EDF-153, se encaixa e avalia um modelo de tempo de U em um conjunto de dados de trem/Val/teste de teste. Observe que o código abaixo não reproduz o experimento Sleep-EDF-153 de [1] como CV 10 vezes foi usado. Para executar um experimento CV, consulte os comandos ut cv_split --help e ut cv_experiment --help .
# Obtenha um conjunto de dados de preparação de sono público
UT Fetch -DataSet sedf_sc -out_dir conjuntos de dados/sedf_sc
# Prepare um experimento de divisão fixa
ut cv_split -data_dir 'conjuntos de dados/sedf_sc'
--subject_dir_pattern 'sc*'
--CV 1
--Validation_fração 0.20
--Test_fraction 0.20
---subject_matching_regex 'sc4 ( d {2}).*'
--File_list
# Inicialize um projeto de tempo de U
Ut init - -name my_utime_project
-Modelo utime
-Data_Dir DataSets/Sedf_SC/Views/FILT_SPLIT
# Comece a treinar
CD my_utime_project
Trem UT --num_gpus = 1 --Channels 'EEG FPZ-CZ'
# Prever e avaliar
ut avaliar -out_dir avaliar --one_shot
# Imprima uma matriz de confusão
ut cm --- verdade 'aval/test_data/dataset_1/files/*/true.npz'
--Pred 'aval/test_data/dataset_1/files/*/pred.npz'
# Imprimir estatísticas de resumo por sujeito
Resumo da UT ---csv_pattern 'aval/test_data/*/avaliação_dice.csv'
--print_all
# Saída de estágios de sono para cada 3 segundos de sinal de 128 Hz
# Aqui, o 'pasta_regex' corresponde a 2 arquivos no conjunto de dados
UT previsto-Foldder_regex '../datasets/sedf_sc/sc400 Oh1-2l ]e0'
-olt_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
