Add support for custom row labels

README.md

@@ -144,7 +144,7 @@ samples = [
 # And finish by styling it up to your liking!
 fig = ridgeplot(
     samples=samples,
-    labels=months,
+    row_labels=months,
     colorscale="Inferno",
     bandwidth=4,
     kde_points=np.linspace(-40, 110, 400),

cicd_utils/ridgeplot_examples/_lincoln_weather.py

@@ -33,7 +33,7 @@ def main(
 
     fig = ridgeplot(
         samples=samples,
-        labels=months,
+        row_labels=months,
         colorscale=colorscale,
         colormode=colormode,
         bandwidth=4,

docs/getting_started/getting_started.md

@@ -134,7 +134,7 @@ samples = [
 # And finish by styling it up to your liking!
 fig = ridgeplot(
     samples=samples,
-    labels=months,
+    row_labels=months,
     colorscale="Inferno",
     bandwidth=4,
     kde_points=np.linspace(-40, 110, 400),
@@ -228,7 +228,7 @@ Finally, we can pass the {py:paramref}`~ridgeplot.ridgeplot.samples` list to the
 ```python
 fig = ridgeplot(
     samples=samples,
-    labels=months,
+    row_labels=months,
     colorscale="Inferno",
     bandwidth=4,
     kde_points=np.linspace(-40, 110, 400),

docs/reference/changelog.md

@@ -5,7 +5,13 @@ This document outlines the list of changes to ridgeplot between each release. Fo
 Unreleased changes
 ------------------
 
-- ...
+### Features
+
+- Add support for custom row labels via a new `row_labels` argument ({gh-pr}`333`)
+
+### Deprecations
+
+- Deprecated the `show_yticklabels` argument in favor of the new more general and flexible `row_labels` argument ({gh-pr}`333`)
 
 ---
 

mypy.ini

@@ -44,8 +44,6 @@ plugins = numpy.typing.mypy_plugin
 
 [mypy-importlib_resources.*]
 ignore_missing_imports = True
-[mypy-plotly.*]
-ignore_missing_imports = True
 [mypy-_plotly_utils.*]
 ignore_missing_imports = True
 [mypy-pre_commit_hooks.*]

requirements/typing.txt

@@ -7,6 +7,7 @@ types-pytz
 types-PyYAML
 types-requests
 types-tqdm
+plotly-stubs; python_version >= "3.10"
 pandas-stubs
 
 # pyright also needs to inherit other environment dependencies in

src/ridgeplot/_figure_factory.py

@@ -74,15 +74,14 @@ def normalise_trace_labels(
     return trace_labels
 
 
-def normalise_y_labels(trace_labels: LabelsArray) -> LabelsArray:
-    return [ordered_dedup(row) for row in trace_labels]
+def normalise_row_labels(trace_labels: LabelsArray) -> Collection[str]:
+    return [",".join(ordered_dedup(row)) for row in trace_labels]
 
 
 def update_layout(
     fig: go.Figure,
-    y_labels: LabelsArray,
+    row_labels: Collection[str] | Literal[False],
     tickvals: list[float],
-    show_yticklabels: bool,
     xpad: float,
     x_max: float,
     x_min: float,
@@ -96,11 +95,15 @@ def update_layout(
         showgrid=True,
     )
     fig.update_yaxes(
-        showticklabels=show_yticklabels,
-        tickvals=tickvals,
-        ticktext=y_labels,
+        showticklabels=row_labels is not False,
         **axes_common,
     )
+    if row_labels is not False:
+        fig.update_yaxes(
+            tickmode="array",
+            tickvals=tickvals,
+            ticktext=row_labels,
+        )
     x_padding = xpad * (x_max - x_min)
     fig.update_xaxes(
         range=[x_min - x_padding, x_max + x_padding],
@@ -122,14 +125,14 @@ def update_layout(
 def create_ridgeplot(
     densities: Densities,
     trace_types: TraceTypesArray | ShallowTraceTypesArray | TraceType,
+    row_labels: Collection[str] | None | Literal[False],
     colorscale: ColorScale | Collection[Color] | str | None,
     opacity: float | None,
     colormode: Literal["fillgradient"] | SolidColormode,
     trace_labels: LabelsArray | ShallowLabelsArray | None,
     line_color: Color | Literal["fill-color"],
     line_width: float | None,
     spacing: float,
-    show_yticklabels: bool,
     xpad: float,
 ) -> go.Figure:
     # ==============================================================
@@ -152,12 +155,14 @@ def create_ridgeplot(
         trace_labels=trace_labels,
         n_traces=n_traces,
     )
-    y_labels = normalise_y_labels(trace_labels)
+    if row_labels is None:
+        row_labels = normalise_row_labels(trace_labels)
+    elif row_labels is not False and len(row_labels) != n_rows:
+        raise ValueError(f"Expected {n_rows} row_labels, got {len(row_labels)} instead.")
 
     # Force cast certain arguments to the expected types
     line_width = float(line_width) if line_width is not None else None
     spacing = float(spacing)
-    show_yticklabels = bool(show_yticklabels)
     xpad = float(xpad)
     colorscale = validate_coerce_colorscale(colorscale)
 
@@ -182,13 +187,13 @@ def create_ridgeplot(
     tickvals: list[float] = []
     fig = go.Figure()
     ith_trace = 0
-    for ith_row, (row_traces, row_trace_types, row_labels, row_colors) in enumerate(
+    for ith_row, (row_traces, row_trace_types, row_trace_labels, row_colors) in enumerate(
         zip_strict(densities, trace_types, trace_labels, solid_colors)
     ):
         y_base = float(-ith_row * y_max * spacing)
         tickvals.append(y_base)
         for trace, trace_type, label, color in zip_strict(
-            row_traces, row_trace_types, row_labels, row_colors
+            row_traces, row_trace_types, row_trace_labels, row_colors
         ):
             trace_drawer = get_trace_cls(trace_type)(
                 trace=trace,
@@ -212,9 +217,8 @@ def create_ridgeplot(
 
     fig = update_layout(
         fig,
-        y_labels=y_labels,
+        row_labels=row_labels,
         tickvals=tickvals,
-        show_yticklabels=show_yticklabels,
         xpad=xpad,
         x_max=x_max,
         x_min=x_min,

src/ridgeplot/_ridgeplot.py

@@ -101,6 +101,7 @@ def ridgeplot(
     densities: Densities | ShallowDensities | None = None,
     trace_type: TraceTypesArray | ShallowTraceTypesArray | TraceType | None = None,
     labels: LabelsArray | ShallowLabelsArray | None = None,
+    row_labels: Collection[str] | None | Literal[False] = None,
     # KDE parameters
     kernel: str = "gau",
     bandwidth: KDEBandwidth = "normal_reference",
@@ -117,11 +118,11 @@ def ridgeplot(
     line_color: Color | Literal["fill-color"] = "black",
     line_width: float | None = None,
     spacing: float = 0.5,
-    show_yticklabels: bool = True,
     xpad: float = 0.05,
     # Deprecated parameters
     coloralpha: float | None | MissingType = MISSING,
     linewidth: float | MissingType = MISSING,
+    show_yticklabels: bool | MissingType = MISSING,
 ) -> go.Figure:
     r"""Return an interactive ridgeline (Plotly) |~go.Figure|.
 
@@ -196,10 +197,24 @@ def ridgeplot(
         .. versionadded:: 0.3.0
 
     labels : LabelsArray or ShallowLabelsArray or None
-        A list of string labels for each trace. If not specified (default), the
-        labels will be automatically generated as ``"Trace {n}"``, where ``n``
-        is the trace's index. If instead a list of labels is specified, it
-        should have the same shape as the samples array.
+        A collection of string labels for each trace. If not specified
+        (default), the labels will be automatically generated as
+        ``"Trace {i}"``, where ``i`` is the trace's index. If instead a
+        collection of labels is specified, it should have the same shape as the
+        samples array.
+
+    row_labels : Collection[str] or None or False
+        A collection of string labels for each row in the ridgeline plot. If
+        specified, the length of this collection should match the number of rows
+        in the plot (i.e., the :math:`R` dimension in the :paramref:`.samples`
+        or :paramref:`.densities` parameter). If not specified (default), the
+        row labels displayed on the y-axis will be automatically generated based
+        on the :paramref:`.labels` argument. If set to ``False``, the row
+        labels won't be displayed at all.
+
+        .. versionadded:: 0.4.0
+            Added support for custom row labels, and replaced the deprecated
+            :paramref:`.show_yticklabels` parameter.
 
     kernel : str
         The Kernel to be used during Kernel Density Estimation. The default is
@@ -226,14 +241,14 @@ def ridgeplot(
           ``"scott"`` bandwidth for gaussian kernels. See `bandwidths.py`_.
         - If a float is given, its value is used as the bandwidth.
         - If a callable is given, it's return value is used. The callable
-          should take exactly two parameters, i.e., ``fn(x, kern)``, and return
+          should take exactly two arguments, i.e., ``fn(x, kern)``, and return
           a float, where:
 
           - ``x``: the clipped input data
           - ``kern``: the kernel instance used
 
     kde_points : KDEPoints
-        This argument controls the points at which KDE is computed. If an
+        This parameter controls the points at which KDE is computed. If an
         ``int`` value is passed (default=500), the densities will be evaluated
         at ``kde_points`` evenly spaced points between the min and max of each
         set of samples. Optionally, you can also pass a custom 1D numerical
@@ -278,7 +293,7 @@ def ridgeplot(
         template.
 
     colormode : "fillgradient" or SolidColormode
-        This argument controls the logic used for the coloring of each
+        This parameter controls the logic used for the coloring of each
         ridgeline trace.
 
         The ``"fillgradient"`` mode (default) will fill each trace with a
@@ -323,13 +338,13 @@ def ridgeplot(
             ``"fillgradient"``.
 
     opacity : float or None
-        If None (default), this argument will be ignored and the transparency
+        If None (default), this parameter will be ignored and the transparency
         values of the specified color-scale will remain untouched. Otherwise,
         if a float value is passed, it will be used to overwrite the
         opacity/transparency of the color-scale's colors.
 
         .. versionadded:: 0.2.0
-            Replaces the deprecated :paramref:`.coloralpha` argument.
+            Replaces the deprecated :paramref:`.coloralpha` parameter.
 
     line_color : Color or "fill-color"
         The color of the traces' lines. Any valid CSS color is allowed
@@ -347,20 +362,14 @@ def ridgeplot(
         of 0.5 px.
 
         .. versionadded:: 0.2.0
-            Replaces the deprecated :paramref:`.linewidth` argument.
+            Replaces the deprecated :paramref:`.linewidth` parameter.
 
         .. versionchanged:: 0.2.0
             The default value changed from 1 to 1.5
 
     spacing : float
         The vertical spacing between density traces, which is defined in units
-        of the highest distribution (i.e. the maximum y-value).
-
-    show_yticklabels : bool
-        Whether to show the tick labels on the y-axis. The default is True.
-
-        .. versionadded:: 0.1.21
-            Replaces the deprecated :paramref:`.show_annotations` argument.
+        of the highest distribution (i.e., the maximum y-value).
 
     xpad : float
         Specifies the extra padding to use on the x-axis. It is defined in
@@ -377,6 +386,11 @@ def ridgeplot(
         .. deprecated:: 0.2.0
             Use :paramref:`.line_width` instead.
 
+    show_yticklabels : bool
+
+        .. deprecated:: 0.4.0
+            Use :paramref:`.row_labels` instead.
+
     Returns
     -------
     :class:`plotly.graph_objects.Figure`
@@ -437,6 +451,21 @@ def ridgeplot(
         )
         line_width = linewidth
 
+    if show_yticklabels is not MISSING:
+        if row_labels is not None:
+            raise ValueError(
+                "You may not specify both the 'show_yticklabels' and 'row_labels' arguments! "
+                "HINT: Use the new 'row_labels' argument instead of the deprecated "
+                "'show_yticklabels'."
+            )
+        warnings.warn(
+            "The 'show_yticklabels' argument has been deprecated in favor of 'row_labels'. "
+            "Support for the deprecated argument will be removed in a future version.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        row_labels = False if not show_yticklabels else None
+
     if colorscale == "default":
         warnings.warn(
             "colorscale='default' is deprecated and support for it will be removed in a future "
@@ -454,13 +483,13 @@ def ridgeplot(
         densities=densities,
         trace_labels=labels,
         trace_types=trace_type,
+        row_labels=row_labels,
         colorscale=colorscale,
         opacity=opacity,
         colormode=colormode,
         line_color=line_color,
         line_width=line_width,
         spacing=spacing,
-        show_yticklabels=show_yticklabels,
         xpad=xpad,
     )
     return fig