Skip to content

Simplify color personalization #654

Open

Description

@guerinclement

Issue: Improve Color Palette Customization and Readability

Problem Description

Color palettes in Shapash are currently difficult to customize and understand. The mapping between dictionary keys and the actual HTML elements rendered in the web application is unclear, making personalization unintuitive and error-prone.

For example, in shapash/shapash/style/colors.json (lines 47–51, commit 5c99856):

"featureimp_bar": {
  "1": "rgba(0, 154, 203, 1)",
  "2": "rgba(223, 103, 0, 0.8)",
  "3": "rgba(240, 195, 162, 0.8)",
  "4": "rgba(245, 122, 0, 0.8)"
}

Using numeric keys such as "1", "2", "3" does not convey any semantic meaning, making it hard to determine which color corresponds to which UI element.

Proposed Solution

  1. Replace generic numeric keys with explicit, descriptive names wherever possible (e.g. primary, secondary, highlight, background, etc.) to clearly indicate their purpose.
  2. Add support for standard color scales (e.g. viridis, plasma, inferno, etc.) to allow easier and more flexible customization of color themes.

Expected Benefits

  • Improved readability and maintainability of color configuration files
  • Easier customization for users
  • Better alignment with common visualization practices

Activity

  1. milton-minervino commented on Nov 4, 2026

    @milton-minervino
    Collaborator

    Colour personalization: current state

    I checked how the classical and NLP paths handle colours on develop (ccd9892). Neither request in this issue is implemented, and the classical path also has bugs that affect customization today.

    Simple cases do work: the blues palette and full-value overrides reach the plots through xpl.plot. title_color reached all 6 plots I ran, and the plotter passes _style_dict to the other plots I read.

    Status of this issue

    • Descriptive names: not done. 9 of the 26 palette keys still use numeric keys, such as featureimp_bar and localplot_bar.
    • Standard scales: not supported. Setting a scale key to "viridis" crashes all 4 classical plot calls I tried, and palette_name="viridis" is rejected as an unknown palette.

    Classical bugs (all reproduced)

    # Problem Result Where
    1 define_style never updates self.palette_name Calling it with blues, then with an override, silently reverts to default smart_explainer.py:332
    2 define_style rebuilds from the full palette Earlier overrides are lost, including those passed to the constructor smart_explainer.py:333-336
    3 The report's confusion matrix gets the raw palette, not _style_dict The report ignores blues and custom title colours, while xpl.plot applies them report/blocks.py:1026, plot_evaluation_metrics.py:792-796
    4 distribution_plot looks up colours by level or column name in _style_dict, which never has them Colours are random on every call and ignore the palette smart_plotter.py:3021, plot_univariate.py:218,249
    5 Overrides are merged shallowly {"featureimp_bar": {"1": "red"}} raises KeyError: 2; the tutorial works around it by copying the whole dict style_utils.py:128-133
    6 Colour formats are handled inconsistently Hex works in featureimp_bar but crashes the cumulative importance plot style_utils.py:91
    7 Keys aren't validated A typo like titel_color is silently accepted smart_explainer.py:232

    Other classical gaps (from reading the code)

    • colors_dict has three meanings: raw palette (SmartExplainer), resolved style dict (SmartPlotter to the plots), and label-to-colour map (report to plot_distribution). This is the root cause of bugs 3 and 4.
    • Dead key: nothing outside style_utils.py reads report_confusion_matrix, so setting it has no effect.
    • Hard-coded colours: clustering's active-cluster red and greys (plot_evaluation_metrics.py:1095-1100) and the report's target distribution colours (report/blocks.py:38).
    • Consistency: it accepts palette_name but has no colors_dict (consistency.py:23).
    • Scale shape assumption: correlations only use the top half of the contribution scale (plot_correlations.py:295), which assumes it has 11 colours and diverges around the middle. Converting viridis to a list would fix the crash, but the colours could still look wrong.
    • Test coverage: test_define_style_1 mocks the palette loading and makes a single call, so it can't catch bugs 1 and 2.

    NLP path

    The NLP path is cleaner: resolve_nlp_theme is a single entry point, and its flat keys avoid bug 5. It still has some gaps:

    • viridis breaks the theme: colors_dict={"confusion_matrix_colorscale": "viridis"} becomes ('v','i','r','i','d','i','s'), because of the tuple(...) at style_utils.py:243. plot_confusion_matrix itself accepts a scale name, but the theme never passes one intact.
    • Hex is accepted, then fails later: the theme takes it, but the sentence highlight's _parse_rgb raises ValueError.
    • Limited scope: the theme is only set through the webapp, and some colours stay fixed, such as BACKEND_COLORS and the scatter's categorical list.

    Proposal

    I suggest two PRs:

    1. Fix the bugs (non-breaking): fix bugs 1–5, and stop using colors_dict for the label-to-colour map in plot_distribution.
    2. Implement this issue: add one shared resolver for both paths that deep-merges overrides, validates keys, normalises colours to rgb(...), and expands named scales to stop lists. Then rename the numeric keys.

    Renaming breaks existing users' colors_dict, so the old keys need a deprecation period. I'd also keep the signed contrib_colorscale diverging by rejecting or warning on sequential scales like viridis, because they would misrepresent the sign.

  2. milton-minervino commented on Nov 6, 2026

    @milton-minervino
    Collaborator

    #830 covers the second request (standard colour scales) and fixes the bugs listed in my report above.

    • Scales and palettes: colors_dict accepts plotly scale names ("viridis", "RdBu"…) on the continuous scale keys, and qualitative palette names ("Set2"…) on the discrete ones.
    • Colours: any colour format works (hex, colour names, rgb/rgba), and partial nested overrides are supported.
    • Validation: invalid values raise a clear error, and unknown keys warn.
    • Report: it now follows the explainer's palette and custom colours everywhere: confusion matrix, distribution plots and target distribution.
    • Gaps from the report: clustering colours are configurable and Consistency takes colors_dict. Setting the unused report_confusion_matrix key now warns.

    Still to do: the first request, descriptive names instead of numeric keys (featureimp_bar: {"1": ...}). Renaming breaks existing colors_dicts, so it will come in a separate PR, with a deprecation period for the old keys. That PR will also remove report_confusion_matrix. This issue stays open until then.

  3. milton-minervino commented on Nov 16, 2026

    @milton-minervino
    Collaborator

    Follow-up: make colors_dict keys discoverable

    #830 documents the palette names (default, blues) and the accepted colors_dict value formats in the docstrings. One usability gap remains. To override a color, users need to know the palette keys (about 26 in shapash/style/colors.json, e.g. title_color, featureimp_bar, contrib_colorscale, webapp_bkg). Today they can only find those by opening a file inside the installed package.

    Listing every key in each docstring would be too long. Two options:

    • A helper, e.g. shapash.style.list_palette_keys(palette_name), returning the keys of a palette. The docstrings would point to it. It adds a small public API.
    • A docs page with a table of keys and which plot or webapp element each one controls. It adds no API, but needs maintaining when colors.json changes.

    I would rather go for the first option. This is out of scope for #830, so I'd handle it separately.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions