Skip to content

funky_heatmap

funky_heatmap: a table of bars, circles, rounded squares, pies, text and images.

Column groups, row groups and legends included.

Ports the R package funkyheatmap 0.5 (MIT, see THIRD_PARTY_NOTICES.md): the argument model (data, column_info, row_info, column_groups, row_groups, palettes, legends, position_arguments()), the cell geometry (calculate_*_positions, score_to_funky_rectangle), the default palettes and the legend layouts. funkyheatmap draws with ggplot2 + ggforce + patchwork; here every shape becomes an ordinary ggrust layer (geom_rect, geom_polygon, geom_segment, geom_text, image layers) on one coord_fixed canvas, so the result is a normal PlotSpec that composes with +. One data unit is 0.25 inch, as in funkyheatmap (24 px at 96 dpi).

What it does not do: measure text (column widths come from width, as in funkyheatmap), or read image formats other than PNG. Differences from funkyheatmap are listed in deviations.md.

MAX_HEIGHT module-attribute

MAX_HEIGHT = 10000

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

MAX_WIDTH module-attribute

MAX_WIDTH = 10000

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

PaletteValue module-attribute

PaletteValue = (
    str
    | collections.abc.Sequence[str]
    | collections.abc.Mapping[str, str]
)

Represent a union type

E.g. for int | str

TYPE_CHECKING module-attribute

TYPE_CHECKING = False

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

TableLike module-attribute

TableLike = (
    polars.dataframe.frame.DataFrame
    | collections.abc.Sequence[
        collections.abc.Mapping[str, typing.Any]
    ]
    | collections.abc.Mapping[
        str, collections.abc.Sequence[typing.Any]
    ]
)

Represent a union type

E.g. for int | str

ColumnNotFoundError

ColumnNotFoundError(
    message: str,
    *,
    column: str,
    available: list[str],
    path: str = "",
)

Bases: ggrust.errors.DataError

Raised when a mapping refers to a column that is not in the data.

Parameters:

  • message (str) –

    The full message, listing the available columns and a close match.

  • column (str) –

    The missing column.

  • available (list of str) –

    Names of the columns the data has.

  • path (str, default: "" ) –

    Spec path of the mapping that names the column, e.g. "layers[0].mapping.x".

Examples:

>>> from ggrust import *
>>> from ggrust.errors import ColumnNotFoundError
>>> data = {"weight": [2.6, 2.9, 3.2, 3.4, 3.6, 4.1], "mpg": [31, 28, 24, 22, 19, 15]}
>>> chart = ggplot(data, aes("wieght", "mpg")) + geom_point()
>>> try:
...     svg = chart.to_svg()
... except ColumnNotFoundError as error:
...     print(error.column, error.available)
wieght ['weight', 'mpg']

PositionArguments

PositionArguments(
    row_height: float = 1.0,
    row_space: float = 0.1,
    row_bigspace: float = 1.2,
    col_width: float = 1.0,
    col_space: float = 0.1,
    col_bigspace: float = 0.5,
    col_annot_offset: float = 3.0,
    col_annot_angle: float = 30.0,
    expand_xmin: float = 0.0,
    expand_xmax: float = 2.0,
    expand_ymin: float = 0.0,
    expand_ymax: float = 0.0,
    col_annot_position: Literal["top", "bottom"] = "top",
    col_group_radius: float = 0.0,
    legend_position: Literal[
        "bottom", "right", "none"
    ] = "bottom",
)

Spacing and placement settings of a funky_heatmap; see position_arguments.

Build one with position_arguments(), which checks the values and documents each field.

Examples:

>>> from ggrust.bistro import position_arguments
>>> positions = position_arguments(row_height=1.2, legend_position="right")
>>> positions.row_height, positions.legend_position
(1.2, 'right')

col_annot_angle class-attribute

col_annot_angle = 30.0

Convert a string or number to a floating-point number, if possible.

col_annot_offset class-attribute

col_annot_offset = 3.0

Convert a string or number to a floating-point number, if possible.

col_annot_position class-attribute

col_annot_position = 'top'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

col_bigspace class-attribute

col_bigspace = 0.5

Convert a string or number to a floating-point number, if possible.

col_group_radius class-attribute

col_group_radius = 0.0

Convert a string or number to a floating-point number, if possible.

col_space class-attribute

col_space = 0.1

Convert a string or number to a floating-point number, if possible.

col_width class-attribute

col_width = 1.0

Convert a string or number to a floating-point number, if possible.

expand_xmax class-attribute

expand_xmax = 2.0

Convert a string or number to a floating-point number, if possible.

expand_xmin class-attribute

expand_xmin = 0.0

Convert a string or number to a floating-point number, if possible.

expand_ymax class-attribute

expand_ymax = 0.0

Convert a string or number to a floating-point number, if possible.

expand_ymin class-attribute

expand_ymin = 0.0

Convert a string or number to a floating-point number, if possible.

legend_position class-attribute

legend_position = 'bottom'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

row_bigspace class-attribute

row_bigspace = 1.2

Convert a string or number to a floating-point number, if possible.

row_height class-attribute

row_height = 1.0

Convert a string or number to a floating-point number, if possible.

row_space class-attribute

row_space = 0.1

Convert a string or number to a floating-point number, if possible.

SpecError

SpecError(
    message: str, *, path: str = "", reason: str = ""
)

Bases: ggrust.errors.GgrustError, builtins.ValueError

Raised when the plot specification holds an invalid value.

Parameters:

  • message (str) –

    The full message, including the location.

  • path (str, default: "" ) –

    Spec path of the offending value, e.g. "layers[0].size" or "theme.axis_text.size"; empty when the error concerns the whole spec.

  • reason (str, default: "" ) –

    What was wrong and what is accepted, without the location.

Examples:

>>> from ggrust import *
>>> from ggrust.errors import SpecError
>>> data = {"weight": [2.6, 2.9, 3.2, 3.4, 3.6, 4.1], "mpg": [31, 28, 24, 22, 19, 15]}
>>> chart = ggplot(data, aes("weight", "mpg")) + geom_point(shape="star")
>>> try:
...     svg = chart.to_svg()
... except SpecError as error:
...     print(error.path)
layers[0].shape

aes

aes(
    x: str | Sequence[Any] | None = None,
    y: str | Sequence[Any] | None = None,
    **kwargs: object,
) -> FeatureSpec

Define aesthetic mappings.

Parameters:

  • x (str, default: None ) –

    Columns mapped to the x and y positions.

  • y (str, default: None ) –

    Columns mapped to the x and y positions.

  • **kwargs (object) –

    Other aesthetics, e.g. color="cluster", size="count", group=[...].

Returns:

  • FeatureSpec –

    Aesthetic mapping specification (kind "mapping").

Examples:

>>> from ggrust import *
>>> data = {"height": [150, 165, 180, 172], "weight": [52, 61, 80, 70],
...         "sex": ["f", "f", "m", "m"]}
>>> mapping = aes(x="height", y="weight", color="sex")
>>> plot = ggplot(data, mapping) + geom_point(size=5)

coord_fixed

coord_fixed(
    ratio: Number = 1.0,
    xlim: Sequence[Number | None] | None = None,
    ylim: Sequence[Number | None] | None = None,
    flip: bool = False,
    *,
    expand: bool | None = None,
) -> FeatureSpec

Cartesian coordinates with a fixed aspect ratio.

Parameters:

  • ratio (float, default: 1.0 ) –

    Length of one y unit relative to one x unit on screen; the panel shrinks to keep it and is centred.

  • xlim (list, default: None ) –

    As in coord_cartesian.

  • ylim (list, default: None ) –

    As in coord_cartesian.

  • flip (bool, default: False ) –

    Swap x and y.

  • expand (bool, default: True ) –

    As in coord_cartesian. Not in lets_plot.

Returns:

  • FeatureSpec –

    The coordinate system.

Examples:

>>> from ggrust import *
>>> data = {"x": [0, 1, 2, 3, 4], "y": [0, 1, 4, 9, 16]}
>>> plot = ggplot(data, aes("x", "y")) + geom_line() + coord_fixed(ratio=0.25)

A square panel: the same limits on both axes, one unit as long on each:

>>> plot = ggplot(data, aes("x", "y")) + geom_line()
>>> plot = plot + coord_fixed(xlim=[0, 16], ylim=[0, 16], expand=False)

