YASA v0.7.0

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

New Contributors

• @bartromb made their first contribution in #198
• @ChinHui-Chen made their first contribution in #220

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

0.6.5

Highlights of this release are:

• PR 130: Add new yasa.EpochByEpochAgreement and yasa.SleepStatsAgreement modules for evaluating the agreement between two scorers (e.g. human vs YASA), either at the epoch-by-epoch level or at the level of summary sleep statistics. This is an experimental feature. Remaining tasks to complete the Evaluation pipeline are described in #166. Huge kudos to @remrama for this incredible new module!
• PR 171: Fix deprecated scipy.integrate.simps.

What's Changed

• Update mne.pick_channels() to mne.pick() by @sjg2203 in #154
• Replace Error raised by less than 5 minutes of data by a Warning by @nabilalibou in #160
• chore: update black by @raphaelvallat in #161
• Add back support for old hypnogram format in plot_hypnogram by @raphaelvallat in #162
• Remove deprecation warning for seaborn by @raphaelvallat in #163
• evaluation module by @remrama in #130
• Updated deprecated functions by @sjg2203 in #167
• BUG: Fix bug with removed SciPy function by @larsoner in #171
• Release 0.6.5 by @raphaelvallat in #176

New Contributors

• @sjg2203 made their first contribution in #154
• @nabilalibou made their first contribution in #160
• @larsoner made their first contribution in #171

Full Changelog: v0.6.4...v0.6.5

v0.6.4

Minor release with one bugfix and several other improvements:

• Fix MNE plot_topomap deprecation (#119)
• Pass relative_prominence parameters in :py:func:yasa.rem_detect (#151)
• Rename yasa.simulate_hypno function to yasa.simulate_hypnogram
• Add Hypnogram class in public API. Hypnogram will become the default method for manipulating hypnograms in YASA starting from v0.7.
• Requires mne>=1.3, numpy>=1.18.1, numba>=0.57.1

v0.6.3

This is a minor release with one bugfix and one new function. Big shoutout to @remrama for his huge help on this new version!

Bugfix

Solved a bug in the spindles detection which resulted in no spindle being detected on some systems. See #107 and #115.

New functions

Added the yasa.simulate_hypno function to generate a simulated hypnogram, primarily for testing purposes and tutorials. The hypnogram is simulated as a Markov sequence based on sleep stage transition probabilities. Transition probabilities can be user-defined or will default to those published in Metzner et al., 2021, Commun Biol (see Figure 5b). See #109 and #110

Improvements

• Added the ax keyword-argument to yasa.plot_hypnogram and removed figsize. Now select figure aesthetics (e.g., size, dpi) by opening a matplotlib.axes.Axes instance and passing to ax. See PR #108
• yasa.plot_hypnogram now draws the hypnogram withmatplotlib.pyplot.stairs instead of matplotlib.pyplot.step. See issue #106 and PR #108

v0.6.2

This releases implement several new functions. Please refer to the full changelog at: https://raphaelvallat.com/yasa/build/html/changelog.html#v0-6-2-august-2022

What's Changed

• Add two new functions: a) find periods in hypnogram and b) heart rate by stage by @raphaelvallat in #68
• Use MNE for conversion Volts to uV by @raphaelvallat in #70
• Add conda install instructions by @raphaelvallat in #76
• Black formatting by @raphaelvallat in #83
• Better handling of flat data in numba function and spindles detect by @raphaelvallat in #86
• Functions to compare agreement of events detections by @raphaelvallat in #71
• adding vmax vmin functionality with minimal tests #73 by @matiasandina in #75
• Add EEG-HRV coupling notebook by @raphaelvallat in #89
• Release v0.6.2 by @raphaelvallat in #92

New Contributors

• @matiasandina made their first contribution in #75

v0.6.1

This release fixes a CRITICAL BUG with the spindles detection. Specifically, the yasa.spindles_detect() could return different results depending on the sampling rate of the data. For example, downsampling the data from 256 Hz to 128 Hz may have significantly reduced the number of detected spindles. As explained in issue 54, this bug was caused by a floating-point error in numpy.convolve() when calculating the soft spindle threshold. Tests seem to indicate that only certain sampling frequencies were impacted, such as 200 Hz, 256 Hz or 400 Hz. Other sampling frequencies such as 100 Hz and 500 Hz were seemingly not affected by this bug.

