feat(plotnine): implement biplot-pca (#3478)

## Implementation: `biplot-pca` - plotnine

Implements the **plotnine** version of `biplot-pca`.

**File:** `plots/biplot-pca/implementations/plotnine.py`

**Parent Issue:** #3417

---
:robot: *[impl-generate
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/20853039303)*

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/biplot-pca/implementations/plotnine.py

@@ -0,0 +1,127 @@
+""" pyplots.ai
+biplot-pca: PCA Biplot with Scores and Loading Vectors
+Library: plotnine 0.15.2 | Python 3.13.11
+Quality: 91/100 | Created: 2026-01-09
+"""
+
+import numpy as np
+import pandas as pd
+from plotnine import (
+    aes,
+    arrow,
+    element_text,
+    geom_path,
+    geom_point,
+    geom_segment,
+    geom_text,
+    ggplot,
+    labs,
+    scale_color_manual,
+    theme,
+    theme_minimal,
+)
+from sklearn.datasets import load_iris
+from sklearn.decomposition import PCA
+from sklearn.preprocessing import StandardScaler
+
+
+# Load Iris dataset
+iris = load_iris()
+X = iris.data
+y = iris.target
+feature_names = iris.feature_names
+species_names = [iris.target_names[i] for i in y]
+
+# Standardize features
+scaler = StandardScaler()
+X_scaled = scaler.fit_transform(X)
+
+# Perform PCA
+pca = PCA(n_components=2)
+scores = pca.fit_transform(X_scaled)
+loadings = pca.components_.T  # Shape: (n_features, n_components)
+var_explained = pca.explained_variance_ratio_ * 100
+
+# Create scores DataFrame
+df_scores = pd.DataFrame({"PC1": scores[:, 0], "PC2": scores[:, 1], "Species": species_names})
+
+# Scale loadings to be visible alongside scores
+# Use a scaling factor based on the score range
+score_scale = np.max(np.abs(scores)) * 0.8
+loading_scale = np.max(np.abs(loadings))
+scale_factor = score_scale / loading_scale
+
+# Create loadings DataFrame for arrows
+xend = loadings[:, 0] * scale_factor
+yend = loadings[:, 1] * scale_factor
+
+df_loadings = pd.DataFrame(
+    {
+        "x": [0] * len(feature_names),
+        "y": [0] * len(feature_names),
+        "xend": xend,
+        "yend": yend,
+        "variable": [name.replace(" (cm)", "") for name in feature_names],
+    }
+)
+
+# Create label positions with smart offsets to avoid overlap
+label_offset = 0.25
+df_labels = pd.DataFrame(
+    {
+        "x": xend + np.sign(xend) * label_offset,
+        "y": yend + np.sign(yend) * label_offset * 0.8,
+        "variable": [name.replace(" (cm)", "") for name in feature_names],
+    }
+)
+# Manually adjust overlapping labels (petal length and petal width)
+df_labels.loc[2, "y"] -= 0.15  # petal length - move down
+df_labels.loc[3, "y"] += 0.15  # petal width - move up
+
+# Create unit circle reference (scaled)
+theta = np.linspace(0, 2 * np.pi, 100)
+df_circle = pd.DataFrame({"x": np.cos(theta) * scale_factor, "y": np.sin(theta) * scale_factor})
+
+# Colors - Python Blue variants for species
+colors = ["#306998", "#FFD43B", "#E67E22"]
+
+# Create biplot
+plot = (
+    ggplot()
+    # Unit circle reference
+    + geom_path(df_circle, aes(x="x", y="y"), color="gray", linetype="dashed", size=0.8, alpha=0.5)
+    # Observation scores as points
+    + geom_point(df_scores, aes(x="PC1", y="PC2", color="Species"), size=4, alpha=0.7)
+    # Loading arrows
+    + geom_segment(
+        df_loadings,
+        aes(x="x", y="y", xend="xend", yend="yend"),
+        color="#1a1a1a",
+        size=1.2,
+        arrow=arrow(length=0.15, type="closed"),
+    )
+    # Loading labels (using separate df with pre-computed positions)
+    + geom_text(df_labels, aes(x="x", y="y", label="variable"), size=12, color="#1a1a1a", fontweight="bold")
+    # Labels
+    + labs(
+        x=f"PC1 ({var_explained[0]:.1f}%)",
+        y=f"PC2 ({var_explained[1]:.1f}%)",
+        title="biplot-pca · plotnine · pyplots.ai",
+        color="Species",
+    )
+    # Theme
+    + theme_minimal()
+    + theme(
+        figure_size=(16, 9),
+        text=element_text(size=14),
+        axis_title=element_text(size=20),
+        axis_text=element_text(size=16),
+        plot_title=element_text(size=24),
+        legend_text=element_text(size=16),
+        legend_title=element_text(size=18),
+    )
+    + scale_color_manual(values=colors)
+)
+
+# Save
+plot.save("plot.png", dpi=300, verbose=False)

plots/biplot-pca/metadata/plotnine.yaml

@@ -0,0 +1,214 @@
+library: plotnine
+specification_id: biplot-pca
+created: '2026-01-09T13:20:35Z'
+updated: '2026-01-09T13:23:55Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 20853039303
+issue: 3417
+python_version: 3.13.11
+library_version: 0.15.2
+preview_url: https://storage.googleapis.com/pyplots-images/plots/biplot-pca/plotnine/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/biplot-pca/plotnine/plot_thumb.png
+preview_html: null
+quality_score: 91
+review:
+  strengths:
+  - 'Excellent implementation of all biplot requirements: scores, loadings with arrows,
+    variable labels, and unit circle reference'
+  - Smart label positioning with manual adjustments to reduce overlap between petal
+    length/width labels
+  - Appropriate color palette that is colorblind-safe
+  - Well-scaled loadings that are visible alongside score points
+  - Proper axis labels with variance explained percentages
+  - Clean ggplot2-style layered composition using plotnine grammar of graphics
+  weaknesses:
+  - Slight overlap between petal length and petal width labels despite manual adjustment
+    attempt
+  - No random seed set (though not strictly needed since Iris is deterministic data)
+  - Could use more distinctive plotnine features like scale_color_brewer instead of
+    manual colors
+  image_description: 'The plot displays a PCA biplot using the Iris dataset with 150
+    observations (50 per species). The three Iris species (setosa, versicolor, virginica)
+    are shown as colored scatter points: blue for setosa clustered on the left, golden-yellow
+    for versicolor in the middle, and orange for virginica on the right. Four black
+    arrows originate from the origin representing variable loadings: "sepal width"
+    points upward-left, "sepal length" points to the upper-right, "petal width" and
+    "petal length" point to the right (nearly overlapping). A dashed gray unit circle
+    provides reference for loading magnitudes. Axis labels show "PC1 (73.0%)" and
+    "PC2 (22.9%)" with variance explained percentages. The title correctly follows
+    the format "biplot-pca · plotnine · pyplots.ai". The plot uses a 16:9 landscape
+    format with a minimal theme and subtle gray grid.'
+  criteria_checklist:
+    visual_quality:
+      score: 37
+      max: 40
+      items:
+      - id: VQ-01
+        name: Text Legibility
+        score: 10
+        max: 10
+        passed: true
+        comment: Title at 24pt, axis labels at 20pt, tick labels at 16pt, all perfectly
+          readable
+      - id: VQ-02
+        name: No Overlap
+        score: 7
+        max: 8
+        passed: true
+        comment: Minor overlap between petal length and petal width labels due to
+          similar loading directions; still readable
+      - id: VQ-03
+        name: Element Visibility
+        score: 8
+        max: 8
+        passed: true
+        comment: Point size 4 with alpha 0.7 is well-suited for 150 data points
+      - id: VQ-04
+        name: Color Accessibility
+        score: 5
+        max: 5
+        passed: true
+        comment: Blue, yellow, orange palette is colorblind-safe
+      - id: VQ-05
+        name: Layout Balance
+        score: 4
+        max: 5
+        passed: true
+        comment: Good proportions, unit circle extends close to edges
+      - id: VQ-06
+        name: Axis Labels
+        score: 2
+        max: 2
+        passed: true
+        comment: Descriptive with variance explained percentages
+      - id: VQ-07
+        name: Grid & Legend
+        score: 1
+        max: 2
+        passed: true
+        comment: Grid subtle, legend well-placed; grid could be slightly less prominent
+    spec_compliance:
+      score: 25
+      max: 25
+      items:
+      - id: SC-01
+        name: Plot Type
+        score: 8
+        max: 8
+        passed: true
+        comment: Correct biplot with scores as points and loadings as arrows
+      - id: SC-02
+        name: Data Mapping
+        score: 5
+        max: 5
+        passed: true
+        comment: PC1 on X-axis, PC2 on Y-axis correctly assigned
+      - id: SC-03
+        name: Required Features
+        score: 5
+        max: 5
+        passed: true
+        comment: 'All spec features present: scores, loadings, labels, unit circle,
+          variance explained'
+      - id: SC-04
+        name: Data Range
+        score: 3
+        max: 3
+        passed: true
+        comment: Axes show all data points and loading arrows
+      - id: SC-05
+        name: Legend Accuracy
+        score: 2
+        max: 2
+        passed: true
+        comment: Species legend labels are correct
+      - id: SC-06
+        name: Title Format
+        score: 2
+        max: 2
+        passed: true
+        comment: Uses exact format biplot-pca · plotnine · pyplots.ai
+    data_quality:
+      score: 19
+      max: 20
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 8
+        max: 8
+        passed: true
+        comment: Shows clear species separation, variable loadings with different
+          directions and magnitudes
+      - id: DQ-02
+        name: Realistic Context
+        score: 7
+        max: 7
+        passed: true
+        comment: Iris dataset is a classic, neutral, real-world example for PCA
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 4
+        max: 5
+        passed: true
+        comment: Scaled loadings visible alongside scores; loading scale factor could
+          be slightly larger
+    code_quality:
+      score: 8
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: 'Linear flow: imports, data loading, PCA, dataframes, plot, save'
+      - id: CQ-02
+        name: Reproducibility
+        score: 1
+        max: 3
+        passed: false
+        comment: Uses load_iris() which is deterministic, but no explicit np.random.seed()
+      - id: CQ-03
+        name: Clean Imports
+        score: 2
+        max: 2
+        passed: true
+        comment: All imports are used
+      - id: CQ-04
+        name: No Deprecated API
+        score: 1
+        max: 1
+        passed: true
+        comment: Modern plotnine and sklearn APIs
+      - id: CQ-05
+        name: Output Correct
+        score: 1
+        max: 1
+        passed: true
+        comment: Saves as plot.png with dpi=300
+    library_features:
+      score: 2
+      max: 5
+      items:
+      - id: LF-01
+        name: Distinctive Features
+        score: 2
+        max: 5
+        passed: false
+        comment: Uses layered composition but no advanced plotnine-specific features
+          like faceting or statistical transformations
+  verdict: APPROVED
+impl_tags:
+  dependencies:
+  - sklearn
+  techniques:
+  - annotations
+  - layer-composition
+  patterns:
+  - dataset-loading
+  dataprep:
+  - pca
+  - normalization
+  styling:
+  - alpha-blending
+  - grid-styling