Visualizer

Visualizer bound to a trainer. Exposes single-model plots. User can subclass to customize plotting behavior.

Source code in gradiend/visualizer/visualizer.py

def __init__(self, trainer: Any):
    self._trainer = trainer

_trainer instance-attribute

_trainer = trainer

trainer property

trainer

Trainer instance this visualizer delegates to.

compute_topk_sets staticmethod

compute_topk_sets(models, topk=100, part='decoder-weight')

Compute top-k weight sets for multiple models.

Parameters:

Name	Type	Description	Default
models	Dict[str, Any]	Mapping from model label to model with get_topk_weights.	required
topk	int	Number of top weights to select per model.	100
part	str	Model part passed to get_topk_weights.	'decoder-weight'

Source code in gradiend/visualizer/visualizer.py

@staticmethod
def compute_topk_sets(models: Dict[str, Any], topk: int = 100, part: str = "decoder-weight"):
    """Compute top-k weight sets for multiple models.

    Args:
        models: Mapping from model label to model with ``get_topk_weights``.
        topk: Number of top weights to select per model.
        part: Model part passed to ``get_topk_weights``.
    """
    return compute_topk_sets(models, topk=topk, part=part)

plot_encoder_by_target

plot_encoder_by_target(encoder_df=None, *, plot_style='strip', title=None, output=None, show=True, figsize=None, jitter=0.25, dodge=True, point_size=1.5, interactive=False, height=520, legend_loc='upper right', highlight_non_convergence=None, **kwargs)

Plot encoded values by masked target token for this trainer.

Parameters:

Name	Type	Description	Default
encoder_df	Optional[DataFrame]	Optional precomputed encoder analysis DataFrame.	None
plot_style	Literal['strip', 'box', 'violin']	Static plot style: strip, box, or violin.	'strip'
title	Optional[str]	Optional plot title.	None
output	Optional[str]	Explicit output path.	None
show	bool	Whether to display the plot.	True
figsize	Optional[Tuple[float, float]]	Static figure size in inches.	None
jitter	float	Jitter width for static strip plots.	0.25
dodge	bool	Whether to dodge points by hue.	True
point_size	float	Marker size for static strip plots.	1.5
interactive	bool	Return/write a Plotly interactive strip plot instead of a static plot.	False
height	int	Plotly figure height for interactive plots.	520
legend_loc	str	Matplotlib legend location for static plots.	'upper right'
highlight_non_convergence	Optional[bool]	Append a non-convergence marker when requested.	None
**kwargs	Any	Forwarded to gradiend.visualizer.encoder_by_target.plot_encoder_by_target.	{}

Source code in gradiend/visualizer/visualizer.py

def plot_encoder_by_target(
    self,
    encoder_df: Optional[pd.DataFrame] = None,
    *,
    plot_style: Literal["strip", "box", "violin"] = "strip",
    title: Optional[str] = None,
    output: Optional[str] = None,
    show: bool = True,
    figsize: Optional[Tuple[float, float]] = None,
    jitter: float = 0.25,
    dodge: bool = True,
    point_size: float = 1.5,
    interactive: bool = False,
    height: int = 520,
    legend_loc: str = "upper right",
    highlight_non_convergence: Optional[bool] = None,
    **kwargs: Any,
) -> Optional[str]:
    """Plot encoded values by masked target token for this trainer.

    Args:
        encoder_df: Optional precomputed encoder analysis DataFrame.
        plot_style: Static plot style: ``strip``, ``box``, or ``violin``.
        title: Optional plot title.
        output: Explicit output path.
        show: Whether to display the plot.
        figsize: Static figure size in inches.
        jitter: Jitter width for static strip plots.
        dodge: Whether to dodge points by hue.
        point_size: Marker size for static strip plots.
        interactive: Return/write a Plotly interactive strip plot instead of a static plot.
        height: Plotly figure height for interactive plots.
        legend_loc: Matplotlib legend location for static plots.
        highlight_non_convergence: Append a non-convergence marker when requested.
        **kwargs: Forwarded to ``gradiend.visualizer.encoder_by_target.plot_encoder_by_target``.
    """
    return _plot_encoder_by_target(
        trainer=self._trainer,
        encoder_df=encoder_df,
        plot_style=plot_style,
        title=title,
        output=output,
        show=show,
        figsize=figsize,
        jitter=jitter,
        dodge=dodge,
        point_size=point_size,
        interactive=interactive,
        height=height,
        legend_loc=legend_loc,
        highlight_non_convergence=highlight_non_convergence,
        **kwargs,
    )

