Plotting

HiMaLAYAS uses a layered plotting system. Declare layers in order, then render with show() or save().

For most use cases, start with the quickstart notebooks and use this page as a method reference when you need a specific layer, track, legend, or export option.

Signature

Plotter(results: Results) -> Plotter

Parameters

Parameter	Type	Description
results	Results	Results with a matrix and layout from Analysis.finalize(...).

Example

from matplotlib.colors import Normalize
from himalayas.plot import Plotter

# Assumes `vlim`, `essentiality_map`, and `essentiality_colors` are prepared upstream.
# See `quickstart.html` for the core workflow and `quickstart_advanced.html`
# for rails, legends, and nested zoom extensions.
plotter = (
    Plotter(results)
    .set_figure(figsize=(9, 7), subplots_adjust={"left": 0.15, "right": 0.70, "bottom": 0.05, "top": 0.95})
    .set_background(color="white")
    .plot_title("HiMaLAYAS - Yeast GI Matrix", fontsize=17)
    .plot_dendrogram(axes=[0.06, 0.16, 0.09, 0.79], linewidth=0.75, color="#888888")
    .plot_matrix(cmap="RdBu_r", center=0, vmin=-vlim, vmax=vlim, outer_lw=0)
    .plot_matrix_axis_labels(xlabel="Gene", ylabel="Gene", fontsize=16)
    .set_label_panel(axes=[0.62, 0.16, 0.36, 0.79], text_pad=0.02)
    .plot_cluster_labels(
        rank_by="q",
        label_fields=("label", "q"),
        wrap_text=True,
        wrap_width=40,
    )
    .plot_cluster_bar(
        name="sigbar",
        norm=Normalize(0, 30),
        width=0.04,
        left_pad=0.02,
    )
    .plot_label_bar(
        name="essentiality",
        values=essentiality_map,
        mode="categorical",
        colors=essentiality_colors,
        width=0.04,
        left_pad=0.06,
    )
    .plot_bar_labels(font="Helvetica", fontsize=14, rotation=90)
    .set_label_track_order(("sigbar", "essentiality"))
    .add_colorbar(name="matrix", cmap="RdBu_r", norm=Normalize(-vlim, vlim), label="Similarity")
    .plot_colorbars(ncols=1, height=0.045, gap=0.05)
)

plotter.show()

Common Methods

Method	Description
plotter.plot_matrix(...)	Declares the main matrix heatmap layer.
plotter.plot_dendrogram(...)	Declares a dendrogram layer aligned to matrix rows.
plotter.set_label_panel(...)	Configures shared label-panel geometry for labels and tracks.
plotter.plot_cluster_labels(...)	Declares cluster-level labels generated from attached Results.
plotter.plot_cluster_labels_compact(...)	Declares compact radiating cluster labels with leader lines; mutually exclusive with plot_cluster_labels(...).
plotter.plot_cluster_bar(...)	Declares a cluster-level bar track derived from cluster ranking scores.
plotter.plot_label_bar(...)	Declares a row-level annotation bar track in the label panel.
plotter.set_label_track_order(...)	Sets explicit ordering of registered label-panel tracks.
plotter.plot_bar_labels(...)	Declares titles for registered label-panel tracks.
plotter.plot_title(...)	Declares a matrix title layer.
plotter.plot_matrix_axis_labels(...)	Declares x-axis and y-axis labels for the matrix panel.
plotter.plot_row_ticks(...)	Declares row tick labels for the matrix panel.
plotter.plot_col_ticks(...)	Declares column tick labels for the matrix panel.
plotter.add_colorbar(...)	Declares a figure-level colorbar specification.
plotter.plot_colorbars(...)	Declares layout for the bottom colorbar strip.
plotter.add_label_legend(...)	Declares a categorical legend block for a row-level label bar.
plotter.plot_label_legends(...)	Declares layout for categorical legend blocks below the colorbar strip or matrix.
plotter.set_figure(...)	Configures figure size and subplot margins.
plotter.set_background(...)	Sets figure background color used for display and save.
plotter.show()	Renders (if needed) and displays the current plot.
plotter.save(...)	Renders (if needed) and saves the current plot.

Core Layers

Layers render in declaration order. Later layers draw on top of earlier ones.

plot_matrix

