You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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):
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
Replace generic numeric keys with explicit, descriptive names wherever possible (e.g. primary, secondary, highlight, background, etc.) to clearly indicate their purpose.
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
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
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:
Fix the bugs (non-breaking): fix bugs 1–5, and stop using colors_dict for the label-to-colour map in plot_distribution.
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.
#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.
#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.
Activity
milton-minervino commentedon Nov 4, 2026
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
bluespalette and full-value overrides reach the plots throughxpl.plot.title_colorreached all 6 plots I ran, and the plotter passes_style_dictto the other plots I read.Status of this issue
featureimp_barandlocalplot_bar."viridis"crashes all 4 classical plot calls I tried, andpalette_name="viridis"is rejected as an unknown palette.Classical bugs (all reproduced)
define_stylenever updatesself.palette_nameblues, then with an override, silently reverts todefaultsmart_explainer.py:332define_stylerebuilds from the full palettesmart_explainer.py:333-336_style_dictbluesand custom title colours, whilexpl.plotapplies themreport/blocks.py:1026,plot_evaluation_metrics.py:792-796distribution_plotlooks up colours by level or column name in_style_dict, which never has themsmart_plotter.py:3021,plot_univariate.py:218,249{"featureimp_bar": {"1": "red"}}raisesKeyError: 2; the tutorial works around it by copying the whole dictstyle_utils.py:128-133featureimp_barbut crashes the cumulative importance plotstyle_utils.py:91titel_coloris silently acceptedsmart_explainer.py:232Other classical gaps (from reading the code)
colors_dicthas three meanings: raw palette (SmartExplainer), resolved style dict (SmartPlotterto the plots), and label-to-colour map (report toplot_distribution). This is the root cause of bugs 3 and 4.style_utils.pyreadsreport_confusion_matrix, so setting it has no effect.plot_evaluation_metrics.py:1095-1100) and the report's target distribution colours (report/blocks.py:38).Consistency: it acceptspalette_namebut has nocolors_dict(consistency.py:23).plot_correlations.py:295), which assumes it has 11 colours and diverges around the middle. Convertingviridisto a list would fix the crash, but the colours could still look wrong.test_define_style_1mocks 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_themeis a single entry point, and its flat keys avoid bug 5. It still has some gaps:viridisbreaks the theme:colors_dict={"confusion_matrix_colorscale": "viridis"}becomes('v','i','r','i','d','i','s'), because of thetuple(...)atstyle_utils.py:243.plot_confusion_matrixitself accepts a scale name, but the theme never passes one intact._parse_rgbraisesValueError.BACKEND_COLORSand the scatter's categorical list.Proposal
I suggest two PRs:
colors_dictfor the label-to-colour map inplot_distribution.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 signedcontrib_colorscalediverging by rejecting or warning on sequential scales likeviridis, because they would misrepresent the sign.milton-minervino commentedon Nov 6, 2026
#830 covers the second request (standard colour scales) and fixes the bugs listed in my report above.
colors_dictaccepts plotly scale names ("viridis","RdBu"…) on the continuous scale keys, and qualitative palette names ("Set2"…) on the discrete ones.rgb/rgba), and partial nested overrides are supported.Consistencytakescolors_dict. Setting the unusedreport_confusion_matrixkey now warns.Still to do: the first request, descriptive names instead of numeric keys (
featureimp_bar: {"1": ...}). Renaming breaks existingcolors_dicts, so it will come in a separate PR, with a deprecation period for the old keys. That PR will also removereport_confusion_matrix. This issue stays open until then.milton-minervino commentedon Nov 16, 2026
Follow-up: make
colors_dictkeys discoverable#830 documents the palette names (
default,blues) and the acceptedcolors_dictvalue formats in the docstrings. One usability gap remains. To override a color, users need to know the palette keys (about 26 inshapash/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:
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.colors.jsonchanges.I would rather go for the first option. This is out of scope for #830, so I'd handle it separately.