feat(plotting): Replace group_cmaps with group_colors using OKLab interpolation

- Implemented group_colors parameter accepting dict of colors
- Added OKLab white-to-color gradient generation in _utils.py
- Updated DotPlot to use dynamic ListedColormaps
- Added colour-science as optional dependency
- Updated default legend width to 2.0 to fix layout bugs
- Updated reference images for dotplots and affected plots

Author: rwbaber

docs/release-notes/3764.feature.md

@@ -144,6 +144,8 @@ skmisc = [ "scikit-misc>=0.5.1" ]                      # highly_variable_genes m
 harmony = [ "harmonypy" ]                              # Harmony dataset integration
 scanorama = [ "scanorama" ]                            # Scanorama dataset integration
 scrublet = [ "scikit-image>=0.23" ]                    # Doublet detection with automatic thresholds
+# Plotting
+plotting = [ "colour-science" ]
 # Acceleration
 rapids = [ "cudf>=0.9", "cuml>=0.9", "cugraph>=0.9" ] # GPU accelerated calculation of neighbors
 dask = [ "dask[array]>=2024.5.1", "anndata[dask]" ]   # Use the Dask parallelization engine

pyproject.toml

@@ -6,12 +6,19 @@
 from matplotlib import colormaps
 
 from .. import logging as logg
-from .._compat import old_positionals
+from .._compat import old_positionals, warn
 from .._settings import settings
 from .._utils import _doc_params, _empty
 from ._baseplot_class import BasePlot, doc_common_groupby_plot_args
 from ._docs import doc_common_plot_args, doc_show_save_ax, doc_vboundnorm