Declares the main matrix heatmap layer.

Plotter.plot_matrix(
    *,
    cmap: str = "viridis",
    center: float | None = None,
    vmin: float | None = None,
    vmax: float | None = None,
    show_minor_rows: bool = True,
    minor_row_step: int = 1,
    minor_row_lw: float = 0.15,
    minor_row_alpha: float = 0.15,
    outer_lw: float = 1.2,
    outer_color: str = "black",
    gutter_color: str | None = None,
) -> Plotter

Parameter	Type	Default	Description
cmap	str	"viridis"	Colormap name.
center	float | None	None	Center value for diverging normalization.
vmin	float | None	None	Minimum value override.
vmax	float | None	None	Maximum value override.
show_minor_rows	bool	True	Draw thin row gridlines.
minor_row_step	int	1	Spacing for minor row lines.
minor_row_lw	float	0.15	Minor row line width.
minor_row_alpha	float	0.15	Minor row line alpha.
outer_lw	float	1.2	Outer border width.
outer_color	str	"black"	Outer border color.
gutter_color	str | None	None	Mask color for edge artifacts in the matrix panel.

Use center for diverging color scales and vmin/vmax for explicit limits. Use set_figure(...) to configure figure size and subplot margins.

plot_dendrogram

Declares a dendrogram layer aligned to matrix rows.

Plotter.plot_dendrogram(
    *,
    axes: Sequence[float] | None = None,
    color: str | None = None,
    linewidth: float | None = None,
    data_pad: float = 0.25,
) -> Plotter

Parameter	Type	Default	Description
axes	Sequence[float] | None	[0.06, 0.05, 0.09, 0.90]	Dendrogram panel box [x0, y0, w, h] in figure fraction.
color	str | None	"#888888"	Dendrogram line color.
linewidth	float | None	1.0	Dendrogram line width.
data_pad	float	0.25	Expands y-limits to avoid clipping at the top or bottom.

set_label_panel

Configures shared label-panel geometry for labels and tracks.

Plotter.set_label_panel(
    *,
    axes: Sequence[float] | None = None,
    track_x: float | None = None,
    gutter_width: float | None = None,
    gutter_color: str | None = None,
    text_pad: float | None = None,
) -> Plotter

Parameter	Type	Default	Description
axes	Sequence[float] | None	[0.70, 0.05, 0.29, 0.90]	Label-panel box [x0, y0, w, h] in figure fraction.
track_x	float | None	0.02	Starting x-position for label-panel tracks (label-panel axes fraction).
gutter_width	float | None	0.01	Gutter width before label-panel tracks (label-panel axes fraction).
gutter_color	str | None	"white"	Label-panel gutter color.
text_pad	float | None	0.01	Padding between tracks and label text (label-panel axes fraction).

plot_cluster_labels

Declares cluster-level labels generated from attached Results.

Labels are generated internally from attached Results via Results.cluster_labels(...). Use Results.cluster_labels(...) when you need an explicit post hoc label table for inspection, export, or external workflows, not as a required input to this method. The list below documents the supported keyword arguments and effective defaults.

Plotter.plot_cluster_labels(
    *,
    overrides: Dict[int, str] | None = None,
    rank_by: str = "p",
    label_mode: str = "top_term",
    max_words: int | None = None,
    label_fields: Tuple[str, ...] | None = ("label", "n", "p"),
    label_prefix: str | None = None,
    wrap_text: bool = True,
    wrap_width: int | None = None,
    overflow: str = "wrap",
    font: str = "Helvetica",
    fontsize: float | None = 9,
    color: str | None = "black",
    alpha: float | None = 0.9,
    skip_unlabeled: bool = False,
    placeholder_text: str | None = "\\u2014",
    placeholder_color: str | None = "#b22222",
    placeholder_alpha: float | None = 0.6,
    omit_words: Sequence[str] | None = None,
    label_sep_color: str | None = "gray",
    label_sep_lw: float | None = 0.5,
    label_sep_alpha: float | None = 0.3,
    label_sep_xmin: float | None = None,
    label_sep_xmax: float | None = 1.0,
    boundary_color: str | None = "black",
    boundary_lw: float | None = 0.5,
    boundary_alpha: float | None = 0.6,
    cluster_span: str | None = None,
    cluster_span_color: str | None = None,
    cluster_span_lw: float | None = None,
    cluster_span_alpha: float | None = None,
    cluster_span_gap: float | None = None,
    cluster_span_cap_width: float | None = None,
    cluster_span_left_pad: float | None = None,
    cluster_span_right_pad: float | None = None,
) -> Plotter