plot_encoder_distributions

plot_encoder_distributions(encoder_df=None, *, output=None, output_dir=None, show=True, title=True, target_and_neutral_only=True, split_plot_mode='facet', include_neutral=False, figsize=None, img_format='png', dpi=None, highlight_non_convergence=None, return_fig_ax=False, **kwargs)

Plot encoder distributions for this trainer.

Parameters:

Name	Type	Description	Default
encoder_df	Optional[DataFrame]	Optional precomputed encoder analysis DataFrame.	None
output	Optional[str]	Explicit output path.	None
output_dir	Optional[str]	Directory used when resolving the default output filename.	None
show	bool	Whether to display the plot.	True
title	Union[str, bool]	True for the default title, False for no title, or a custom title string.	True
target_and_neutral_only	bool	Restrict to target transitions and neutral rows.	True
split_plot_mode	str	Multi-split layout mode.	'facet'
include_neutral	bool	Include neutral encoder rows.	False
figsize	Optional[Tuple[float, float]]	Figure size in inches.	None
img_format	str	File format used when saving.	'png'
dpi	Optional[int]	Optional savefig DPI.	None
highlight_non_convergence	Optional[bool]	Append a non-convergence marker when requested.	None
return_fig_ax	bool	Return (fig, axes) instead of the output path.	False
**kwargs	Any	Forwarded to gradiend.visualizer.encoder_distributions.plot_encoder_distributions.	{}

Source code in gradiend/visualizer/visualizer.py

def plot_encoder_distributions(
    self,
    encoder_df: Optional[pd.DataFrame] = None,
    *,
    output: Optional[str] = None,
    output_dir: Optional[str] = None,
    show: bool = True,
    title: Union[str, bool] = True,
    target_and_neutral_only: bool = True,
    split_plot_mode: str = "facet",
    include_neutral: bool = False,
    figsize: Optional[Tuple[float, float]] = None,
    img_format: str = "png",
    dpi: Optional[int] = None,
    highlight_non_convergence: Optional[bool] = None,
    return_fig_ax: bool = False,
    **kwargs: Any,
) -> str:
    """Plot encoder distributions for this trainer.

    Args:
        encoder_df: Optional precomputed encoder analysis DataFrame.
        output: Explicit output path.
        output_dir: Directory used when resolving the default output filename.
        show: Whether to display the plot.
        title: True for the default title, False for no title, or a custom title string.
        target_and_neutral_only: Restrict to target transitions and neutral rows.
        split_plot_mode: Multi-split layout mode.
        include_neutral: Include neutral encoder rows.
        figsize: Figure size in inches.
        img_format: File format used when saving.
        dpi: Optional savefig DPI.
        highlight_non_convergence: Append a non-convergence marker when requested.
        return_fig_ax: Return ``(fig, axes)`` instead of the output path.
        **kwargs: Forwarded to ``gradiend.visualizer.encoder_distributions.plot_encoder_distributions``.
    """
    return _plot_encoder_distributions(
        self._trainer,
        encoder_df=encoder_df,
        output=output,
        output_dir=output_dir,
        show=show,
        title=title,
        target_and_neutral_only=target_and_neutral_only,
        split_plot_mode=split_plot_mode,
        include_neutral=include_neutral,
        figsize=figsize,
        img_format=img_format,
        dpi=dpi,
        highlight_non_convergence=highlight_non_convergence,
        return_fig_ax=return_fig_ax,
        **kwargs,
    )

plot_encoder_scatter

plot_encoder_scatter(encoder_df=None, *, color_by='label', x_col=None, label_name_mapping=None, max_points=None, show=True, title=None, height=500, split='test', highlight_non_convergence=None, **kwargs)

Create an interactive encoder scatter plot for this trainer.

Parameters:

Name	Type	Description	Default
encoder_df	Optional[DataFrame]	Optional precomputed encoder analysis DataFrame.	None
color_by	str	Column used for point colors.	'label'
x_col	Optional[str]	Optional column used for the x-axis. Defaults to target token when available.	None
label_name_mapping	Optional[dict]	Optional display-name mapping for color labels.	None
max_points	Optional[int]	Optional stratified point limit.	None
show	bool	Whether to display the Plotly figure.	True
title	Optional[str]	Optional plot title.	None
height	int	Plotly figure height.	500
split	str	Encoder split to compute when encoder_df is not supplied.	'test'
highlight_non_convergence	Optional[bool]	Append a non-convergence marker when requested.	None
**kwargs	Any	Forwarded to gradiend.visualizer.encoder_scatter.plot_encoder_scatter.	{}