did_you_mean

did_you_mean(word: str, candidates: Iterable[str]) -> str

Return "; did you mean 'x'?" for the closest candidate, or "".

Same rule as the engine's suggestions: about one edit (insertion, deletion, substitution or swap of neighbours) per three letters, none for one- and two-letter words; case differences alone always match. No suggestion when several candidates are equally close or word starts several of them.

Parameters:

  • word (str) –

    The misspelt name.

  • candidates (iterable of str) –

    The accepted names.

Returns:

  • str –

    The suggestion, ready to append to a message.

funky_heatmap

funky_heatmap(
    data: DataFrame | Mapping[str, Sequence[Any]],
    column_info: TableLike | None = None,
    row_info: TableLike | None = None,
    column_groups: TableLike | None = None,
    row_groups: TableLike | None = None,
    palettes: Mapping[str, PaletteValue] | None = None,
    legends: Sequence[Mapping[str, Any]] | None = None,
    position_args: PositionArguments | None = None,
    scale_column: bool = True,
    add_abc: bool = True,
) -> PlotSpec

Draw a funky heatmap: a table of bars, circles, rounded squares, pies, text and images.

Column groups, row groups and legends are drawn around the cells.

Follows the R package funkyheatmap: the same arguments, defaults and layout. The result is an ordinary plot built from rect, polygon, segment, text and image layers on a coord_fixed canvas (one unit is 0.25 inch), so + adds layers in the same coordinates: row i (1-based) of an ungrouped table is centred at y = -i * (row_height + row_space).

Parameters:

  • data (polars.DataFrame or dict of columns) –

    One row per table row, with a unique id column. Pie cells are struct (dict) values of category -> amount; image cells are PNG file paths or URLs.

  • column_info (DataFrame or list of dict, default: None ) –

    One entry per column to draw, in order. Keys: id (data column, required), name (header text; None for none), geom ("funkyrect", "circle", "rect", "bar", "pie", "text" or "image"), group, palette, width, overlay (draw over the previous column), legend, draw_outline (dashed guides around bars), id_color and id_size (columns giving the color and the size, default id), and options: a dict merged into the entry (hjust, vjust, size, fontface, label, scale, directory, extension). A key left out of an entry takes funkyheatmap's default; None is R's NA ("name": None draws no name). Default: every data column, geoms guessed from the types.

  • row_info (DataFrame or list of dict, default: None ) –

    Rows to draw, in order: id and an optional group. Default: every row.

  • column_groups (DataFrame or list of dict, default: None ) –

    One entry per column group: group, palette (its header color is the palette's middle color) and one or more level keys with the header texts. The first key's level is drawn solid with white bold text, others translucent.

  • row_groups (DataFrame or list of dict, default: None ) –

    One entry per row group: group and level keys with the group titles.

  • palettes (dict, default: None ) –

    Palette name -> a default palette name ("Blues", "Reds", "YlOrBr", "Greens", "Greys", "Set1", "Set2", "Set3", "Dark2"), a list of colors (numbers in 0..1 pick along it), or a dict of category -> color. Missing palettes get defaults in turn.

  • legends (list of dict, default: None ) –

    Legends to draw: title, geom, palette, labels, size, color, values (text and image legends), label_hjust, label_width, enabled. Every used palette without a legend gets one.

  • position_args (PositionArguments, default: None ) –

    Spacing and placement from position_arguments().

  • scale_column (bool, default: True ) –

    Min-max scale each numeric column to 0..1 (per column option scale).

  • add_abc (bool, default: True ) –

    Prefix the first-level column group headers with a), b), ...

Returns:

  • PlotSpec –

    The heatmap, sized to its content.

Raises:

  • ColumnNotFoundError –

    When data has no id column, or column_info names a missing column.

  • SpecError –

    For an unknown geom or palette, an undescribed group, a non-PNG image, or a malformed argument; the message names the argument and the accepted values.

Examples:

>>> import polars as pl
>>> from ggrust import *
>>> from ggrust.bistro import funky_heatmap
>>> scores = pl.DataFrame(
...     {
...         "id": ["Alpha", "Beta", "Gamma", "Delta"],
...         "speed": [0.9, 0.6, 0.4, 0.1],
...         "accuracy": [0.7, 0.8, 0.3, 0.5],
...         "memory": [0.2, 0.5, 0.9, 0.7],
...     }
... )
>>> column_info = [
...     {"id": "id", "name": "Method", "geom": "text", "group": "method",
...      "options": {"hjust": 0, "width": 3}},
...     {"id": "speed", "name": "Speed", "geom": "bar", "group": "scores",
...      "palette": "scores", "options": {"width": 3}},
...     {"id": "accuracy", "name": "Accuracy", "geom": "funkyrect", "group": "scores",
...      "palette": "scores"},
...     {"id": "memory", "name": "Memory", "geom": "circle", "group": "scores",
...      "palette": "scores"},
... ]
>>> column_groups = [
...     {"Category": "Method", "group": "method", "palette": "black"},
...     {"Category": "Scores", "group": "scores", "palette": "scores"},
... ]
>>> plot = funky_heatmap(
...     scores,
...     column_info=column_info,
...     column_groups=column_groups,
...     palettes={"scores": "Blues", "black": ["black", "black"]},
... )

The defaults, from the data alone (geoms are guessed from the column types):

>>> plot = funky_heatmap(scores)

One geom for every score, without column groups and with the legend on the right:

>>> from ggrust.bistro import position_arguments
>>> bars = [
...     {"id": "id", "name": "Method", "geom": "text", "options": {"hjust": 0, "width": 3}},
...     {"id": "speed", "geom": "bar", "palette": "scores", "options": {"width": 4}},
...     {"id": "accuracy", "geom": "bar", "palette": "scores", "options": {"width": 4}},
...     {"id": "memory", "geom": "bar", "palette": "scores", "options": {"width": 4}},
... ]
>>> plot = funky_heatmap(
...     scores,
...     column_info=bars,
...     palettes={"scores": "Greens"},
...     position_args=position_arguments(legend_position="right"),
... )

geom_polygon

geom_polygon(
    mapping: FeatureSpec | None = None,
    *,
    data: PlotData | None = None,
    stat: str | None = None,
    position: Position | None = None,
    show_legend: bool | None = None,
    inherit_aes: bool | None = None,
    manual_key: ManualKey | None = None,
    sampling: Sampling | None = None,
    tooltips: Tooltips | None = None,
    color_by: str | None = None,
    fill_by: str | None = None,
    na_rm: bool | None = None,
    **other_args: Any,
) -> LayerSpec

Draw filled polygons, one per group.

Parameters:

  • mapping (FeatureSpec, default: None ) –

    Aesthetic mapping from aes().

  • data (DataFrame or dict, default: None ) –

    Layer data; inherits the plot data when None.

  • stat (str, default: None ) –

    Statistical transformation, by name.

  • position (str or FeatureSpec, default: None ) –

    Position adjustment: a name such as "dodge" or a position_*() spec.

  • show_legend (bool, default: None ) –

    False hides this layer from the legend.

  • inherit_aes (bool, default: None ) –

    False ignores the plot's default mapping for this layer.

  • manual_key (str or FeatureSpec, default: None ) –

    This layer's key in a manual legend: a label, or layer_key().

  • sampling ((str, int or FeatureSpec), default: None ) –

    Rows to draw: a sampling_*() spec, an int n (sampling_random(n)) or "none". Default: every row.

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

    Tooltip content: layer_tooltips(), a list of column names, or "none" to disable tooltips (HTML output).

  • color_by (str, default: None ) –

    Aesthetic the color scale applies to ("color" or "fill").

  • fill_by (str, default: None ) –

    Aesthetic the fill scale applies to ("fill" or "color").

  • na_rm (bool, default: None ) –

    True removes rows with missing values silently; otherwise they are removed with a warning.

  • **other_args (Any) –

    Constant aesthetics such as color="red" or size=2, and the geom's options. As in lets_plot; options ggrust does not read yet are reported as not supported.

Returns:

  • LayerSpec –

    The layer.

Examples:

