Change hue_pal to HCL color space

closes has2k1/plotnine#937

Author: has2k1

doc/changelog.rst

@@ -1,6 +1,19 @@
 Changelog
 =========
 
+v0.14.0
+-------
+
+*not-yet-released*
+
+API Changes
+***********
+
+- Changed :class:`~mizani.palettes.hue_pal` to use HCL color space
+  from HSL (or HSLuv) space. The previous functionality is now available
+  with :class:`~mizani.palettes.hls_pal`.
+
+
 v0.13.5
 -------
 

mizani/palettes.py

@@ -357,7 +357,67 @@ def __call__(self, n: int) -> Sequence[RGBHexColor | None]:
 @dataclass
 class hue_pal(_discrete_pal):
     """
-    Utility for making hue palettes for color schemes.
+    Make a hue palette in HCL colour space
+
+    Parameters
+    ----------
+    h : float | tuple[float, float]
+        If a float, it is the first hue value, in the range `[0, 360]`.
+        The range of the palette will be `[first, first + 360)`.
+
+        If a tuple, it is the range `[first, last)` of the hues.
+    c : float
+        The chroma value, in the range [0, 100].
+    l : float
+        The lightness value, in the range [0, 100].
+    direction : 1 | -1
+        The order of colours in the scale. If -1 the order
+        of colours is reversed. The default is 1.
+
+    Returns
+    -------
+    palette : Callable
+        A function that takes an integer and returns a that number of
+        colours from the HCL colour space.
+
+    Examples
+    --------
+    >>> hue_pal()(5)
+    ['#f8766d', '#a3a500', '#00bf7d', '#00b0f6', '#e76bf3']
+    >>> hue_pal((100, 300))(5)
+    ['#88ac00', '#00be67', '#00becd', '#3fa1ff', '#e36ef6']
+    """
+
+    h: float | tuple[float, float] = 15
+    c: float = 100
+    l: float = 65
+    direction: Literal[1, -1] = 1
+
+    def __post_init__(self):
+        # Ensure a proper range for the palette
+        if isinstance(self.h, tuple):
+            self._hue_range = self.h
+        else:
+            self._hue_range = self.h, self.h + 360
+
+    def __call__(self, n: int) -> Sequence[RGBHexColor]:
+        h = self._hue_range
+
+        # Make a hue range that is functionally zero wrap around and
+        # and cover the entire hue space.
+        # h = (0, 360) == (360, 360) == (720, 360)
+        # h = (200, 200) == (200, 200+360) == (200, 200+720)
+        if (h[1] - h[0]) % 360 < 1:
+            h = h[0] % 360, (h[1] - 360 / n) % 360
+
+        hues = np.linspace(h[0], h[1], n)[:: self.direction] % 360
+        return [hsluv.lch_to_hex((self.l, self.c, h)) for h in hues]
+
+
+@dataclass
+class hls_pal(_discrete_pal):
+    """
+    Make a hue palette in HLS or HSLUV colour space
 
     Parameters
     ----------
@@ -384,9 +444,9 @@ class hue_pal(_discrete_pal):
 
     Examples
     --------
-    >>> hue_pal()(5)
+    >>> hls_pal()(5)
     ['#db5f57', '#b9db57', '#57db94', '#5784db', '#c957db']
-    >>> hue_pal(color_space='hsluv')(5)
+    >>> hls_pal(color_space='hsluv')(5)
     ['#e0697e', '#9b9054', '#569d79', '#5b98ab', '#b675d7']
     """
 
@@ -399,7 +459,7 @@ def __post_init__(self):
         h, l, s = self.h, self.l, self.s
         if not all(0 <= val <= 1 for val in (h, l, s)):
             msg = (
-                "hue_pal expects values to be between 0 and 1. "
+                "hls_pal expects values to be between 0 and 1. "
                 f"I got {h=}, {l=}, {s=}"
             )
             raise ValueError(msg)

tests/test_palettes.py

@@ -13,6 +13,7 @@
     desaturate_pal,
     gradient_n_pal,
     grey_pal,
+    hls_pal,
     hls_palette,
     hsluv_palette,
     hue_pal,
@@ -71,24 +72,35 @@ def test_grey_pal():
     assert all(s[1:3] * 3 == s[1:] for s in result)
 
 
-def test_hue_pal():
-    palette = hue_pal()
+def test_hls_pal():
+    palette = hls_pal()
     result = palette(5)
     assert all(s[0] == "#" and len(s) == 7 for s in result)
 
     # branches #
     with pytest.raises(ValueError):
-        hue_pal(0.1, 2.3, 3)
+        hls_pal(0.1, 2.3, 3)
 
     with pytest.raises(ValueError):
-        hue_pal(color_space="slh")  # pyright: ignore
+        hls_pal(color_space="slh")  # pyright: ignore
 
     # Backword compatibility check
-    palette = hue_pal(color_space="husl")  # pyright: ignore
+    palette = hls_pal(color_space="husl")  # pyright: ignore
     result = palette(5)
     assert all(s[0] == "#" and len(s) == 7 for s in result)
 
 
+def test_hue_pal():
+    pal1, pal2 = hue_pal((0, 360)), hue_pal((360, 360))
+    assert pal1(5) == pal2(5)
+
+    pal1, pal2 = hue_pal((100, 100)), hue_pal((100, 100 + 360))
+    assert pal1(5) == pal2(5)
+
+    pal = hue_pal()
+    assert pal(3) == ["#f8766d", "#00ba38", "#619cff"]
+
+
 def test_brewer_pal():
     result = brewer_pal()(5)
     assert all(s[0] == "#" and len(s) == 7 for s in result)