We recommend all users to upgrade to this new version ASAP and check any results obtained with the yasa.spindles_detect() function!

v0.6.0

YASA 0.6.0

This is a MAJOR release with several API-breaking changes, new functions, bugfixes and a new section in the documentation.

Slow oscillations—sigma coupling

IMPORTANT — The default behavior of coupling=True in yasa.sw_detect() has been changed: YASA now uses a ± 1 second window around the negative peak of the slow-waves (2 sec total) to calculate the coupling, instead of a ± 2 sec window. Overall, this tends to increase the ndPAC values because of the higher temporal specificity. To keep a 4-sec window, use coupling_params['time'] = 2.

We’ve enabled the statistical thresholding in the ndPAC calculation. Practically, this means that events with a weak/unreliable coupling are assigned an ndPAC value of zero. Statistical thresholding can be disabled with coupling_params['p'] = None.

Because of these changes, the coupling values are therefore not comparable with previous versions of YASA. Please make sure to re-run your analyses with the new default parameters.

Events detection

• The yasa.sw_detect() function now uses more conservative amplitude thresholds: the max PTP amplitude has been reduced from 500 to 350 uV, the max negative amplitude has been reduced from 300 to 200 uV, and the max positive amplitude has been reduced from 200 to 150 uV.
• Added yasa.SWResults.find_cooccurring_spindles() to detect whether each slow-wave co-occurr with a sleep spindle.
• Added the as_dataframe parameter in yasa.SWResults.get_sync_events() and yasa.SpindlesResults.get_sync_events(). If set to False, YASA will return the peak-locked data as a list (n_channels) of numpy arrays (n_events, n_times). This facilitates any analyses that requires access to event-locked data (e.g. time-frequency plot, or comodulogram).
• Added the mask parameter in yasa.SWResults.summary(), yasa.SWResults.get_sync_events(), and yasa.SWResults.plot_average(). This allows users to only include selected events in the summary or plots (e.g. the slow-waves with the largest peak-to-peak amplitude, or strongest coupling).
• Added the mask parameter in yasa.SpindlesResults.summary(), yasa.SpindlesResults.get_sync_events(), and yasa.SpindlesResults.plot_average(). This allows users to only include selected events in the summary or plots (e.g. the spindles with the largest amplitude).
• Added the mask parameter in yasa.REMResults.summary(), yasa.REMResults.get_sync_events(), and yasa.REMResults.plot_average().

Plotting

• Added the yasa.plot_hypnogram() function to plot an hypnogram.

Documentation

• Added a Quickstart section to illustrate the main functions of YASA. Make sure to check it out!

Others

• yasa.irasa() now informs about the maximum resampled fitting range, and raises a warning if parameters/frequencies are ill-specified. See #42 and associated paper: https://doi.org/10.1101/2021.10.15.464483
• Added a verbose parameter to yasa.hypno_upsample_to_data() and yasa.irasa().
• Remove Travis CI
• Remove CI testing for Python 3.6

v0.5.1

This is a bugfix release. The latest pre-trained classifiers for yasa.SleepStaging were accidentally missing from the previous release. They have now been included in this release. We recommend all users to upgrade to this version with pip install –upgrade yasa

v0.5.0

This is a major release with an important bugfix for the slow-waves detection as well as API-breaking changes in the automatic sleep staging module. Please read the full changelog here.

We recommend all users to upgrade to this version with pip install –upgrade yasa.

v0.4.1

New functions

Added yasa.topoplot(), a wrapper around mne.viz.plot_topomap(). See 15_topoplot.ipynb.

Enhancements

• The default frequency range for slow-waves in yasa.sw_detect() is now 0.3-1.5 Hz instead of 0.3-2 Hz. Indeed, most slow-waves have a frequency below 1Hz. This may result in slightly different coupling values when coupling=True so make sure to homogenize your slow-waves detection pipeline across all nights in your dataset.
• yasa.trimbothstd() now handles missing values in input array.
• yasa.bandpower_from_psd() and yasa.bandpower_from_psd_ndarray() now print a warning if the PSD contains negative values. See issue 29.
• Upon loading, YASA will now use the outdated package to check and warn the user if a newer stable version is available.
• YASA now uses the AntroPy package to calculate non-linear features in the automatic sleep staging module. Previously, YASA was using EntroPy, which could not be installed using pip.