YASA: a Python toolbox for sleep staging and spindle detection

A command-line toolbox for polysomnography data

The README describes YASA, which stands for Yet Another Spindle Algorithm, as a command-line sleep analysis toolbox in Python, and the repository as a Python package to analyze polysomnographic sleep recordings. The project site is yasa-sleep.org and the licence is BSD-3-Clause.

The main functions are listed in five groups. Automatic sleep staging of polysomnography data, with a link to the eLife article describing the approach. Event detection for sleep spindles, slow-waves and rapid eye movements, on single or multi-channel EEG data. Artefact rejection, also on single or multi-channel EEG. Spectral analyses covering bandpower, phase-amplitude coupling and the 1/f slope. And hypnogram analysis, which is sleep statistics, stage transitions, visualization and manipulation.

The grouping tells you what kind of tool this is. It is not a viewer for a sleep study and not a device interface. It is the analysis layer, the part where a recording becomes measurements, and the fact that hypnogram manipulation is included alongside detection says it is meant to be used as a working environment rather than a one-shot script.

The topic tags describe the internals as well: artefact-rejection, deep-sleep, eeg-signals, peak-detection, signal-processing, sleep-scoring, sleep-staging, spectral-analysis and stft, plus numba.

Install it with pip, conda or uv, and pick your extras

Installation is a single package from three sources, and the README says it can be easily installed using pip, conda, or uv:

    uv pip install yasa
    pip install --upgrade yasa
    conda install -c conda-forge yasa

Some features require optional dependencies, and they are installed with extras:

    pip install "yasa[full]"    # all optional dependencies

The packaging metadata names what each extra pulls in. The `heart` extra is `sleepecg`, which is the ECG side of the analysis, the `art` extra is `pyriemann` for artefact rejection, the `plot` extra is `ipywidgets`, and `full` is defined as `yasa[heart,art,plot]`, so the full extra is literally the union of the other three.

That structure is worth understanding before you install, because the extras are not all about plotting. The heart extra adds the cardiac signal to a package whose core is EEG, and the art extra adds the riemannian machinery used for artefact rejection. Installing `yasa[full]` gets you a different analysis than the base package, not just prettier output.

The base package itself, by contrast, has a substantial numeric stack, with numpy, scipy, pandas, matplotlib, seaborn, mne, antropy, scikit-learn, lspopt, joblib, lightgbm and pooch all in the runtime dependencies.

Building from source is an editable uv install and a test run

The source install path is documented as a clone, an editable install with uv, and a test run:

  git clone https://github.com/raphaelvallat/yasa.git
  cd yasa
  uv pip install --group=test --editable .

  # test the package
  pytest --verbose

The editable install is the point. A package that computes sleep statistics and fits models needs to be run against the code you are editing, and an editable install makes the test suite run against your working tree rather than a copy.

The dependency groups in the packaging metadata are the other thing to look at. The `dev` group is a single pinned entry, `ruff==0.16.10`, with a comment that it is kept in sync with the .pre-commit-config.yaml, which is the pattern of a project where the linter version is fixed because the pre-commit hooks and the local run must agree. The `test` group carries pytest, pytest-cov and coverage with the toml extra, with a comment explaining that coverage has to be new enough for `source_pkgs`. The `docs` group is a Sphinx setup with the pydata theme, numpydoc and several extensions.

The package requires Python 3.11 or newer, and the classifiers list 3.11 through 3.14, so a Python 3.10 environment is not a supported configuration.

The tutorials are the entry point, and the notebooks come with a warning

The README points at two places to start. The tutorials section of the documentation, which includes a quickstart guide and step-by-step walkthroughs of the most common workflows, is described as the best starting point. And for common questions about prerequisites, data formats, and how to load EEG data, there is a separate FAQ page.

Additional worked examples are available as Jupyter notebooks on GitHub, and here the README attaches a caveat that is worth taking seriously: some notebooks may not reflect the latest API. That is a small sentence, but it points at a real property of a fast-moving research library, that the examples age faster than the package, and that a notebook that runs against version 0.6 may not run against 0.8.

The data formats question is the one to resolve first, because everything downstream depends on it. The FAQ is the documented place for it, and the fact that it is called out separately from the tutorials suggests the input format is the part people actually get stuck on.

