Labels¶

xlabel(
    ax: Axes,
    text: str,
    flush: bool = True,
    labelpad: float | None = None,
    **kwargs: Any,
) -> Text

Set an x-label that sits below the right end of the bottom spine.

Call after range_frame.

Parameters:

• ax (Axes) –

  A range-framed axes.

• text (str) –

  The label text.

• flush (bool, default: True) –

  Where the label's right edge sits. True (the default) pushes it out to the rightmost tick label's right edge, so the label and the tick-label row share a flush right margin. False anchors it at the spine end (the last tick in 'nice' mode, the data max in 'data'), lining up with the centre of that tick label. The nudge is strictly outward (clamped never to move left of the spine end), so it only takes effect where the last tick sits at the spine end ('nice'/'loose' mode); in 'data' mode, where the spine already reaches past the last tick label, it is a no-op.

• labelpad (float, default: None) –

  Gap in points between the label and the tick-label column, whose edge is set by the widest tick label (matplotlib's own per-draw computation). None keeps matplotlib's default (rcParam axes.labelpad, 4.0).

• **kwargs (Any, default: {}) –

  matplotlib.text.Text properties forwarded to set_xlabel, for styling: color, fontsize, fontweight, and the like. vanzelfsprekend owns the label's alignment and position, so a horizontalalignment here is overridden.

Returns:

• Text –

  The label artist.

ylabel(
    ax: Axes,
    text: str,
    place: str = "above",
    labelpad: float | None = None,
    **kwargs: Any,
) -> Text

Set a horizontal y-label at the top of the left spine.

Call after range_frame. The two placements are Doumont's two recommended y-labels (Trees, maps and theorems): 'above' is his "better graph", 'beside' his "good graph".

Parameters:

• ax (Axes) –

  A range-framed axes.

• text (str) –

  The label text.

• place ((above, beside), default: 'above') –

  Where the horizontal label sits relative to the top tick. 'above' (the default) stacks it above the top tick label, its left edge aligned with the top tick label's left edge, as a separate clip-free text artist (see Notes). 'beside' anchors it level with the top tick label (va='center_baseline'), to its left, on matplotlib's own y-axis label; it costs the label's own width, so reach for it where the space above the frame is already taken, by a title or by the panel above.

• labelpad (float, default: None) –

  Gap in points between the label and the tick labels. None keeps matplotlib's default (rcParam axes.labelpad, 4.0). Which tick label sets the reference edge follows the placement: 'beside' measures from the widest one (matplotlib's own per-draw computation), 'above' from the top one.

• **kwargs (Any, default: {}) –

  matplotlib.text.Text properties for styling the label, such as color, fontsize, fontweight. For 'beside' they go to set_ylabel; for 'above' they style the managed above-label text. vanzelfsprekend owns the label's rotation, alignment and position, so a rotation here is overridden.

Returns:

• Text –

  The label artist: matplotlib's own ax.yaxis.label for 'beside', or the managed above-label text for 'above'.

Raises:

• ValueError –

  If place is not 'above' or 'beside'.

Notes

'above' draws the label as a standalone text child rather than relocating ax.yaxis.label, because Axes.get_tightbbox collapses an axis label's cross-height (it assumes the label sits centred on the axis) and would clip a label stacked above it. A plain child text is enclosed at full extent, so savefig(bbox_inches="tight") keeps the above-label whole with no bbox_extra_artists. The real axis label is emptied while 'above' is active.

line_labels(
    ax: Axes,
    at: Literal["start", "end"] = "end",
    labelcolor: str
    | ColorType
    | list[ColorType] = "linecolor",
    pad: float = 4.0,
    gap: float | None = None,
    labels: list[str | None] | None = None,
    **kwargs: Any,
) -> list[Annotation]

Label each line at one end, in place of a legend.