-from ._utils import _dk, check_colornorm, fix_kwds, make_grid_spec, savefig_or_show
+from ._utils import (
+    _create_white_to_color_gradient,
+    _dk,
+    check_colornorm,
+    fix_kwds,
+    make_grid_spec,
+    savefig_or_show,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Mapping, Sequence
@@ -156,7 +163,7 @@ def __init__(  # noqa: PLR0913
         vmax: float | None = None,
         vcenter: float | None = None,
         norm: Normalize | None = None,
-        group_cmaps: Mapping[str, str] | None = None,
+        group_colors: Mapping[str, ColorLike] | None = None,
         **kwds,
     ) -> None:
         BasePlot.__init__(
@@ -209,23 +216,30 @@ def __init__(  # noqa: PLR0913
         self.standard_scale = standard_scale
         self.expression_cutoff = expression_cutoff
         self.mean_only_expressed = mean_only_expressed
-        self.group_cmaps = group_cmaps
+        self.group_colors = group_colors
+        self.group_cmaps = None
 
         self.dot_color_df, self.dot_size_df = self._prepare_dot_data(
             dot_color_df, dot_size_df
         )
-
-        # If group_cmaps is used, validate that all plotted groups have a defined colormap.
-        if self.group_cmaps is not None:
-            plotted_groups = set(self.dot_color_df.index)
-            defined_groups = set(self.group_cmaps.keys())
-            missing_groups = plotted_groups - defined_groups
+        if self.group_colors is not None:
+            self.group_cmaps = {}
+            plotted_groups = self.dot_color_df.index
+            missing_groups = []
+            for group in plotted_groups:
+                if group in self.group_colors:
+                    self.group_cmaps[group] = _create_white_to_color_gradient(
+                        self.group_colors[group]
+                    )
+                else:
+                    self.group_cmaps[group] = self.cmap
+                    missing_groups.append(group)
             if missing_groups:
-                msg = (
-                    "The following groups are in the plot data but are missing from the `group_cmaps` dictionary. "
-                    f"Please define a colormap for them: {sorted(missing_groups)}"
+                warn(
+                    f"The following groups will use the default colormap as no "
+                    f"specific colors were assigned: {missing_groups}",
+                    UserWarning,
                 )
-                raise ValueError(msg)
 
     def _prepare_dot_data(self, dot_color_df, dot_size_df):
         """Calculate the dataframes for dot size and color."""
@@ -638,7 +652,10 @@ def _plot_stacked_colorbars(self, fig, colorbar_area_spec, normalize):
             ax = fig.add_subplot(
                 colorbar_gs[i, 0]
             )  # Place the colorbar Axes in the first, wider column
-            cmap = colormaps.get_cmap(self.group_cmaps[group_name])
+            cmap = self.group_cmaps[group_name]
+            # Handle fallback case where cmap might be a string
+            if isinstance(cmap, str):
+                cmap = colormaps.get_cmap(cmap)
             mappable = ScalarMappable(norm=legend_norm, cmap=cmap)
 
             cb = matplotlib.colorbar.Colorbar(
@@ -894,8 +911,10 @@ def _dotplot(  # noqa: PLR0912, PLR0913, PLR0915
 
             # Here we loop through each group and plot it with its own cmap
             for group_idx, group_name in enumerate(groups_iter):
-                group_cmap_name = group_cmaps[group_name]
-                group_cmap = colormaps.get_cmap(group_cmap_name)
+                group_cmap = group_cmaps[group_name]
+                # Handle fallback case where group_cmap might be a string
+                if isinstance(group_cmap, str):
+                    group_cmap = colormaps.get_cmap(group_cmap)
 
                 # Slice the flattened data arrays correctly depending on orientation
                 if not are_axes_swapped:
@@ -1017,7 +1036,7 @@ def dotplot(  # noqa: PLR0913
     norm: Normalize | None = None,
     # Style parameters
     cmap: Colormap | str | None = DotPlot.DEFAULT_COLORMAP,
-    group_cmaps: Mapping[str, str] | None = None,
+    group_colors: Mapping[str, ColorLike] | None = None,
     dot_max: float | None = DotPlot.DEFAULT_DOT_MAX,
     dot_min: float | None = DotPlot.DEFAULT_DOT_MIN,
     smallest_dot: float = DotPlot.DEFAULT_SMALLEST_DOT,
@@ -1056,11 +1075,14 @@ def dotplot(  # noqa: PLR0913
     mean_only_expressed
         If True, gene expression is averaged only over the cells
         expressing the given genes.
-    group_cmaps
-        A mapping of group names to colormap names, e.g.
-        `{{'T-cell': 'Blues', 'B-cell': 'Reds'}}`. This allows for specifying a
-        different colormap for each group. If used, all groups in the plot
-        must have a colormap defined in this mapping.
+    group_colors
+        A mapping of group names to colors.
+        e.g. `{{'T-cell': 'blue', 'B-cell': '#aa40fc'}}`.
+        Colors can be specified as any valid matplotlib color.
+        If `group_colors` is used, a colormap is generated from white
+        to the given color for each group.
+        If a group is not present in the dictionary, the value of `cmap`
+        is used.
     dot_max
         If ``None``, the maximum dot size is set to the maximum fraction value found
         (e.g. 0.6). If given, the value should be a number between 0 and 1.
@@ -1129,6 +1151,14 @@ def dotplot(  # noqa: PLR0913
     # instead of `cmap`
     cmap = kwds.pop("color_map", cmap)
 
+    # Warn if both cmap and group_colors are specified
+    if group_colors is not None and cmap != DotPlot.DEFAULT_COLORMAP:
+        warn(
+            "Both `cmap` and `group_colors` are specified. "
+            "`group_colors` takes precedence for the specified groups.",
+            UserWarning,
+        )
+
     dp = DotPlot(
         adata,
         var_names,
@@ -1148,7 +1178,7 @@ def dotplot(  # noqa: PLR0913
         var_group_rotation=var_group_rotation,
         layer=layer,
         dot_color_df=dot_color_df,
-        group_cmaps=group_cmaps,
+        group_colors=group_colors,
         ax=ax,
         vmin=vmin,
         vmax=vmax,

src/scanpy/plotting/_dotplot.py

@@ -1105,3 +1105,56 @@ def _deprecated_scale(
 def _dk(dendrogram: bool | str | None) -> str | None:  # noqa: FBT001
     """Convert the `dendrogram` parameter to a `dendrogram_key` parameter."""
     return None if isinstance(dendrogram, bool) else dendrogram
+
+
+def _create_white_to_color_gradient(color: ColorLike, n_steps: int = 256):
+    """Generate a perceptually uniform colormap from white to a target color.
+
+    This function uses the OKLab color space for interpolation to ensure that
+    the brightness of the generated colormap changes uniformly.
+
+    Parameters
+    ----------
+    color
+        The target color for the gradient. Can be any valid matplotlib color.
+    n_steps
+        The number of steps in the colormap.
+
+    Returns
+    -------
+    A `matplotlib.colors.ListedColormap` object.
+    """
+    try:
+        import colour
+    except ImportError:
+        msg = (
+            "Please install the `colour-science` package to use `group_colors`: "
+            "`pip install colour-science` or `pip install scanpy[plotting]`"
+        )
+        raise ImportError(msg) from None
+    from matplotlib.colors import ListedColormap, to_hex
+
+    # Convert the input color to a hex string
+    hex_color = to_hex(color, keep_alpha=False)
+
+    # Define the color space for interpolation
+    space = "OKLab"
+
+    # Convert start (white) and end (target color) to the OKLab color space
+    target_oklab = colour.convert(hex_color, "Hexadecimal", space)
+    white_oklab = colour.convert("#ffffff", "Hexadecimal", space)
+
+    # Create the gradient through linear interpolation in OKLab
+    gradient = colour.algebra.lerp(
+        np.linspace(0, 1, n_steps)[..., np.newaxis],
+        white_oklab,
+        target_oklab,
+    )
+
+    # Convert the gradient back to sRGB for display
+    rgb_gradient = colour.convert(gradient, space, "sRGB")
+
+    # Clip values to be within the valid [0, 1] range for RGB
+    clipped_rgb = np.clip(rgb_gradient, 0, 1)
+
+    return ListedColormap(clipped_rgb)

src/scanpy/plotting/_utils.py

@@ -30,6 +30,7 @@ def _generate_next_value_(
 
     mod: str
 
+    colour = "colour-science"
     dask = auto()
     dask_ml = auto()
     fa2 = auto()