Legend

Color-space legend rendering for matplotlib axes (pipeline step 5).

render_legend

render_legend(
    ax: Axes,
    method: str,
    *,
    n_sets: int | None = None,
    gene_set_names: list[str] | None = None,
    colors: list[tuple[float, float, float]] | None = None,
    component_labels: list[str] | None = None,
    resolution: int = 128,
) -> Axes

Draw a color-space legend onto ax.

Parameters:

Name	Type	Description	Default
ax	Axes	Matplotlib axes to draw on.	required
method	str	"direct" for multiplicative blend legends, or any other string ("pca", "nmf", "ica", "reduce", ...) for a reduction-style RGB triangle legend.	required
n_sets	int | None	Number of gene sets (required for method="direct").	None
gene_set_names	list[str] | None	Human-readable labels. For "direct" mode the length must match n_sets. For reduction modes, names are optional (vertices are labelled by component).	None
colors	list[tuple[float, float, float]] | None	Base colours for direct mode. Ignored for reduction modes.	None
component_labels	list[str] | None	Labels for the three triangle vertices in reduction mode (e.g. ["PC1", "PC2", "PC3"]). If None, defaults to ["C1", "C2", "C3"]; for method="pca" defaults to ["PC1", "PC2", "PC3"] for backward compatibility.	None
resolution	int	Pixel resolution of the legend image.	128

Returns:

Type	Description
Axes	The axes with the legend drawn on it.

Source code in src/multiscoresplot/_legend.py

def render_legend(
    ax: Axes,
    method: str,
    *,
    n_sets: int | None = None,
    gene_set_names: list[str] | None = None,
    colors: list[tuple[float, float, float]] | None = None,
    component_labels: list[str] | None = None,
    resolution: int = 128,
) -> Axes:
    """Draw a color-space legend onto *ax*.

    Parameters
    ----------
    ax
        Matplotlib axes to draw on.
    method
        ``"direct"`` for multiplicative blend legends, or any other string
        (``"pca"``, ``"nmf"``, ``"ica"``, ``"reduce"``, ...) for a
        reduction-style RGB triangle legend.
    n_sets
        Number of gene sets (required for ``method="direct"``).
    gene_set_names
        Human-readable labels.  For ``"direct"`` mode the length must match
        *n_sets*.  For reduction modes, names are optional (vertices are
        labelled by component).
    colors
        Base colours for direct mode.  Ignored for reduction modes.
    component_labels
        Labels for the three triangle vertices in reduction mode
        (e.g. ``["PC1", "PC2", "PC3"]``).  If *None*, defaults to
        ``["C1", "C2", "C3"]``; for ``method="pca"`` defaults to
        ``["PC1", "PC2", "PC3"]`` for backward compatibility.
    resolution
        Pixel resolution of the legend image.

    Returns
    -------
    Axes
        The axes with the legend drawn on it.
    """
    # Anything that is not "direct" is treated as a reduction method.
    if method != "direct":
        if component_labels is None:
            component_labels = ["PC1", "PC2", "PC3"] if method == "pca" else ["C1", "C2", "C3"]
        _legend_reduce_triangle(ax, component_labels, resolution)
        return ax

    # --- direct mode ---
    if n_sets is None:
        if gene_set_names is not None:
            n_sets = len(gene_set_names)
        else:
            raise ValueError(
                "For method='direct', provide n_sets or gene_set_names "
                "so the legend type can be determined."
            )

    if n_sets < 2 or n_sets > 3:
        raise ValueError(f"Direct legend supports 2-3 gene sets, got {n_sets}.")

    # Default gene set names if not provided.
    if gene_set_names is None:
        gene_set_names = [f"Set {i + 1}" for i in range(n_sets)]
    elif len(gene_set_names) != n_sets:
        raise ValueError(f"gene_set_names length ({len(gene_set_names)}) != n_sets ({n_sets}).")

    # Default colours.
    if colors is None:
        colors = DEFAULT_COLORS_2 if n_sets == 2 else DEFAULT_COLORS_3

    if n_sets == 2:
        _legend_direct_square(ax, gene_set_names, colors, resolution)
    else:
        _legend_direct_triangle(ax, gene_set_names, colors, resolution)

    return ax