Implementation of the SUMO (Slim U-Net trained on MODA) model

Related tags

Deep Learningsumo
Overview

SUMO - Slim U-Net trained on MODA

Implementation of the SUMO (Slim U-Net trained on MODA) model as described in:

TODO: add reference to paper once available

Installation Guide

On Linux with anaconda or miniconda installed, the project can be used by running the following commands to clone the repository, create a new environment and install the required dependencies:

git clone https://github.com/dslaborg/sumo.git
cd sumo
conda env create --file environment.yaml
conda activate sumo

Scripts - Quick Guide

Running and evaluating an experiment

The main model training and evaluation procedure is implemented in bin/train.py and bin/eval.py using the Pytorch Lightning framework. A chosen configuration used to train the model is called an experiment, and the evaluation is carried out using a configuration and the result folder of a training run.

train.py

Trains the model as specified in the corresponding configuration file, writes its log to the console and saves a log file and intermediate results for Tensorboard and model checkpoints to a result directory.

Arguments:

  • -e NAME, --experiment NAME: name of experiment to run, for which a NAME.yaml file has to exist in the config directory; default is default

eval.py

Evaluates a trained model, either on the validation data or test data and reports the achieved metrics.

Arguments:

  • -e NAME, --experiment NAME: name of configuration file, that should be used for evaluation, for which a NAME.yaml file has to exist in the config directory; usually equals the experiment used to train the model; default is default
  • -i PATH, --input PATH: path containing the model that should be evaluated; the given input can either be a model checkpoint, which then will be used directly, or the output directory of a train.py execution, in which case the best model will be used from PATH/models/; if the configuration has cross validation enabled, the output directory is expected and the best model per fold will be obtained from PATH/fold_*/models/; no default value
  • -t, --test: if given, the test data is used instead of the validation data

Further example scripts

In addition to scripts used to create the figures in our manuscript (spindle_analysis.py, spindle_analysis_correlations.py and spindle_detection_examply.py), the scripts directory contains two scripts that demonstrate the usage of this project.

create_data_splits.py

Demonstrates the procedure used to split the data into test and non-test subjects and the subsequent creation of a hold-out validation set and (alternatively) cross validation folds.

Arguments:

  • -i PATH, --input PATH: path containing the (necessary) input data, as produced by the MODA file MODA02_genEEGVectBlock.m; relative paths starting from the scripts directory; default is ../input/
  • -o PATH, --output PATH: path in which the generated data splits should be stored in; relative paths starting from the scripts directory; default is ../output/datasets_{datatime}
  • -n NUMBER, --n_datasets NUMBER: number of random split-candidates drawn/generated; default is 25
  • -t FRACTION, --test FRACTION: Proportion of data that is used as test data; 0<=FRACTION<=1; default is 0.2

predict_plain_data.py

Demonstrates how to predict spindles with a trained SUMO model on arbitrary EEG data, which is expected as a dict with the keys representing the EEG channels and the values the corresponding data vector.

Arguments:

  • -d PATH, --data_path PATH: path containing the input data, either in .pickle or .npy format, as a dict with the channel name as key and the EEG data as value; relative paths starting from the scripts directory; no default value
  • -m PATH, --model_path PATH: path containing the model checkpoint, which should be used to predict spindles; relative paths starting from the scripts directory; default is ../output/final.ckpt
  • -g NUMBER, --gpus NUMBER: number of GPUs to use, if 0 is given, calculations are done using CPUs; default is 0
  • -sr RATE, --sample_rate RATE: sample rate of the provided data; default is 100.0

Project Setup

The project is set up as follows:

  • bin/: contains the train.py and eval.py scripts, which are used for model training and subsequent evaluation in experiments (as configured within the config directory) using the Pytorch Lightning framework
  • config/: contains the configurations of the experiments, configuring how to train or evaluate the model
    • default.yaml: provides a sensible default configuration
    • final.yaml: contains the configuration used to train the final model checkpoint (output/final.ckpt)
    • predict.yaml: configuration that can be used to predict spindles on arbitrary data, e.g. by using the script at scripts/predict_plain_data.py
  • input/: should contain the used input files, e.g. the EEG data and annotated spindles as produced by the MODA repository and transformed as demonstrated in the /scripts/create_data_splits.py file
  • output/: contains generated output by any experiment runs or scripts, e.g. the created figures
    • final.ckpt: the final model checkpoint, on which the test data performance, as reported in the paper, was obtained
  • scripts/: various scripts used to create the plots of our paper and to demonstrate the usage of this project
    • a7/: python implementation of the A7 algorithm as described in:
      Karine Lacourse, Jacques Delfrate, Julien Beaudry, Paul E. Peppard and Simon C. Warby. "A sleep spindle detection algorithm that emulates human expert spindle scoring." Journal of Neuroscience Methods 316 (2019): 3-11.
      
    • create_data_splits.py: demonstrates the procedure, how the data set splits were obtained, including the evaluation on the A7 algorithm
    • predict_plain_data.py: demonstrates the prediction of spindles on arbitrary EEG data, using a trained model checkpoint
    • spindle_analysis.py, spindle_analysis_correlations.py, spindle_detection_example.py: scripts used to create some of the figures used in our paper
  • sumo/: the implementation of the SUMO model and used classes and functions, for more information see the docstrings

