Plotnine

plotnine

> This skill targets plotnine 0.15+ with pandas 2.x.

Behavioral Rules

1. Runnability — all generated code is executable as-is. Include imports,

data loading, and the full ggplot expression. No pseudocode, no ... elisions, no undefined variables.

1. Idiomatic plotnine — use + layering, aes(), theme_*, labs(),

scale_*. Never fall back to matplotlib. If plotnine cannot achieve the result, propose the closest plotnine-idiomatic alternative and explain the limitation.

1. Data completeness — generated code must include all data needed to run:

inline pd.DataFrame() construction, plotnine.data datasets, or clearly referenced from the user's existing context. Never reference undefined DataFrames.

1. Minimal transformations — prefer simple pandas ops (groupby, agg,

melt) or polars equivalents. Prefer plotnine stat_*/position_* over manual aggregation when possible.

1. Accessibility — always provide descriptive axis labels via labs() and

clear legend titles. When the user requests accessible colors, recommend colorblind-safe palettes (Set2, viridis, Okabe-Ito). Provide alt-text guidance when asked.

1. Reproducibility — use random_state=42 for any plotnine method that

accepts it (e.g., DataFrame.sample()). Seed synthetic data with numpy.random.default_rng(42).

When to Use What

Task: Create a basic plot (scatter, bar, line, histogram, boxplot) Use: "Plotnine Essentials" below, then [references/geoms.md](references/geoms.md)

Task: Map variables to visual properties or customize scales Use: [references/aesthetics-and-scales.md](references/aesthetics-and-scales.md)

Task: Customize appearance (fonts, backgrounds, gridlines, themes) Use: [references/themes-and-styling.md](references/themes-and-styling.md)

Task: Choose accessible colors or palettes Use: [references/color-and-accessibility.md](references/color-and-accessibility.md)

Task: Reshape or prepare data for a specific chart Use: [references/data-preparation.md](references/data-preparation.md)

Task: Revise an existing plot (iterative refinement) Use: [references/iterative-refinement.md](references/iterative-refinement.md)

Task: Create small multiples / faceted plots Use: [references/facets.md](references/facets.md)

Task: Add titles, subtitles, annotations, labels Use: [references/labels-and-annotations.md](references/labels-and-annotations.md)

Task: Add trend lines, smoothers, statistical summaries Use: [references/statistical-layers.md](references/statistical-layers.md)

Task: Adjust axes, coordinates, transforms Use: [references/coords-and-axes.md](references/coords-and-axes.md)

Task: Save / export a figure Use: [references/saving-and-export.md](references/saving-and-export.md)

Task: Combine multiple plots side-by-side or stacked Use: [references/composition.md](references/composition.md)

Task: Plot geographic / map data Use: [references/maps.md](references/maps.md)

Task: Specify literal aesthetic values (colors, linetypes, shapes, fonts) Use: [references/aesthetic-specification.md](references/aesthetic-specification.md)

Task: Look up a specific symbol's parameters, types, or defaults Use: references/api/.md (e.g. [references/api/geompoint.md](references/api/geompoint.md)). British-spelling aliases (scale_colour_*) and 2d-suffix aliases (geom_bin2d, stat_bin2d) redirect to the canonical spelling.

Decision Trees

Natural-language routing for when a user's question doesn't map cleanly onto the task table above. Every leaf points to a reference file.

I need to show …

Show what?
├─ one variable's distribution         → references/geoms.md (histogram, density, boxplot)
├─ relationship between two variables  → references/geoms.md (point, smooth)
│                                        + references/statistical-layers.md for trend lines
├─ a categorical breakdown             → references/geoms.md (bar, col)
├─ change over time                    → references/geoms.md (line, area)
├─ geographic / spatial data           → references/maps.md
├─ group comparison                    → references/geoms.md (violin, boxplot)
│                                        + references/facets.md for small multiples
└─ counts / proportions / heatmap      → references/geoms.md (bar, tile)

I need to customize …

Customize what?
├─ colors / palettes                   → references/color-and-accessibility.md
├─ fonts / backgrounds / gridlines     → references/themes-and-styling.md
├─ legends and guides                  → references/aesthetics-and-scales.md §Legends and Guides
├─ scales (breaks, labels, limits)     → references/aesthetics-and-scales.md
├─ axes / coordinates / transforms     → references/coords-and-axes.md
├─ titles / subtitles / annotations    → references/labels-and-annotations.md
└─ literal aesthetic values            → references/aesthetic-specification.md
   (e.g. a specific hex, dash pattern, font weight)

I need to lay out multiple plots or panels …

