Skip to content

Layers

A layer is a geom (the shape that is drawn), a stat (what is computed from the data first) and a position (how overlapping shapes are arranged). The geom_* functions set all three with sensible defaults.

Stacking layers

Layers are drawn in the order they are added. Here a boxplot summarises each transport mode, and a jitter layer draws every commuter on top of it.

import polars as pl
from ggrust import *

DATA = "https://raw.githubusercontent.com/datavil/ggrust/main/docs/data/"
commute = pl.read_csv(DATA + "commute.csv")

plot = (
    ggplot(commute, aes("mode", "minutes"))
    + geom_boxplot(outlier_alpha=0, width=0.6)
    + geom_jitter(aes(color="mode"), width=0.25, size=1.2, alpha=0.4)
    + labs(x="", y="Commute (minutes)")
    + theme_classic()
    + theme(legend_position="none")
    + ggsize(600, 400)
)
plot

A mapping given to ggplot() is shared by every layer. A mapping given to a layer, like aes(color="mode") above, applies to that layer only.

Stats

geom_histogram uses the bin stat: it counts rows in bins and draws one bar per bin.

import polars as pl
from ggrust import *

DATA = "https://raw.githubusercontent.com/datavil/ggrust/main/docs/data/"
commute = pl.read_csv(DATA + "commute.csv")

plot = (
    ggplot(commute, aes("minutes", fill="mode"))
    + geom_histogram(bins=40, color="white", size=0.2)
    + scale_fill_brewer(palette="Dark2")
    + labs(x="Commute (minutes)", y="People", fill="Mode")
    + ggsize(640, 380)
)
plot

When the data already holds the values to draw, use stat="identity". Here each row is a number of cups:

import polars as pl
from ggrust import *

DATA = "https://raw.githubusercontent.com/datavil/ggrust/main/docs/data/"
coffee = pl.read_csv(DATA + "coffee.csv")

plot = (
    ggplot(coffee, aes("weekday", "cups", fill="drink"))
    + geom_bar(stat="identity", width=0.7)
    + scale_fill_brewer(palette="Set2")
    + labs(x="", y="Cups sold", fill="Drink")
    + ggsize(600, 380)
)
plot

Positions

Bars that share an x value are stacked by default. position="dodge" puts them side by side instead; "fill" stacks them to 100 percent. position_dodge(width=...), position_jitter(...) and position_nudge(...) take parameters.

import polars as pl
from ggrust import *

DATA = "https://raw.githubusercontent.com/datavil/ggrust/main/docs/data/"
coffee = pl.read_csv(DATA + "coffee.csv").filter(pl.col("weekday").is_in(["Mon", "Wed", "Sat"]))

plot = (
    ggplot(coffee, aes("drink", "cups", fill="weekday"))
    + geom_bar(stat="identity", position="dodge", width=0.8)
    + coord_flip()
    + scale_fill_manual(values=["#264653", "#2a9d8f", "#e9c46a"])
    + labs(x="", y="Cups sold", fill="Day")
    + theme_light()
    + ggsize(600, 380)
)
plot

Available geoms

Kind Geoms
Points geom_point, geom_jitter, geom_sina
Lines geom_line, geom_path, geom_segment, geom_hline, geom_vline, geom_function
Areas geom_area, geom_ribbon, geom_area_ridges, geom_polygon, geom_rect
Bars geom_bar, geom_histogram
Distributions geom_boxplot, geom_violin
Ranges geom_errorbar, geom_crossbar, geom_linerange, geom_pointrange
Tiles and images geom_tile, geom_raster, geom_imshow
Text geom_text, geom_label, geom_text_repel, geom_label_repel, geom_bracket

Each one is documented, with every parameter, in the API reference.