Source code in gradiend/visualizer/visualizer.py

def plot_encoder_scatter(
    self,
    encoder_df: Optional[pd.DataFrame] = None,
    *,
    color_by: str = "label",
    x_col: Optional[str] = None,
    label_name_mapping: Optional[dict] = None,
    max_points: Optional[int] = None,
    show: bool = True,
    title: Optional[str] = None,
    height: int = 500,
    split: str = "test",
    highlight_non_convergence: Optional[bool] = None,
    **kwargs: Any,
) -> Any:
    """Create an interactive encoder scatter plot for this trainer.

    Args:
        encoder_df: Optional precomputed encoder analysis DataFrame.
        color_by: Column used for point colors.
        x_col: Optional column used for the x-axis. Defaults to target token when available.
        label_name_mapping: Optional display-name mapping for color labels.
        max_points: Optional stratified point limit.
        show: Whether to display the Plotly figure.
        title: Optional plot title.
        height: Plotly figure height.
        split: Encoder split to compute when ``encoder_df`` is not supplied.
        highlight_non_convergence: Append a non-convergence marker when requested.
        **kwargs: Forwarded to ``gradiend.visualizer.encoder_scatter.plot_encoder_scatter``.
    """
    return _plot_encoder_scatter(
        trainer=self._trainer,
        encoder_df=encoder_df,
        color_by=color_by,
        x_col=x_col,
        label_name_mapping=label_name_mapping,
        max_points=max_points,
        show=show,
        title=title,
        height=height,
        split=split,
        highlight_non_convergence=highlight_non_convergence,
        **kwargs,
    )

plot_encoder_strip_by_split

plot_encoder_strip_by_split(encoder_df=None, *, include_neutral=False, title=None, output=None, show=True, figsize=None, jitter=0.08, dodge=True, point_size=5.0, label_points=False, highlight_non_convergence=None, **kwargs)

Plot encoded values by feature group and data split for this trainer.

Parameters:

Name	Type	Description	Default
encoder_df	Optional[DataFrame]	Optional precomputed encoder analysis DataFrame.	None
include_neutral	bool	Include neutral encoder rows.	False
title	Optional[str]	Optional plot title.	None
output	Optional[str]	Explicit output path.	None
show	bool	Whether to display the plot.	True
figsize	Optional[Tuple[float, float]]	Figure size in inches.	None
jitter	float	Horizontal jitter width.	0.08
dodge	bool	Whether to dodge points by hue.	True
point_size	float	Marker size.	5.0
label_points	Union[bool, Literal['outliers', 'outliers+sample', 'sample'], str]	Point-label mode.	False
highlight_non_convergence	Optional[bool]	Append a non-convergence marker when requested.	None
**kwargs	Any	Forwarded to gradiend.visualizer.encoder_strip_split.plot_encoder_strip_by_split.	{}

Source code in gradiend/visualizer/visualizer.py

def plot_encoder_strip_by_split(
    self,
    encoder_df: Optional[pd.DataFrame] = None,
    *,
    include_neutral: bool = False,
    title: Optional[str] = None,
    output: Optional[str] = None,
    show: bool = True,
    figsize: Optional[Tuple[float, float]] = None,
    jitter: float = 0.08,
    dodge: bool = True,
    point_size: float = 5.0,
    label_points: Union[bool, Literal["outliers", "outliers+sample", "sample"], str] = False,
    highlight_non_convergence: Optional[bool] = None,
    **kwargs: Any,
) -> Optional[str]:
    """Plot encoded values by feature group and data split for this trainer.

    Args:
        encoder_df: Optional precomputed encoder analysis DataFrame.
        include_neutral: Include neutral encoder rows.
        title: Optional plot title.
        output: Explicit output path.
        show: Whether to display the plot.
        figsize: Figure size in inches.
        jitter: Horizontal jitter width.
        dodge: Whether to dodge points by hue.
        point_size: Marker size.
        label_points: Point-label mode.
        highlight_non_convergence: Append a non-convergence marker when requested.
        **kwargs: Forwarded to ``gradiend.visualizer.encoder_strip_split.plot_encoder_strip_by_split``.
    """
    return _plot_encoder_strip_by_split(
        trainer=self._trainer,
        encoder_df=encoder_df,
        include_neutral=include_neutral,
        title=title,
        output=output,
        show=show,
        figsize=figsize,
        jitter=jitter,
        dodge=dodge,
        point_size=point_size,
        label_points=label_points,
        highlight_non_convergence=highlight_non_convergence,
        **kwargs,
    )