Layout how?
├─ one plot split by a variable                    → references/facets.md
│  (facet_wrap / facet_grid)
└─ several independent plots side-by-side or stacked → references/composition.md
   (| and / operators)

I need to prepare my data …

Data shape problem?
├─ reshape wide → long (or vice versa)  → references/data-preparation.md
├─ order categorical axes               → references/data-preparation.md
├─ aggregate before plotting            → references/data-preparation.md
│                                         or references/statistical-layers.md (stat_summary)
└─ drop / handle NAs                    → references/data-preparation.md

I'm revising an existing plot

→ references/iterative-refinement.md

I need to save / export

→ references/saving-and-export.md

Plotnine Essentials

Standard import

from plotnine import *
from plotnine.data import mpg
import pandas as pd          # only when pandas ops are used
import numpy as np           # only when generating synthetic data

Alternative import for users who prefer no wildcard:

import plotnine as p9
from plotnine.data import mpg

(
    p9.ggplot(mpg, p9.aes(x="displ", y="hwy"))
    + p9.geom_point()
    + p9.labs(x="Engine Displacement (L)", y="Highway MPG", title="Fuel Efficiency")
)

Alternative import for users who prefer explicit imports:

from plotnine import ggplot, aes, geom_point, labs
from plotnine.data import mpg

(
    ggplot(mpg, aes(x="displ", y="hwy"))
    + geom_point()
    + labs(x="Engine Displacement (L)", y="Highway MPG", title="Fuel Efficiency")
)

Minimal working plot

from plotnine import *
from plotnine.data import mpg

(
    ggplot(mpg, aes(x="displ", y="hwy"))
    + geom_point()
    + labs(x="Engine Displacement (L)", y="Highway MPG", title="Fuel Efficiency by Engine Size")
)

Saving a plot

from plotnine import *
from plotnine.data import penguins

p = (
    ggplot(penguins.dropna(), aes(x="species", fill="species"))
    + geom_bar()
    + labs(x="Species", y="Count", title="Penguin Species Counts", fill="Species")
)

p.save("penguins.png", width=6, height=4, dpi=300)

Supported formats: PNG, PDF, SVG, and any format supported by matplotlib's savefig.

Difficulty Guidance

| Difficulty | Examples | Strategy | |-----------|---------|----------| | Easy | Scatter, bar of counts, histogram, boxplot, line chart | Single canonical pattern from Essentials above | | Medium | Grouped bar, faceted scatter, violin + jitter, custom theme, color palette | Combine 2-3 layers; consult reference files | | Hard | Multi-dataset layers, heatmap with annotations, composition, lollipop chart | Propose closest plotnine approach; explain limitations if any |

Hard case guidance

If plotnine genuinely cannot produce the requested visualization (e.g., true dual y-axes, interactive tooltips), explain the limitation and propose the closest achievable result using only plotnine. Never fall back to matplotlib.

Resources

Reference Files

• [references/geoms.md](references/geoms.md) — Geom catalog with canonical patterns and examples
• [references/aesthetics-and-scales.md](references/aesthetics-and-scales.md) — Aesthetic mappings, scale functions, computed aesthetics
• [references/themes-and-styling.md](references/themes-and-styling.md) — Built-in themes, theme() customization, reusable themes
• [references/color-and-accessibility.md](references/color-and-accessibility.md) — Palettes, colorblind safety, alt-text guidance
• [references/data-preparation.md](references/data-preparation.md) — Tidy data, reshaping, aggregation, categorical ordering
• [references/iterative-refinement.md](references/iterative-refinement.md) — Edit protocol, diff format, revision patterns
• [references/facets.md](references/facets.md) — facetwrap, facetgrid, labellers, strip styling
• [references/labels-and-annotations.md](references/labels-and-annotations.md) — labs(), annotate(), geomtext, geomlabel, reference lines
• [references/statistical-layers.md](references/statistical-layers.md) — geomsmooth, statsummary, stat_ecdf, position adjustments
• [references/coords-and-axes.md](references/coords-and-axes.md) — coordcartesian, coordflip, coordfixed, coordtrans
• [references/saving-and-export.md](references/saving-and-export.md) — ggplot.save(), formats, sizes, in-memory saving
• [references/composition.md](references/composition.md) — Plot composition with |, /, +, &, *, plotlayout, plotannotation
• [references/maps.md](references/maps.md) — geommap, GeoPandas, choropleths, coordfixed, theme_void
• [references/aesthetic-specification.md](references/aesthetic-specification.md) — Literal color/linetype/shape/size/text value formats
• references/api/.md — Parameter reference for every public geom, stat, scale, and coord

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: has2k1
• Source: has2k1/plotnine-skill
• License: MIT

Install and usage instructions live in the source repository linked above.