Defaults shown here are effective user-facing defaults resolved from internal style configuration.

Parameter	Type	Default	Description
overrides	Dict[int, str] | None	None	Per-cluster label overrides (cluster_id -> label string).
rank_by	str	"p"	Ranking statistic for representative terms. Must be "p" or "q".
label_mode	str	"top_term"	One of "top_term" or "compressed" for internal label generation.
max_words	int | None	None	Word-based truncation limit for rendered labels.
label_fields	tuple[str, ...] | None	("label", "n", "p")	Fields shown in each label; allowed values are "label", "n", "p", "q", "fe". Use None to suppress base label and statistic text.
label_prefix	str | None	None	Optional prefix mode for display labels. Supported values are None, "cid", and "alpha".
wrap_text	bool	True	Enables wrapping logic; wrapping is applied only when wrap_width is set.
wrap_width	int | None	None	Characters per line when wrapping.
overflow	str	"wrap"	Overflow behavior: "wrap" or "ellipsis".
font	str	"Helvetica"	Label font family.
fontsize	float | None	9	Label font size.
color	str | None	"black"	Label text color.
alpha	float | None	0.9	Label text alpha for regular (non-placeholder) labels.
skip_unlabeled	bool	False	Skip clusters with no label.
placeholder_text	str | None	"\\u2014"	Placeholder label for unlabeled clusters.
placeholder_color	str | None	"#b22222"	Placeholder text color. Falls back to color, then default.
placeholder_alpha	float | None	0.6	Placeholder text alpha. Falls back to alpha, then default.
omit_words	Sequence[str] | None	None	Words omitted from rendered label text before formatting.
label_sep_color	str | None	"gray"	Separator line color.
label_sep_lw	float | None	0.5	Separator line width.
label_sep_alpha	float | None	0.3	Separator line alpha.
label_sep_xmin	float | None	auto (label_text_x)	Separator start x position.
label_sep_xmax	float | None	1.0	Separator end x position.
boundary_color	str | None	"black"	Cluster boundary color in matrix.
boundary_lw	float | None	0.5	Cluster boundary line width in matrix.
boundary_alpha	float | None	0.6	Cluster boundary alpha in matrix.
cluster_span	str | None	None	Vertical span drawn beside each cluster's row extent, one of None or "line". None draws no span (default); "line" draws a gapped vertical line with optional end caps sized by cluster_span_cap_width.
cluster_span_color	str | None	style cluster_span_color (falls back to label_sep_color)	Span line color.
cluster_span_lw	float | None	style cluster_span_lw	Span line width.
cluster_span_alpha	float | None	style cluster_span_alpha	Span line opacity.
cluster_span_gap	float | None	style cluster_span_gap	Row units trimmed from each end of the span, clamped to at most half the cluster's row extent.
cluster_span_cap_width	float | None	0.0	End-cap width (axes fraction). 0 draws a bare line; >0 draws end caps.
cluster_span_left_pad	float | None	style cluster_span_left_pad	Horizontal space (label-panel axes fraction) between the label-panel track/gutter region and the span centerline.
cluster_span_right_pad	float | None	style cluster_span_right_pad	Horizontal space (label-panel axes fraction) between the span centerline and the label text.

Use overrides to edit labels per cluster. Configure panel geometry with set_label_panel(...).

Behavior notes:

• Labels are always generated from the attached Results object.
• plot_cluster_labels(...) and plot_cluster_labels_compact(...) are mutually exclusive in one render; combining both raises an error.
• Unknown keyword arguments in plot_cluster_labels(...) raise TypeError.
• With label_mode="compressed", Results.cluster_labels(...) applies max_words during label generation (default 6 unless overridden). Plotter.plot_cluster_labels(...) applies additional Plotter-side truncation only when max_words is explicitly provided.
• label_fields values outside { "label", "n", "p", "q", "fe" } raise ValueError.
• label_fields=None suppresses base label and statistic text.
• label_prefix="cid" or label_prefix="alpha" can prefix labels even when "label" is omitted from label_fields.
• label_prefix="alpha" uses Excel-style indexing (A., B., ..., Z., AA., ...).
• If skip_unlabeled=True, clusters without labels are omitted instead of receiving placeholder text.
• Placeholder style resolves as placeholder_color -> color -> default, and placeholder_alpha -> alpha -> default.