plot_probability_shifts

plot_probability_shifts(decoder_results=None, class_ids=None, target_class=None, increase_target_probabilities=True, use_cache=None, *, output=None, show=True, figsize=None, highlight_non_convergence=None, return_fig_ax=False, **kwargs)

Plot decoder probability shifts for this trainer.

Parameters:

Name	Type	Description	Default
decoder_results	Optional[Dict[str, Any]]	Optional precomputed decoder evaluation results.	None
class_ids	Optional[List[str]]	Classes to include. Defaults to trainer classes.	None
target_class	Optional[str]	Target class whose probability shift is highlighted.	None
increase_target_probabilities	bool	Select strengthening or weakening summary.	True
use_cache	Optional[bool]	Cache flag forwarded to trainer decoder evaluation/analysis.	None
output	Optional[str]	Explicit output path.	None
show	bool	Whether to display the plot.	True
figsize	Optional[Tuple[float, float]]	Figure size in inches.	None
highlight_non_convergence	Optional[bool]	Append a non-convergence marker when requested.	None
return_fig_ax	bool	Return (fig, axes) instead of the output path.	False
**kwargs	Any	Forwarded to gradiend.visualizer.probability_shifts.plot_probability_shifts.	{}

Source code in gradiend/visualizer/visualizer.py

def plot_probability_shifts(
    self,
    decoder_results: Optional[Dict[str, Any]] = None,
    class_ids: Optional[List[str]] = None,
    target_class: Optional[str] = None,
    increase_target_probabilities: bool = True,
    use_cache: Optional[bool] = None,
    *,
    output: Optional[str] = None,
    show: bool = True,
    figsize: Optional[Tuple[float, float]] = None,
    highlight_non_convergence: Optional[bool] = None,
    return_fig_ax: bool = False,
    **kwargs: Any,
) -> str:
    """Plot decoder probability shifts for this trainer.

    Args:
        decoder_results: Optional precomputed decoder evaluation results.
        class_ids: Classes to include. Defaults to trainer classes.
        target_class: Target class whose probability shift is highlighted.
        increase_target_probabilities: Select strengthening or weakening summary.
        use_cache: Cache flag forwarded to trainer decoder evaluation/analysis.
        output: Explicit output path.
        show: Whether to display the plot.
        figsize: Figure size in inches.
        highlight_non_convergence: Append a non-convergence marker when requested.
        return_fig_ax: Return ``(fig, axes)`` instead of the output path.
        **kwargs: Forwarded to ``gradiend.visualizer.probability_shifts.plot_probability_shifts``.
    """
    if decoder_results is None:
        decoder_results = self.trainer.evaluate_decoder(use_cache=use_cache)

    plotting_data = self.trainer.analyze_decoder_for_plotting(
        decoder_results=decoder_results,
        class_ids=class_ids,
        use_cache=use_cache,
    )

    return _plot_probability_shifts(
        trainer=self.trainer,
        decoder_results=decoder_results,
        plotting_data=plotting_data,
        class_ids=class_ids,
        target_class=target_class,
        increase_target_probabilities=increase_target_probabilities,
        output=output,
        show=show,
        figsize=figsize,
        highlight_non_convergence=highlight_non_convergence,
        return_fig_ax=return_fig_ax,
        **kwargs,
    )

plot_topk_neuron_intersection

plot_topk_neuron_intersection(models=None, topk=100, part='decoder-weight', **kwargs)

Plot a top-k neuron intersection Venn diagram.

Parameters:

Name	Type	Description	Default
models	Optional[Dict[str, Any]]	Optional mapping of model label to model. When None, uses this trainer's current model.	None
topk	int	Number of top weights to include per model.	100
part	str	Model part passed to get_topk_weights.	'decoder-weight'
**kwargs	Any	Forwarded to plot_topk_overlap_venn.	{}

Source code in gradiend/visualizer/visualizer.py

