Aesthetic Mappings

This notebook adapts the plotnine guide on aesthetic mappings to the fluent API style.

import polars as pl
from plotnine import aes, ggplot
from plotnine.data import penguins

Setup

penguins = pl.from_pandas(penguins)
penguins.head()

shape: (5, 8)

species	island	bill_length_mm	bill_depth_mm	flipper_length_mm	body_mass_g	sex	year
cat	cat	f64	f64	f64	f64	cat	i64
"Adelie"	"Torgersen"	39.1	18.7	181.0	3750.0	"male"	2007
"Adelie"	"Torgersen"	39.5	17.4	186.0	3800.0	"female"	2007
"Adelie"	"Torgersen"	40.3	18.0	195.0	3250.0	"female"	2007
"Adelie"	"Torgersen"	null	null	null	null	null	2007
"Adelie"	"Torgersen"	36.7	19.3	193.0	3450.0	"female"	2007

Basics

The simplest mapping sends columns to the x- and y-axes at the plot level.

(
    ggplot(penguins)
    .aes(x="flipper_length_mm", y="body_mass_g")
    .geom_point()
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.

Variable Mappings

Color

(
    ggplot(penguins)
    .aes(x="flipper_length_mm", y="body_mass_g", color="species")
    .geom_point()
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.

Shape

(
    ggplot(penguins)
    .aes(x="flipper_length_mm", y="body_mass_g", shape="species")
    .geom_point()
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.

Size and Alpha

(
    ggplot(penguins)
    .aes(
        x="flipper_length_mm",
        y="body_mass_g",
        size="body_mass_g",
        alpha="body_mass_g",
    )
    .geom_point()
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.

Literal Mappings

Literal values are set directly on the geom, not inside aes().

(
    ggplot(penguins)
    .aes(x="flipper_length_mm", y="body_mass_g")
    .geom_point(size=7, alpha=0.5, color="purple")
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.

aes() Inside a Specific Geom

Layer-local mappings apply to only that geom.

(
    ggplot(penguins)
    .aes(x="flipper_length_mm", y="body_mass_g")
    .geom_point(aes(color="species"), size=5)
    .geom_point(aes(shape="species"))
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.
/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.

Collective Groupings

Explicit Grouping

(
    ggplot(penguins)
    .aes(x="flipper_length_mm", y="body_mass_g", group="species")
    .geom_point()
    .geom_smooth(method="lm")
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.

Automatic Grouping Through Color

(
    ggplot(penguins)
    .aes(x="flipper_length_mm", y="body_mass_g", color="species")
    .geom_point()
    .geom_smooth(method="lm")
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.

Working Around Automatic Grouping

(
    ggplot(penguins)
    .aes(x="flipper_length_mm", y="body_mass_g")
    .geom_point(aes(color="species"))
    .geom_smooth(method="lm")
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.

Mappings With Expressions

Mappings in aes() can also be expressions.

(
    ggplot(penguins)
    .aes(x="bill_length_mm / bill_depth_mm", y="body_mass_g")
    .geom_point(aes(color="species"))
)

/Users/iangow/git/plotnine-fluid/.venv/lib/python3.14/site-packages/plotnine/layer.py:419: PlotnineWarning: geom_point : Removed 2 rows containing missing values.