>>> from ggrust import *
>>> data = {"x": [0, 2, 3, 1, 4, 6, 5], "y": [0, 0, 2, 2, 0, 0, 3],
...         "shape": ["a", "a", "a", "a", "b", "b", "b"]}
>>> plot = ggplot(data, aes("x", "y", fill="shape")) + geom_polygon(alpha=0.7)

geom_rect

geom_rect(
    mapping: FeatureSpec | None = None,
    *,
    data: PlotData | None = None,
    stat: str | None = None,
    position: Position | None = None,
    show_legend: bool | None = None,
    inherit_aes: bool | None = None,
    manual_key: ManualKey | None = None,
    sampling: Sampling | None = None,
    tooltips: Tooltips | None = None,
    map: PlotData | None = None,
    map_join: str | Sequence[str] | None = None,
    use_crs: str | None = None,
    color_by: str | None = None,
    fill_by: str | None = None,
    na_rm: bool | None = None,
    **other_args: Any,
) -> LayerSpec

Rectangles from xmin, xmax, ymin, ymax.

Parameters:

  • mapping (FeatureSpec, default: None ) –

    Aesthetic mapping from aes().

  • data (DataFrame or dict, default: None ) –

    Layer data; inherits the plot data when None.

  • map (optional, default: None ) –

    GIS options of lets_plot; ggrust does not support maps.

  • map_join (optional, default: None ) –

    GIS options of lets_plot; ggrust does not support maps.

  • use_crs (optional, default: None ) –

    GIS options of lets_plot; ggrust does not support maps.

  • stat (str, default: None ) –

    Statistical transformation, by name.

  • position (str or FeatureSpec, default: None ) –

    Position adjustment: a name such as "dodge" or a position_*() spec.

  • show_legend (bool, default: None ) –

    False hides this layer from the legend.

  • inherit_aes (bool, default: None ) –

    False ignores the plot's default mapping for this layer.

  • manual_key (str or FeatureSpec, default: None ) –

    This layer's key in a manual legend: a label, or layer_key().

  • sampling ((str, int or FeatureSpec), default: None ) –

    Rows to draw: a sampling_*() spec, an int n (sampling_random(n)) or "none". Default: every row.

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

    Tooltip content: layer_tooltips(), a list of column names, or "none" to disable tooltips (HTML output).

  • color_by (str, default: None ) –

    Aesthetic the color scale applies to ("color" or "fill").

  • fill_by (str, default: None ) –

    Aesthetic the fill scale applies to ("fill" or "color").

  • na_rm (bool, default: None ) –

    True removes rows with missing values silently; otherwise they are removed with a warning.

  • **other_args (Any) –

    Constant aesthetics and the geom's options, as in lets_plot.

Returns:

  • LayerSpec –

    The layer.

Examples:

>>> from ggrust import *
>>> data = {"room": ["kitchen", "hall", "office"], "left": [0, 4, 0], "right": [4, 6, 3],
...         "bottom": [0, 0, 3], "top": [3, 5, 5]}
>>> plot = ggplot(data) + geom_rect(
...     aes(xmin="left", xmax="right", ymin="bottom", ymax="top", fill="room"), color="white"
... )

One rectangle from constants, highlighting a region behind the points:

>>> from ggrust.data import mpg
>>> plot = ggplot(mpg, aes("displ", "hwy")) + geom_rect(
...     xmin=5, xmax=7.2, ymin=22, ymax=27, fill="gold", alpha=0.4
... ) + geom_point()

geom_segment

geom_segment(
    mapping: FeatureSpec | None = None,
    *,
    data: PlotData | None = None,
    stat: str | None = None,
    position: Position | None = None,
    show_legend: bool | None = None,
    inherit_aes: bool | None = None,
    manual_key: ManualKey | None = None,
    sampling: Sampling | None = None,
    tooltips: Tooltips | None = None,
    arrow: FeatureSpec | None = None,
    spacer: float | None = None,
    color_by: str | None = None,
    na_rm: bool | None = None,
    **other_args: Any,
) -> LayerSpec

Line segments from (x, y) to (xend, yend), optionally with arrows.

Parameters:

  • mapping (FeatureSpec, default: None ) –

    Aesthetic mapping from aes().

  • data (DataFrame or dict, default: None ) –

    Layer data; inherits the plot data when None.

  • stat (str, default: None ) –

    Statistical transformation, by name.

  • position (str or FeatureSpec, default: None ) –

    Position adjustment: a name such as "dodge" or a position_*() spec.

  • show_legend (bool, default: None ) –

    False hides this layer from the legend.

  • inherit_aes (bool, default: None ) –

    False ignores the plot's default mapping for this layer.

  • manual_key (str or FeatureSpec, default: None ) –

    This layer's key in a manual legend: a label, or layer_key().

  • sampling ((str, int or FeatureSpec), default: None ) –

    Rows to draw: a sampling_*() spec, an int n (sampling_random(n)) or "none". Default: every row.

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

    Tooltip content: layer_tooltips(), a list of column names, or "none" to disable tooltips (HTML output).

  • arrow (FeatureSpec, default: None ) –

    Arrow spec from arrow().

  • spacer (float, default: 0.0 ) –

    Pixels to cut off both ends, on top of the size_start/size_end and stroke_start/stroke_end padding.

  • color_by (str, default: None ) –

    Aesthetic the color scale applies to ("color" or "fill").

  • na_rm (bool, default: None ) –

    True removes rows with missing values silently; otherwise they are removed with a warning.

  • **other_args (Any) –

    Constant aesthetics such as color="red" or size=2, and the geom's options. As in lets_plot; options ggrust does not read yet are reported as not supported. size_start/size_end and stroke_start/stroke_end (constant or mapped) stop the line short of a point of that size and stroke at the start/end, so it touches the point's outline instead of its center.

Returns:

  • LayerSpec –

    The layer.

Examples:

>>> from ggrust import *
>>> data = {"task": ["plan", "build", "test"], "start": [1, 3, 7], "end": [3, 8, 10]}
>>> plot = ggplot(data) + geom_segment(
...     aes(x="start", xend="end", y="task", yend="task"), size=3
... )

Arrows on the segment ends:

>>> plot = ggplot(data) + geom_segment(
...     aes(x="start", xend="end", y="task", yend="task"),
...     arrow=arrow(type="closed", length=12, ends="both"),
... )

Segments that stop short of the points they connect: size_start and size_end take the point size, spacer adds a gap in pixels:

>>> flights = {"x": [1, 4], "y": [1, 2], "xend": [3, 6], "yend": [2, 1]}
>>> plot = ggplot(flights, aes(x="x", y="y", xend="xend", yend="yend"))
>>> plot = plot + geom_point(size=10, shape=1)
>>> plot = plot + geom_point(aes("xend", "yend"), size=10, shape=1)
>>> plot = plot + geom_segment(
...     size_start=10, size_end=10, spacer=4, arrow=arrow(length=10),
... )

geom_text

geom_text(
    mapping: FeatureSpec | None = None,
    *,
    data: PlotData | None = None,
    stat: str | None = None,
    position: Position | None = None,
    show_legend: bool | None = None,
    inherit_aes: bool | None = None,
    manual_key: ManualKey | None = None,
    sampling: Sampling | None = None,
    tooltips: Tooltips | None = None,
    label_format: str | None = None,
    na_text: str | None = None,
    halo_width: Number | None = None,
    halo_color: Color | None = None,
    nudge_x: Number | None = None,
    nudge_y: Number | None = None,
    nudge_unit: Literal["identity", "size", "px"]
    | None = None,
    check_overlap: bool | None = None,
    na_rm: bool | None = None,
    **other_args: Any,
) -> LayerSpec

Text labels at (x, y); the text comes from the label aesthetic.

