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
idcolumn. 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_colorandid_size(columns giving the color and the size, defaultid), andoptions: 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": Nonedraws 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:
idand an optionalgroup. 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:
groupand 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
datahas noidcolumn, orcolumn_infonames 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 aposition_*()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 intn(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
colorscale applies to ("color"or"fill"). -
fill_by(str, default:None) –Aesthetic the
fillscale 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"orsize=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 aposition_*()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 intn(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
colorscale applies to ("color"or"fill"). -
fill_by(str, default:None) –Aesthetic the
fillscale 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 aposition_*()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 intn(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_endandstroke_start/stroke_endpadding. -
color_by(str, default:None) –Aesthetic the
colorscale 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"orsize=2, and the geom's options. As in lets_plot; options ggrust does not read yet are reported as not supported.size_start/size_endandstroke_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 aposition_*()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 intn(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 ofsize=1(2.2 px), or pixels. A positivenudge_yin"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"orsize=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:
-
PositionArguments–The settings, for
funky_heatmap(position_args=...).
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 aguide_*()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 aguide_*()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^6as 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 (Nonekeeps 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 takearrowandextentfor arrow-headed, truncated axes. -
axis_line_x(dict or str, default:None) –Axis lines (
element_line()); they also takearrowandextentfor arrow-headed, truncated axes. -
axis_line_y(dict or str, default:None) –Axis lines (
element_line()); they also takearrowandextentfor 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 atlegend_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"andguide_*(position="inside"). None useslegend_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'shjustplaces both the title and the keys across the legend width (0 left, 0.5 centred); left or right, itsvjustplaces 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:_xthe x side panel's height,_ythe 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:_xthe x side panel's height,_ythe 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:_xthe x side panel's height,_ythe 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:
_xbeside a y side panel,_ybeside 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:
_xbeside a y side panel,_ybeside 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:
_xbeside a y side panel,_ybeside 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'sggside.panel.background:ggside_xside_panel_backgroundstyles the x side panels (above or below),ggside_yside_panel_backgroundthe y side panels (left or right). Unset ones fall back toggside_panel_background, then topanel_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'sggside.panel.background:ggside_xside_panel_backgroundstyles the x side panels (above or below),ggside_yside_panel_backgroundthe y side panels (left or right). Unset ones fall back toggside_panel_background, then topanel_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 (lastpanel_border).ggside_panel_border=element_blank()keeps the main panel's border and drops the side panels' ones. Undercoord_flip()the_xside_and_yside_elements follow their aesthetic, as theggside_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 (lastpanel_border).ggside_panel_border=element_blank()keeps the main panel's border and drops the side panels' ones. Undercoord_flip()the_xside_and_yside_elements follow their aesthetic, as theggside_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 everyggside_axis_*element)._ystyles only the x side panel's (y) axis and_xonly the y side panel's (x) axis;_top,_bottom,_left,_rightpick the axis drawn on that side. The most specific one set wins, and anything unset comes from the mainaxis_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. Undercoord_flip()the elements follow their aesthetic, as the mainaxis_*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 everyggside_axis_*element)._ystyles only the x side panel's (y) axis and_xonly the y side panel's (x) axis;_top,_bottom,_left,_rightpick the axis drawn on that side. The most specific one set wins, and anything unset comes from the mainaxis_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. Undercoord_flip()the elements follow their aesthetic, as the mainaxis_*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 fromaxis_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 fromaxis_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(), witharrowandextentas onaxis_line); unset ones come fromaxis_line*. -
ggside_axis_line_(ThemeElement | None, default:None) –Axis line of a side panel's own axis (
element_line(), witharrowandextentas onaxis_line); unset ones come fromaxis_line*. -
legendry_bracket(dict or str, default:None) –Bracket line of
guide_axis_nested()(element_line()), as R legendry'slegendry.bracket; unset, it comes fromline. -
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'slegendry.box; unset, it comes fromrect(legendry inheritsstrip.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(); itscolor,sizeandlinetype, the fill is not drawn), around the triangle caps too (ggplot2 3.5legend.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.
Falseturns 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