Skip to content

/plotnine

Python guide to plotnine, the ggplot2 grammar of graphics for static publication figures: geoms, aesthetics, scales, facets and themes.

Category: figures
Field: general
License: LGPL-3.0-or-later (as declared in the README, badge and CITATION.cff; the repo ships the GPL-3.0 text as LICENSE plus COPYING.LESSER)
Updated: 2026-07-16
Stages: data-analysis

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

File Purpose When to Read
quickstart.md Installation, imports, basic syntax Starting out
geoms.md Geometric objects (points, lines, bars) Choosing chart types
aesthetics.md Mapping data to visual properties Customizing appearance
scales-coords.md Scales, coordinates, positions Axis/color control
facets-themes.md Multi-panel plots and styling Layout and themes
gotchas.md Common errors and best practices Debugging

The reference-file routing in this skill applies to advisory and brainstorming turns as much as implementation. Recommending an approach, reviewing a plan, or answering a question that touches a routed topic calls for reading the routed reference file just as much as writing code does — the reference files carry curated caveats and environment-specific constraints that this overview and general knowledge lack.

Quick Decision Trees

"I need to create a plot"

Text Only
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"

Text Only
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"

Text Only
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), all visualizations are generated through script files in scripts/stage8_analysis/, not interactively. This ensures auditability and reproducibility.

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 for the mandatory file-first execution protocol covering complete code file writing, output capture, and file versioning rules.

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

Python
from plotnine import ggplot, aes, geom_point

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

Essential Imports

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

Common Geoms

Geom Use Case
geom_point() Scatter plots
geom_line() Line plots
geom_bar() Count bars
geom_col() Value bars
geom_histogram() Distributions
geom_boxplot() Box plots
geom_smooth() Trend lines

Common Aesthetics

Aesthetic Controls
x, y Position
color Point/line color
fill Area fill color
size Point/line size
shape Point shape
alpha Transparency

Saving Plots

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

Topic Index

Topic Reference File
Installation ./references/quickstart.md
Basic syntax ./references/quickstart.md
Chart types ./references/geoms.md
Data mapping ./references/aesthetics.md
Color/shape values ./references/aesthetics.md
Axis scales ./references/scales-coords.md
Color scales ./references/scales-coords.md
Coordinates ./references/scales-coords.md
Faceting ./references/facets-themes.md
Themes ./references/facets-themes.md
Labels/titles ./references/facets-themes.md
Common errors ./references/gotchas.md
Best practices ./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.