plot_topk_overlap_venn

Plot top-k weight index set intersection across multiple GRADIEND models and return overlap stats.

This is a standalone function: pass a dict of label -> ModelWithGradiend. Dict keys are used as set labels; use pretty labels (e.g. "3SG $\longleftrightarrow$ 3PL") as keys for consistent display with the heatmap. Uses Venn diagrams: matplotlib_venn for 2–3 models, venn package for 4–6 models. Missing packages raise ImportError with install instructions.

Parameters:

Name	Type	Description	Default
models	Dict[str, object]	Mapping from display label (or model id) to ModelWithGradiend instance.	required
topk	int	Number of top weights to consider per model (base-model weight indices).	1000
part	str	'encoder-weight' or 'decoder-weight'.	'decoder-weight'
output_path	Optional[str]	Optional path to save the figure.	None
show	bool	If True, display the plot (default True so something is shown when running).	True
figsize	Optional[Tuple[float, float]]	(width, height) in inches. Default (6, 6) for 2–3 models, (8, 8) for 4–6.	None
circle_names_fontsize	Optional[Union[int, float]]	Font size for the name of each circle (e.g. model label). Default scales with figsize.	None
region_counts_fontsize	Optional[Union[int, float]]	Font size for the numbers inside each region (overlap counts). Default scales with figsize.	None
patch_linewidth	Optional[float]	Line width of Venn patch borders. Default 3.0.	None
alpha	float	Patch transparency in [0, 1].	0.5
title	Optional[str]	Optional figure title.	None
highlight_non_convergence	bool	When True, append a non-convergence marker to circle labels for non-converged models.	True
converged_by_id	Optional[Dict[str, Optional[bool]]]	Optional explicit convergence status keyed by model id.	None
label_mapping	Optional[Dict[str, str]]	Optional display label keyed by model id.	None
seed_group_policy	str	How to collapse multi-seed groups into one Venn set.	'primary'

Returns:

Type	Description
Dict[str, object]	Dict with keys: per_model (model_id -> list of weight indices), intersection,
Dict[str, object]	union, topk, part.

Source code in gradiend/visualizer/topk/venn_.py

def plot_topk_overlap_venn(
    models: Dict[str, object],
    topk: int = 1000,
    part: str = "decoder-weight",
    output_path: Optional[str] = None,
    show: bool = True,
    figsize: Optional[Tuple[float, float]] = None,
    circle_names_fontsize: Optional[Union[int, float]] = None,
    region_counts_fontsize: Optional[Union[int, float]] = None,
    patch_linewidth: Optional[float] = None,
    alpha: float = 0.5,
    title: Optional[str] = None,
    highlight_non_convergence: bool = True,
    converged_by_id: Optional[Dict[str, Optional[bool]]] = None,
    label_mapping: Optional[Dict[str, str]] = None,
    seed_group_policy: str = "primary",
) -> Dict[str, object]:
    """
    Plot top-k weight index set intersection across multiple GRADIEND models and return overlap stats.

    This is a standalone function: pass a dict of label -> ModelWithGradiend. Dict keys are used
    as set labels; use pretty labels (e.g. ``"3SG $\\longleftrightarrow$ 3PL"``) as keys for
    consistent display with the heatmap. Uses Venn diagrams: matplotlib_venn for 2–3 models, venn
    package for 4–6 models. Missing packages raise ImportError with install instructions.

    Args:
        models: Mapping from display label (or model id) to ModelWithGradiend instance.
        topk: Number of top weights to consider per model (base-model weight indices).
        part: ``'encoder-weight'`` or ``'decoder-weight'``.
        output_path: Optional path to save the figure.
        show: If True, display the plot (default True so something is shown when running).
        figsize: (width, height) in inches. Default (6, 6) for 2–3 models, (8, 8) for 4–6.
        circle_names_fontsize: Font size for the name of each circle (e.g. model label). Default scales with figsize.
        region_counts_fontsize: Font size for the numbers inside each region (overlap counts). Default scales with figsize.
        patch_linewidth: Line width of Venn patch borders. Default 3.0.
        alpha: Patch transparency in [0, 1].
        title: Optional figure title.
        highlight_non_convergence: When True, append a non-convergence marker to circle labels
            for non-converged models.
        converged_by_id: Optional explicit convergence status keyed by model id.
        label_mapping: Optional display label keyed by model id.
        seed_group_policy: How to collapse multi-seed groups into one Venn set.

    Returns:
        Dict with keys: ``per_model`` (model_id -> list of weight indices), ``intersection``,
        ``union``, ``topk``, ``part``.
    """
    if not models:
        return {"per_model": {}, "intersection": [], "union": [], "topk": topk, "part": part}
    if not isinstance(models, dict):
        models = {"model": models}

    per_model, intersection, union = compute_topk_sets(
        models,
        topk=topk,
        part=part,
        seed_group_policy=seed_group_policy,
    )
    plot_topk_venn(
        models,
        topk=topk,
        part=part,
        output_path=output_path,
        show=show,
        figsize=figsize,
        circle_names_fontsize=circle_names_fontsize,
        region_counts_fontsize=region_counts_fontsize,
        patch_linewidth=patch_linewidth,
        alpha=alpha,
        title=title,
        highlight_non_convergence=highlight_non_convergence,
        converged_by_id=converged_by_id,
        label_mapping=label_mapping,
        seed_group_policy=seed_group_policy,
    )

    return {
        "per_model": per_model,
        "intersection": intersection,
        "union": union,
        "topk": topk,
        "part": part,
        "seed_group_policy": seed_group_policy,
    }