API reference¶

ggrust follows lets-plot's Python API. Every public name is listed here by topic; open one for its parameters and examples. The usual import is

from ggrust import *

Missing something you use from lets-plot? Open a feature request

Plotting¶

Start a plot, map columns to aesthetics, and work with the plot object.

Name	Description
`ggplot()`	Create a new plot.
`aes()`	Define aesthetic mappings.
`layer()`	Create a layer from a geom name, stat, data, mapping and position.
`ggsize()`	Set the plot size in pixels.
`as_discrete()`	Use a discrete scale for a mapped column, optionally ordering its values.
`PlotSpec`	A plot: data, mapping, layers, scales and features. Build it with `ggplot()`.

Geometries¶

Layers that draw data. Each one sets a geom, a default stat and a position.

Name	Description
`geom_point()`	Scatter points.
`geom_jitter()`	Points with random noise added to their positions. Not drawn yet.
`geom_sina()`	Sina plot: points spread within the violin outline.
`geom_line()`	Connect observations sorted by x.
`geom_path()`	Connect observations in data order.
`geom_segment()`	Line segments from (x, y) to (xend, yend), optionally with arrows.
`geom_hline()`	Horizontal reference lines at `yintercept`.
`geom_vline()`	Vertical reference lines at `xintercept`.
`geom_function()`	Evaluate `fun` at x values and draw the result.
`geom_area()`	Fill the area under a line, stacked by default (`position="stack"`).
`geom_ribbon()`	Fill the band between ymin and ymax along x.
`geom_area_ridges()`	Ridgeline plot: one density curve per y level. Not drawn yet.
`geom_polygon()`	Draw filled polygons, one per group.
`geom_rect()`	Rectangles from `xmin`, `xmax`, `ymin`, `ymax`. Not drawn yet.
`geom_bar()`	Bars, by default the count of rows per x (`stat="count"`), stacked.
`geom_histogram()`	Histogram of binned x values (`stat="bin"`), stacked.
`geom_boxplot()`	Box and whiskers plot, dodged by group.
`geom_violin()`	Violin plot: mirrored kernel density per x (`stat="ydensity"`). Not drawn yet.
`geom_errorbar()`	Error bars from ymin to ymax at x, with fences `width` wide (default 0.45).
`geom_crossbar()`	Boxes from ymin to ymax at x with a midline at y, dodged by group.
`geom_linerange()`	Draw a vertical line from ymin to ymax at x.
`geom_pointrange()`	Draw a vertical line from ymin to ymax at x with a point at y.
`geom_tile()`	Rectangles centred on (x, y), e.g. heatmap cells. Not drawn yet.
`geom_raster()`	Equal-sized tiles on a regular grid. Not drawn yet.
`geom_imshow()`	Display an image array, as lets_plot `geom_imshow`.
`geom_text()`	Text labels at (x, y); the text comes from the `label` aesthetic.
`geom_label()`	Text labels in a rounded box at (x, y).
`geom_text_repel()`	Text labels pushed apart so they do not overlap each other or the points.
`geom_label_repel()`	Boxed text labels pushed apart so they do not overlap each other or the points.
`geom_bracket()`	Labelled brackets from `xmin` to `xmax` at height `y` (significance marks).
`geom_blank()`	Draw nothing; the mapped data still trains the scales. No tooltips (as lets_plot).
`arrow()`	Describe the arrow heads of a line (`geom_segment`, `geom_path`).

Positions¶

Arrange marks that would overlap.

Name	Description
`position_dodge()`	Place overlapping objects side by side.
`position_jitter()`	Add random noise to positions.
`position_jitterdodge()`	Dodge, then jitter (points over dodged boxplots).
`position_nudge()`	Shift positions by a fixed offset.
`position_stack()`	Stack overlapping objects on top of each other.
`position_fill()`	Stack overlapping objects and normalise each stack to height 1.

Position scales¶

Axes: breaks, labels, limits and transforms.

