Skip to content

Simplify and fix colour personalization - #830

Merged
milton-minervino merged 13 commits into
MAIF:developfrom
milton-minervino:fix/color-personalization
Nov 16, 2026
Merged

milton-minervino merged 13 commits into
MAIF:developfrom
milton-minervino:fix/color-personalization

Conversation

@milton-minervino

@milton-minervino milton-minervino commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Refs #654.

Customising colours in the classical path had several bugs, and the accepted formats were narrow and inconsistent. This PR fixes the bugs and lets colors_dict take common colour formats, plotly scale names and partial overrides. The NLP plots go through the same resolver, and the report now follows the explainer's colours everywhere.

The other request in #654, descriptive names instead of numeric keys such as featureimp_bar: {"1": ...}, breaks existing colors_dicts. It will come in a separate PR, with a deprecation period for the old keys.

Bug fixes

  • define_style lost state. It did not update palette_name, and each call dropped earlier overrides. Overrides now accumulate on the current colours. Passing palette_name starts again from that palette, and an unknown palette name leaves the current state unchanged.
  • Partial nested overrides raised KeyError. Overriding one entry of a nested key, such as {"featureimp_bar": {"1": ...}}, replaced the whole dict. Nested dicts are now merged key by key.
  • Report confusion matrix: it read the raw palette instead of the resolved plot style. With blues or custom colours, it kept the default scale and title colour.
  • Report distribution plots ignored the explainer's style. This covered feature distribution, univariate analysis, target analysis and target distribution. These plots only received the series colours, so their titles and axes always used the default palette. They now get the explainer's resolved style.
  • Target distribution colours were hard-coded. They used a fixed blue and gold whatever the palette, and now take the pred/true colours of report_feature_distribution.
  • Distribution plots used random colours for series without an explicit colour. They now take the palette's discrete colours (interaction_discrete) in turn, the same on every call.
  • Clipped captions in the report. In univariate analysis and target analysis, the "Distribution of …" caption below the plot was clipped at the bottom, and the legend was cut at the top. This bug predates this PR.
  • NLP highlight and backend comparison plots: a hex code made them fail, and a scale name like "viridis" was split into characters. Both are now handled.

New

  • Formats accepted in colors_dict:
    • Any single colour: rgb(...), rgba(...), a hex code or a colour name, normalised to rgb/rgba strings.
    • Continuous scale keys (contrib_colorscale, confusion_matrix_colorscale, interaction_scale, feature_contributions_cumulative): a plotly scale name such as "RdBu" or "viridis_r". The name is sampled to the same number of stops as the default scale.
    • Discrete keys (interaction_discrete, compare_plot): a plotly qualitative palette name such as "Plotly" or "Set2".
    • Partial overrides: only the keys you pass change.
  • Clustering colours: a new clustering palette key (active_fill, active_line, inactive_fill, inactive_line) replaces the colours hard-coded in the clustering plot. Its default values are the old ones, so the plot looks the same.
  • Consistency(colors_dict=...) takes the same overrides as SmartExplainer.
  • plot_distribution(hue_colors=...) sets the colour of each series. colors_dict now only carries the style; a label → colour map passed through colors_dict still works.

Behaviour changes to note

  • Invalid values raise errors. An invalid colour or an unknown scale name raises a ValueError naming the key and the accepted formats. Before, the value failed later inside plotly, or was ignored.
  • Unknown keys warn. The warning suggests the closest valid key (e.g. Did you mean 'contrib_colorscale'?).
  • report_confusion_matrix warns. No plot reads this key, so setting it warns and points to confusion_matrix_colorscale. It will be removed with the key renaming.
  • Non-diverging scales warn. contrib_colorscale also colours the correlation plots, so a non-diverging scale there triggers a warning that the sign of correlations will no longer be visible.
  • Default colours that change:
    • Target distribution: with default, predictions turn gold and true values blue-grey, the other way round from before and the same as test/train in the other report blocks. With blues, they are orange and blue.
    • Report confusion matrix with blues: it now uses the blues scale.
    • Distribution plots: series without an explicit colour are no longer random.

Implementation

  • shapash/style/style_utils.py: new merge_palette, normalize_colors, resolve_colors, to_rgb_string and parse_rgb. resolve_nlp_theme now uses resolve_colors.
  • SmartExplainer.__init__, define_style and Consistency: they all resolve colours through the same helper.
  • shapash/report/blocks.py:
    • the confusion matrix and distribution blocks take the explainer's plot._style_dict;
    • _title_below replaces the two copies of the caption layout.
  • NLP plots: plot_sentence_highlight and plot_backend_comparison use the shared parse_rgb instead of their own parser.
  • Dependencies: none new. The plotly helpers used (sample_colorscale, plotly.colors.qualitative/diverging) exist in plotly 5.12.0, the current lower bound. Colour names are parsed by matplotlib, already a core dependency.

Tests and docs

  • Tests:
    • new unit tests for the resolver, define_style, the report blocks, the distribution and clustering plots, Consistency and the NLP plots;
    • end-to-end tests in tests/unit_tests/explainer/test_smart_explainer_colors.py;
    • the unit suite passes (1989 tests) and patch coverage is 100%.
  • Manual check: I compared reports generated on develop and on this branch with default, blues and custom colours. Titles, axes, series colours and captions now follow the explainer's colours, and nothing is clipped.
  • Tutorial: tuto-common02-colors.ipynb lists the accepted formats, shows a partial override, and adds an Option 4 that uses a plotly scale name. The colour tutorials (common02, plot07) run without errors.

@codecov

codecov Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.37%. Comparing base (58f4562) to head (350eda2).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files
@@             Coverage Diff             @@
##           develop     #830      +/-   ##
===========================================
+ Coverage    86.18%   86.37%   +0.18%     
===========================================
  Files          115      115              
  Lines        11859    11958      +99     
  Branches      2161     2176      +15     
===========================================
+ Hits         10221    10329     +108     
+ Misses         997      996       -1     
+ Partials       641      633       -8     
Files with missing lines Coverage Δ
shapash/explainer/consistency.py 86.44% <100.00%> (ø)
shapash/explainer/smart_explainer.py 77.32% <100.00%> (+0.58%) ⬆️
shapash/plots/plot_backend_comparison.py 100.00% <100.00%> (ø)
shapash/plots/plot_evaluation_metrics.py 79.67% <100.00%> (+1.05%) ⬆️
shapash/plots/plot_sentence_highlight.py 94.87% <100.00%> (-0.48%) ⬇️
shapash/plots/plot_univariate.py 76.87% <100.00%> (+1.52%) ⬆️
shapash/report/blocks.py 73.21% <100.00%> (+1.10%) ⬆️
shapash/style/style_utils.py 94.88% <100.00%> (+2.02%) ⬆️
shapash/webapp/nlp_app.py 94.27% <ø> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@milton-minervino
milton-minervino marked this pull request as ready for review November 6, 2026 16:56
@milton-minervino
milton-minervino requested review from guerinclement and guillaume-vignal and removed request for guillaume-vignal November 6, 2026 16:56
@guillaume-vignal guillaume-vignal linked an issue Nov 13, 2026 that may be closed by this pull request
@milton-minervino
milton-minervino merged commit cda4d07 into MAIF:develop Nov 16, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants