guide_axis_nested ¶

Axis guide with brackets naming groups of breaks (R legendry guide_axis_nested).

Each group gets a bracket (or a box) spanning its breaks and its name past it, outside the axis labels (side="axis") or across the panel (side="opposite", e.g. gene groups above a dot plot whose gene names are below). Works on any axis side (position=), under coord_flip(), in facets (beside the axis only), in gggrid() and on side panel axes (scale_xsidey_*()). Names take the axis text theme and may hold "\n" line breaks; the bracket takes theme(legendry_bracket=...), its depth legendry_bracket_size, the box legendry_box. One level of groups. In HTML output with zoom (ggtb()) the brackets follow the breaks; names of groups that leave the panel are hidden.

Parameters:

• key (mapping or RangeKey) –

  The groups: a mapping of group name to its categories ({"Citrus": ["lemon", "lime"]}; a group spans its first to last category on the axis), or key_range_manual(start, end, name). Categories not on the axis are skipped; groups with none are dropped.

• type ((bracket, box), default: "bracket" ) –

  Bracket beside the breaks with the name past it, or a box holding the name.

• bracket ((line, square, chevron), default: "line" ) –

  Bracket shape (legendry's bracket_line(), bracket_square(), bracket_chevron()).

• side ((axis, opposite), default: "axis" ) –

  Past the axis labels, or across the panel from the axis.

• pad_discrete (float, default: 0.4 ) –

  Categories a group reaches past its first and last category.

• angle (float, default: 0 ) –

  Angle of the group names, in degrees.

Returns:

• FeatureSpec –

  Guide specification for scale_*(guide=...) or guides(x=...).

Raises:

• SpecError –

  If an option value is unknown, or a level is in two groups.

• UnsupportedValueError –

  If key or an option has the wrong type.

Examples:

>>> from ggrust import *
>>> data = {"fruit": ["lemon", "lime", "apple", "pear", "plum"],
...         "sales": [4, 3, 8, 5, 2]}
>>> plot = (
...     ggplot(data, aes("fruit", "sales"))
...     + geom_col()
...     + scale_x_discrete(
...         limits=data["fruit"],
...         guide=guide_axis_nested(
...             {"Citrus": ["lemon", "lime"], "Pome": ["apple", "pear"]},
...             bracket="square",
...         ),
...     )
... )