Add FutureWarning in hypnogram functions

[raphaelvallat]

This is a pretty straightforward PR that adds a FutureWarning to the now-outdated yasa.hypno functions. I did not add a warning for a few functions that are called directly from the class methods (e.g. transition_matrix).

This PR also implements a few minor fixes and improvements in the docstring.

@remrama would appreciate your review if time allows it. Otherwise I can just merge as is since it's a low-risk PR.

[codecov-commenter]

Codecov Report

Base: 92.53% // Head: 92.48% // Decreases project coverage by -0.04% ⚠️

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

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #123      +/-   ##
==========================================
- Coverage   92.53%   92.48%   -0.05%     
==========================================
  Files          23       23              
  Lines        3106     3088      -18     
==========================================
- Hits         2874     2856      -18     
  Misses        232      232              

Impacted Files	Coverage Δ
yasa/tests/test_hypno.py	100.00% <ø> (ø)
yasa/tests/test_hypnoclass.py	100.00% <ø> (ø)
yasa/hypno.py	98.27% <100.00%> (-0.05%)	⬇️
yasa/sleepstats.py	100.00% <100.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]

Great!

I'm surprised you didn't deprecate yasa.hypno.hypno_consolidate_stages? Or maybe just remove it? I was thinking that function is so new that it could probably just get removed without notice. I think it was maybe even added knowing that it would not be needed for long.

Whatever you wanna do is cool with me. Merge! 🚀

[raphaelvallat]

Thanks for the super quick review! Good catch re: yasa.hypno_consolidate_stages. I have decided to remove it since it wasn't part of the public API anyway.

One pending comment for you regarding as_int. If we decide to return a numpy array instead I'll implement in a separate PR.

[remrama]

I did not add a warning for a few functions that are called directly from the class methods (e.g. transition_matrix).

Just wanted to add an argument here for always retaining these functions as isolated utility functions. I'm currently developing some examples for an upcoming PR and I am finding it useful to have functions like transition_matrix and sleep_statistics on their own (i.e., as functions and not methods attached to Hypnograms). I like passing them to pandas methods like apply and transform. If you think of YASA as a more broad sleep analysis utility, others might find these useful too.

I see here you aren't planning to immediately deprecate them, just noting in case it's on the table.

Of course best to not have redundant code, so not sure how to handle it.

[raphaelvallat]

Good point, I actually also use pandas.apply quite a lot. However for sleep_statistics the method implementation is now better than the original function. So maybe we can create a class instance internally and then just return the method? This would also avoid code redundancy.

We can also discuss whether to leave or remove them from the public API in 6-12 months when we get closer to v0.8