Parameters:

  • mapping (FeatureSpec, default: None ) –

    Aesthetic mapping from aes().

  • data (DataFrame or dict, default: None ) –

    Layer data; inherits the plot data when None.

  • stat (str, default: None ) –

    Statistical transformation, by name.

  • position (str or FeatureSpec, default: None ) –

    Position adjustment: a name such as "dodge" or a position_*() spec.

  • show_legend (bool, default: None ) –

    False hides this layer from the legend.

  • inherit_aes (bool, default: None ) –

    False ignores the plot's default mapping for this layer.

  • manual_key (str or FeatureSpec, default: None ) –

    This layer's key in a manual legend: a label, or layer_key().

  • sampling ((str, int or FeatureSpec), default: None ) –

    Rows to draw: a sampling_*() spec, an int n (sampling_random(n)) or "none". Default: every row.

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

    Tooltip content: layer_tooltips(), a list of column names, or "none" to disable tooltips (HTML output).

  • label_format (str, default: None ) –

    Format pattern of the label text, e.g. ".2f" or "{d} %".

  • na_text (str, default: None ) –

    Text shown for missing values.

  • halo_width (float, default: None ) –

    Width of the text halo: how far, in pixels, it reaches beyond the glyph outlines. A halo is drawn only when halo_width > 0.

  • halo_color (str, default: None ) –

    Color of the text halo. Defaults to the panel background color, else the plot background color. Constant only, not an aesthetic.

  • nudge_x (float, default: None ) –

    Horizontal offset of the labels.

  • nudge_y (float, default: None ) –

    Vertical offset of the labels.

  • nudge_unit ((identity, size, px), default: "identity" ) –

    Unit of nudge_x/nudge_y: data units, point diameters of size=1 (2.2 px), or pixels. A positive nudge_y in "size"/"px" moves up.

  • check_overlap (bool, default: None ) –

    True skips labels that overlap labels drawn before them.

  • na_rm (bool, default: None ) –

    True removes rows with missing values silently; otherwise they are removed with a warning.

  • **other_args (Any) –

    Constant aesthetics such as color="red" or size=2, and the geom's options. As in lets_plot; options ggrust does not read yet are reported as not supported.

Returns:

  • LayerSpec –

    The layer.

Examples:

>>> from ggrust import *
>>> data = {"city": ["Oslo", "Rome", "Lima"], "rain": [763, 798, 16], "sun": [1668, 2473, 1230]}
>>> plot = ggplot(data, aes("sun", "rain", label="city")) + geom_text(size=8)

Bar values formatted with label_format, nudged above the bar tops by a pixel distance:

>>> plot = ggplot(data, aes("city", "sun")) + geom_col() + geom_text(
...     aes(label="sun"), label_format="{d} h", nudge_y=10, nudge_unit="px"
... )

Many labels: check_overlap skips those that would cover an earlier one:

>>> from ggrust.data import mpg
>>> plot = ggplot(mpg, aes("displ", "hwy", label="model")) + geom_text(check_overlap=True)

ggplot

ggplot(
    data: PlotData | None = None,
    mapping: FeatureSpec | None = None,
) -> PlotSpec

Create a new plot.

Parameters:

  • data (DataFrame or dict, default: None ) –

    Data shared by all layers: polars or pandas DataFrame, pyarrow Table, any object exporting __arrow_c_stream__, or a dict of columns.

  • mapping (FeatureSpec, default: None ) –

    Default aesthetic mapping from aes().

Returns:

  • PlotSpec –

    The plot. Add layers, scales and features with +.

Examples:

>>> from ggrust import *
>>> data = {"weight": [2.6, 2.9, 3.2, 3.4, 3.6, 4.1], "mpg": [31, 28, 24, 22, 19, 15]}
>>> plot = ggplot(data, aes(x="weight", y="mpg")) + geom_point()

ggsize

ggsize(width: Number, height: Number) -> FeatureSpec

Set the plot size in pixels.

Parameters:

  • width (float) –

    Size in pixels, at most 10,000 each (NaN is rejected, as in lets_plot).

  • height (float) –

    Size in pixels, at most 10,000 each (NaN is rejected, as in lets_plot).

Returns:

  • FeatureSpec –

    The size feature.

Examples:

>>> from ggrust import *
>>> data = {"weight": [2.6, 2.9, 3.2, 3.4, 3.6, 4.1], "mpg": [31, 28, 24, 22, 19, 15]}
>>> plot = ggplot(data, aes("weight", "mpg")) + geom_point() + ggsize(400, 250)

Added to a grid, it sets the size of the whole figure:

>>> points = ggplot(data, aes("weight", "mpg")) + geom_point()
>>> plot = gggrid([points, points + geom_line()]) + ggsize(700, 250)

position_arguments

position_arguments(
    row_height: float = 1.0,
    row_space: float = 0.1,
    row_bigspace: float = 1.2,
    col_width: float = 1.0,
    col_space: float = 0.1,
    col_bigspace: float = 0.5,
    col_annot_offset: float = 3.0,
    col_annot_angle: float = 30.0,
    expand_xmin: float = 0.0,
    expand_xmax: float = 2.0,
    expand_ymin: float = 0.0,
    expand_ymax: float = 0.0,
    col_annot_position: Literal["top", "bottom"] = "top",
    col_group_radius: float = 0.0,
    legend_position: Literal[
        "bottom", "right", "none"
    ] = "bottom",
) -> PositionArguments

Spacing and placement settings for funky_heatmap, in data units (0.25 inch).

The first twelve arguments are funkyheatmap's position_arguments(), with the same defaults. The last three are ggrust additions.

Parameters:

  • row_height (float, default: 1.0 ) –

    Height of a row.

  • row_space (float, default: 0.1 ) –

    Space between rows.

  • row_bigspace (float, default: 1.2 ) –

    Space between row groups.

  • col_width (float, default: 1.0 ) –

    Kept for funkyheatmap compatibility; column widths come from column_info.

  • col_space (float, default: 0.1 ) –

    Space between columns.

  • col_bigspace (float, default: 0.5 ) –

    Space between column groups.

  • col_annot_offset (float, default: 3.0 ) –

    Room reserved for the column names.

  • col_annot_angle (float, default: 30.0 ) –

    Angle of the column names, in degrees.

  • expand_xmin (float, default: 0.0 ) –

    Extra room around the table (defaults 0, 2, 0, 0), e.g. for long column names.

  • expand_xmax (float, default: 0.0 ) –

    Extra room around the table (defaults 0, 2, 0, 0), e.g. for long column names.

  • expand_ymin (float, default: 0.0 ) –

    Extra room around the table (defaults 0, 2, 0, 0), e.g. for long column names.

  • expand_ymax (float, default: 0.0 ) –

    Extra room around the table (defaults 0, 2, 0, 0), e.g. for long column names.

  • col_annot_position ((top, bottom), default: "top" ) –

    Where the column names go. "bottom" writes them below the table, ending at the table, and keeps the column groups on top.

  • col_group_radius (float, default: 0.0 ) –

    Corner radius of the column group headers; half the header height (0.5) draws pills.

  • legend_position ((bottom, right, none), default: "bottom" ) –

    Where the legends go: in a row below the table (funkyheatmap), in a column to its right, or nowhere.

Returns:

Raises:

  • SpecError –

    For a negative size, or an unknown col_annot_position / legend_position.

Examples:

>>> from ggrust.bistro import position_arguments
>>> position_arguments(col_annot_angle=90, legend_position="right").legend_position
'right'

scale_color_identity

scale_color_identity(
    name: str | None = None,
    breaks: Breaks | None = None,
    labels: Labels | None = None,
    lablim: int | None = None,
    limits: Limits | None = None,
    na_value: Color | Number | None = None,
    guide: Guide = "none",
    format: str | None = None,
) -> FeatureSpec

Use the data as colors (names or hex codes); no legend by default.

Parameters:

  • name (str, default: None ) –

    Title of the scale, shown on the axis or the legend.

  • breaks (list or dict, default: None ) –

    Positions of the ticks or legend keys: a list, or a dict of labels to values.

  • labels (list or dict, default: None ) –

    Texts at the breaks: a list, or a dict of break values to texts.

  • lablim (int, default: None ) –

    Maximum number of characters of a label; longer labels are cut.

  • limits (list, default: None ) –

    Data range of the scale: [low, high] for continuous scales (None keeps a side), or the levels of a discrete scale.

  • na_value (str or float, default: None ) –

    Value used for missing data.

  • guide (str or FeatureSpec, default: 'none' ) –

    Guide: "legend", "colorbar", "none", or a guide_*() spec.

  • format (str, default: None ) –

    Format pattern of the labels, e.g. ".2f" or "{d} %".

Returns:

  • FeatureSpec –

    The scale.

Examples:

>>> from ggrust import *
>>> data = {"x": [1, 2, 3], "y": [3, 1, 2], "paint": ["tomato", "gold", "teal"]}
>>> plot = ggplot(data, aes("x", "y", color="paint")) + geom_point(size=8)
>>> plot = plot + scale_color_identity()