Configuration Parameters

The configuration of an experiment is implemented using yaml configuration files. These files must be placed within the config directory and must match the name past as --experiment to the eval.py or train.py script. The default.yaml is always loaded as a set of default configuration parameters and parameters specified in an additional file overwrite the default values. Any parameters or groups of parameters that should be None, have to be configured as either null or Null following the YAML definition.

The available parameters are as follows:

  • data: configuration of the used input data; optional, can be None if spindle should be annotated on arbitrary EEG data
    • directory and file_name: the input file containing the Subject objects (see scripts/create_data_splits.py) is expected to be located at ${directory}/${file_name}, where relative paths are to be starting from the root project directory; the file should be a (pickled) dict with the name of a data set as key and the list of corresponding subjects as value; default is input/subjects.pickle
    • split: describing the keys of the data sets to be used, specifying either train and validation, or cross_validation, and optionally test
      • cross_validation: can be either an integer k>=2, in which the keys fold_0, ..., fold_{k-1} are expected to exist, or a list of keys
    • batch_size: size of the used minbatches during training; default is 12
    • preprocessing: if z-scoring should be performed on the EEG data, default is True
  • experiment: definition of the performed experiment; mandatory
    • model: definition of the model configuration; mandatory
      • n_classes: number of output parameters; default is 2
      • activation: name of an activation function as defined in torch.nn package; default is ReLU
      • depth: number of layers of the U excluding the last layer; default is 2
      • channel_size: number of filters of the convolutions in the first layer; default is 16
      • pools: list containing the size of pooling and upsampling operations; has to contain as many values as the value of depth; default [4;4]
      • convolution_params: parameters used by the Conv1d modules
      • moving_avg_size: width of the moving average filter; default is 42
    • train: configuration used in training the model; mandatory
      • n_epochs: maximal number of epochs to be run before stopping training; default is 800
      • early_stopping: number of epochs without any improvement in the val_f1_mean metric, after which training is stopped; default is 300
      • optimizer: configuration of an optimizer as defined in torch.optim package; contains class_name (default is Adam) and parameters, which are passed to the constructor of the used optimizer class
      • lr_scheduler: used learning rate scheduler; optional, default is None
      • loss: configuration of loss function as defined either in sumo.loss package (GeneralizedDiceLoss) or torch.nn package; contains class_name (default is GeneralizedDiceLoss) and parameters, which are passed to the constructor of the used loss class
    • validation: configuration used in evaluating the model; mandatory
      • overlap_threshold_step: step size of the overlap thresholds used to calculate (validation) F1 scores
Code for the paper: Sketch Your Own GAN

Sketch Your Own GAN Project | Paper | Youtube | Slides Our method takes in one or a few hand-drawn sketches and customizes an off-the-shelf GAN to mat

677 Dec 28, 2022
Elucidating Robust Learning with Uncertainty-Aware Corruption Pattern Estimation

Elucidating Robust Learning with Uncertainty-Aware Corruption Pattern Estimation Introduction 📋 Official implementation of Explainable Robust Learnin

JeongEun Park 6 Apr 19, 2022
Voice Gender Recognition

In this project it was used some different Machine Learning models to identify the gender of a voice (Female or Male) based on some specific speech and voice attributes.

Anne Livia 1 Jan 27, 2022
Styled text-to-drawing synthesis method. Featured at the 2021 NeurIPS Workshop on Machine Learning for Creativity and Design

Styled text-to-drawing synthesis method. Featured at the 2021 NeurIPS Workshop on Machine Learning for Creativity and Design

