Prep for 0.7.0 (major update to dependencies, tests, documentation and build infra)

[raphaelvallat]

@remrama — with major help from Claude, I'm preparing a major upgrade of YASA. I don't expect you to review all the changes in this PR but just an FYI. A (non-exhaustive) list of all the changes implemented in this PR is provided below — see also the changelog.rst file

Dependencies

• Pandas 3.0 / numpy 2 compatibility 🎉
  • Fixed ValueError: underlying array is read-only in coincidence matrix computation in compare_detection — replaced np.fill_diagonal(coinc_mat.values, ...) with np.diag_indices_from + coinc_mat.iloc[idx].
  • Fixed TypeError: Cannot setitem on a Categorical with a new category in Hypnogram.consolidate_stages.
  • Fixed AssertionError in Hypnogram.__init__ when pandas returns an ArrowStringArray (new default string backend in pandas 3.0).
  • Fixed PerformanceWarning: DataFrame is highly fragmented in SleepStaging — switched from sequential column assignment to pd.concat.
  • Fixed Pandas4Warning for Series.sum(1) → Series.sum(axis=1) in Hypnogram and the test suite.
• Python support: Dropped Python 3.9 (EOL October 2025); added Python 3.13. Now requires Python ≥ 3.10.
• Minimum dependency versions bumped: numpy >= 1.22.4, scipy >= 1.8.1, pandas >= 2.1.1.
• Packaging: src/ layout, pyproject.toml-only config, development dependencies moved to [dependency-groups] (PEP 735). Removed setuptools from runtime dependencies.
• Package manager: Switched to uv as the recommended package manager.

New features

• new Hypnogram.from_integers classmethod: New convenience constructor to create a Hypnogram directly from a legacy integer-encoded array (e.g. loaded from a plain-text file via np.loadtxt). Replaces the old
  two-step hypno_int_to_str + Hypnogram(...) pattern and accepts an optional custom mapping for non-standard integer encodings.
• transition_matrix accepts Hypnogram: yasa.transition_matrix now accepts a Hypnogram instance in addition to integer arrays. When passed a Hypnogram, output DataFrames use string stage labels ("WAKE", "N1",
  etc.) instead of integers.

Unit tests

• Added minimal unit tests for EpochByEpochAgreement and SleepStatsAgreement covering construction, input validation, all public methods
• Commented out --cov from pytest addopts so individual test files can be run without triggering full coverage collection
• GitHub CI overhaul:
  • Updated all GitHub Actions to latest versions (checkout@v6, setup-python@v6, setup-uv@v7).
  • Added a test-dependency-combinations job: runs tests against both minimum-supported and latest versions of numpy, scipy, pandas, MNE, and numba.
  • Coverage reporting moved to a dedicated coverage.yml workflow.
  • Added ruff linting and formatting to CI.
  • CI now only triggers on changes to src/, tests/, or pyproject.toml.

Bugfix

• Fixed SleepStatsAgreement bootstrap regression: column_order was hardcoding "Reference" instead of self.ref_scorer, causing incorrect column lookups when a custom scorer name was used

Documentation

• Major updates to the Quickstart, README and index.rst files (e.g. to use the new Hypnogram API)
• Updated and ran all tutorial notebooks to use the new Hypnogram API
• Fixed multiple broken or outdated links in doc and docstrings
• Custom Sphinx autosummary template for classes that generates a methods and attributes summary table in the auto-generated API pages

Remaining tasks before merge

• Ensure all tests are passing
  • Fix random zenodo download error
• Run all notebooks
• Do a full read of the documentation and API
  • Index
  • Changelog
  • Contribute
  • SleepStaging
  • Hypnogram
  • EpochByEpochAgreement
  • SleepStatsAgreement
• Verify docstring code block output

[codecov-commenter]

Codecov Report

❌ Patch coverage is 83.33333% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.36%. Comparing base (cbdba7f) to head (6ae2d60).

Files with missing lines	Patch %	Lines
src/yasa/fetchers.py	50.00%	4 Missing and 1 partial ⚠️
src/yasa/evaluation.py	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #225      +/-   ##
==========================================
+ Coverage   77.45%   85.36%   +7.90%     
==========================================
  Files          14       14              
  Lines        2684     2705      +21     
  Branches      326      330       +4     
==========================================
+ Hits         2079     2309     +230     
+ Misses        568      342     -226     
- Partials       37       54      +17     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[remrama]

@raphaelvallat this is great, thanks for all the updates and cleaning up the evaluation module. I'm just catching up on all the new changes and the last things I was hoping to add in #166. Whenever you're ready, if you think it's appopriate I can give this a quick review. I wouldn't get into much detail on anything other than the evaluation module. I'd just like to give that a quick test run locally.

[raphaelvallat]

@remrama — I'm mostly done now, please feel free to review the changes in the evaluation module!

Out of the 4 remaining tasks in #166, this PR implements:

• Add (minimal) unittests
• Updated changelog
• Mini tutorial in the changelog of the 0.7.0, but we should definitely add a dedicated tutorial page (and notebook) at some point (maybe for the next release), ideally re-using the same dataset as the Menghini tutorial (edit: we could ask the authors to share the dataset)

I don't think we need to include the BA plots for this release, unless you think it's critical.

[raphaelvallat]

This PR is becoming too big so I'll merge it once you had a chance to review, but we can definitely take a few more days or weeks to add more functionalities/documentation before I do the formal 0.7.0 release 👍

[raphaelvallat]

Proposal: Remaining tasks/issues after merging this PR before formal 0.7.0 release

• Finalize evaluation module #166
• Add yasa.Hypnogram.as_events() example #191
• Update plot_spectrogram to handle hypnograms with <5 stages #215
• Spindle amplitude is calculated on raw instead of bandpassed data #216
• Add support for Hypnogram class in all the functions that require an upsampled hypnogram in integer format (e.g. automatically get .as_int() from the Hypnogram object)

Stretch:

• Add Bland-Altmann plot in Evaluation module
• Add full tutorial with sample data for Evaluation module

[remrama]

This is great @raphaelvallat! Fantastic push to get things up to date and modernized. The evaluation module looks solid, thanks again for cleaning it up. I assume the testing is appropriate and it's clear that it's passing, so I'm not worried about that. Only thing I was gonna do is verify that the values in docstring examples are accurate (since those are manually input). Do we have anything in the CI workflows or doc build that handles that verification? If not, I'll run locally and verify.

[raphaelvallat]

Only thing I was gonna do is verify that the values in docstring examples are accurate (since those are manually input). Do we have anything in the CI workflows or doc build that handles that verification? If not, I'll run locally and verify.

Not in the CI but I asked Claude to run and fix all the doctest for the evaluation and hypnogram modules

[remrama]

Not in the CI but I asked Claude to run and fix all the doctest for the evaluation and hypnogram modules

Cool, ya I saw some values (in docstrings) were updated so I figured there was some kind of check. That's cool for now. I'll double-check next time I submit anything related to that module, but for this let's leave it as-is without another check since it's not a functional piece of the module anyways. Good to go 🚀