label_fields reference:

• "label": Cluster label text generated by Results.cluster_labels(...) using the selected label_mode.
• "n": Cluster size (n, number of members in the cluster).
• "p": Representative-term hypergeometric p-value (pval), formatted as scientific notation.
• "q": Representative-term BH-FDR q-value (qval), formatted as scientific notation.
• "fe": Representative-term fold enrichment (fe), formatted as FE=<value>.
• Field order follows the order you pass in label_fields (for example, ("label", "q", "fe")).

plot_cluster_labels_compact

Declares compact radiating cluster labels: a short marker at each cluster's true vertical center, connected by a leader line to its full label in an equally-spaced floating label column on the right. An alternative to plot_cluster_labels(...) for figures with many or highly size-skewed clusters; the two are mutually exclusive in one render. Supports the same label-panel tracks as plot_cluster_labels(...) (plot_label_bar(...) and plot_cluster_bar(...)).

Plotter.plot_cluster_labels_compact(
    *,
    overrides: Dict[int, str] | None = None,
    cluster_marker: str | None = None,
    rank_by: str = "p",
    label_mode: str = "top_term",
    max_words: int | None = None,
    label_fields: Tuple[str, ...] | None = ("label", "n", "p"),
    label_prefix: str | None = "alpha",
    font: str | None = None,
    fontsize: float | None = None,
    color: str | None = None,
    alpha: float | None = None,
    skip_unlabeled: bool = False,
    placeholder_text: str | None = None,
    placeholder_color: str | None = None,
    placeholder_alpha: float | None = None,
    omit_words: Sequence[str] | None = None,
    wrap_text: bool = True,
    wrap_width: int | None = None,
    overflow: str = "wrap",
    line_shape: str | None = None,
    line_style: str | None = None,
    cluster_span: str | None = None,
    line_start: str | None = None,
    line_end: str | None = None,
    cluster_span_gap: float | None = None,
    cluster_span_color: str | None = None,
    cluster_span_lw: float | None = None,
    cluster_span_alpha: float | None = None,
    cluster_span_cap_width: float | None = None,
    cluster_span_left_pad: float | None = None,
    cluster_span_right_pad: float | None = None,
    label_left_pad: float | None = None,
    connector_width: float | None = None,
    line_color: str | None = None,
    line_lw: float | None = None,
    line_alpha: float | None = None,
    boundary_color: str | None = None,
    boundary_lw: float | None = None,
    boundary_alpha: float | None = None,
) -> Plotter

