Plotting¶

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

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`, `gene_essential_map`, and `gene_essential_colors` are prepared upstream.
# See `quickstart.html` for a complete example showing where these are defined.
plotter = (
    Plotter(results)
    .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=gene_essential_map,
        mode="categorical",
        colors=gene_essential_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_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/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.plot_sigbar_legend(...)`	Declares a significance-bar legend layer.
`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,
    figsize: tuple[float, float] | None = None,
    subplots_adjust: dict[str, float] | 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.
`figsize`	`tuple[float, float] \| None`	`(9, 7)`	Figure size override.
`subplots_adjust`	`dict[str, float] \| None`	`{"left": 0.15, "right": 0.70, "bottom": 0.05, "top": 0.95}`	Figure margins override.

Use center for diverging color scales and vmin/vmax for explicit limits.

`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.
`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 top/bottom clipping.

`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.
`track_x`	`float \| None`	`0.02`	Starting x-position for label-panel tracks.
`gutter_width`	`float \| None`	`0.01`	Gutter width before label-panel tracks.
`gutter_color`	`str \| None`	`"white"`	Label-panel gutter color.
`text_pad`	`float \| None`	`0.01`	Padding between tracks and label text.

`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 = 6,
    label_fields: tuple[str, ...] = ("label", "n", "p"),
    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,
    dendro_boundary_color: str | None = "white",
    dendro_boundary_lw: float | None = 0.5,
    dendro_boundary_alpha: float | None = 0.3,
) -> 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`	`6`	Word-based truncation limit for labels. Use `None` to avoid truncation in compressed mode.
`label_fields`	`tuple[str, ...]`	`("label", "n", "p")`	Fields shown in each label; allowed values are `"label"`, `"n"`, `"p"`, `"q"`.
`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.
`dendro_boundary_color`	`str \| None`	`"white"`	Cluster boundary color in dendrogram.
`dendro_boundary_lw`	`float \| None`	`0.5`	Dendrogram boundary line width.
`dendro_boundary_alpha`	`float \| None`	`0.3`	Dendrogram boundary alpha.

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.
Unknown keyword arguments in plot_cluster_labels(...) raise TypeError.
label_fields values outside { "label", "n", "p", "q" } raise ValueError.
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 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 statistic selected by plot_cluster_labels(rank_by=...).

Requires plot_cluster_labels(...) in the same plotting chain. Rendering raises ValueError if an enabled cluster bar track is declared without a cluster-label layer.

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.
`left_pad`	`float`	`0.0`	Left padding in the label panel.
`right_pad`	`float`	`0.0`	Right padding in the label panel.
`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., row variance).
row_variance = {
    "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.
`width`	`float \| None`	`0.012`	Track width.
`right_pad`	`float`	`0.0`	Right padding in the label panel.
`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,
    pad: float | None = None,
    color: str | None = None,
) -> Plotter

Parameter	Type	Default	Description
`title`	`str`	required	Title text.
`fontsize`	`float \| None`	`14`	Title font size.
`pad`	`float \| None`	`15`	Padding above the plot.
`color`	`str \| None`	`"black"`	Title color.

`plot_matrix_axis_labels`¶

Declares x/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.
`ylabel_pad`	`float \| None`	`0.015`	Padding between matrix and y-axis label.
`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,
) -> 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.

`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,
) -> 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.

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",
    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.
`hpad`	`float`	`0.01`	Horizontal spacing between colorbars.
`vpad`	`float`	`0.01`	Vertical spacing between colorbars.
`gap`	`float`	`0.02`	Gap between matrix and strip.
`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"`.
`tick_decimals`	`int \| None`	`None`	Maximum decimal places for colorbar ticks; trailing zeros are trimmed.

Legends¶

`plot_sigbar_legend`¶

Declares a significance-bar legend layer.

Plotter.plot_sigbar_legend(
    *,
    axes: Sequence[float] = [0.92, 0.20, 0.015, 0.25],
    sigbar_cmap: str | None = None,
    norm: Normalize | None = None,
    sigbar_min_logp: float | None = None,
    sigbar_max_logp: float | None = None,
) -> Plotter

Parameter	Type	Default	Description
`axes`	`Sequence[float]`	`[0.92, 0.20, 0.015, 0.25]`	Legend box `[x0, y0, w, h]`.
`sigbar_cmap`	`str \| None`	`"YlOrBr"`	Colormap for the legend.
`norm`	`Normalize \| None`	`None`	Normalization for `-log10(score)`.
`sigbar_min_logp`	`float \| None`	`2.0`	Lower bound for legend scale.
`sigbar_max_logp`	`float \| None`	`10.0`	Upper bound for legend scale.

Rendering¶

`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, **kwargs) -> None

**kwargs are passed to Matplotlib savefig.

Notes¶

Plotter expects Results with layout from Analysis.finalize().

Plotting¶

Signature¶

Parameters¶

Example¶

Common Methods¶

Core Layers¶

plot_matrix¶

plot_dendrogram¶

set_label_panel¶

plot_cluster_labels¶

Label Panel Tracks¶

plot_cluster_bar¶

plot_label_bar¶

Track Order¶

Track Titles¶

Axes and Titles¶

plot_title¶

plot_matrix_axis_labels¶

plot_row_ticks¶

plot_col_ticks¶