YASA v0.7.0

[raphaelvallat]

v0.7.0 — March 2026

This is the first major release of YASA in two years 🎉 !

This release introduces a new object-oriented hypnogram API, new functionalities, and several bugfixes. This version requires Python 3.10+ and is fully compatible with pandas 3.x and numpy 2.x.

New: Object-oriented Hypnogram class

Warning

Breaking changes — action required

This release introduces the yasa.Hypnogram class as the new standard for representing hypnograms throughout YASA. Several functions and classes that previously returned plain NumPy arrays now return a yasa.Hypnogram instead, which will break existing code that expects an array. Key examples:

• SleepStaging.predict() now returns a Hypnogram instead of a string array. To recover the underlying array use .hypno (string labels) or .as_int() (integer-encoded).
• yasa.plot_hypnogram() now requires a Hypnogram as input.

See the migration guide for step-by-step instructions, and the Working with Hypnograms tutorial for a full introduction to the new API.

New functions

• yasa.fetch_sample: download and cache sample YASA data files. (PR #192), special thanks to @remrama for implementing this!

API changes

• SleepStaging.predict() now returns a Hypnogram instead of a string NumPy array. Stage probabilities are stored in .proba and can be plotted with .plot_hypnodensity().
• yasa.plot_hypnogram() now requires a Hypnogram instance as input (previously accepted a plain array).
• Detection functions (spindles_detect, sw_detect, rem_detect) now log an explicit warning when sf or ch_names are ignored because an MNE object was passed. (PR #207)
• spindles_detect output now includes an AmplitudeFiltered column reporting the spindle amplitude measured on the filtered signal. (issue #216)

Bugfixes

• Fixed slow-wave slope calculation: the slope numerator was incorrectly using the positive half-wave amplitude instead of the negative half-wave amplitude. (PR #220)
• Fixed multiple compatibility issues with pandas 3.x and numpy 2.x in yasa.compare_detection, yasa.Hypnogram, and yasa.SleepStaging.
• Fixed multiple broken or outdated links in documentation and docstrings.

Dependencies

• Python ≥ 3.10 is now required (dropped Python 3.9, which reached end-of-life in October 2025; added Python 3.13).
• Bumped minimum versions: numpy >= 1.22.4, scipy >= 1.8.1, pandas >= 2.1.1.
• Non-essential dependencies (mne, scikit-learn, lightgbm, antropy, tensorpac) are now optional
• Bumped minimum lspopt version. (PR #195)

Documentation

• New Tutorials section with three step-by-step guides: Quickstart, Working with Hypnograms, and Migrating from v0.6.
• Overhauled the documentation with the PyData Sphinx Theme. (PR #194)
• Added YASA Flaskified (a web-based interface built on YASA) to README and FAQ. (PR #198)
• Fixed multiple broken or outdated links. (PR #202, PR #210)

Packaging & tooling

• Modern packaging: migrated to src/ layout, pyproject.toml-only configuration, numpy 2 compatibility. (PR #187)
• Switched to uv as the recommended package manager; development dependencies moved to [dependency-groups] (PEP 735).
• Added ruff linting and formatting to the CI pipeline.
• New test-dependency-combinations CI job: runs the test suite against minimum-supported and latest versions of numpy, scipy, pandas, MNE, and numba.

---

Merged PRs

• SleepStaging returns a yasa.Hypnogram instance by @raphaelvallat in SleepStaging returns a yasa.Hypnogram instance #127
• Modern packaging + ruff + numpy 2 compat by @raphaelvallat in Modern packaging + ruff + numpy 2 compat #187
• bump lspopt version requirement by @remrama in bump lspopt version requirement #195
• Overhaul docs with PyData Sphinx Theme by @remrama in Overhaul docs with PyData Sphinx Theme #194
• ruff + fix FAQ + remove announcement by @raphaelvallat in ruff + fix FAQ + remove announcement #199
• Fix 404 page by @remrama in Fix 404 page #202
• Add volts vs micro-volts to FAQ by @remrama in Add volts vs micro-volts to FAQ #204
• specify REM density units in docs by @remrama in specify REM density units in docs #206
• Add YASA Flaskified details to README and FAQ by @bartromb in Add YASA Flaskified details to README and FAQ #198
• New fetchers module to download/cache all YASA sample data by @remrama in New fetchers module to download/cache all YASA sample data #192
• Log warning when sf or ch_names are ignored by @remrama in Log warning when sf or ch_names are ignored #207
• yasa-sleep.org by @raphaelvallat in yasa-sleep.org #210
• Fix: use negative half-wave amplitude for SW slope numerator by @ChinHui-Chen in Fix: use negative half-wave amplitude for SW slope numerator #220
• Prep for 0.7.0 (major update to dependencies, tests, documentation and build infra) by @raphaelvallat in Prep for 0.7.0 (major update to dependencies, tests, documentation and build infra) #225
• Prep for 0.7.0 release (part 2) by @raphaelvallat in Prep for 0.7.0 release (part 2) #227
• Hypnogram improvements: timestamp-aware alignment, new API, and bug fixes by @raphaelvallat in Hypnogram improvements: timestamp-aware alignment, new API, and bug fixes #229
• Hypnogram: Add to_dict / from_dict and to_json / from_json methods by @raphaelvallat in Hypnogram: Add to_dict / from_dict and to_json / from_json methods #230
• Hypnogram.upsample_to_data: treat EDF meas_date as local time by default by @raphaelvallat in Hypnogram.upsample_to_data: treat EDF meas_date as local time by default #231
• Hypnogram: add pad method and doc improvements by @raphaelvallat in Hypnogram: add pad method and doc improvements #232
• Add Hypnogram.plot_hypnodensity method by @raphaelvallat in Add Hypnogram.plot_hypnodensity method #233
• DOC: Add Hypnogram tutorial and Migration tutorial from 0.6 to 0.7 by @raphaelvallat in DOC: Add Hypnogram tutorial and Migration tutorial from 0.6 to 0.7 #234

New Contributors

• @bartromb made their first contribution in Add YASA Flaskified details to README and FAQ #198
• @ChinHui-Chen made their first contribution in Fix: use negative half-wave amplitude for SW slope numerator #220

Full Changelog: v0.6.5...v0.7.0

---

This discussion was created from the release YASA v0.7.0.

[remrama]

Fantastic! Thanks @raphaelvallat for putting in the huge amount of work to catch this up. The two new tutorials (migration guide and working with Hypnograms) look especially useful. I was worried about users picking up on that but those are a huge help and I think they will make the transition much more palettable. I myself have been using the Hypnogram class a lot and find it super convenient so I hope others do to.

[ChinHui-Chen]

Great to see the new release. Awesome work!