Skip to content

annotate

annotate(
    geom: str,
    x: _Position | None = None,
    y: _Position | None = None,
    *,
    xmin: _Position | None = None,
    xmax: _Position | None = None,
    ymin: _Position | None = None,
    ymax: _Position | None = None,
    xend: _Position | None = None,
    yend: _Position | None = None,
    **other_args: Any,
) -> FeatureSpec

Add a one-off layer from constants, without a data frame.

The positions train the axes, as data would. The layer inherits nothing from ggplot(), shows in no legend and has no tooltips unless tooltips is given.

Parameters:

  • geom (str) –

    The geom name, without geom_: "text", "rect", "segment", ...

  • x ((number, str or sequence), default: None ) –

    Positions. Single values repeat to the length of the sequences.

  • y ((number, str or sequence), default: None ) –

    Positions. Single values repeat to the length of the sequences.

  • xmin ((number, str or sequence), default: None ) –

    Positions. Single values repeat to the length of the sequences.

  • xmax ((number, str or sequence), default: None ) –

    Positions. Single values repeat to the length of the sequences.

  • ymin ((number, str or sequence), default: None ) –

    Positions. Single values repeat to the length of the sequences.

  • ymax ((number, str or sequence), default: None ) –

    Positions. Single values repeat to the length of the sequences.

  • xend ((number, str or sequence), default: None ) –

    Positions. Single values repeat to the length of the sequences.

  • yend ((number, str or sequence), default: None ) –

    Positions. Single values repeat to the length of the sequences.

  • **other_args (Any) –

    Other aesthetics and parameters of the geom, for example label, color or size. A sequence gives one value per row.

Returns:

  • FeatureSpec –

    A layer, or several (one per row) when a sequence is given for a style aesthetic such as color.

Raises:

  • SpecError –

    If geom is unknown, stat, position, data or mapping is given, sequences differ in length, or a connected geom gets a style sequence.

Examples:

>>> from ggrust import *
>>> data = {"day": [1, 2, 3, 4], "sales": [10, 14, 9, 17]}
>>> plot = ggplot(data, aes("day", "sales")) + geom_line()
>>> plot = plot + annotate("rect", xmin=2, xmax=3, ymin=8, ymax=18, alpha=0.2)
>>> plot = plot + annotate("text", x=4, y=17, label="record", vjust=-1)

An arrow that points at a value, with its label:

>>> base = ggplot(data, aes("day", "sales")) + geom_line()
>>> plot = base + annotate(
...     "segment", x=2.2, y=10, xend=2.9, yend=9.1, arrow=arrow(length=8), color="red"
... )
>>> plot = plot + annotate("text", x=2.2, y=10, label="dip", hjust=1.2, color="red")

A label just inside the top left corner of the panel, whatever the data range:

>>> plot = base + annotate(
...     "text", x=float("-inf"), y=float("inf"), label="store 12",
...     hjust=-0.1, vjust=1.5, size=10,
... )

An arrow that points at a value, with its label

A label just inside the top left corner of the panel, whatever the data range