Visualizations

plot_attributions

Display token-level attribution visualizations for classification or generation tasks.

Classification tasks (single- and multi-class) share the same visualization layout.

Parameters:

Name	Type	Description	Default
attribution_output	AttributionOutput	Attribution output returned by an attribution explainer.	required
classes_names	dict[int, str] | list[str] | tuple[str, ...] | None	Optional mapping or list of class display names.	None
save_path	str | PathLike[str] | None	Optional path to save the HTML visualization.	None
normalize	bool	Whether to normalize attribution magnitudes for display.	True
positive_color	str	Hex color for positive contributions.	'#ff0000'
negative_color	str	Hex color for negative contributions.	'#0000ff'
default_colormap	dict[int, str] | None	Optional {class_id: color} override for class colors.	None
onclick_colormap	tuple[str, str] | list[str] | None	(selected_color, hover_color) for active labels.	None
highlight_border	bool	Whether to highlight the selected token span.	False
margin_right	str	Extra right margin for generation layouts.	'0.2em'
custom_css	str	Additional CSS injected into the HTML visualization.	''

Raises:

Type	Description
ValueError	If the attribution output uses an unsupported model task.

Examples:

>>> # classification example (from docs/notebooks/classification_demonstration.ipynb)
>>> attribution_explainer = Lime(model, tokenizer)
>>> attributions = attribution_explainer(
...     model_inputs="Love and hate are two sides of the same coin.",
...     targets=torch.tensor([[0, 1, 2, 3, 4, 5]]),
... )
>>> plot_attributions(attributions[0], classes_names=classes_names)
>>>
>>> # generation example (from docs/notebooks/generation_demonstration.ipynb)
>>> attribution_explainer = KernelShap(model, tokenizer)
>>> attributions = attribution_explainer(
...     model_inputs="Alice and Bob enter the bar, ",
...     targets="then Alice offers a drink to Bob.",
... )
>>> plot_attributions(attributions[0])

plot_concepts

Plot concept importance and activation visualizations for classification or generation tasks.

The mode is inferred from the inputs: - classification_global: sample is None and concepts_activations is None. - classification_local: sample and concepts_activations provided, classes_names provided. - generation_local: sample and concepts_activations provided, classes_names omitted.

Parameters:

Name	Type	Description	Default
concepts_importances	Any	Concept importance scores. - classification_global: tensor or dict {class_id/class_name: [scores]}. - classification_local: tensor/list/dict with shape (nb_classes, nb_concepts) or {class_id/class_name: [scores]}. - generation_local: tensor/list with shape (nb_outputs, nb_concepts).	required
concepts_labels	list[str | list[str]] | tuple[str | list[str], ...] | dict[Any, Any]	Concept labels. - classification_global: dict {concept_id: label} or {class_id/class_name: {concept_id: label}}. - classification_local: list/tuple/dict of labels or class-wise dict as above. - generation_local: list/tuple/dict of labels.	required
sample	list[str] | None	Required for local modes. Full sequence tokens (inputs + outputs for generation).	None
classes_names	list[str] | dict[int, str] | None	Optional class display names. If omitted, the plot defaults to generation_local.	None
concepts_activations	Any | None	Token-level concept activations. - classification_local: tensor/list with shape (len(sample), nb_concepts) or (1, nb_concepts); dicts may be keyed by class id/name. - generation_local: tensor/list with shape (len(sample), nb_concepts).	None
top_k	int | None	Number of concepts shown in classification lists, and for generation_local when no output token is selected.	10
concept_color	str	Default concept color for ranking bars.	'#f39c12'
default_colormap	dict[int, str] | None	Optional {concept_id: color} override for concept colors.	None
onclick_colormap	tuple[str, str] | list[str] | None	(selected_color, hover_color) for active labels.	None
custom_css	str	Additional CSS injected into the HTML visualization.	''
save_path	str | PathLike[str] | None	Optional path to save the HTML visualization.	None

Raises:

Type	Description
ValueError	If sample and concepts_activations are not provided together, or top_k is invalid.

Examples:

>>> # classification global (from docs/notebooks/classification_demonstration.ipynb)
>>> plot_concepts(
...     classes_names=classes_names,
...     concepts_importances=mean_gradients,
...     concepts_labels={k: list(v.keys()) for k, v in topk_words.items()},
... )
>>>
>>> # classification local (from docs/notebooks/classification_concept_tutorial.ipynb)
>>> plot_concepts(
...     sample=[example],
...     classes_names=classes_names,
...     concepts_activations=concepts_activations,
...     concepts_importances=local_importance.squeeze(),
...     concepts_labels=concept_interpretations,
... )
>>>
>>> # generation local (from docs/notebooks/generation_concept_tutorial.ipynb)
>>> plot_concepts(
...     concepts_activations=concepts_activations,
...     concepts_importances=local_importances,
...     concepts_labels=interpretations,
...     sample=sample_tokens,
... )