scale_fill_identity

scale_fill_identity(
    name: str | None = None,
    breaks: Breaks | None = None,
    labels: Labels | None = None,
    lablim: int | None = None,
    limits: Limits | None = None,
    na_value: Color | Number | None = None,
    guide: Guide = "none",
    format: str | None = None,
) -> FeatureSpec

Use the data as fill colors; no legend by default.

Parameters:

  • name (str, default: None ) –

    Title of the scale, shown on the axis or the legend.

  • breaks (list or dict, default: None ) –

    Positions of the ticks or legend keys: a list, or a dict of labels to values.

  • labels (list or dict, default: None ) –

    Texts at the breaks: a list, or a dict of break values to texts.

  • lablim (int, default: None ) –

    Maximum number of characters of a label; longer labels are cut.

  • limits (list, default: None ) –

    Data range of the scale: [low, high] for continuous scales (None keeps a side), or the levels of a discrete scale.

  • na_value (str or float, default: None ) –

    Value used for missing data.

  • guide (str or FeatureSpec, default: 'none' ) –

    Guide: "legend", "colorbar", "none", or a guide_*() spec.

  • format (str, default: None ) –

    Format pattern of the labels, e.g. ".2f" or "{d} %".

Returns:

  • FeatureSpec –

    The scale.

Examples:

>>> from ggrust import *
>>> data = {"x": ["a", "b", "c"], "y": [3, 1, 2], "paint": ["tomato", "gold", "teal"]}
>>> plot = ggplot(data, aes("x", "y", fill="paint")) + geom_bar(stat="identity")
>>> plot = plot + scale_fill_identity()

text_width builtin

text_width(text, size, fontface='plain')

Advance width in pixels of one line of text at size px in the default font, with fontface parsed as lets-plot does ("bold", "bold_italic", ...).

theme

theme(
    *,
    exponent_format: str
    | tuple[str, int | None, int | None]
    | None = None,
    line: ThemeElement | None = None,
    rect: ThemeElement | None = None,
    text: ThemeElement | None = None,
    title: ThemeElement | None = None,
    axis: ThemeElement | None = None,
    axis_ontop: bool | None = None,
    axis_ontop_x: bool | None = None,
    axis_ontop_y: bool | None = None,
    axis_title: ThemeElement | None = None,
    axis_title_x: ThemeElement | None = None,
    axis_title_y: ThemeElement | None = None,
    axis_text: ThemeElement | None = None,
    axis_text_x: ThemeElement | None = None,
    axis_text_y: ThemeElement | None = None,
    axis_text_spacing: Number | None = None,
    axis_text_spacing_x: Number | None = None,
    axis_text_spacing_y: Number | None = None,
    axis_ticks: ThemeElement | None = None,
    axis_ticks_x: ThemeElement | None = None,
    axis_ticks_y: ThemeElement | None = None,
    axis_minor_ticks: ThemeElement | None = None,
    axis_minor_ticks_x: ThemeElement | None = None,
    axis_minor_ticks_y: ThemeElement | None = None,
    axis_ticks_length: Number | None = None,
    axis_ticks_length_x: Number | None = None,
    axis_ticks_length_y: Number | None = None,
    axis_minor_ticks_length: Number | None = None,
    axis_minor_ticks_length_x: Number | None = None,
    axis_minor_ticks_length_y: Number | None = None,
    axis_line: ThemeElement | None = None,
    axis_line_x: ThemeElement | None = None,
    axis_line_y: ThemeElement | None = None,
    legend_background: ThemeElement | None = None,
    legend_text: ThemeElement | None = None,
    legend_title: ThemeElement | None = None,
    legend_position: str | Sequence[Number] | None = None,
    legend_position_inside: Sequence[Number] | None = None,
    legend_justification: str
    | Sequence[Number]
    | None = None,
    legend_direction: Literal[horizontal, vertical]
    | None = None,
    legend_title_position: Literal[top, right, bottom, left]
    | None = None,
    legend_margin: Margins | None = None,
    legend_spacing: Number | None = None,
    legend_spacing_x: Number | None = None,
    legend_spacing_y: Number | None = None,
    legend_key: ThemeElement | None = None,
    legend_key_size: Number | None = None,
    legend_key_width: Number | None = None,
    legend_key_height: Number | None = None,
    legend_key_spacing: Number | None = None,
    legend_key_spacing_x: Number | None = None,
    legend_key_spacing_y: Number | None = None,
    legend_box: Literal[horizontal, vertical] | None = None,
    legend_box_just: str | None = None,
    legend_box_spacing: Number | None = None,
    legend_ticks: ThemeElement | None = None,
    legend_ticks_length: Number
    | Sequence[Number]
    | None = None,
    legend_frame: ThemeElement | None = None,
    legend_interactive: bool | None = None,
    panel_background: ThemeElement | None = None,
    panel_border: ThemeElement | None = None,
    panel_border_ontop: bool | None = None,
    panel_grid: ThemeElement | None = None,
    panel_grid_ontop: bool | None = None,
    panel_grid_ontop_x: bool | None = None,
    panel_grid_ontop_y: bool | None = None,
    panel_grid_major: ThemeElement | None = None,
    panel_grid_minor: ThemeElement | None = None,
    panel_grid_major_x: ThemeElement | None = None,
    panel_grid_minor_x: ThemeElement | None = None,
    panel_grid_major_y: ThemeElement | None = None,
    panel_grid_minor_y: ThemeElement | None = None,
    panel_inset: Margins | None = None,
    plot_background: ThemeElement | None = None,
    plot_title: ThemeElement | None = None,
    plot_subtitle: ThemeElement | None = None,
    plot_caption: ThemeElement | None = None,
    plot_tag: ThemeElement | None = None,
    plot_message: ThemeElement | None = None,
    plot_margin: Margins | None = None,
    plot_inset: Margins | None = None,
    plot_title_position: Literal[panel, plot] | None = None,
    plot_caption_position: Literal[panel, plot]
    | None = None,
    plot_tag_position: str | Sequence[Number] | None = None,
    plot_tag_location: str | None = None,
    plot_tag_prefix: str | None = None,
    plot_tag_suffix: str | None = None,
    strip_background: ThemeElement | None = None,
    strip_background_x: ThemeElement | None = None,
    strip_background_y: ThemeElement | None = None,
    strip_text: ThemeElement | None = None,
    strip_text_x: ThemeElement | None = None,
    strip_text_y: ThemeElement | None = None,
    strip_spacing: Number | None = None,
    strip_spacing_x: Number | None = None,
    strip_spacing_y: Number | None = None,
    panel_spacing: Number | None = None,
    panel_spacing_x: Number | None = None,
    panel_spacing_y: Number | None = None,
    axis_tooltip: ThemeElement | None = None,
    axis_tooltip_x: ThemeElement | None = None,
    axis_tooltip_y: ThemeElement | None = None,
    axis_tooltip_text: ThemeElement | None = None,
    axis_tooltip_text_x: ThemeElement | None = None,
    axis_tooltip_text_y: ThemeElement | None = None,
    tooltip: ThemeElement | None = None,
    tooltip_text: ThemeElement | None = None,
    tooltip_title_text: ThemeElement | None = None,
    tooltip_merge: bool | None = None,
    tooltip_max_count: int | None = None,
    label_text: ThemeElement | None = None,
    geom: Mapping[str, Any] | None = None,
    ggside_panel_scale: Number | None = None,
    ggside_panel_scale_x: Number | None = None,
    ggside_panel_scale_y: Number | None = None,
    ggside_panel_spacing: Number | None = None,
    ggside_panel_spacing_x: Number | None = None,
    ggside_panel_spacing_y: Number | None = None,
    ggside_panel_background: ThemeElement | None = None,
    ggside_xside_panel_background: ThemeElement
    | None = None,
    ggside_yside_panel_background: ThemeElement
    | None = None,
    ggside_panel_border: ThemeElement | None = None,
    ggside_xside_panel_border: ThemeElement | None = None,
    ggside_yside_panel_border: ThemeElement | None = None,
    ggside_axis_text: ThemeElement | None = None,
    ggside_axis_text_x: ThemeElement | None = None,
    ggside_axis_text_x_top: ThemeElement | None = None,
    ggside_axis_text_x_bottom: ThemeElement | None = None,
    ggside_axis_text_y: ThemeElement | None = None,
    ggside_axis_text_y_left: ThemeElement | None = None,
    ggside_axis_text_y_right: ThemeElement | None = None,
    ggside_axis_ticks: ThemeElement | None = None,
    ggside_axis_ticks_x: ThemeElement | None = None,
    ggside_axis_ticks_x_top: ThemeElement | None = None,
    ggside_axis_ticks_x_bottom: ThemeElement | None = None,
    ggside_axis_ticks_y: ThemeElement | None = None,
    ggside_axis_ticks_y_left: ThemeElement | None = None,
    ggside_axis_ticks_y_right: ThemeElement | None = None,
    ggside_axis_ticks_length: Number | None = None,
    ggside_axis_ticks_length_x: Number | None = None,
    ggside_axis_ticks_length_x_top: Number | None = None,
    ggside_axis_ticks_length_x_bottom: Number | None = None,
    ggside_axis_ticks_length_y: Number | None = None,
    ggside_axis_ticks_length_y_left: Number | None = None,
    ggside_axis_ticks_length_y_right: Number | None = None,
    ggside_axis_minor_ticks: ThemeElement | None = None,
    ggside_axis_minor_ticks_x: ThemeElement | None = None,
    ggside_axis_minor_ticks_x_top: ThemeElement
    | None = None,
    ggside_axis_minor_ticks_x_bottom: ThemeElement
    | None = None,
    ggside_axis_minor_ticks_y: ThemeElement | None = None,
    ggside_axis_minor_ticks_y_left: ThemeElement
    | None = None,
    ggside_axis_minor_ticks_y_right: ThemeElement
    | None = None,
    ggside_axis_minor_ticks_length: Number | None = None,
    ggside_axis_minor_ticks_length_x: Number | None = None,
    ggside_axis_minor_ticks_length_x_top: Number
    | None = None,
    ggside_axis_minor_ticks_length_x_bottom: Number
    | None = None,
    ggside_axis_minor_ticks_length_y: Number | None = None,
    ggside_axis_minor_ticks_length_y_left: Number
    | None = None,
    ggside_axis_minor_ticks_length_y_right: Number
    | None = None,
    ggside_axis_line: ThemeElement | None = None,
    ggside_axis_line_x: ThemeElement | None = None,
    ggside_axis_line_x_top: ThemeElement | None = None,
    ggside_axis_line_x_bottom: ThemeElement | None = None,
    ggside_axis_line_y: ThemeElement | None = None,
    ggside_axis_line_y_left: ThemeElement | None = None,
    ggside_axis_line_y_right: ThemeElement | None = None,
    legendry_bracket: ThemeElement | None = None,
    legendry_bracket_size: Number | None = None,
    legendry_box: ThemeElement | None = None,
    legendry_guide_spacing: Number | None = None,
) -> FeatureSpec