Parameter	Type	Default	Description
overrides	Dict[int, str] | None	None	Per-cluster label overrides keyed by cluster id.
cluster_marker	str | None	None	Identity marker drawn at the matrix-side marker column, one of None, "cid", "alpha". Off by default; identity is shown via the floating label's label_prefix instead.
rank_by	str	"p"	Ranking statistic for representative terms, "p" or "q".
label_mode	str	"top_term"	One of "top_term" or "compressed".
max_words	int | None	None	Maximum words in rendered display labels.
label_fields	tuple[str, ...] | None	("label", "n", "p")	Fields to include in floating labels: "label", "n", "p", "q", "fe". None suppresses base label/stat text.
label_prefix	str | None	"alpha"	Sole owner of the floating-label identity prefix, one of None, "cid", "alpha".
font	str | None	None	Font family for markers and floating labels.
fontsize	float | None	None	Font size for floating label text (points). The marker glyph size defaults independently from style compact_marker_fontsize.
color	str | None	None	Floating label text color.
alpha	float | None	None	Floating label text opacity.
skip_unlabeled	bool	False	Omit clusters without a label entirely.
placeholder_text	str | None	None	Text for unlabeled clusters.
placeholder_color	str | None	None	Color override for placeholder labels.
placeholder_alpha	float | None	None	Alpha override for placeholder labels.
omit_words	Sequence[str] | None	None	Words to omit from labels.
wrap_text	bool	True	Whether to wrap long label text.
wrap_width	int | None	None	Characters per wrapped line.
overflow	str	"wrap"	Truncation mode, "wrap" or "ellipsis".
line_shape	str | None	style compact_line_shape ("straight")	Leader-line shape, one of "straight", "curved", "elbow".
line_style	str | None	style compact_line_style ("solid")	Leader-line style, one of "solid", "dashed", "dotted".
cluster_span	str | None	None	Vertical span drawn beside each cluster's row extent, one of None or "line"; mirrors plot_cluster_labels(cluster_span=...). "line" draws a gapped vertical line with optional end caps sized by cluster_span_cap_width.
line_start	str | None	style compact_line_start ("tick")	Connector-start point decoration, one of "tick", "round", "none". Drawn only when cluster_span is None.
line_end	str | None	style compact_line_end ("tick")	Table-side endpoint decoration, one of "tick", "arrow", "round", "none".
cluster_span_gap	float | None	style cluster_span_gap	Row units trimmed from each end of a span, clamped to at most half the cluster's span height.
cluster_span_color	str | None	style cluster_span_color (falls back to label_sep_color)	Span color, independent of line_color.
cluster_span_lw	float | None	style cluster_span_lw	Span line width, independent of line_lw.
cluster_span_alpha	float | None	style cluster_span_alpha	Span opacity, independent of line_alpha.
cluster_span_cap_width	float | None	0.0	End-cap width (label-panel axes fraction). 0 draws a bare line; >0 draws end caps.
cluster_span_left_pad	float | None	style cluster_span_left_pad	Horizontal space (label-panel axes fraction) between the label-panel track/gutter region and the span centerline. Only applies when cluster_span is not None.
cluster_span_right_pad	float | None	style cluster_span_right_pad	Horizontal space (label-panel axes fraction) immediately right of the span centerline — the span-to-leader-line-start gap. Only applies when cluster_span is not None.
label_left_pad	float | None	style compact_label_left_pad (0.0)	Horizontal space (label-panel axes fraction) between the floating label column's left edge and the label text. Moves the label text only; the leader line still ends at the connector region's right edge.
connector_width	float | None	style compact_bridge_width (0.45)	Width (label-panel axes fraction) reserved for the leader-line region between the cluster span and the floating label column. Must be > 0; widening it lengthens the leader lines and pushes the label column right.
line_color	str | None	style compact_line_color	Leader-line color.
line_lw	float | None	style compact_line_lw	Leader-line width.
line_alpha	float | None	style compact_line_alpha	Leader-line opacity.
boundary_color	str | None	style boundary_color	Matrix cluster-boundary line color.
boundary_lw	float | None	style boundary_lw	Matrix cluster-boundary line width.
boundary_alpha	float | None	style boundary_alpha	Matrix cluster-boundary opacity.

Behavior notes:

• plot_cluster_labels(...) and plot_cluster_labels_compact(...) are mutually exclusive in one render; declaring both raises an error.
• Raises ValueError at render time if label-panel track widths/pads and connector_width leave no room for the floating label column, or if the span pads overrun connector_width.

Label Panel Tracks

plot_cluster_bar

Declares a cluster-level bar track derived from cluster ranking scores. Bars are scaled from -log10(score), where score is the per-cluster ranking statistic generated by Results.cluster_labels().

Does not require plot_cluster_labels(...) in the same plotting chain; it can render standalone as a cluster-level label-panel track.

Plotter.plot_cluster_bar(
    name: str,
    *,
    width: float | None = None,
    left_pad: float = 0.0,
    right_pad: float = 0.0,
    cmap: str | Colormap = "YlOrBr",
    norm: Normalize | None = None,
    alpha: float = 0.9,
    enabled: bool = True,
    title: str | None = None,
) -> Plotter

Parameter	Type	Default	Description
name	str	required	Track name used for ordering.
width	float | None	0.015	Track width (label-panel axes fraction).
left_pad	float	0.0	Left padding in the label panel (label-panel axes fraction).
right_pad	float	0.0	Right padding in the label panel (label-panel axes fraction).
cmap	str | Colormap	"YlOrBr"	Colormap name or instance.
norm	Normalize | None	None	Normalization for -log10(score).
alpha	float	0.9	Bar alpha.
enabled	bool	True	Register the track.
title	str | None	None	Optional track title.

