Hypnogram plot_hypnogram method

[remrama]

This PR brings yasa.plot_hypnogram up to speed with the new yasa.Hypnogram class (Issue #116). See Issue #122 for more details.

Main changes:

• yasa.plot_hypnogram does not accept int/str sequence hypnograms anymore. Input must be a Hypnogram instance.
• The function yasa.plot_hypnogram still exists, but should mostly be considered a utility function at this point. The user should always plot with yasa.Hypnogram.plot_hypnogram
• plot_hypnogram handles any valid n_stages
• plot_hypnogram takes a highlight parameter where any valid stage label can be passed for a red highlight (this used to be automatic to REM, but with variable n_stages options this might differ among use-cases).
• The hypnogram plot x-axis will have a datetime axis with time as HH:MM if the Hypnogram instance has a start value.
• yasa.plot_spectrogram now accepts an optional hyp Hypnogram, as opposed to an optional hypno array.

I didn't update any Jupyter notebooks. That feels like it would be easier to do all at once after all the new functions properly handle Hypnogram objects? Maybe as a final step?

Sidenote: Currently, yasa.Hypnogram.upsample_to_data returns an array but yasa.Hypnogram.upsample returns another Hypnogram instance. Is that intended? It seems like they should both return another Hypnogram instance and then user can get the integer array as-needed. But maybe you have some other logic behind this.

btw, yasa.Hypnogram.mapping is awesome! Sorry @raphaelvallat when I originally reviewed #116 I wasn't familiar with Python setters and so didn't realize how powerful and simple this is.

[codecov-commenter]

Codecov Report

Base: 92.53% // Head: 92.57% // Increases project coverage by +0.04% 🎉

Coverage data is based on head (ff637a0) compared to base (3dfe2d6).
Patch coverage: 98.14% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #124      +/-   ##
==========================================
+ Coverage   92.53%   92.57%   +0.04%     
==========================================
  Files          23       23              
  Lines        3106     3112       +6     
==========================================
+ Hits         2874     2881       +7     
+ Misses        232      231       -1     

Impacted Files	Coverage Δ
yasa/plotting.py	96.98% <96.92%> (+0.15%)	⬆️
yasa/hypno.py	98.57% <100.00%> (+0.25%)	⬆️
yasa/tests/test_hypnoclass.py	100.00% <100.00%> (ø)
yasa/tests/test_plotting.py	100.00% <100.00%> (ø)
yasa/sleepstats.py	100.00% <0.00%> (ø)
yasa/tests/test_hypno.py	100.00% <0.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[remrama]

Here's pngs of the new examples under yasa.plot_hypnogram.

Example 1

from yasa import Hypnogram
import matplotlib.pyplot as plt
values = 4 * ["W", "N1", "N2", "N3", "REM"] + ["ART", "N2", "REM", "W", "UNS"]
hyp = Hypnogram(values, freq="24min").upsample("30s")
ax = hyp.plot_hypnogram(lw=2, highlight="REM", fill_color="thistle")
plt.tight_layout()

Example 2

from yasa import simulate_hypno
fig, axes = plt.subplots(nrows=2, figsize=(6, 4), constrained_layout=True)
hyp_a = simulate_hypno(tib=90, n_stages=3, seed=99)
hyp_b = simulate_hypno(tib=90, n_stages=3, seed=99, start="2022-01-31 23:30:00")
hyp_a.plot_hypnogram(fill_color="whitesmoke", ax=axes[0])
hyp_b.plot_hypnogram(fill_color="whitesmoke", ax=axes[1])

[raphaelvallat]

Just an incredible amount of work @remrama. This is 🔥

• Please rebase and force-push to master. You can do it directly from GitHub.
• My major comment concerns the input of plot_spectrogram and more generally the behavior of yasa.Hypnogram.upsample_to_data. See comment for more details.

[remrama]

@raphaelvallat all set! Take a look, probably the only thing is the copy method. I left that comment open for you to add to or resolve if you're good.

If you're satisfied with the changes, go ahead and merge or give me the go-ahead to do so.

[raphaelvallat]

Thanks @remrama! Approved and merged 👏