plotnine

name	plotnine
description	Generate, refine and export data visualizations using plotnine. Use this skill when the user asks to create plots or charts with plotnine. Also use when customizing themes, applying colorblind-safe palettes, reshaping data for plotting with plotnine, or saving figures to PNG/PDF/SVG/JPEG.

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.

2. 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.

3. 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.

4. Minimal transformations — prefer simple pandas ops (groupby, agg, melt) or polars equivalents. Prefer plotnine stat_*/position_* over manual aggregation when possible.

5. 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.

6. 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

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

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

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

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

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

Task: Create small multiples / faceted plots Use: references/facets.md

Task: Add titles, subtitles, annotations, labels Use: references/labels-and-annotations.md

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

Task: Adjust axes, coordinates, transforms Use: references/coords-and-axes.md

Task: Save / export a figure Use: references/saving-and-export.md

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

Task: Plot geographic / map data Use: references/maps.md

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

Task: Look up a specific symbol's parameters, types, or defaults Use: references/api/<symbol>.md (e.g. references/api/geom_point.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 — Geom catalog with canonical patterns and examples
• references/aesthetics-and-scales.md — Aesthetic mappings, scale functions, computed aesthetics
• references/themes-and-styling.md — Built-in themes, theme() customization, reusable themes
• references/color-and-accessibility.md — Palettes, colorblind safety, alt-text guidance
• references/data-preparation.md — Tidy data, reshaping, aggregation, categorical ordering
• references/iterative-refinement.md — Edit protocol, diff format, revision patterns
• references/facets.md — facet_wrap, facet_grid, labellers, strip styling
• references/labels-and-annotations.md — labs(), annotate(), geom_text, geom_label, reference lines
• references/statistical-layers.md — geom_smooth, stat_summary, stat_ecdf, position adjustments
• references/coords-and-axes.md — coord_cartesian, coord_flip, coord_fixed, coord_trans
• references/saving-and-export.md — ggplot.save(), formats, sizes, in-memory saving
• references/composition.md — Plot composition with |, /, +, &, *, plot_layout, plot_annotation
• references/maps.md — geom_map, GeoPandas, choropleths, coord_fixed, theme_void
• references/aesthetic-specification.md — Literal color/linetype/shape/size/text value formats
• references/api/<symbol>.md — Parameter reference for every public geom, stat, scale, and coord