plot_label_bar

Declares a row-level annotation bar track in the label panel.

values is a mapping from matrix row id to either a category label or a numeric value. Row-level label tracks can render without plot_cluster_labels(...).

# Categorical example: row_id -> category, plus category -> color.
characterization_map = {
    "YLR088W": "characterized",
    "YBR004C": "characterized",
    "YNL127W": "uncharacterized",
}
characterization_colors = {
    "uncharacterized": "#1e90ff",
    "characterized": "#ffffff",
}

# Continuous example: row_id -> numeric value (e.g., single-mutant fitness).
single_mutant_fitness = {
    "YLR088W": 0.82,
    "YBR004C": 0.15,
    "YNL127W": 0.67,
}
# Continuous mode uses `cmap` (and optional `vmin`/`vmax`) instead of `colors`.

Plotter.plot_label_bar(
    values: Mapping[Hashable, Any],
    *,
    mode: str = "categorical",
    colors: Dict[Any, Any] | None = None,
    cmap: str = "viridis",
    vmin: float | None = None,
    vmax: float | None = None,
    missing_color: str | None = None,
    left_pad: float = 0.0,
    width: float | None = None,
    right_pad: float = 0.0,
    name: str = "label_bar",
    title: str | None = None,
    enabled: bool = True,
) -> Plotter

Parameter	Type	Default	Description
values	Mapping[Hashable, Any]	required	Row label to category or numeric value.
mode	str	"categorical"	"categorical" or "continuous".
colors	Dict[Any, Any] | None	None	Category to color mapping for categorical mode.
cmap	str	"viridis"	Colormap for continuous mode.
vmin	float | None	None	Minimum for continuous mode normalization.
vmax	float | None	None	Maximum for continuous mode normalization.
missing_color	str | None	"#eeeeee"	Missing-value color.
left_pad	float	0.0	Left padding in the label panel (label-panel axes fraction).
width	float | None	0.012	Track width (label-panel axes fraction).
right_pad	float	0.0	Right padding in the label panel (label-panel axes fraction).
name	str	"label_bar"	Track name used for ordering.
title	str | None	None	Optional track title.
enabled	bool	True	Register the track.

Track Order

Sets explicit ordering of registered label-panel tracks.

Plotter.set_label_track_order(order: Sequence[str] | None = None) -> Plotter

Parameter	Type	Default	Description
order	Sequence[str] | None	declaration order	Explicit track order.

Track Titles

Declares titles for registered label-panel tracks.

Plotter.plot_bar_labels(
    *,
    font: str = "Helvetica",
    fontsize: float = 10,
    color: str | None = None,
    alpha: float = 1.0,
    pad: float = 2,
    rotation: float = 0,
) -> Plotter

Parameter	Type	Default	Description
font	str	"Helvetica"	Font family for track titles.
fontsize	float	10	Font size for track titles.
color	str | None	"black"	Text color.
alpha	float	1.0	Text alpha.
pad	float	2	Padding in points below the tracks.
rotation	float	0	Text rotation in degrees.

Axes and Titles

plot_title

Declares a matrix title layer.

Plotter.plot_title(
    title: str,
    *,
    fontsize: float | None = None,
    font: str | None = None,
    pad: float | None = None,
    color: str | None = None,
    alpha: float | None = None,
    **kwargs,
) -> Plotter

Parameter	Type	Default	Description
title	str	required	Title text.
fontsize	float | None	14	Title font size.
font	str | None	None	Title font family.
pad	float | None	15	Padding above the plot (points).
color	str | None	"black"	Title color.
alpha	float | None	None	Title text alpha.

**kwargs are forwarded to Matplotlib title text kwargs.

plot_matrix_axis_labels

Declares x-axis and y-axis labels for the matrix panel.

Plotter.plot_matrix_axis_labels(
    *,
    xlabel: str = "",
    ylabel: str = "",
    fontsize: float = 12,
    fontweight: str = "normal",
    xlabel_pad: float = 8,
    ylabel_pad: float | None = None,
    font: str | None = None,
    color: str | None = None,
    alpha: float = 1.0,
) -> Plotter

