Skip to content

Commit cda4d07

Browse files
Simplify and fix colour personalization (#830)
* fix(explainer): keep the palette and earlier overrides in define_style * fix(report): use the resolved plot style for the confusion matrix * fix(plots): use palette colours in distribution plots instead of random ones * feat(style): accept hex codes, colour names and plotly scale names in colors_dict * fix(plots): accept any colour format in the NLP highlight plots * chore: correct statement about contribution signs * doc(tutorial): add supported options to colour notebook * fix(report): apply the explainer's style to distribution plots * fix(report): stop clipping distribution plot captions and legends * feat(style): make clustering colours configurable * feat(explainer): add colors_dict to Consistency * chore(style): warn when setting the unused report_confusion_matrix key * docs(style): list the available palettes and colors.json keys in docstrings
1 parent 6f10e31 commit cda4d07

20 files changed

Lines changed: 977 additions & 124 deletions

‎shapash/explainer/consistency.py‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,26 @@
1212
from plotly.subplots import make_subplots
1313
from sklearn.manifold import MDS
1414

15-
from shapash.style.style_utils import colors_loading, define_style, select_palette
15+
from shapash.style.style_utils import define_style, resolve_colors
1616
from shapash.utils.dtypes import text_like_columns
1717
from shapash.utils.utils import adjust_title_height
1818

1919

2020
class Consistency:
21-
"""Consistency class."""
22-
23-
def __init__(self, palette_name: str = "default") -> None:
21+
"""
22+
Compare the contributions computed by several explainability methods.
23+
24+
Parameters
25+
----------
26+
palette_name : str, default="default"
27+
Name of the color palette, as for ``SmartExplainer``.
28+
colors_dict : dict[str, Any] or None, default=None
29+
Colors overriding the palette's, in the formats ``SmartExplainer`` accepts.
30+
"""
31+
32+
def __init__(self, palette_name: str = "default", colors_dict: dict[str, Any] | None = None) -> None:
2433
self._palette_name = palette_name
25-
self._style_dict = define_style(select_palette(colors_loading(), self._palette_name))
34+
self._style_dict = define_style(resolve_colors(palette_name, colors_dict))
2635

2736
def tuning_colorscale(self, values: pd.Series | pd.DataFrame) -> list[list[Any]]:
2837
"""Adapts the color scale to the distribution of points.

‎shapash/explainer/smart_explainer.py‎

Lines changed: 58 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22

33
from __future__ import annotations
44

5-
import copy
65
import logging
76
from pathlib import Path
87
from typing import TYPE_CHECKING, Any, cast
@@ -13,7 +12,7 @@
1312

1413
import shapash.explainer.smart_predictor
1514
from shapash.backend import BaseBackend
16-
from shapash.style.style_utils import colors_loading, select_palette
15+
from shapash.style.style_utils import colors_loading, merge_palette, normalize_colors, select_palette
1716
from shapash.utils.custom_thread import CustomThread
1817
from shapash.utils.drift import SchemaDriftConfig, compute_schema_distribution, resolve_schema_drift_config
1918
from shapash.utils.io import load_pickle, save_pickle
@@ -116,10 +115,18 @@ class SmartExplainer:
116115
title_story : str, optional
117116
Custom title used in visualizations and reports. Default is empty.
118117
palette_name : str, optional
119-
Name of the color palette used for visualizations (see the `style` folder for options).
118+
Name of the color palette used for visualizations: ``"default"`` or ``"blues"``, the
119+
palettes defined in ``shapash/style/colors.json``. Defaults to ``"default"``.
120120
colors_dict : dict, optional
121-
Dictionary containing the full color palette configuration.
122-
Can be used to override default plot colors.
121+
Colors overriding those of ``palette_name``, with the same keys as the palette (the
122+
keys of the chosen palette in ``shapash/style/colors.json``, e.g. ``title_color``,
123+
``featureimp_bar``, ``contrib_colorscale``, ``webapp_bkg``). A nested mapping such as
124+
``featureimp_bar`` can be given partially. Colors can be
125+
``rgb(...)``/``rgba(...)`` strings, hex codes or color names. A continuous scale
126+
(``contrib_colorscale``, ``confusion_matrix_colorscale``, ``interaction_scale``,
127+
``feature_contributions_cumulative``) also accepts a plotly scale name such as
128+
``"RdBu"`` or ``"viridis_r"``, and a list of distinct colors (``interaction_discrete``,
129+
``compare_plot``) a plotly qualitative palette name such as ``"Set2"``.
123130
**backend_kwargs : dict
124131
Additional keyword arguments passed to the backend.
125132
@@ -227,9 +234,7 @@ def __init__(
227234
title_story = title_story if title_story is not None else ""
228235
self.title_story = title_story
229236
self.palette_name = palette_name if palette_name else "default"
230-
self.colors_dict = copy.deepcopy(select_palette(colors_loading(), self.palette_name))
231-
if colors_dict is not None:
232-
self.colors_dict.update(colors_dict)
237+
self.colors_dict = self._resolve_colors(select_palette(colors_loading(), self.palette_name), colors_dict)
233238

234239
self.explainer = Explainer(
235240
model=model,
@@ -326,16 +331,55 @@ def compile(
326331
)
327332

328333
def define_style(self, palette_name: str | None = None, colors_dict: dict[str, Any] | None = None) -> None:
329-
"""Set the color set to use in plots."""
334+
"""
335+
Change the colors used in plots.
336+
337+
Parameters
338+
----------
339+
palette_name : str, optional
340+
Name of the palette to switch to: ``"default"`` or ``"blues"`` (see
341+
``shapash/style/colors.json``). Switching palette discards the colors
342+
overridden earlier, in the constructor or in a previous call.
343+
colors_dict : dict[str, Any], optional
344+
Colors to override, merged on top of the palette and of the overrides already
345+
in place. Keys are those of ``shapash/style/colors.json``; accepts the same
346+
values as the constructor's ``colors_dict``.
347+
348+
Raises
349+
------
350+
ValueError
351+
If neither ``palette_name`` nor ``colors_dict`` is given, if the palette does
352+
not exist, or if a color in ``colors_dict`` is not valid.
353+
"""
330354
if palette_name is None and colors_dict is None:
331355
raise ValueError("At least one of palette_name or colors_dict parameters must be defined")
332-
new_palette_name = palette_name or self.palette_name
333-
new_colors_dict = copy.deepcopy(select_palette(colors_loading(), new_palette_name))
334-
if colors_dict is not None:
335-
new_colors_dict.update(colors_dict)
336-
self.colors_dict.update(new_colors_dict)
356+
if palette_name is not None:
357+
base = select_palette(colors_loading(), palette_name)
358+
self.palette_name = palette_name
359+
else:
360+
base = self.colors_dict
361+
self.colors_dict = self._resolve_colors(base, colors_dict)
337362
self.plot.define_style_attributes(colors_dict=self.colors_dict)
338363

364+
@staticmethod
365+
def _resolve_colors(base: dict[str, Any], colors_dict: dict[str, Any] | None) -> dict[str, Any]:
366+
"""
367+
Return ``base`` with the validated ``colors_dict`` overrides merged on top.
368+
369+
Parameters
370+
----------
371+
base : dict[str, Any]
372+
Colors the overrides apply to.
373+
colors_dict : dict[str, Any] or None
374+
Color overrides.
375+
376+
Returns
377+
-------
378+
dict[str, Any]
379+
The resolved colors.
380+
"""
381+
return merge_palette(base, normalize_colors(colors_dict, base))
382+
339383
def add(
340384
self,
341385
y_pred: pd.Series | pd.DataFrame | None = None,

‎shapash/plots/plot_backend_comparison.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@
2626
from dash import html
2727
from plotly import graph_objs as go
2828

29-
from shapash.plots.plot_sentence_highlight import _parse_rgb, _shap_style
30-
from shapash.style.style_utils import DEFAULT_NLP_THEME
29+
from shapash.plots.plot_sentence_highlight import _shap_style
30+
from shapash.style.style_utils import DEFAULT_NLP_THEME, parse_rgb
3131

3232
# Backend identity colors, assigned in this fixed order (never cycled) — the reference categorical
3333
# palette's first slots, validated for colour-vision-deficiency separation. Only the grouped bar
@@ -52,7 +52,7 @@ def _check(tokens: Sequence[str], values_by_backend: Mapping[str, np.ndarray]) -
5252

5353

5454
def _opaque(color: str) -> str:
55-
r, g, b = _parse_rgb(color)
55+
r, g, b = parse_rgb(color)
5656
return f"rgb({r},{g},{b})"
5757

5858

@@ -247,15 +247,15 @@ def plot_backend_highlight(
247247
subtitle : str, optional
248248
A line shown under the legend (e.g. agreement scores).
249249
color_positive, color_negative : str
250-
``rgb(...)``/``rgba(...)`` strings, as for
250+
Colors, as for
251251
:func:`~shapash.plots.plot_sentence_highlight.plot_sentence_highlight`.
252252
253253
Returns
254254
-------
255255
html.Div
256256
"""
257257
values_by_backend = _check(tokens, values_by_backend)
258-
pos_rgb, neg_rgb = _parse_rgb(color_positive), _parse_rgb(color_negative)
258+
pos_rgb, neg_rgb = parse_rgb(color_positive), parse_rgb(color_negative)
259259
span_base = {"padding": "3px 5px", "borderRadius": "3px", "margin": "2px 1px", "display": "inline-block"}
260260
unattributed = {**span_base, "color": "#aaaaaa", "textDecoration": "line-through"}
261261

‎shapash/plots/plot_evaluation_metrics.py‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -971,7 +971,8 @@ def plot_clustering_by_explainability(
971971
marker_size : int, optional, default=10
972972
Size of the data point markers in the plot.
973973
style_dict : dict[str, Any] or None, optional, default=None
974-
Custom styling options (e.g., fonts, layout settings).
974+
Resolved style, such as ``SmartExplainer.plot._style_dict``. Its ``clustering`` entry
975+
colors the selected cluster and the other ones. The default palette is used when None.
975976
opacity : float, optional, default=0.8
976977
Opacity of the data point markers (between 0 and 1).
977978
width : int, optional, default=900
@@ -1007,6 +1008,7 @@ def plot_clustering_by_explainability(
10071008
"""
10081009
if style_dict is None:
10091010
style_dict = define_style(get_palette("default"))
1011+
cluster_colors = style_dict["clustering"]
10101012

10111013
dict_title = build_tsne_title(title, subtitle, addnote, style_dict=style_dict, height=height)
10121014

@@ -1092,12 +1094,12 @@ def plot_clustering_by_explainability(
10921094
# Couleurs dynamiques pour le hover
10931095
c_n = c # curve number
10941096
if c_n == active_cluster:
1095-
fill = "rgba(255,0,0,0.30)"
1096-
line_color = "rgba(200,0,0,1)"
1097+
fill = cluster_colors["active_fill"]
1098+
line_color = cluster_colors["active_line"]
10971099
else:
10981100
if show_points:
1099-
fill = "rgba(150,150,150,0.15)"
1100-
line_color = "rgba(200,200,200,0.8)"
1101+
fill = cluster_colors["inactive_fill"]
1102+
line_color = cluster_colors["inactive_line"]
11011103
else:
11021104
fill = value_to_rgba(float(cluster_color[c]), colorscale, float(cmin), float(cmax), alpha=0.99)
11031105
line_color = value_to_rgba(

‎shapash/plots/plot_sentence_highlight.py‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,11 @@
1313
import numpy as np
1414
from dash import html
1515

16-
from shapash.style.style_utils import DEFAULT_NLP_THEME
16+
from shapash.style.style_utils import DEFAULT_NLP_THEME, parse_rgb
1717

1818
_SPECIAL_RE = re.compile(r"^\[.*\]$|^##|^\s*$")
1919

2020

21-
def _parse_rgb(color: str) -> tuple[int, int, int]:
22-
"""Parse a ``rgb(r, g, b)``/``rgba(r, g, b, a)`` string (the ``colors.json`` format) to ints."""
23-
nums = color.replace("rgba", "").replace("rgb", "").replace("(", "").replace(")", "").split(",")
24-
r, g, b = (int(float(n)) for n in nums[:3])
25-
return r, g, b
26-
27-
2821
def _shap_style(
2922
val: float, max_abs: float, pos_rgb: tuple[int, int, int], neg_rgb: tuple[int, int, int]
3023
) -> dict[str, str]:
@@ -74,8 +67,8 @@ def plot_sentence_highlight(
7467
symmetry with the other plot functions.
7568
color_positive, color_negative : str
7669
Span background for a non-negative / negative contribution, interpolated from white by
77-
magnitude. Must be a ``rgb(r, g, b)``/``rgba(r, g, b, a)`` string (the ``colors.json``
78-
format). Default to the ``"default"`` palette's ``nlp_xpl_positive``/``nlp_xpl_negative``
70+
magnitude. Any ``rgb(...)``/``rgba(...)`` string, hex code or color name; the
71+
opacity is ignored. Default to the ``"default"`` palette's ``nlp_xpl_positive``/``nlp_xpl_negative``
7972
— see :class:`~shapash.webapp.nlp_app.NlpWebApp`'s ``palette_name``/``colors_dict`` to
8073
theme every NLP chart at once instead of overriding this one call.
8174
@@ -92,7 +85,7 @@ def plot_sentence_highlight(
9285
if max_abs == 0:
9386
max_abs = 1.0
9487

95-
pos_rgb, neg_rgb = _parse_rgb(color_positive), _parse_rgb(color_negative)
88+
pos_rgb, neg_rgb = parse_rgb(color_positive), parse_rgb(color_negative)
9689

9790
_span_base = {
9891
"padding": "3px 5px",

0 commit comments

Comments
 (0)