def plot_topk_neuron_intersection(
    self,
    models: Optional[Dict[str, Any]] = None,
    topk: int = 100,
    part: str = "decoder-weight",
    **kwargs: Any,
) -> Any:
    """Plot a top-k neuron intersection Venn diagram.

    Args:
        models: Optional mapping of model label to model. When ``None``, uses this
            trainer's current model.
        topk: Number of top weights to include per model.
        part: Model part passed to ``get_topk_weights``.
        **kwargs: Forwarded to ``plot_topk_overlap_venn``.
    """
    if models is None:
        model = self._trainer.get_model()
        models = {getattr(model, "name_or_path", "model"): model} if model is not None else {}
    return plot_topk_overlap_venn(models, topk=topk, part=part, **kwargs)

plot_training_convergence

plot_training_convergence(*, plot_mean_by_class=True, plot_mean_by_feature_class=None, plot_correlation=True, class_spread=None, output=None, show=True, title=True, figsize=None, img_format='png', dpi=None, highlight_non_convergence=None, return_fig_ax=False, **kwargs)

Plot convergence statistics for this trainer.

Parameters:

Name	Type	Description	Default
plot_mean_by_class	bool	Include mean encoded value by class.	True
plot_mean_by_feature_class	Optional[bool]	Include mean encoded value by feature class. None auto-disables redundant feature-class plots.	None
plot_correlation	bool	Include correlation over training steps.	True
class_spread	Optional[Literal['minmax', 'iqr', 'ci95']]	Optional spread band behind class means. "minmax" shades min-max encoded values, "iqr" shades Q1-Q3, "ci95" shades mean +/- 1.96 standard errors, and None disables spread shading.	None
output	Optional[str]	Explicit output path.	None
show	bool	Whether to display the plot.	True
title	Union[str, bool]	True for the default title, False for no title, or a custom title string.	True
figsize	Optional[Tuple[float, float]]	Figure size in inches.	None
img_format	str	File format used when saving.	'png'
dpi	Optional[int]	Optional savefig DPI.	None
highlight_non_convergence	Optional[bool]	Append a non-convergence marker when requested.	None
return_fig_ax	bool	Return (fig, axes) instead of the output path.	False
**kwargs	Any	Forwarded to gradiend.visualizer.convergence.plot_training_convergence.	{}

Source code in gradiend/visualizer/visualizer.py

def plot_training_convergence(
    self,
    *,
    plot_mean_by_class: bool = True,
    plot_mean_by_feature_class: Optional[bool] = None,
    plot_correlation: bool = True,
    class_spread: Optional[Literal["minmax", "iqr", "ci95"]] = None,
    output: Optional[str] = None,
    show: bool = True,
    title: Union[str, bool] = True,
    figsize: Optional[Tuple[float, float]] = None,
    img_format: str = "png",
    dpi: Optional[int] = None,
    highlight_non_convergence: Optional[bool] = None,
    return_fig_ax: bool = False,
    **kwargs: Any,
) -> str:
    """Plot convergence statistics for this trainer.

    Args:
        plot_mean_by_class: Include mean encoded value by class.
        plot_mean_by_feature_class: Include mean encoded value by feature class. ``None``
            auto-disables redundant feature-class plots.
        plot_correlation: Include correlation over training steps.
        class_spread: Optional spread band behind class means.
            ``"minmax"`` shades min-max encoded values, ``"iqr"`` shades Q1-Q3,
            ``"ci95"`` shades mean +/- 1.96 standard errors,
            and ``None`` disables spread shading.
        output: Explicit output path.
        show: Whether to display the plot.
        title: True for the default title, False for no title, or a custom title string.
        figsize: Figure size in inches.
        img_format: File format used when saving.
        dpi: Optional savefig DPI.
        highlight_non_convergence: Append a non-convergence marker when requested.
        return_fig_ax: Return ``(fig, axes)`` instead of the output path.
        **kwargs: Forwarded to ``gradiend.visualizer.convergence.plot_training_convergence``.
    """
    return _plot_training_convergence(
        trainer=self._trainer,
        plot_mean_by_class=plot_mean_by_class,
        plot_mean_by_feature_class=plot_mean_by_feature_class,
        plot_correlation=plot_correlation,
        class_spread=class_spread,
        output=output,
        show=show,
        title=title,
        figsize=figsize,
        img_format=img_format,
        dpi=dpi,
        highlight_non_convergence=highlight_non_convergence,
        return_fig_ax=return_fig_ax,
        **kwargs,
    )