Parameter	Type	Default	Description
xlabel	str	""	X-axis label text.
ylabel	str	""	Y-axis label text.
fontsize	float	12	Axis label font size.
fontweight	str	"normal"	Axis label font weight.
xlabel_pad	float	8	Padding for the x-axis label (points).
ylabel_pad	float | None	0.015	Offset between matrix and y-axis label axes (figure fraction).
font	str | None	None	Font family for axis labels.
color	str | None	"black"	Axis label color.
alpha	float	1.0	Axis label alpha.

plot_row_ticks

Declares row tick labels for the matrix panel.

Plotter.plot_row_ticks(
    labels: Sequence[str] | None = None,
    *,
    position: str = "right",
    fontsize: float = 9,
    max_labels: int | None = None,
    pad: float | None = None,
) -> Plotter

Parameter	Type	Default	Description
labels	Sequence[str] | None	matrix.df.index (ordered)	Row labels.
position	str	"right"	Tick side: "left" or "right".
fontsize	float	9	Tick label font size.
max_labels	int | None	all labels	Show at most this many labels.
pad	float | None	Matplotlib default	Tick-label padding (points).

plot_col_ticks

Declares column tick labels for the matrix panel.

Plotter.plot_col_ticks(
    labels: Sequence[str] | None = None,
    *,
    position: str = "top",
    fontsize: float = 9,
    rotation: float = 90,
    max_labels: int | None = None,
    pad: float | None = None,
) -> Plotter

Parameter	Type	Default	Description
labels	Sequence[str] | None	matrix.df.columns (ordered)	Column labels.
position	str	"top"	Tick side: "top" or "bottom".
fontsize	float	9	Tick label font size.
rotation	float	90	Tick label rotation in degrees.
max_labels	int | None	all labels	Show at most this many labels.
pad	float | None	Matplotlib default	Tick-label padding (points).

Colorbars

add_colorbar

Declares a figure-level colorbar specification.

Plotter.add_colorbar(
    *,
    name: str,
    cmap: str | Colormap,
    norm: Normalize,
    label: str | None = None,
    ticks: Sequence[float] | None = None,
    color: str | None = None,
) -> Plotter

Parameter	Type	Default	Description
name	str	required	Colorbar name.
cmap	str / Colormap	required	Colormap name or instance.
norm	Normalize	required	Matplotlib normalization.
label	str | None	None	Colorbar label.
ticks	Sequence[float] | None	None	Tick locations.
color	str | None	"black"	Tick and label color.

plot_colorbars

Declares layout for the bottom colorbar strip.

Plotter.plot_colorbars(
    *,
    nrows: int | None = None,
    ncols: int | None = None,
    height: float = 0.05,
    hpad: float = 0.01,
    vpad: float = 0.01,
    gap: float = 0.02,
    border_color: str | None = None,
    border_width: float = 0.8,
    border_alpha: float = 1.0,
    fontsize: float | None = None,
    font: str | None = None,
    color: str | None = None,
    label_position: str = "below",
    label_pad: float = 2.0,
    tick_decimals: int | None = None,
) -> Plotter

Parameter	Type	Default	Description
nrows	int | None	auto	Grid rows.
ncols	int | None	auto	Grid columns.
height	float	0.05	Total colorbar strip height (figure fraction).
hpad	float	0.01	Horizontal spacing between colorbars (figure fraction).
vpad	float	0.01	Vertical spacing between colorbars (figure fraction).
gap	float	0.02	Gap between matrix and strip (figure fraction).
border_color	str | None	"black"	Border color.
border_width	float	0.8	Border line width.
border_alpha	float	1.0	Border alpha.
fontsize	float | None	9	Tick and label font size.
font	str | None	None	Tick and label font family.
color	str | None	"black"	Tick and label color.
label_position	str	"below"	Label placement: "below" or "above".
label_pad	float	2.0	Padding between colorbar and label text (points).
tick_decimals	int | None	None	Maximum decimal places for colorbar ticks; trailing zeros are trimmed.

add_label_legend

Declares a categorical legend block for a row-level label bar. The referenced track must be declared with plot_label_bar(..., mode="categorical").

Plotter.add_label_legend(
    *,
    name: str,
    title: str | None = None,
    nrows: int | None = None,
    ncols: int | None = None,
    row_pad: float | None = None,
    col_pad: float | None = None,
    show_only_present: bool = True,
) -> Plotter

