misst 0.1.1

Automated murine polysomnogram sleep staging for Python.

A Murine-based Intelligent Sleep Staging Tool

MISST is a Python library that utilizes deep neural networks in order to automate the grading of murinae polysomnograms (PSGs). By using a combination of residual connections, bottleneck blocks, and fully-connected layers, MISST is able to classify raw PSGs with little to no preprocessing, while still remaining lightweight and consistent. On a dataset of ~10 hours of murine PSGs, MISST reached a validation accuracy of 87.6% and a Cohen's Kappa of 0.74.

This program was developed as part of a research project conducted at the Johns Hopkins Center for Interdisciplinary Sleep Research and Education.

Features

• Easy-to-use Python API
• Scalable for large datasets
  • All data manipulation (preprocessing, training, etc.) uses the same amount of RAM, regardless of dataset size.
• Full GUI for Real-Time Data Analysis
• Support for both Hyperband Tuning and Bayesian Optimization
• Distributed Training (Model-Parallel & Data-Parallel)

GUI

• Automatic Model Configuration Generator
  • A model configuration menu is automatically generated as per the user's entered parameters
• Live accuracy and loss metrics
  • Updated in real-time during training
• Prediction Error Distribution graphs
  • Incorporates a custom metric to directly interface with the model predictions
• Built-in failsafes for early stopping

Getting Started

System Requirements:

• Python 3.10 or later
• A system with 8 GB RAM or more
• At least 5 GB of free disk space
• Windows, MacOS, or Linux

To install MISST, run the following command:

C:\...> pip install misst

Using MISST

At a high-level, MISST can be thought of as TensorFlow-based model training application designed specifically for processing murine polysomnograms.

Importing MISST into a Python project is as simple as import misst. However, in order to use any of MISST's functions, there are several supplementary files that must be placed alongside your Python script. Conceptually, MISST uses the following file pipeline:

In practice, the directory tree of a MISST project should look as follows:

└──Your_Project
    ├──data
    │  ├───[subdirectory_1]
    │  ├───[subdirectory_2]
    │  └───[subdirectory_3]
    ├──my_program.py
    └──config.yaml

• my_program.py represents the script that you're writing. While it can contain anything, you can find a barebones example here.
• For the config.yaml file, you should always use this template. You can modify and tweak parameters accordingly, but deleting an entry altogether may result in an error.
• The data directory must abide by strict formatting rules, which is outlined in the Dataset section of this guide.

For an example of how this should look, reference the example folder in the GitHub Repo.

Dataset Formatting

In order to use MISST, a specific dataset format must be followed. This section outlines the rules for both the PSG and Hypnogram files. The program may result in an error if this formatting is not strictly adhered to.

The dataset must be placed into the ~/MISST/mist/data/ directory, with the following structure:

• Each PSG recording must be in it's own subdirectory
  • The subdirectory can be named anything
  • The subdirectory can include unrelated files
• Both a Hypnogram (in .csv format) and a PSG (in .edf format) recording must be present within each subdirectory
• The Hypnogram and PSG can be named anything, as long as the RegEx is able to properly filter it out

The final MISST directory tree should look as follows:

└──data
   └──raw
      ├───[subdirectory_1]
      │   └───EDF.edf
      │   └───hypnogram.csv
      ├───[subdirectory_2]
      │   └───EDF.edf
      │   └───hypnogram.csv
      ├───[subdirectory_3]
      │   └───EDF.edf
      │   └───hypnogram.csv
      │   ...
      └────[subdirectory_n]
          └───EDF.edf
          └───hypnogram.csv

Each Hypnogram ".csv" file should follow this format:

type	start	stop
SLEEP-S0	2021-10-19 10:12:44.000	2021-10-19 10:12:54.000
SLEEP-S2	2021-10-19 10:12:54.000	2021-10-19 10:13:04.000
SLEEP-REM	2021-10-19 10:13:04.000	2021-10-19 10:13:14.000

Disclaimer: MISST is still in development. Johns Hopkins is not liable for any incorrect or misleading predictions outputted by the MISST model.

Code Completion

The following table represents current progress on MISST:

Module	Feature	Description	Current Status
Trainer	"PLAIN" Mode	Basic model training mode	✅ Finished
	"TUNER" Mode	Uses a KerasTuner during training	✅ Finished
	"GUI" Mode	Provides a GUI for real-time training visualization	🚧 In Progress
	"DIST" Mode	Trains using a distributed computing network	🚧 In Progress
Predictor	Hypnograms	Create hypnograms from inputted polysomnogram	❌ Not Started
	Azure Webapp	Interactive web-app for Hypnogram prediction	❌ Not Started

Contributors

Lead Developer: Hudson Liu • 🖥️ GitHub @hudson-liu • 📧 Email [e-mail]

Mentor/Team Lead: Luu Van Pham, M.D.

Team Member: Lenise Kim

Logo Design: delogodesign & Tomona Oishi

Acknowledgements

MISST was developed by Hudson Liu over the course of an internship led by Luu Van Pham, M.D. (IT Director of the Johns Hopkins Center for Interdisciplinary Sleep Research and Education). Additionally, this project was made possible thanks to Lenise Kim's gold-standard murine sleep staging data.

MISST's logo is the product of a combined effort by both delogodesign and Tomona Oishi.