The gallery in the README is worth a look for a different reason: it shows what the output looks like, from an overlay of detected spindles on real EEG data, through a time-frequency representation of a whole night with the hypnogram on top and a sleep stage probability transition matrix, down to a topographic plot, the average template of all detected slow-waves stratified by channels, and a phase-amplitude coupling comodulogram.

The staging model is a peer reviewed paper you can cite

YASA is not only a toolbox of algorithms. The automatic sleep staging is the subject of a paper, and the README asks you to cite it: the eLife publication by Raphael Vallat and Matthew P. Walker, An open-source, high-performance tool for automated sleep staging, Elife 10 (2021), with the DOI 10.7554/eLife.70092.

That is a meaningful difference from a hobby script. A staging method is something a reviewer will ask about, so having the method published, the code open, and a DOI to point at changes how a result can be used. The link to the article is in the features list, next to automatic sleep staging of polysomnography data.

The repository root also contains HYPNOGRAM_MULTIPLE_SCORERS.md, a document on comparing hypnograms produced by different scorers. That is the kind of artefact that only exists in a package used by people who care about inter-rater agreement, and it is a good signal about the audience.

The package is created and maintained by Raphael Vallat, with the authorship and maintenance in the manifest shared with Remington Mallett, and contributions are welcome through the contributing guide.

The dependency list explains what the package actually does

The runtime dependencies are worth reading as a description of the methods, because a sleep analysis package needs a specific set of numerics.

`numpy>=2.2.2`, `scipy>=1.15` and `pandas>=2.3` are the base, with `matplotlib>=3.10.1` and `seaborn>=0.13.2` for the figures. `mne>=1.10` is the EEG library, which is what handles reading the recording formats and the channel conventions. `antropy>=0.1.9` is the IED package used for the event detection, so the spindle, slow-wave and REM detectors are based on published IED algorithms rather than on ad hoc thresholds. `scikit-learn>=1.6.1` and `lightgbm>=4.6` cover the machine learning side, which is what the automatic staging model needs, and `lspopt>=1.4` is for the spectral estimation.

Two entries explain the ergonomics rather than the method. `joblib` is there for parallelism, and `pooch>=1.8` for fetching and caching remote files, which in a sleep analysis package is almost certainly the reference datasets and the trained model weights.

That last one is the detail to think about for a clinical or institutional deployment, since a package that downloads its model at first use needs a way to work in an environment without outbound network access, and the README does not describe one.

An alpha status in spirit, a growing release line in practice

The recent releases are v0.8.0 from 2026-10-02, v0.7.0 from 2026-03-08 and v0.6.5 from 2024-07-04. The repository is not archived and the last push was on 2026-10-17, so the work is current and the version line is moving again after a quiet stretch in 2024 and 2025.

The project is built on the usual research foundations: a codecov badge, a ruff badge, a PyPI version badge, a pre-commit configuration, a `docs` directory, `notebooks`, a `paper` directory and a `tests` directory, with the source under `src` and a setuptools build backend requiring setuptools 80 or newer. The version is dynamic rather than written into the manifest, and there is a `push_pypi.md` file describing the release procedure.

What is unusual is the disclaimer. The README states plainly that this program is provided with NO WARRANTY OF ANY KIND, and the licence is BSD-3-Clause. For a package whose headline feature is an automatic staging model, that is an honest pairing. The staging is validated by a peer reviewed paper rather than by a support commitment, and anyone using the output in a clinical context needs to know which of those two they are relying on.

Editorial conclusion

YASA fits a sleep researcher or clinician who wants reproducible analysis of polysomnography recordings, with automatic staging, event detection and hypnogram statistics in one package rather than a folder of scripts. It is the wrong choice if you need a packaged application rather than a library, and the wrong choice if you cannot accept a dependency set that includes scikit-learn, LightGBM and MNE. Verify first that your recordings load through the format the FAQ describes, which version of the staging model matches the paper you want to reproduce, and which optional extras your workflow actually needs, since the heart and art extras pull in separate packages.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. raphaelvallat/yasa on GitHub
4. README
5. Releases