MiSleep
MiSleep is an open-source Python toolbox for mice sleep EEG/EMG visualization, scoring, and analysis.
The name MiSleep comes from "Mice Sleep" and sounds like "my sleep".
| License | BSD 3-Clause |
| Python | 3.9 – 3.14 |
| GUI toolkit | PySide6 (Qt6) — Windows, macOS, Linux |
| Documentation | https://bryanwang.cn/MiSleep/ |
Features
- Cross-platform desktop GUI built on PySide6 (Qt6). Works on Windows, macOS and Linux without any platform-specific code.
- Flexible data input — load MATLAB, EDF/EDF+, BDF, NumPy NPY/NPZ, CSV and TSV recordings; JSON/CSV/TSV annotation imports are also built in.
- Full scoring workflow — per-second sleep state scoring (NREM / REM / Wake / Init), single time-point markers, start-end events, hypnogram, spectrogram and per-state spectral analysis.
- Event detection — slow-wave activity (SWA) and sleep spindle detection with state-specific thresholds.
- Automatic sleep staging — a LightGBM classifier (trained on time- and frequency-domain features) and an optional PyTorch causal-transformer model.
- Analysis export — per-hour and 12 h light/dark phase sleep statistics exported to Excel.
- Clean, modular architecture — data, I/O, preprocessing, analysis, visualization and GUI are separate modules with a stable public API and plugin-friendly extension points (see the developer guide).
Installation
# Base install - includes everything (data, I/O, preprocessing, analysis,
# visualization AND the PySide6 GUI)
pip install misleep
# With the LightGBM auto-staging model as well
pip install "misleep[full]"
# For development / contributing
git clone https://github.com/BryanWang0702/MiSleep.git
cd misleepv3
pip install -e ".[analysis,dev]"
Note on PyTorch: the causal-transformer auto-staging model requires
torch, which is not available on every platform. Install it separately withpip install "misleep[transformer]".
Quick start
Launch the GUI
python -m misleep
# or, after installation:
misleep
Open files directly (command line)
misleep data.mat # open a recording
misleep data.mat anno.txt # open a recording + its annotation
misleep --data data.edf --anno anno.txt
python -m misleep data.mat # same via the module
Open files by double-clicking (Windows)
Register MiSleep as the handler for your recording files:
python tools/install_file_associations.py
After that, double-clicking a .mat or .edf file opens it in MiSleep
(no console window). Annotation .txt files get an "Open with MiSleep"
right-click menu item without changing their default handler. The previous
.mat/.edf handlers are backed up automatically and restored with:
python tools/install_file_associations.py --uninstall
On macOS/Linux, run the same script for instructions (or open files from the command line as shown above).
Use the library
import misleep as ms
# Load a recording
midata = ms.load_signal("data.npz") # MAT, EDF/BDF, NPY/NPZ, CSV or TSV
# Inspect it
print(midata.channels, midata.sf, midata.duration)
# Preprocess
midata.filter(chans=["EEG"], btype="bandpass", low=0.5, high=30)
nrem, rem, wake, init = ms.crop_state_data(midata, mianno)
# Analyze
freq, psd = ms.spectrum(midata.signals[0], midata.sf[0])
swa = ms.SWA_detection(midata.signals[0], midata.sf[0], df=True)
# Plot
fig, ax = ms.plot_hypno(mianno.sleep_state)
See docs/getting_started.md and the examples folder for more.
Project layout
misleepv3/
├── pyproject.toml # modern packaging (PEP 621)
├── src/misleep/
│ ├── data/ # data model: MiData, MiAnnotation
│ ├── io/ # input/output: MAT, EDF, annotations (+ plugin registry)
│ ├── preprocessing/ # filtering, artifact rejection, spectral analysis
│ ├── analysis/ # detection, feature extraction, auto staging
│ ├── viz/ # matplotlib plotting (signals, spectra, hypnograms)
│ ├── gui/ # PySide6 desktop application
│ ├── utils/ # shared helpers
│ ├── config.py # INI configuration handling
│ └── logger.py # logging setup
├── tests/ # pytest suite
├── docs/ # user + developer documentation
├── examples/ # runnable examples
└── tools/ # UI/resource compilation scripts
Documentation
- Getting started — installation and first steps
- User guide — the GUI in detail
- Data formats — how data and annotations are stored
- Configuration — the
config.inireference - API reference — full API documentation
- Developer guide — architecture and how to extend MiSleep
- Changelog
Citing MiSleep
If you use this software in your research, please cite it as:
Xueqiang Wang. (2024). BryanWang0702/MiSleep. Zenodo. https://doi.org/10.5281/zenodo.14511905
License
BSD 3-Clause. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for misleep 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| misleep-0.3.3.tar.gz | 26.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| misleep-0.3.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 53.0 MB
Release files / misleep-0.3.3.tar.gz
| Download URL | misleep-0.3.3.tar.gz |
|---|---|
| Size | 26.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
513d6275324e5367f72831650e6c339d7a7ae2a1e8ca8f254dab80f43f55e5f5
|
|
BLAKE2b-256 checksum How to use checksums |
d15a58e64584337bbdedd304758252e71a66c2f74951bb2e726b1469a1fc8c18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.1 CPython/3.8.20
|
Release files / misleep-0.3.3-py3-none-any.whl
| Download URL | misleep-0.3.3-py3-none-any.whl |
|---|---|
| Size | 26.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9ed7b27e34d41e9f30b56d1219fedca90d59a6fb00dd21914536de7b4118395c
|
|
BLAKE2b-256 checksum How to use checksums |
7b0b329dedfbaa6bc5f30cf74d51155db2cac2c28e981c10019e17b6ba5a8b79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.1 CPython/3.8.20
|
