docs: Add example of `cmap` usage with Plotnine

[apcamargo]

"It would be helpful to include an example of how to use cmap with Plotnine in the documentation. I'll give it a try and return if I manage to get it working.

[tlambert03]

that would be great, thanks @apcamargo. i haven't seen/used plotnine

[beskep]

I've recently been trying out plotnine.
Here's what I tried.
It's a bit inelegant since plotnine relies on hex colors I guess.

import functools
from dataclasses import dataclass
from typing import TYPE_CHECKING

import cmap
import numpy as np
import plotnine as gg
from matplotlib.colors import to_hex
from mizani._colors import ColorMapKind, ListedMap
from mizani.palettes import _continuous_color_pal
from plotnine import aes
from plotnine.data import penguins
from plotnine.scales.scale_color import _scale_color_continuous

if TYPE_CHECKING:
    from collections.abc import Sequence

    from mizani.typing import RGBHexColor
    from plotnine.typing import FloatArrayLike


@dataclass
class cmap_pal(_continuous_color_pal):  # noqa: N801
    # replaces mizani.palettes.cmap_pal
    value: cmap.ColormapLike

    def __post_init__(self) -> None:
        colors = cmap.Colormap(self.value).color_stops.color_array[:, :-1]
        self.cm = ListedMap(colors, kind=ColorMapKind.sequential)

    def __call__(self, x: FloatArrayLike) -> Sequence[RGBHexColor | None]:
        return self.cm.continuous_palette(x)


@dataclass
class scale_continuous_mizani(_scale_color_continuous):  # noqa: N801
    value: cmap.ColormapLike

    def __post_init__(self) -> None:
        super().__post_init__()

        self.palette = cmap_pal(self.value)  # ty: ignore[invalid-assignment]


@dataclass
class scale_continuous(_scale_color_continuous):  # noqa: N801
    value: cmap.ColormapLike

    @functools.cached_property
    def _cmap(self) -> cmap.Colormap:
        return cmap.Colormap(self.value)

    def palette(self, x: np.ndarray) -> list[str]:
        return [to_hex(c) for c in np.atleast_2d(self._cmap(x))]


def sequential() -> None:
    p = (
        gg.ggplot(penguins, aes("bill_length_mm", "bill_depth_mm", color="body_mass_g"))
        + gg.geom_point()
        + scale_continuous("cmasher:arctic")
        # or
        # + scale_continuous_mizani("cmasher:arctic")
    )
    p.show()


def qualitative() -> None:
    colors = [c.hex for c in cmap.Colormap("tol:bright-alt").iter_colors()]
    p = (
        gg.ggplot(penguins, aes("bill_length_mm", "bill_depth_mm", color="species"))
        + gg.geom_point()
        + gg.scale_color_manual(colors)
    )
    p.show()


if __name__ == "__main__":
    sequential()
    qualitative()