gghighlight ¶

Highlight the rows or series that match predicates (R package gghighlight).

Added with +, it redraws the layers before it: every row in grey, then the matching rows on top in their own colors. A predicate is evaluated per series first (the groups of the discrete mappings or group), so pl.col("y").max() > 10 keeps whole lines; when it does not give one value per series (pl.col("y") > 10) it is evaluated per row instead, with a warning.

Parameters:

• *predicates (Expr or str) –

  Conditions on the layer data: polars expressions, or SQL strings such as "max(y) > 10" (read with pl.sql_expr). Several are combined with AND. A boolean result filters; a numeric one keeps the max_highlight series (or rows) with the largest values.

• n (int, default: None ) –

  Highlight only the last n layers; None highlights every layer.

• max_highlight (int, default: 5 ) –

  How many series (or rows) a numeric predicate keeps.

• unhighlighted_params (dict, default: None ) –

  Layer parameters of the grey copies, e.g. {"color": "pink", "size": 0.5}. The default is gghighlight's grey "#BEBEBEB2" for color and fill.

• use_group_by (bool, default: None ) –

  True evaluates per series, False per row; None (default) tries per series and falls back to per row.

• use_direct_label (bool, default: None ) –

  True labels the highlighted lines or points with geom_label_repel and hides the color and fill legends; False keeps the legends. None (default) labels when there are at most 20 labels.

• label_key (str, default: None ) –

  Column used as the label text; None uses the first series column.

• label_params (dict, default: None ) –

  Parameters of the label layer; default {"fill": "white"} for labels, none for line_label_type="ggrepel_text".

• keep_scales (bool, default: False ) –

  True keeps the color and fill scales trained on every row (adds a geom_blank layer), so the colors match the unhighlighted plot.

• calculate_per_facet (bool, default: False ) –

  True evaluates the predicates per facet panel (the facet must be added before gghighlight()), and each panel greys only its own rows. False greys every row in every panel.

• line_label_type ((ggrepel_label, ggrepel_text), default: "ggrepel_label" ) –

  Label lines with geom_label_repel or geom_text_repel.

Returns:

• FeatureSpec –

  The marker, to add to a plot with +.

Raises:

• SpecError –

  When an argument has the wrong value, or a SQL predicate does not parse.

• UnsupportedValueError –

  When a predicate is not a polars expression or a string.

Examples:

>>> import polars as pl
>>> from ggrust import *
>>> data = {
...     "day": [1, 2, 3, 4] * 3,
...     "sales": [3, 5, 4, 6, 2, 3, 9, 12, 4, 4, 5, 5],
...     "shop": ["north"] * 4 + ["south"] * 4 + ["east"] * 4,
... }
>>> plot = (
...     ggplot(data, aes("day", "sales", color="shop"))
...     + geom_line(size=1.5)
...     + gghighlight(pl.col("sales").max() > 8)
... )
>>> plot = ggplot(data, aes("day", "sales")) + geom_point(size=4)
>>> plot = plot + gghighlight("sales > 4", label_key="shop")