Name	Description
`scale_x_continuous()`	Continuous position scale x.
`scale_y_continuous()`	Continuous position scale y. See `scale_x_continuous`.
`scale_x_discrete()`	Discrete position scale x.
`scale_y_discrete()`	Discrete position scale y. See `scale_x_discrete`.
`scale_x_discrete_reversed()`	`scale_x_discrete(reverse=True)`.
`scale_y_discrete_reversed()`	`scale_y_discrete(reverse=True)`.
`scale_x_log10()`	Continuous position scale x with the 'log10' transformation. See `scale_x_continuous`.
`scale_y_log10()`	Continuous position scale y with the 'log10' transformation. See `scale_y_continuous`.
`scale_x_log2()`	Continuous position scale x with the 'log2' transformation. See `scale_x_continuous`.
`scale_y_log2()`	Continuous position scale y with the 'log2' transformation. See `scale_y_continuous`.
`scale_x_reverse()`	Continuous position scale x with the 'reverse' transformation. See `scale_x_continuous`.
`scale_y_reverse()`	Continuous position scale y with the 'reverse' transformation. See `scale_y_continuous`.
`lims()`	Limits for both axes: `xlim(x) + ylim(y)`.
`xlim()`	Limits of the x axis, e.g. `xlim(0, 10)`, `xlim(None, 10)` or `xlim("B", "T")`.
`ylim()`	Limits of the y axis. See `xlim`.

Color scales¶

Map data to color (lines, points, text) and fill (areas).

Name	Description
`scale_color_continuous()`	Map `color` continuously: a gradient unless `scale_mapper_kind` says otherwise.
`scale_color_gradient()`	Map `color` to a two-color gradient (in LAB space).
`scale_color_gradient2()`	Map `color` to a diverging gradient around `midpoint` (continuous data only).
`scale_color_gradientn()`	Map `color` to a gradient through several colors, evenly spaced over the data.
`scale_color_viridis()`	Map `color` with a viridis-family color map.
`scale_color_brewer()`	Map `color` with a ColorBrewer palette.
`scale_color_hue()`	Qualitative colors evenly spaced around the HCL color wheel, for `color`.
`scale_color_manual()`	Your own colors for `color`.
`scale_color_identity()`	Use the data as colors (names or hex codes); no legend by default.
`scale_fill_continuous()`	Map `fill` continuously. See `scale_color_continuous`.
`scale_fill_gradient()`	Map `fill` to a two-color gradient. See `scale_color_gradient`.
`scale_fill_gradient2()`	Map `fill` to a diverging gradient. See `scale_color_gradient2`.
`scale_fill_gradientn()`	Map `fill` to a gradient through several colors. See `scale_color_gradientn`.
`scale_fill_viridis()`	Map `fill` with a viridis-family color map. See `scale_color_viridis`.
`scale_fill_brewer()`	Map `fill` with a ColorBrewer palette. See `scale_color_brewer`.
`scale_fill_hue()`	Qualitative colors evenly spaced around the HCL color wheel, for `fill`.
`scale_fill_manual()`	Your own colors for `fill`.
`scale_fill_identity()`	Use the data as fill colors; no legend by default.

Size, shape and alpha scales¶

Map data to point size, point shape and transparency.

Name	Description
`scale_size()`	Sizes for `size`: data mapped linearly onto `range`.
`scale_size_area()`	Sizes whose circle area is proportional to the data.
`scale_size_manual()`	Your own sizes for `size`, matched in order with the categories (or a dict).
`scale_size_identity()`	Use the data as sizes; no legend by default.
`scale_shape()`	Point shapes for categories.
`scale_shape_manual()`	Your own point shapes (lets-plot codes 0..25) for `shape`.
`scale_shape_identity()`	Use the data as shape codes (0..25); no legend by default.
`scale_alpha()`	Transparency for `alpha`: data mapped linearly onto `range`.
`scale_alpha_manual()`	Your own alphas for `alpha`, matched in order with the categories (or a dict).
`scale_alpha_identity()`	Use the data as alphas; no legend by default.

Coordinate systems, and small multiples.

Name	Description
`coord_cartesian()`	Cartesian coordinates; limits zoom without dropping data.
`coord_fixed()`	Cartesian coordinates with a fixed aspect ratio.
`coord_flip()`	Swap the x and y axes (not drawn yet; ggrust warns and keeps them).
`facet_wrap()`	Wrap one panel per level of `facets` into rows.
`facet_grid()`	Lay panels out in a grid: columns by `x`, rows by `y`.

