plotnine 0.15.2__tar.gz → 0.15.4__tar.gz

{plotnine-0.15.2/plotnine.egg-info → plotnine-0.15.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotnine
-Version: 0.15.2
+Version: 0.15.4
 Summary: A Grammar of Graphics for Python
 Author-email: Hassan Kibirige <has2k1@gmail.com>
 License: The MIT License (MIT)
@@ -49,7 +49,8 @@ Requires-Dist: pandas>=2.2.0
 Requires-Dist: mizani~=0.14.0
 Requires-Dist: numpy>=1.23.5
 Requires-Dist: scipy>=1.8.0
-Requires-Dist: statsmodels>=0.14.5
+Requires-Dist: statsmodels<=0.14.4; sys_platform == "emscripten"
+Requires-Dist: statsmodels>=0.14.6; sys_platform != "emscripten"
 Provides-Extra: all
 Requires-Dist: plotnine[extra]; extra == "all"
 Requires-Dist: plotnine[doc]; extra == "all"
@@ -70,6 +71,7 @@ Requires-Dist: jupyter; extra == "doc"
 Requires-Dist: click; extra == "doc"
 Requires-Dist: numpydoc>=0.9.1; extra == "doc"
 Requires-Dist: quartodoc>=0.7.2; extra == "doc"
+Requires-Dist: griffe<2.0.0; extra == "doc"
 Provides-Extra: lint
 Requires-Dist: ruff; extra == "lint"
 Provides-Extra: test

{plotnine-0.15.2 → plotnine-0.15.4}/doc/changelog.qmd

@@ -2,13 +2,35 @@
 title: Changelog
 ---
 
-## v0.15.1
-(2025-12-12)
+## v0.15.4
+(2026-05-05)
+
+### New
+
+- Bundled agent skills
 
 ### Bug Fixes
 
+- Allow `statsmodels==0.14.4` on pyodide, which bundles that version. Other
+  platforms still require `statsmodels>=0.14.6` for pandas 3 compatibility.
+
+
+## v0.15.3
+(2025-01-28)
+
+### Enhancements
+
+- Removed warnings about copy-on-write for pandas >= 3.0.0
+
+## v0.15.2
+(2025-12-12)
+
+### Bug Fixes
 - Fixed random failures for when using plotnine in quarto == 1.8.26. {{< issue 1017 >}}
 
+## v0.15.1
+(2025-09-30)
+
 ### New
 
 - Added [](:class:`~plotnine.scale_stroke_identity`) which was conspicuously missing!

plotnine-0.15.4/plotnine/.agents/skills/plotnine/SKILL.md

@@ -0,0 +1,255 @@
+---
+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](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/<symbol>.md` (e.g. [references/api/geom_point.md](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
+
+```python
+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:
+
+```python
+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:
+
+```python
+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
+
+```python
+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
+
+```python
+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) — facet_wrap, facet_grid, labellers, strip styling
+- [references/labels-and-annotations.md](references/labels-and-annotations.md) — labs(), annotate(), geom_text, geom_label, reference lines
+- [references/statistical-layers.md](references/statistical-layers.md) — geom_smooth, stat_summary, stat_ecdf, position adjustments
+- [references/coords-and-axes.md](references/coords-and-axes.md) — coord_cartesian, coord_flip, coord_fixed, coord_trans
+- [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 |, /, +, &, *, plot_layout, plot_annotation
+- [references/maps.md](references/maps.md) — geom_map, GeoPandas, choropleths, coord_fixed, theme_void
+- [references/aesthetic-specification.md](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

plotnine-0.15.4/plotnine/.agents/skills/plotnine/references/aesthetic-specification.md

@@ -0,0 +1,182 @@
+# Aesthetic Specification
+
+How to *literally* specify values for aesthetic properties like color,
+linetype, point shape, size, and text. This is the concrete-values
+reference — for mapping data variables to aesthetics, see
+[aesthetics-and-scales.md](aesthetics-and-scales.md).
+
+Use these forms outside `aes()` (fixed values, no legend) or as the
+`values=` argument to `scale_*_manual()`.
+
+## Color and Fill
+
+Color accepts:
+
+- **Named colors** — any matplotlib-recognized name: `"red"`,
+  `"steelblue"`, `"navy"`, `"forestgreen"`.
+- **Hex codes** — `"#RRGGBB"` or `"#RRGGBBAA"` (alpha in the last pair).
+- **`"none"`** — fully transparent (for fill or border).
+
+```python
+from plotnine import *
+from plotnine.data import mpg
+
+(
+    ggplot(mpg, aes(x="displ", y="hwy"))
+    + geom_point(color="#E69F00", size=2, alpha=0.7)
+    + labs(x="Engine Displacement (L)", y="Highway MPG", title="Fixed color and alpha")
+)
+```
+
+For a transparent fill with a visible border use `fill="none"` and set
+`color` explicitly.
+
+## Linetype
+
+Named types: `"solid"`, `"dashed"`, `"dotted"`, `"dashdot"`, plus
+`"longdash"` and `"twodash"`.
+
+Custom dash patterns are `(offset, (on, off, on, off, ...))` tuples in
+point units. The second element repeats the on/off pattern indefinitely.
+
+```python
+from plotnine import *
+import pandas as pd
+
+df = pd.DataFrame({
+    "x": list(range(10)) * 3,
+    "y": list(range(10)) + [v + 1 for v in range(10)] + [v + 2 for v in range(10)],
+    "series": ["a"] * 10 + ["b"] * 10 + ["c"] * 10,
+})
+
+(
+    ggplot(df, aes(x="x", y="y", group="series"))
+    + geom_line(linetype="dashed", size=0.8)
+    + labs(x="X", y="Y", title="Dashed line with fixed linetype")
+)
+```
+
+## Line Attributes
+
+- **`size`** — line thickness, in approximately 0.75 mm units.
+- **`lineend`** — `"round"`, `"butt"`, or `"square"`. Controls the shape
+  of the end of an un-joined line.
+- **`linejoin`** — `"round"`, `"mitre"`, or `"bevel"`. Controls corners
+  where line segments meet.
+
+```python
+from plotnine import *
+import pandas as pd
+
+df = pd.DataFrame({"x": [0, 1, 2, 3], "y": [0, 2, 1, 3]})
+
+(
+    ggplot(df, aes(x="x", y="y"))
+    + geom_line(size=2, lineend="round", linejoin="bevel", color="#009E73")
+    + labs(x="X", y="Y", title="Thick line with rounded ends and beveled joins")
+)
+```
+
+## Point Shape
+
+Shape accepts:
+
+- **Integers** (0–25) — standard matplotlib marker codes. Selected
+  common values:
+
+| Integer | Shape                   |
+|---------|-------------------------|
+| 0       | open square             |
+| 1       | open circle             |
+| 2       | open triangle up        |
+| 3       | plus                    |
+| 4       | cross (×)               |
+| 15      | filled square           |
+| 16      | filled circle (default) |
+| 17      | filled triangle         |
+| 19      | large filled circle     |
+
+- **Single-character strings** — `"+"`, `"x"`, `"*"`, `"."`.
+- **Mathtex strings** — `r"$\alpha$"`, `r"$\heartsuit$"`.
+- **Polygon tuples** — `(n_sides, style, rotation)` where style is
+  `0` (regular polygon), `1` (star), or `2` (asterisk).
+
+```python
+from plotnine import *
+from plotnine.data import mpg
+
+(
+    ggplot(mpg, aes(x="displ", y="hwy"))
+    + geom_point(shape="D", size=3, color="#56B4E9")
+    + labs(x="Engine Displacement (L)", y="Highway MPG", title="Points with fixed shape 'D'")
+)
+```
+
+## Point Sizing
+
+- **`size`** — diameter in mm. Default is about 1.5.
+- **`stroke`** — outline width in mm (applies to open shapes only).
+
+```python
+from plotnine import *
+from plotnine.data import mpg
+
+(
+    ggplot(mpg, aes(x="displ", y="hwy"))
+    + geom_point(shape="o", size=4, stroke=0.8, color="#D55E00")
+    + labs(x="Engine Displacement (L)", y="Highway MPG", title="Open circles with thick stroke")
+)
+```
+
+## Text
+
+Applies to `geom_text`, `geom_label`, and `theme(text=element_text(...))`.
+
+- **`family`** — generic families (`"sans"`, `"serif"`, `"mono"`) or a
+  specific installed font name (`"Arial"`, `"DejaVu Sans"`).
+- **`weight`** — `"normal"`, `"bold"`, `"light"`, `"heavy"`, or numeric
+  (100–900).
+- **`style`** — `"normal"`, `"italic"`, `"oblique"`.
+- **`size`** — in mm by default for `geom_text` / `geom_label`; in
+  points within `theme()` elements.
+- **`ha`** / **`va`** — horizontal and vertical alignment. Strings
+  (`"left"`, `"center"`, `"right"`; `"top"`, `"center"`, `"bottom"`) or
+  floats in the 0–1 range.
+- **`color`** — any color accepted above.
+
+```python
+from plotnine import *
+import pandas as pd
+
+df = pd.DataFrame({"x": [1, 2, 3], "y": [1, 2, 3], "label": ["A", "B", "C"]})
+
+(
+    ggplot(df, aes(x="x", y="y", label="label"))
+    + geom_text(family="serif", style="italic", weight="bold", size=14, color="#0072B2")
+    + labs(x="X", y="Y", title="Styled text labels")
+)
+```
+
+## Common Pitfalls
+
+- **Color inside vs outside `aes()`**: `aes(color="red")` creates a
+  legend entry for the literal string `"red"`. To set a fixed color,
+  put it outside `aes()`: `geom_point(color="red")`.
+
+- **`size` units differ by context**: for `geom_point`/`geom_text`,
+  size is in mm. Inside `theme(text=element_text(size=...))`, size is
+  in points. A 12 pt font is roughly 4.2 mm.
+
+- **Linetype tuple form**: the outer tuple is `(offset, pattern)`, not
+  a flat list. `(0, (4, 4))` is valid; `(4, 4)` alone is not.
+
+- **Shape integers don't all accept `fill`**: open shapes (0–14) use
+  only `color` and `stroke`. Filled shapes (15–25) use `fill` for the
+  interior and `color` for the border.
+
+## See Also
+
+- [aesthetics-and-scales.md](aesthetics-and-scales.md) — mapping
+  variables to aesthetics, scale customization
+- [themes-and-styling.md](themes-and-styling.md) — theme elements and
+  the `theme()` surface