An existing legend is hidden, since the labels replace it, and restore brings it back. Text comes from each line's label=; lines with matplotlib's auto-generated _-prefixed labels or without a finite point are skipped. Labels sit just outside their line's end, each label's ink centred on the line end (measured from the glyph outlines, so the font's em-box metrics cannot skew it), and are pushed apart vertically only as far as needed to clear each other, keeping the end-value order (an exact least-squares stack, re-solved on every draw). Calling again with the same at rebuilds that side from the current lines; the sides compose, so one call per side labels both ends.

Parameters:

• ax (Axes) –

  The axes whose lines to label.

• at ((end, start), default: 'end') –

  Which end of each line to label. 'end' anchors at the last finite point, text to its right; 'start' at the first finite point, text to its left (slopegraph-style). On a 'nice' or 'data' frame, start labels can collide with the y tick labels; frame='loose' leaves a gutter for them.

• labelcolor (color, list of color, or 'linecolor', default: 'linecolor') –

  'linecolor' colours each label like its line, as in legend(labelcolor=...). A single colour applies to every label; a list is cycled over the lines.

• pad (float, default: 4.0) –

  Horizontal gap in points between a line's end and its label.

• gap (float, default: None) –

  Minimum vertical clearance in points between label boxes. None (the default) uses 2 points.

• labels (list of (str or None), default: None) –

  Supply the text yourself instead of reading each line's label=. Needed for producers that keep the legend text on a separate artist from the drawn line (seaborn labels its data lines _child0, _child1, ... and carries the real text on empty proxy lines). The list has one entry per anchorable line (a line with a finite end point, in draw order), and a None or "" entry skips that line. A length that does not match the anchorable lines raises ValueError. With the default labels=None, lines are read as above and an empty result warns, pointing here.

• **kwargs (Any, default: {}) –

  matplotlib.text.Text properties forwarded to each label, for styling: fontsize, fontweight, fontstyle, and the like. Set the colour through labelcolor, not color; alignment and position are vanzelfsprekend's to set.

Returns:

• list of matplotlib.text.Annotation –

  The label artists, in line order.

label(
    ax: Axes,
    name: str | Artist | Sequence[str | Artist],
    *,
    x: Any | None = None,
    y: Any | None = None,
    side: Side | None = None,
    labelcolor: str
    | ColorType
    | list[ColorType] = "linecolor",
    pad: float = 4.0,
    gap: float | None = None,
    **kwargs: Any,
) -> list[Annotation]

Put a label beside the artist called name, or a column of them.

The text is the artist's label=, the same string a legend would show, and the anchor is where x= or y= meets the artist: a line's crossing, a scatter's nearest point. From there the text slides along a helper line through the anchor, as little as needed, to clear every mark and text in its way. It goes right of the anchor by default and left, above or below when the right is blocked; side= chooses. Lines, scatters, texts and patches count as ink; fills and other collections do not. A one-point artist needs no anchor. Several names with one coordinate form a column on the same helper, stacked in order; a column takes only the sides perpendicular to its helper.

An existing legend is hidden, since the labels replace it, and restore brings it back. Calling again with the same artists rebuilds that group. Labels are re-solved on every draw.

Parameters:

• ax (Axes) –

  The axes holding the artist.

• name (str, artist, or sequence of them) –

  The artist's label=; or the artist itself, when two drawn artists share a label. A sequence is a column. A producer that keeps the legend text on an empty proxy (seaborn names its data lines _child0, _child1, ...) is handled by naming the drawn line first, line.set_label("A"): a drawn artist wins the name over an empty proxy.

• x (float or callable, default: None) –

  The spine coordinate of the anchor; give one, not both. Required for a multi-point artist and for a column. In the axis's own units, so a date works on a date axis. A callable is a feature as in FeatureLocator, (x, y) -> float over the artist's finite points in data units, evaluated on every draw, so x=lambda x, y: x[np.argmax(y)] anchors at the peak. A column needs a fixed number.

• y (float or callable, default: None) –

  The spine coordinate of the anchor; give one, not both. Required for a multi-point artist and for a column. In the axis's own units, so a date works on a date axis. A callable is a feature as in FeatureLocator, (x, y) -> float over the artist's finite points in data units, evaluated on every draw, so x=lambda x, y: x[np.argmax(y)] anchors at the peak. A column needs a fixed number.

• side ((right, left, above, below), default: 'right') –

  Where the text goes. None tries the sides in that order and takes the first that fits.

• labelcolor (color, list of color, or 'linecolor', default: 'linecolor') –

  As in line_labels: the artist's own colour, one colour, or a list cycled over the names.

• pad (float, default: 4.0) –

  Points between the anchor (or the column's helper) and the near edge of the text.

• gap (float, default: None) –

  Minimum clearance in points between the text and anything else. None (the default) uses 2 points.

• **kwargs (Any, default: {}) –

  matplotlib.text.Text properties forwarded to each label, for styling: fontsize, fontweight, fontstyle, and the like. Set the colour through labelcolor, not color; alignment and position are vanzelfsprekend's to set.

Returns:

• list of matplotlib.text.Annotation –

  The label artists, in name order.