Update string representation of yasa.Hypnogram (#129)

* Update string representation of yasa.Hypnogram

* Add scorer to __repr__

* Update docstring

* Add back `

yasa/hypno.py

@@ -83,6 +83,15 @@ class Hypnogram:
     >>> from yasa import Hypnogram
     >>> values = ["W", "W", "W", "S", "S", "S", "S", "S", "W", "S", "S", "S"]
     >>> hyp = Hypnogram(values, n_stages=2)
+    >>> hyp
+    <Hypnogram | 12 epochs x 30s (6.00 minutes), 2 stages>
+     - Use `.hypno` to get the string values as a pandas.Series
+     - Use `.as_int()` to get the integer values as a pandas.Series
+     - Use `.plot_hypnogram()` to plot the hypnogram
+    See the online documentation for more details.
+
+    We can access the actual values, which are stored as a :py:class:`pandas.Series`, with:
+
     >>> hyp.hypno
     Epoch
     0      WAKE
@@ -159,7 +168,14 @@ class Hypnogram:
     >>> from yasa import simulate_hypnogram
     >>> hyp = simulate_hypnogram(
     ...     tib=500, n_stages=5, start="2022-12-15 22:30:00", scorer="S1", seed=42)
-    >>> hyp  # This is a shortcut to `hyp.hypno`
+    >>> hyp
+    <Hypnogram | 1000 epochs x 30s (500.00 minutes), 5 stages, scored by S1>
+     - Use `.hypno` to get the string values as a pandas.Series
+     - Use `.as_int()` to get the integer values as a pandas.Series
+     - Use `.plot_hypnogram()` to plot the hypnogram
+    See the online documentation for more details.
+
+    >>> hyp.hypno
     Time
     2022-12-15 22:30:00    WAKE
     2022-12-15 22:30:30    WAKE
@@ -267,10 +283,27 @@ def __init__(self, values, n_stages=5, *, freq="30s", start=None, scorer=None):
         self._scorer = scorer
 
     def __repr__(self):
-        return f"{self.hypno}"
+        # TODO v0.8: Keep only the text between < and >
+        text_scorer = f", scored by {self.scorer}" if self.scorer is not None else ""
+        return (
+            f"<Hypnogram | {self.n_epochs} epochs x {self.freq} ({self.duration:.2f} minutes), "
+            f"{self.n_stages} stages{text_scorer}>\n"
+            " - Use `.hypno` to get the string values as a pandas.Series\n"
+            " - Use `.as_int()` to get the integer values as a pandas.Series\n"
+            " - Use `.plot_hypnogram()` to plot the hypnogram\n"
+            "See the online documentation for more details."
+        )
 
     def __str__(self):
-        return f"{self.hypno}"
+        text_scorer = f", scored by {self.scorer}" if self.scorer is not None else ""
+        return (
+            f"<Hypnogram | {self.n_epochs} epochs x {self.freq} ({self.duration:.2f} minutes), "
+            f"{self.n_stages} stages{text_scorer}>\n"
+            " - Use `.hypno` to get the string values as a pandas.Series\n"
+            " - Use `.as_int()` to get the integer values as a pandas.Series\n"
+            " - Use `.plot_hypnogram()` to plot the hypnogram\n"
+            "See the online documentation for more details."
+        )
 
     @property
     def hypno(self):
@@ -1599,7 +1632,14 @@ def simulate_hypnogram(
     --------
     >>> from yasa import simulate_hypnogram
     >>> hyp = simulate_hypnogram(tib=5, seed=1)
-    >>> print(hyp)
+    >>> hyp
+    <Hypnogram | 10 epochs x 30s (5.00 minutes), 5 stages>
+     - Use `.hypno` to get the string values as a pandas.Series
+     - Use `.as_int()` to get the integer values as a pandas.Series
+     - Use `.plot_hypnogram()` to plot the hypnogram
+    See the online documentation for more details.
+
+    >>> hyp.hypno
     Epoch
     0    WAKE
     1      N1
@@ -1614,7 +1654,7 @@ def simulate_hypnogram(
     Name: Stage, dtype: object
 
     >>> hyp = simulate_hypnogram(tib=5, n_stages=2, seed=1)
-    >>> print(hyp)
+    >>> hyp.hypno
     Epoch
     0     WAKE
     1    SLEEP
@@ -1632,7 +1672,7 @@ def simulate_hypnogram(
 
     >>> hyp = simulate_hypnogram(tib=5, n_stages=2, seed=1)
     >>> hyp.hypno.iloc[-2:] = "UNS"
-    >>> print(hyp)
+    >>> hyp.hypno
     Epoch
     0     WAKE
     1    SLEEP