Peter Schaldenbrand 247 Dec 23, 2022
[Preprint] ConvMLP: Hierarchical Convolutional MLPs for Vision, 2021

Convolutional MLP ConvMLP: Hierarchical Convolutional MLPs for Vision Preprint link: ConvMLP: Hierarchical Convolutional MLPs for Vision By Jiachen Li

SHI Lab 143 Jan 03, 2023
Learning Temporal Consistency for Low Light Video Enhancement from Single Images (CVPR2021)

StableLLVE This is a Pytorch implementation of "Learning Temporal Consistency for Low Light Video Enhancement from Single Images" in CVPR 2021, by Fan

99 Dec 19, 2022
Autonomous racing with the Anki Overdrive

Anki Autonomous Racing Autonomous racing with the Anki Overdrive. Using the Overdrive-Python API (https://github.com/xerodotc/overdrive-python) develo

3 Dec 11, 2022
Jarvis Project is a basic virtual assistant that uses TensorFlow for learning.

Jarvis_proyect Jarvis Project is a basic virtual assistant that uses TensorFlow for learning. Latest version 0.1 Features: Good morning protocol Tell

Anze Kovac 3 Aug 31, 2022
Registration Loss Learning for Deep Probabilistic Point Set Registration

RLLReg This repository contains a Pytorch implementation of the point set registration method RLLReg. Details about the method can be found in the 3DV

Felix Järemo Lawin 35 Nov 02, 2022
QuakeLabeler is a Python package to create and manage your seismic training data, processes, and visualization in a single place — so you can focus on building the next big thing.

QuakeLabeler Quake Labeler was born from the need for seismologists and developers who are not AI specialists to easily, quickly, and independently bu

Hao Mai 15 Nov 04, 2022
Official implementation of Protected Attribute Suppression System, ICCV 2021

Official implementation of Protected Attribute Suppression System, ICCV 2021

Prithviraj Dhar 6 Jan 01, 2023
Neural Re-rendering for Full-frame Video Stabilization

NeRViS: Neural Re-rendering for Full-frame Video Stabilization Project Page | Video | Paper | Google Colab Setup Setup environment for [Yu and Ramamoo

Yu-Lun Liu 9 Jun 17, 2022
Active window border replacement for window managers.

xborder Active window border replacement for window managers. Usage git clone https://github.com/deter0/xborder cd xborder chmod +x xborders ./xborder

deter 250 Dec 30, 2022
The best solution of the Weather Prediction track in the Yandex Shifts challenge

yandex-shifts-weather The repository contains information about my solution for the Weather Prediction track in the Yandex Shifts challenge https://re

Ivan Yu. Bondarenko 15 Dec 18, 2022
Python package for multiple object tracking research with focus on laboratory animals tracking.

motutils is a Python package for multiple object tracking research with focus on laboratory animals tracking. Features loads: MOTChallenge CSV, sleap

Matěj Šmíd 2 Sep 05, 2022
An NLP library with Awesome pre-trained Transformer models and easy-to-use interface, supporting wide-range of NLP tasks from research to industrial applications.

简体中文 | English News [2021-10-12] PaddleNLP 2.1版本已发布!新增开箱即用的NLP任务能力、Prompt Tuning应用示例与生成任务的高性能推理! 🎉 更多详细升级信息请查看Release Note。 [2021-08-22]《千言:面向事实一致性的生

6.9k Jan 01, 2023
GitHub repository for the ICLR Computational Geometry & Topology Challenge 2021

ICLR Computational Geometry & Topology Challenge 2022 Welcome to the ICLR 2022 Computational Geometry & Topology challenge 2022 --- by the ICLR 2022 W

42 Dec 13, 2022
Cours d'Algorithmique Appliquée avec Python pour BTS SIO SISR

Course: Introduction to Applied Algorithms with Python (in French) This is the source code of the website for the Applied Algorithms with Python cours

Loic Yvonnet 0 Jan 27, 2022
Rayvens makes it possible for data scientists to access hundreds of data services within Ray with little effort.

Rayvens augments Ray with events. With Rayvens, Ray applications can subscribe to event streams, process and produce events. Rayvens leverages Apache

CodeFlare 32 Dec 25, 2022
Semantic Segmentation with Pytorch-Lightning

This is a simple demo for performing semantic segmentation on the Kitti dataset using Pytorch-Lightning and optimizing the neural network by monitoring and comparing runs with Weights & Biases.

Boris Dayma 58 Nov 18, 2022