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
# Core package (data, I/O, preprocessing, analysis, visualization)
pip install misleep
# With the PySide6 GUI (recommended for most users)
pip install "misleep[gui]"
# With everything, including the LightGBM auto-staging model
pip install "misleep[full]"
# For development / contributing
git clone https://github.com/BryanWang0702/MiSleep.git
cd misleepv3
pip install -e ".[gui,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.0
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.0.tar.gz | 8.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| misleep-0.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 17.1 MB
Release files / misleep-0.3.0.tar.gz
| Download URL | misleep-0.3.0.tar.gz |
|---|---|
| Size | 8.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5addeeb55736d8785776fd13190bb02d9cf2b7a9fbd918442641267c8de549b6
|
|
BLAKE2b-256 checksum How to use checksums |
3b39a627b212d00ed00002ddb7c8ad6461a299a772f337ba58c72e5d937e6e25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / misleep-0.3.0-py3-none-any.whl
| Download URL | misleep-0.3.0-py3-none-any.whl |
|---|---|
| Size | 8.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69d267dfdf00c6e9f7ea5de2c9ffaf9a7bd8fbf7908f0c8a129453bf835b6cb8
|
|
BLAKE2b-256 checksum How to use checksums |
574b35832cc00c96eda305ed18abd8abe13648d10dbcd4a078cc08a1b88c7e00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