Labels and guides¶

Titles, axis labels and legends.

Name	Description
`labs()`	Set the title, subtitle, caption, tag and axis or legend titles.
`ggtitle()`	Set the plot title and subtitle.
`xlab()`	Set the x axis title.
`ylab()`	Set the y axis title.
`guides()`	Set guides (legends, colorbars) per aesthetic.
`guide_legend()`	Show a key legend for an aesthetic.
`guide_colorbar()`	Show a colorbar for a continuous color or fill scale.

Themes¶

Complete themes, and theme() to change single elements.

Name	Description
`theme()`	Set theme options: element_*() values, numbers or names per theme element.
`theme_grey()`	Use the grey background theme.
`theme_gray()`	Use the grey background theme (alias of `theme_grey`).
`theme_classic()`	Use the classic theme: axis lines, no grid.
`theme_minimal()`	Use the minimal theme.
`theme_minimal2()`	Use lets-plot's default theme.
`theme_bw()`	Use the black-and-white theme.
`theme_light()`	Use the light theme.
`theme_void()`	Use the classic theme without lines and axes.
`theme_none()`	Use the unstyled theme.

Theme elements and flavors¶

Building blocks for theme(), and color flavors for any theme.

Name	Description
`element_text()`	Style text.
`element_line()`	Style a line (axis lines, ticks, grid).
`element_rect()`	Style a rectangle (backgrounds, borders).
`element_blank()`	Hide a theme element.
`element_geom()`	Set default geom colors.
`element_markdown()`	Style text written in Markdown (drawn as plain text by ggrust).
`margin()`	Return margins `[top, right, bottom, left]` (deprecated in lets_plot).
`flavor_standard()`	Use the standard color flavor of the theme.
`flavor_darcula()`	Use the Darcula color flavor.
`flavor_solarized_light()`	Use the Solarized light color flavor.
`flavor_solarized_dark()`	Use the Solarized dark color flavor.
`flavor_high_contrast_light()`	Use the high-contrast light color flavor.
`flavor_high_contrast_dark()`	Use the high-contrast dark color flavor.

Grids and interactivity¶

Combine plots into one figure, and configure tooltips and the zoom/pan toolbar.

Name	Description
`gggrid()`	Combine plots into a grid.
`SupPlotsSpec`	Several plots in one figure. Build it with `gggrid()`.
`GGBunch`	lets_plot's deprecated free-layout bunch of plots. Not supported; use `gggrid`.
`layer_tooltips()`	Configure hover tooltips.
`ggtb()`	Add the zoom/pan toolbar to an HTML plot.

Export and setup¶

Write files, and lets-plot compatibility helpers.

Name	Description
`ggsave()`	Save a plot to `path/filename`; the extension picks the format.
`LetsPlot`	lets_plot's global settings object. ggrust needs no setup; calls are accepted.
`engine_version`	Return the version of the Rust engine.

Errors and warnings¶

Every error ggrust raises is a GgrustError and the builtin that matches the problem, so except ValueError (as with lets_plot) keeps working. Errors from the engine carry where they happened: SpecError.path is the spec path of the bad value ("layers[0].size"), and ColumnNotFoundError lists the available columns and suggests a close name.

from ggrust.errors import ColumnNotFoundError

try:
    plot.to_svg()
except ColumnNotFoundError as error:
    print(error.column, error.path, error.available)

Name	Description
`GgrustWarning`	Something in the plot was ignored or adjusted; the message says what and where.
`GgrustError`	Base class of every ggrust error.
`SpecError`	Raised when the plot specification holds an invalid value.
`UnsupportedValueError`	Raised when a spec holds a value of a type the engine cannot receive.
`DataError`	Raised when the plot data cannot be read (malformed or inconsistent columns).
`ColumnNotFoundError`	Raised when a mapping refers to a column that is not in the data.
`UnsupportedColumnTypeError`	Raised when a mapped column has a type ggrust cannot plot.
`UnsupportedDataError`	Raised when the data object is not a kind ggrust reads (e.g. a Series).
`RenderError`	Raised when drawing the output fails, e.g. for an image too large to allocate.
`ExportError`	Raised when export options are invalid (file name, unit, size, dpi, scale).