Plotnine Skill

plotnine static visualization library for Python, implementing the grammar of graphics (ggplot2 syntax). Covers geoms (point, line, bar, histogram, boxplot, smooth), aesthetics, scales, coordinates, facets, and themes. Use when creating static publication-quality figures with ggplot2-style syntax, producing charts for print or reports, or working with an R ggplot2 background. Prefer over plotly when static output is needed.

Quick reference for creating data visualizations with plotnine, a Python implementation of the grammar of graphics (ggplot2).

What is Plotnine?

plotnine is a data visualization library based on the grammar of graphics:

• Declarative: Describe what you want, not how to draw it
• Layered: Build plots by adding components with

  +

• ggplot2 compatible: Nearly identical syntax to R's ggplot2
• Publication-ready: Themes and customization for polished output

How to Use This Skill

Reference File Structure

quickstart.md

geoms.md

aesthetics.md

scales-coords.md

facets-themes.md

gotchas.md

Quick Decision Trees

"I need to create a plot"

What kind of plot?
├─ Scatter plot (geom_point) → ./references/geoms.md
├─ Line plot (geom_line) → ./references/geoms.md
├─ Bar chart (geom_bar, geom_col) → ./references/geoms.md
├─ Histogram (geom_histogram) → ./references/geoms.md
├─ Box plot (geom_boxplot) → ./references/geoms.md
└─ Other geoms → ./references/geoms.md

"I need to customize appearance"

What to customize?
├─ Colors, sizes, shapes → ./references/aesthetics.md
├─ Axis limits/labels → ./references/scales-coords.md
├─ Color palettes → ./references/scales-coords.md
├─ Overall theme → ./references/facets-themes.md
├─ Title/labels → ./references/facets-themes.md
└─ Multiple panels (faceting) → ./references/facets-themes.md

"Something isn't working"

Common issues?
├─ Plot not showing → ./references/quickstart.md
├─ Column not found → ./references/gotchas.md
├─ Color not applying → ./references/aesthetics.md
├─ Unexpected grouping → ./references/gotchas.md
└─ Syntax errors → ./references/gotchas.md

File-First Execution in Research Workflows

Important: In data research pipelines (see

CLAUDE.md

scripts/stage8_analysis/

The pattern:

1. Write plot code to

   scripts/stage8_analysis/{step}_{plot-name}.py

2. Execute via Bash with automatic output capture wrapper script
3. Validation results get automatically embedded in scripts as comments
4. If failed, create versioned copy for fixes

Closely read

agent_reference/SCRIPT_EXECUTION_REFERENCE.md

See:

• agent_reference/WORKFLOW_PHASE4_ANALYSIS.md

  — Stage 8 (Analysis & Visualization)

The examples below show plotnine syntax. In research workflows, wrap them in scripts following the file-first pattern.

Quick Reference

Basic Plot Pattern

from plotnine import ggplot, aes, geom_point

(
    ggplot(df, aes(x="col_x", y="col_y"))
    + geom_point()
)

Essential Imports

from plotnine import *           # All components
from plotnine.data import mtcars # Built-in datasets

Common Geoms

geom_point()

geom_line()

geom_bar()

geom_col()

geom_histogram()

geom_boxplot()

geom_smooth()

Common Aesthetics

x

y

color

fill

size

shape

alpha

Saving Plots

p = ggplot(df, aes("x", "y")) + geom_point()
p.save("plot.png", width=10, height=8, dpi=300)

Topic Index

./references/quickstart.md

./references/quickstart.md

./references/geoms.md

./references/aesthetics.md

./references/aesthetics.md

./references/scales-coords.md

./references/scales-coords.md

./references/scales-coords.md

./references/facets-themes.md

./references/facets-themes.md

./references/facets-themes.md

./references/gotchas.md

./references/gotchas.md

Citation

When this library is used as a primary analytical tool, include in the report's Software & Tools references:

Kibirige, H. et al. plotnine: Grammar of graphics for Python [Computer software]. https://plotnine.org/

Cite when: plotnine is the primary visualization library producing figures included in the report. Do not cite when: Only used for quick exploratory plots not included in deliverables.