Visualization

Token attribution visualization plugins.

@domain viz @see [[knowledge/architecture/viz]]

Public helpers for attribution visualization.

@domain viz @see [[knowledge/architecture/viz]] @tested-by [[tests/viz/test_render.py]]

mllm_shap.viz.render.render_attribution(output: ExplainRunOutput, snapshot: ConversationSnapshot, player_set: PlayerSet, *, renderer: str = 'token_text', title: str | None = None, registry: PluginRegistry | None = None) → Figure

Render output attributions with a registered renderer plugin.

Pass registry=runner.registry to reuse the registry of the ExplainRunner that produced output (needed for custom renderers); otherwise the default registry is built.

mllm_shap.viz.render.render_attribution_html(output: ExplainRunOutput, snapshot: ConversationSnapshot, player_set: PlayerSet, *, title: str | None = None) → str

Return an HTML fragment for inline token coloring in Jupyter.

mllm_shap.viz.render.display_attribution_html(output: ExplainRunOutput, snapshot: ConversationSnapshot, player_set: PlayerSet, *, title: str | None = None) → Any

Display colored token HTML when IPython is available.

SHAP-style inline colored token attribution renderer.

@domain viz @see [[knowledge/architecture/viz]]

class mllm_shap.viz.token_text.TokenTextRenderer(context: PluginContext | None = None)

Bases: object

Render attributions as inline colored tokens.

options_model

Accepts no explanation.plugin_options.

alias of PluginOptions

property name: str

Return the registered renderer identifier.

render(labels: Sequence[str], values: Sequence[float], *, estimand: Estimand, title: str | None = None) → Figure

Build a matplotlib figure with SHAP-style colored token labels.

to_html(labels: Sequence[str], values: Sequence[float], *, estimand: Estimand, title: str | None = None) → str

Return an HTML fragment with colored token spans for Jupyter.

Horizontal bar chart renderer for token attributions.

@domain viz @see [[knowledge/architecture/viz]]

class mllm_shap.viz.token_bar.TokenBarRenderer(context: PluginContext | None = None)

Bases: object

Render attributions as a SHAP-style horizontal bar chart.

options_model

Accepts no explanation.plugin_options.

alias of PluginOptions

property name: str

Return the registered renderer identifier.

render(labels: Sequence[str], values: Sequence[float], *, estimand: Estimand, title: str | None = None) → Figure

Build a horizontal bar chart sorted by absolute attribution.

Figure of aligned audio segments: waveform, refined boundaries and energy.

@domain viz @see [[knowledge/architecture/viz]] @tested-by [[tests/viz/test_audio.py]]

mllm_shap.viz.audio.plot_audio_segments(audio: AudioPart, segments: Sequence[AudioSegment], values: Sequence[float] | None = None) → Figure

Draw audio with its segments and how refinement moved each boundary.

The top panel shades each segment (by the sign and size of values when given, as attribution renderers do), labels its token, draws the refined boundaries as solid lines and each rough CTC edge as a dashed line with an arrow to where refinement moved it. The bottom panel shows the RMS energy the refinement looks for minima of. Needs the viz and audio extras.

Raises:

ValueError – If values does not hold one value per segment.

Conversation view: each message under its role, players coloured in place.

@domain viz @see [[knowledge/architecture/viz]] @tested-by [[tests/viz/test_conversation_view.py]]

mllm_shap.viz.conversation.plot_conversation(output: ExplainRunOutput, snapshot: ConversationSnapshot, player_set: PlayerSet, *, title: str | None = None) → Figure

Draw snapshot message by message with each player coloured by value.

Every message gets a "<role>[/<speaker>] <n>" header. Token or message players are shaded on the attribution scale where they stand; text that is no player (roles the partition left out, for example) stays grey, so the context of a filtered explanation remains readable. A message whose players carry samples (sgpa_segments) also gets a waveform strip below, with those players shaded on the same scale, so typed and spoken words compare directly.

Raises:

ValueError – If player_set does not match snapshot or the values.

mllm_shap.viz.conversation.render_conversation_html(output: ExplainRunOutput, snapshot: ConversationSnapshot, player_set: PlayerSet, *, title: str | None = None) → str

Return plot_conversation() as an HTML fragment for Jupyter or reports.

Hovering a player shows its value.

SHAP-inspired diverging colors for signed attributions.

@domain viz @see [[knowledge/architecture/viz]]

mllm_shap.viz.colors.diverging_rgba(value: float, vmax: float) → tuple[float, float, float, float]

Map a signed attribution to an RGBA tuple (SHAP red / blue scale).

mllm_shap.viz.colors.token_background_rgba(value: float, vmax: float) → tuple[float, float, float, float]

Return a soft highlight color for one token (white center, saturated tails).

mllm_shap.viz.colors.bar_color(value: float) → str

Return the SHAP primary color for a signed bar attribution.

mllm_shap.viz.colors.rgba_css(red: float, green: float, blue: float, alpha: float) → str

Format an rgba() string for HTML/CSS.

mllm_shap.viz.colors.token_background_css(value: float, vmax: float) → str

Return a CSS background color for one token span.

Token label helpers for attribution renderers.

@domain viz @see [[knowledge/architecture/viz]] @tested-by [[tests/viz/test_labels.py]]

mllm_shap.viz.labels.token_labels(snapshot: ConversationSnapshot, player_set: PlayerSet) → tuple[str, ...]

Return every player’s PlayerSpan.display_label in mask order.

Raises:

ValueError – If the player set has no spans or its spans do not match snapshot.

mllm_shap.viz.labels.check_attribution(labels: Sequence[str], values: Sequence[float]) → None

Raise ValueError unless labels and values are equal and non-empty.

Seaborn-backed styling for attribution figures.

@domain viz @see [[knowledge/architecture/viz]]

mllm_shap.viz.style.apply_attribution_theme() → None

Apply a clean notebook theme aligned with SHAP plot styling.

mllm_shap.viz.style.new_attribution_figure(*, width: float, height: float) → tuple[Figure, Axes]

Create a styled figure and single axes for attribution plots.

mllm_shap.viz.style.polish_bar_axes(axis: Axes) → None

Remove chart junk and keep a subtle vertical grid.

mllm_shap.viz.style.polish_text_axes(axis: Axes) → None

Minimal axes for inline token layouts.