Set theme options: element_*() values, numbers or names per theme element.

Every parameter is keyword-only, named and valued as in lets_plot theme() (axis_text_x=element_text(size=10), legend_position="bottom", panel_grid=element_blank(), ...). Parameters left as None are not set. Element parameters take an element_*() value, or "blank" to hide the element. _x / _y variants override the shared one for one axis.

Parameters:

  • exponent_format (str or tuple, default: None ) –

    How every number label (axes, legends, text, tooltips) writes exponents: "e" (1e+6), "pow" (10^6 as a superscript, the default) or "pow_full" (1·10^6). A tuple (style, lower, upper) also sets the exponents at or beyond which numbers switch to scientific notation (None keeps the default bound, -7 or 6).

  • line (dict or str, default: None ) –

    Root elements every line, rectangle, text and title inherits from.

  • rect (dict or str, default: None ) –

    Root elements every line, rectangle, text and title inherits from.

  • text (dict or str, default: None ) –

    Root elements every line, rectangle, text and title inherits from.

  • title (dict or str, default: None ) –

    Root elements every line, rectangle, text and title inherits from.

  • axis (dict or str, default: None ) –

    Every part of both axes.

  • axis_ontop (bool, default: None ) –

    True draws the axis over the plot layers.

  • axis_ontop_x (bool, default: None ) –

    True draws the axis over the plot layers.

  • axis_ontop_y (bool, default: None ) –

    True draws the axis over the plot layers.

  • axis_title (dict or str, default: None ) –

    Axis titles (element_text()).

  • axis_title_x (dict or str, default: None ) –

    Axis titles (element_text()).

  • axis_title_y (dict or str, default: None ) –

    Axis titles (element_text()).

  • axis_text (dict or str, default: None ) –

    Tick labels (element_text()).

  • axis_text_x (dict or str, default: None ) –

    Tick labels (element_text()).

  • axis_text_y (dict or str, default: None ) –

    Tick labels (element_text()).

  • axis_text_spacing (float, default: None ) –

    Space between the ticks and their labels, in pixels.

  • axis_text_spacing_x (float, default: None ) –

    Space between the ticks and their labels, in pixels.

  • axis_text_spacing_y (float, default: None ) –

    Space between the ticks and their labels, in pixels.

  • axis_ticks (dict or str, default: None ) –

    Major ticks (element_line()).

  • axis_ticks_x (dict or str, default: None ) –

    Major ticks (element_line()).

  • axis_ticks_y (dict or str, default: None ) –

    Major ticks (element_line()).

  • axis_minor_ticks (dict or str, default: None ) –

    Minor ticks (element_line()).

  • axis_minor_ticks_x (dict or str, default: None ) –

    Minor ticks (element_line()).

  • axis_minor_ticks_y (dict or str, default: None ) –

    Minor ticks (element_line()).

  • axis_ticks_length (float, default: None ) –

    Length of the major ticks, in pixels.

  • axis_ticks_length_x (float, default: None ) –

    Length of the major ticks, in pixels.

  • axis_ticks_length_y (float, default: None ) –

    Length of the major ticks, in pixels.

  • axis_minor_ticks_length (float, default: None ) –

    Length of the minor ticks, in pixels.

  • axis_minor_ticks_length_x (float, default: None ) –

    Length of the minor ticks, in pixels.

  • axis_minor_ticks_length_y (float, default: None ) –

    Length of the minor ticks, in pixels.

  • axis_line (dict or str, default: None ) –

    Axis lines (element_line()); they also take arrow and extent for arrow-headed, truncated axes.

  • axis_line_x (dict or str, default: None ) –

    Axis lines (element_line()); they also take arrow and extent for arrow-headed, truncated axes.

  • axis_line_y (dict or str, default: None ) –

    Axis lines (element_line()); they also take arrow and extent for arrow-headed, truncated axes.

  • legend_background (dict or str, default: None ) –

    Legend box (element_rect()), key labels and title (element_text()).

  • legend_text (dict or str, default: None ) –

    Legend box (element_rect()), key labels and title (element_text()).

  • legend_title (dict or str, default: None ) –

    Legend box (element_rect()), key labels and title (element_text()).

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

    "right", "left", "top", "bottom", "none", or [x, y] inside the plot (0 to 1). "inside" puts legends in the panel at legend_position_inside (ggplot2 3.5).

  • legend_position_inside (list of float, default: None ) –

    [x, y] (0 to 1, from the panel's bottom-left) where inside legends go: legend_position="inside" and guide_*(position="inside"). None uses legend_justification (ggplot2 3.5).

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

    Anchor of the legend box: a name such as "center", or [x, y].

  • legend_direction ((horizontal, vertical), default: "horizontal" ) –

    Layout of the legend keys.

  • legend_title_position ((top, right, bottom, left), default: "top" ) –

    Side of each legend (keys or colorbar) its title goes to (ggplot2 3.5). None puts it at the top of vertical legends and the left of horizontal ones. Above or below, legend_title's hjust places both the title and the keys across the legend width (0 left, 0.5 centred); left or right, its vjust places them down the height (default 0.5, centred). Per guide: guide_colorbar(theme=theme(legend_title_position="bottom")).

  • legend_margin (float or list of float, default: None ) –

    Margins around the legend, in pixels (one number, or 2 to 4 as in CSS).

  • legend_spacing (float, default: None ) –

    Space between legends, in pixels.

  • legend_spacing_x (float, default: None ) –

    Space between legends, in pixels.

  • legend_spacing_y (float, default: None ) –

    Space between legends, in pixels.

  • legend_key (dict or str, default: None ) –

    Background of the legend keys (element_rect()).

  • legend_key_size (float, default: None ) –

    Size of the legend keys, in pixels.

  • legend_key_width (float, default: None ) –

    Size of the legend keys, in pixels.

  • legend_key_height (float, default: None ) –

    Size of the legend keys, in pixels.

  • legend_key_spacing (float, default: None ) –

    Space between legend keys, in pixels.

  • legend_key_spacing_x (float, default: None ) –

    Space between legend keys, in pixels.

  • legend_key_spacing_y (float, default: None ) –

    Space between legend keys, in pixels.

  • legend_box ((horizontal, vertical), default: "horizontal" ) –

    Arrangement of several legends.

  • ggside_panel_scale (float, default: None ) –

    Size of the ggside side panels (geom_xside*(), geom_yside*()) as a share of the main panel: _x the x side panel's height, _y the y side panel's width. Default 0.1, as ggside.

  • ggside_panel_scale_x (float, default: None ) –

    Size of the ggside side panels (geom_xside*(), geom_yside*()) as a share of the main panel: _x the x side panel's height, _y the y side panel's width. Default 0.1, as ggside.

  • ggside_panel_scale_y (float, default: None ) –

    Size of the ggside side panels (geom_xside*(), geom_yside*()) as a share of the main panel: _x the x side panel's height, _y the y side panel's width. Default 0.1, as ggside.

  • ggside_panel_spacing (float, default: None ) –

    Gap between the main panel and a side panel, in pixels: _x beside a y side panel, _y beside an x side panel. Default 2 pt (about 2.7 px).

  • ggside_panel_spacing_x (float, default: None ) –

    Gap between the main panel and a side panel, in pixels: _x beside a y side panel, _y beside an x side panel. Default 2 pt (about 2.7 px).

  • ggside_panel_spacing_y (float, default: None ) –

    Gap between the main panel and a side panel, in pixels: _x beside a y side panel, _y beside an x side panel. Default 2 pt (about 2.7 px).

  • ggside_panel_background (ThemeElement | None, default: None ) –

    Background of the ggside side panels (element_rect()), as R ggside's ggside.panel.background: ggside_xside_panel_background styles the x side panels (above or below), ggside_yside_panel_background the y side panels (left or right). Unset ones fall back to ggside_panel_background, then to panel_background, so by default a side panel looks like the main one. The background's border color and size frame the side panel the way they frame the main panel: ggside_panel_background=element_rect(size=0) keeps the fill and drops the frame, element_blank() drops both. ggmarginal() margins draw neither.

  • ggside_ (ThemeElement | None, default: None ) –

    Background of the ggside side panels (element_rect()), as R ggside's ggside.panel.background: ggside_xside_panel_background styles the x side panels (above or below), ggside_yside_panel_background the y side panels (left or right). Unset ones fall back to ggside_panel_background, then to panel_background, so by default a side panel looks like the main one. The background's border color and size frame the side panel the way they frame the main panel: ggside_panel_background=element_rect(size=0) keeps the fill and drops the frame, element_blank() drops both. ggmarginal() margins draw neither.

  • ggside_panel_border (ThemeElement | None, default: None ) –

    Border of the ggside side panels, drawn over their layers, as R ggside's ggside.panel.border, with the same suffix and fallback rules (last panel_border). ggside_panel_border=element_blank() keeps the main panel's border and drops the side panels' ones. Under coord_flip() the _xside_ and _yside_ elements follow their aesthetic, as the ggside_axis_* ones do.

  • ggside_ (ThemeElement | None, default: None ) –

    Border of the ggside side panels, drawn over their layers, as R ggside's ggside.panel.border, with the same suffix and fallback rules (last panel_border). ggside_panel_border=element_blank() keeps the main panel's border and drops the side panels' ones. Under coord_flip() the _xside_ and _yside_ elements follow their aesthetic, as the ggside_axis_* ones do.

  • ggside_axis_text (ThemeElement | None, default: None ) –

    Tick labels of a side panel's own axis, as R ggside's ggside.axis.text*. Suffixes: _x, _x_top, _x_bottom, _y, _y_left, _y_right (the same for every ggside_axis_* element). _y styles only the x side panel's (y) axis and _x only the y side panel's (x) axis; _top, _bottom, _left, _right pick the axis drawn on that side. The most specific one set wins, and anything unset comes from the main axis_text* elements, so the main axes never change. ggside_axis_text_y=element_blank() hides the x side panel's track names and frees their room. Under coord_flip() the elements follow their aesthetic, as the main axis_* ones do.

  • ggside_axis_text_ (ThemeElement | None, default: None ) –

    Tick labels of a side panel's own axis, as R ggside's ggside.axis.text*. Suffixes: _x, _x_top, _x_bottom, _y, _y_left, _y_right (the same for every ggside_axis_* element). _y styles only the x side panel's (y) axis and _x only the y side panel's (x) axis; _top, _bottom, _left, _right pick the axis drawn on that side. The most specific one set wins, and anything unset comes from the main axis_text* elements, so the main axes never change. ggside_axis_text_y=element_blank() hides the x side panel's track names and frees their room. Under coord_flip() the elements follow their aesthetic, as the main axis_* ones do.

  • ggside_axis_ticks (ThemeElement | None, default: None ) –

    Ticks of a side panel's own axis (element_line()), with the same suffix rules; unset ones come from axis_ticks*.

  • ggside_axis_ticks_ (ThemeElement | None, default: None ) –

    Ticks of a side panel's own axis (element_line()), with the same suffix rules; unset ones come from axis_ticks*.

  • ggside_axis_ticks_length (Number | None, default: None ) –

    Tick length of a side panel's own axis, in pixels; unset ones come from axis_ticks_length*.

  • ggside_axis_ticks_length_ (Number | None, default: None ) –

    Tick length of a side panel's own axis, in pixels; unset ones come from axis_ticks_length*.

  • ggside_axis_minor_ticks (ThemeElement | None, default: None ) –

    Minor ticks of a side panel's own axis; unset ones come from axis_minor_ticks*.

  • ggside_axis_minor_ticks_ (ThemeElement | None, default: None ) –

    Minor ticks of a side panel's own axis; unset ones come from axis_minor_ticks*.

  • ggside_axis_minor_ticks_length (Number | None, default: None ) –

    Minor tick length of a side panel's own axis, in pixels; unset ones come from axis_minor_ticks_length*.

  • ggside_axis_minor_ticks_length_ (Number | None, default: None ) –

    Minor tick length of a side panel's own axis, in pixels; unset ones come from axis_minor_ticks_length*.

  • ggside_axis_line (ThemeElement | None, default: None ) –

    Axis line of a side panel's own axis (element_line(), with arrow and extent as on axis_line); unset ones come from axis_line*.

  • ggside_axis_line_ (ThemeElement | None, default: None ) –

    Axis line of a side panel's own axis (element_line(), with arrow and extent as on axis_line); unset ones come from axis_line*.

  • legendry_bracket (dict or str, default: None ) –

    Bracket line of guide_axis_nested() (element_line()), as R legendry's legendry.bracket; unset, it comes from line.

  • legendry_bracket_size (float, default: None ) –

    Room a bracket takes across its axis, in pixels (legendry's 2 mm: 7.56).

  • legendry_box (dict or str, default: None ) –

    Box of guide_axis_nested(type="box") (element_rect()), as legendry's legendry.box; unset, it comes from rect (legendry inherits strip.background, blank in the lets-plot themes).

  • legendry_guide_spacing (float, default: None ) –

    Gap between an axis's labels and its nested guide, in pixels (0, as in legendry's guide_axis_nested()).

  • legend_box_just (str, default: None ) –

    Justification of the legends within their box.

  • legend_box_spacing (float, default: None ) –

    Space between the plot panel and the legend box, in pixels.

  • legend_ticks (dict or str, default: None ) –

    Ticks of the color bar (element_line()).

  • legend_ticks_length (float or (float, float), default: None ) –

    Length of the color bar ticks, in pixels (default 4). Two numbers set the bottom (vertical bar: right) and top (left) edge apart, as ggplot2 3.5: positive values point into the bar, negative ones out of it, 0 draws none. [-5, 0] gives matplotlib-style ticks outside the bar on the label side; the labels move out to make room. Minor ticks are half as long.

  • legend_frame (dict or str, default: None ) –

    Outline of the color bar (element_rect(); its color, size and linetype, the fill is not drawn), around the triangle caps too (ggplot2 3.5 legend.frame). Unset: no outline, as lets-plot.

  • legend_interactive (bool, default: None ) –

    ggrust extension, HTML output only. Clickable discrete legend keys: click hides or shows a key's marks, double-click isolates the key. False turns it off and leaves the key data out of the HTML. On by default.

  • panel_background (dict or str, default: None ) –

    Panel background and border (element_rect()).

  • panel_border (dict or str, default: None ) –

    Panel background and border (element_rect()).

  • panel_border_ontop (bool, default: None ) –

    True draws the border over the plot layers.

  • panel_grid (dict or str, default: None ) –

    Grid lines (element_line()).

  • panel_grid_major (dict or str, default: None ) –

    Grid lines (element_line()).

  • panel_grid_minor (dict or str, default: None ) –

    Grid lines (element_line()).

  • panel_grid_major_x (dict or str, default: None ) –

    Grid lines of the x axis.

  • panel_grid_minor_x (dict or str, default: None ) –

    Grid lines of the x axis.

  • panel_grid_major_y (dict or str, default: None ) –

    Grid lines of the y axis.

  • panel_grid_minor_y (dict or str, default: None ) –

    Grid lines of the y axis.

  • panel_grid_ontop (bool, default: None ) –

    True draws the grid over the plot layers.

  • panel_grid_ontop_x (bool, default: None ) –

    True draws the grid over the plot layers.

  • panel_grid_ontop_y (bool, default: None ) –

    True draws the grid over the plot layers.

  • panel_inset (float or list of float, default: None ) –

    Inner margins of the panel, in pixels.

  • plot_background (dict or str, default: None ) –

    Background of the whole plot (element_rect()).

  • plot_title (dict or str, default: None ) –

    Title, subtitle, caption and tag texts (element_text()).

  • plot_subtitle (dict or str, default: None ) –

    Title, subtitle, caption and tag texts (element_text()).

  • plot_caption (dict or str, default: None ) –

    Title, subtitle, caption and tag texts (element_text()).

  • plot_tag (dict or str, default: None ) –

    Title, subtitle, caption and tag texts (element_text()).

  • plot_message (dict or str, default: None ) –

    Messages shown on the plot (lets_plot); "blank" hides them.

  • plot_margin (float or list of float, default: None ) –

    Outer and inner margins of the plot, in pixels.

  • plot_inset (float or list of float, default: None ) –

    Outer and inner margins of the plot, in pixels.

  • plot_title_position ((panel, plot), default: "panel" ) –

    Align the title or caption with the panel or with the whole plot.

  • plot_caption_position ((panel, plot), default: "panel" ) –

    Align the title or caption with the panel or with the whole plot.

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

    Where the tag goes: a side name such as "topleft", or [x, y].

  • plot_tag_location (str, default: None ) –

    What the tag position is relative to: "panel", "plot" or "margin".

  • plot_tag_prefix (str, default: None ) –

    Text added before and after the tag.

  • plot_tag_suffix (str, default: None ) –

    Text added before and after the tag.

  • strip_background (dict or str, default: None ) –

    Facet strip backgrounds (element_rect()).

  • strip_background_x (dict or str, default: None ) –

    Facet strip backgrounds (element_rect()).

  • strip_background_y (dict or str, default: None ) –

    Facet strip backgrounds (element_rect()).

  • strip_text (dict or str, default: None ) –

    Facet strip texts (element_text()).

  • strip_text_x (dict or str, default: None ) –

    Facet strip texts (element_text()).

  • strip_text_y (dict or str, default: None ) –

    Facet strip texts (element_text()).

  • strip_spacing (float, default: None ) –

    Space between the strips and the panels, in pixels.

  • strip_spacing_x (float, default: None ) –

    Space between the strips and the panels, in pixels.

  • strip_spacing_y (float, default: None ) –

    Space between the strips and the panels, in pixels.

  • panel_spacing (float, default: None ) –

    Space between facet panels, in pixels.

  • panel_spacing_x (float, default: None ) –

    Space between facet panels, in pixels.

  • panel_spacing_y (float, default: None ) –

    Space between facet panels, in pixels.

  • axis_tooltip (dict or str, default: None ) –

    Axis tooltips of HTML output (element_rect()).

  • axis_tooltip_x (dict or str, default: None ) –

    Axis tooltips of HTML output (element_rect()).

  • axis_tooltip_y (dict or str, default: None ) –

    Axis tooltips of HTML output (element_rect()).

  • axis_tooltip_text (dict or str, default: None ) –

    Text of the axis tooltips (element_text()).

  • axis_tooltip_text_x (dict or str, default: None ) –

    Text of the axis tooltips (element_text()).

  • axis_tooltip_text_y (dict or str, default: None ) –

    Text of the axis tooltips (element_text()).

  • tooltip (dict or str, default: None ) –

    Tooltip box, text and title text of HTML output.

  • tooltip_text (dict or str, default: None ) –

    Tooltip box, text and title text of HTML output.

  • tooltip_title_text (dict or str, default: None ) –

    Tooltip box, text and title text of HTML output.

  • tooltip_merge (bool, default: None ) –

    lets_plot's tooltip merging option.

  • tooltip_max_count (int, default: None ) –

    Maximum number of tooltips shown at once.

  • label_text (dict or str, default: None ) –

    Text of layer_labels() annotations (element_text()). ggrust does not draw annotations yet, so it is reported as unsupported.

  • geom (dict, default: None ) –

    Default geom colors, from element_geom().

Returns:

  • FeatureSpec –

    The theme feature.

Examples:

>>> from ggrust import *
>>> data = {"age": [1, 3, 5, 7, 2, 4, 6, 8, 3, 9],
...         "weight": [4, 6, 6, 7, 8, 12, 14, 15, 2, 3],
...         "pet": ["cat"] * 4 + ["dog"] * 4 + ["rabbit"] * 2}
>>> plot = ggplot(data, aes("age", "weight", color="pet")) + geom_point(size=5)
>>> plot = plot + theme(
...     legend_position="bottom",
...     axis_title=element_text(size=15, face="bold"),
...     panel_grid_minor=element_blank(),
... )

Title, subtitle and axis text:

>>> base = ggplot(data, aes("age", "weight", color="pet")) + geom_point(size=5)
>>> plot = base + ggtitle("Pets", "weight by age") + theme(
...     plot_title=element_text(size=20, face="bold", hjust=0.5),
...     plot_subtitle=element_text(color="grey", hjust=0.5),
...     axis_text=element_text(size=12, color="black"),
... )

The legend inside the panel, in its top left corner:

>>> plot = base + theme(
...     legend_position=[0.02, 0.98],
...     legend_justification=[0, 1],
...     legend_background=element_rect(fill="white", color="grey", size=1),
... )

Panel, grid and axis lines:

>>> plot = base + theme(
...     panel_background=element_rect(fill="aliceblue", color="aliceblue"),
...     panel_grid=element_line(color="white", size=1.5),
...     axis_line_x=element_line(color="black", size=1),
...     axis_line_y=element_line(color="black", size=1),
...     axis_ticks=element_line(color="black"),
...     axis_ticks_length=8,
... )

theme_void

theme_void() -> FeatureSpec

Use the classic theme without lines and axes.

Returns:

  • FeatureSpec –

    The theme.

Examples:

>>> from ggrust import *
>>> data = {"age": [1, 3, 5, 7, 2, 4, 6, 8, 3, 9],
...         "weight": [4, 6, 6, 7, 8, 12, 14, 15, 2, 3],
...         "pet": ["cat"] * 4 + ["dog"] * 4 + ["rabbit"] * 2}
>>> plot = ggplot(data, aes("age", "weight", color="pet")) + geom_point(size=5)
>>> plot = plot + theme_void()

The defaults, from the data alone (geoms are guessed from the column types)

One geom for every score, without column groups and with the legend on the right