Parameter	Type	Default	Description
name	str	required	Name of the row-level categorical track to explain.
title	str | None	None	Legend title override. Falls back to track title, then name.
nrows	int | None	None	Legend grid rows. If None, inferred from ncols.
ncols	int | None	None	Legend grid columns. If None, inferred from nrows.
row_pad	float | None	None	Vertical spacing between item rows (block-relative fraction). Renderer default is 0.02 for multi-row legends and 0.0 for one row.
col_pad	float | None	None	Horizontal spacing between items in a row (block-relative fraction). Renderer default is 0.02 for multi-column legends and 0.0 for one column.
show_only_present	bool	True	If True, includes only categories present in plotted matrix rows.

Behavior notes:

• Referenced legend name must exist and must be a row-level label bar.
• The referenced track must use mode="categorical".
• A non-empty category color mapping is required on the referenced track.
• Duplicate legend declarations for the same name raise ValueError.
• Legends with no items after filtering are skipped.

plot_label_legends

Declares layout for categorical legend blocks. Legends render below the colorbar strip when colorbars exist; otherwise below the matrix.

Plotter.plot_label_legends(
    *,
    height: float = 0.08,
    gap: float = 0.01,
    vpad: float = 0.01,
    title_pad: float = 2.0,
    swatch_scale: float = 0.75,
    fontsize: float | None = None,
    font: str | None = None,
    color: str | None = None,
) -> Plotter

Parameter	Type	Default	Description
height	float	0.08	Total legend strip height (figure fraction).
gap	float	0.01	Gap from the anchor strip above (figure fraction).
vpad	float	0.01	Vertical spacing between legend blocks (figure fraction).
title_pad	float	2.0	Padding between legend title and items (points).
swatch_scale	float	0.75	Relative swatch size inside each legend cell.
fontsize	float | None	9	Legend font size.
font	str | None	None	Legend font family.
color	str | None	"black"	Legend text color.

plotter = (
    Plotter(results)
    .plot_label_bar(
        name="essentiality",
        values=essentiality_map,
        mode="categorical",
        colors=essentiality_colors,
        missing_color="#ffffff",
        width=0.04,
        left_pad=0.02,
    )
    .add_label_legend(
        name="essentiality",
        title="Essentiality",
        show_only_present=True,
    )
    .plot_label_legends(
        height=0.04,
        gap=0.005,
        vpad=0.008,
        title_pad=2.0,
    )
)

Rendering

set_figure

Configures figure-level geometry (size and subplot margins).

Plotter.set_figure(
    *,
    figsize: Tuple[float, float] | None = None,
    subplots_adjust: Dict[str, float] | None = None,
) -> Plotter

Parameter	Type	Default	Description
figsize	tuple[float, float] | None	(9, 7)	Figure size in inches, (width, height).
subplots_adjust	Dict[str, float] | None	{"left": 0.15, "right": 0.70, "bottom": 0.05, "top": 0.95}	Figure subplot margins.

set_background

Sets figure background color used for display and save.

Plotter.set_background(color: str) -> Plotter

Parameter	Type	Default	Description
color	str	required	Figure background color for display and save.

show

Renders (if needed) and displays the current plot.

Plotter.show() -> None

save

Renders (if needed) and saves the current plot.

Plotter.save(
    path: str | PathLike[str],
    *,
    dpi: float | None = None,
    format: str | None = None,
    bbox_inches: str | None = None,
    pad_inches: float | None = None,
    transparent: bool | None = None,
    **kwargs,
) -> None

**kwargs are passed to Matplotlib savefig.

Notes

• Plotter expects Results with layout from Analysis.finalize(...).
• plot_matrix(...) is optional; a matrix-less plot can still render colorbars, legends, label panels, and cluster/label bar tracks.
• Unit convention: text spacing uses points (plot_title(pad=...), plot_bar_labels(pad=...), plot_matrix_axis_labels(xlabel_pad=...), plot_row_ticks(pad=...), plot_col_ticks(pad=...), plot_colorbars(label_pad=...)); layout geometry uses fractions (height, gap, hpad, vpad, left_pad, right_pad, width, axes, track_x, gutter_width, text_pad). ylabel_pad is also a geometry fraction (panel offset).