feat(plotnine): implement ma-differential-expression (#5076)

## Implementation: `ma-differential-expression` - plotnine

Implements the **plotnine** version of `ma-differential-expression`.

**File:** `plots/ma-differential-expression/implementations/plotnine.py`

**Parent Issue:** #4420

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

---------

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/ma-differential-expression/implementations/plotnine.py

@@ -0,0 +1,160 @@
+""" pyplots.ai
+ma-differential-expression: MA Plot for Differential Expression
+Library: plotnine 0.15.3 | Python 3.14.3
+Quality: 90/100 | Created: 2026-03-20
+"""
+
+import numpy as np
+import pandas as pd
+from plotnine import (
+    aes,
+    annotate,
+    element_blank,
+    element_line,
+    element_rect,
+    element_text,
+    geom_hline,
+    geom_point,
+    geom_text,
+    ggplot,
+    guide_legend,
+    guides,
+    labs,
+    scale_alpha_manual,
+    scale_color_manual,
+    scale_size_manual,
+    stat_smooth,
+    theme,
+    theme_minimal,
+)
+
+
+# Data
+np.random.seed(42)
+n_genes = 15000
+
+mean_expression = np.random.uniform(0, 15, n_genes)
+log_fold_change = np.random.normal(0, 0.5, n_genes)
+log_fold_change += 0.15 * np.sin(mean_expression * 0.3)
+
+n_sig = int(n_genes * 0.08)
+sig_indices = np.random.choice(n_genes, n_sig, replace=False)
+log_fold_change[sig_indices] *= np.random.uniform(2.5, 5.0, n_sig)
+
+significant = np.abs(log_fold_change) > 1.0
+significant[sig_indices[: n_sig // 2]] = True
+
+# Categorize into up/down/not significant for richer storytelling
+category = np.where(~significant, "Not significant", np.where(log_fold_change > 0, "Upregulated", "Downregulated"))
+
+gene_names = [f"Gene{i}" for i in range(n_genes)]
+top_genes = ["BRCA1", "TP53", "MYC", "EGFR", "KRAS", "PTEN", "RB1", "APC"]
+top_idx = np.argsort(np.abs(log_fold_change))[-len(top_genes) :]
+for i, idx in enumerate(top_idx):
+    gene_names[idx] = top_genes[i]
+
+df = pd.DataFrame(
+    {
+        "mean_expression": mean_expression,
+        "log_fold_change": log_fold_change,
+        "significant": significant,
+        "gene_name": gene_names,
+        "category": pd.Categorical(
+            category, categories=["Downregulated", "Not significant", "Upregulated"], ordered=True
+        ),
+    }
+)
+
+df_labels = df.loc[top_idx].copy()
+# Position labels offset from data points to avoid overlap
+nudge = np.where(df_labels["log_fold_change"] > 0, 0.8, -0.8)
+
+# Detect close labels within same direction and stagger them
+for direction in [1, -1]:
+    mask = (nudge * direction) > 0
+    subset = df_labels[mask].sort_values("mean_expression")
+    for j in range(1, len(subset)):
+        prev_x = subset.iloc[j - 1]["mean_expression"]
+        curr_x = subset.iloc[j]["mean_expression"]
+        if abs(curr_x - prev_x) < 2.0:
+            idx_curr = subset.index[j]
+            nudge[df_labels.index.get_loc(idx_curr)] *= 2.0
+
+df_labels["label_y"] = df_labels["log_fold_change"] + nudge
+
+# Split labels by direction for separate geom_text layers
+df_labels_up = df_labels[df_labels["log_fold_change"] > 0].copy()
+df_labels_down = df_labels[df_labels["log_fold_change"] < 0].copy()
+
+# Plot
+plot = (
+    ggplot(df, aes(x="mean_expression", y="log_fold_change", color="category"))
+    + geom_point(aes(alpha="category", size="category"), stroke=0)
+    + geom_hline(yintercept=0, color="#2C3E50", size=1.0, alpha=0.8)
+    + geom_hline(yintercept=1, linetype="dashed", color="#95A5A6", size=0.6)
+    + geom_hline(yintercept=-1, linetype="dashed", color="#95A5A6", size=0.6)
+    + annotate(
+        "label",
+        x=14.5,
+        y=1.0,
+        label=" ±2-fold threshold ",
+        size=11,
+        color="#555555",
+        fill="#FAFAFA",
+        alpha=0.9,
+        label_size=0,
+        ha="right",
+        va="center",
+    )
+    + stat_smooth(aes(group=1), method="lowess", color="#306998", size=1.4, se=False, span=0.3, linetype="solid")
+    + geom_text(
+        aes(x="mean_expression", y="label_y", label="gene_name"),
+        data=df_labels_up,
+        color="#1A1A2E",
+        size=14,
+        fontstyle="italic",
+        alpha=1,
+        inherit_aes=False,
+        show_legend=False,
+    )
+    + geom_text(
+        aes(x="mean_expression", y="label_y", label="gene_name"),
+        data=df_labels_down,
+        color="#1A1A2E",
+        size=14,
+        fontstyle="italic",
+        alpha=1,
+        inherit_aes=False,
+        show_legend=False,
+    )
+    + scale_color_manual(values={"Upregulated": "#D45E00", "Not significant": "#C0C0C0", "Downregulated": "#306998"})
+    + scale_alpha_manual(values={"Upregulated": 0.8, "Not significant": 0.15, "Downregulated": 0.8})
+    + scale_size_manual(values={"Upregulated": 2.0, "Not significant": 1.0, "Downregulated": 2.0})
+    + labs(
+        x="Mean Expression (A)",
+        y="Log₂ Fold Change (M)",
+        title="ma-differential-expression · plotnine · pyplots.ai",
+        color="",
+    )
+    + guides(color=guide_legend(override_aes={"alpha": 1, "size": 4}), alpha="none", size="none")
+    + theme_minimal()
+    + theme(
+        figure_size=(16, 9),
+        plot_title=element_text(size=24, weight="bold", color="#1A1A2E"),
+        plot_subtitle=element_text(size=16, color="#555555"),
+        axis_title=element_text(size=20, color="#2C3E50"),
+        axis_text=element_text(size=16, color="#555555"),
+        legend_text=element_text(size=16),
+        legend_title=element_blank(),
+        legend_position="top",
+        legend_background=element_rect(fill="white", alpha=0.8),
+        panel_grid_major_x=element_blank(),
+        panel_grid_major_y=element_line(color="#ECECEC", size=0.3),
+        panel_grid_minor=element_blank(),
+        plot_background=element_rect(fill="#FAFAFA", color="none"),
+        panel_background=element_rect(fill="#FAFAFA", color="none"),
+    )
+)
+
+# Save
+plot.save("plot.png", dpi=300, verbose=False)

plots/ma-differential-expression/metadata/plotnine.yaml

@@ -0,0 +1,227 @@
+library: plotnine
+specification_id: ma-differential-expression
+created: '2026-03-20T10:38:20Z'
+updated: '2026-03-20T10:59:43Z'
+generated_by: claude-opus-4-5-20251101
+workflow_run: 23339077857
+issue: 4420
+python_version: 3.14.3
+library_version: 0.15.3
+preview_url: https://storage.googleapis.com/pyplots-images/plots/ma-differential-expression/plotnine/plot.png
+preview_thumb: https://storage.googleapis.com/pyplots-images/plots/ma-differential-expression/plotnine/plot_thumb.png
+preview_html: null
+quality_score: 90
+review:
+  strengths:
+  - Excellent data storytelling through three-category color/size/alpha mapping that
+    immediately conveys up/down regulation
+  - All spec requirements implemented comprehensively (reference lines, LOESS, gene
+    labels, transparency)
+  - Realistic genomics context with real gene names and appropriate data scales
+  - Clean idiomatic plotnine code leveraging grammar of graphics layering
+  weaknesses:
+  - Label nudge logic is verbose and could be simplified
+  - The ±2-fold threshold annotation text (size=11) is slightly small relative to
+    other text elements
+  image_description: 'The plot displays an MA plot for differential gene expression
+    with Mean Expression (A) on the x-axis (range 0-15) and Log2 Fold Change (M) on
+    the y-axis (range approximately -7 to +7). Three categories are shown via a top
+    legend: Downregulated (blue), Not significant (light gray, faded), and Upregulated
+    (orange). A solid dark horizontal reference line sits at M=0, with dashed gray
+    lines at M=+/-1 labeled "±2-fold threshold" on the right. A dark blue LOESS smoothing
+    curve traces near the zero line showing minimal systematic bias. Eight top differentially
+    expressed genes are labeled in italic text (APC, BRCA1, RB1, TP53, MYC, KRAS,
+    EGFR, PTEN) with labels nudged away from their data points. The background is
+    light gray (#FAFAFA) with subtle horizontal-only gridlines. Significant genes
+    (orange/blue) are larger and more opaque, while non-significant genes are small
+    and nearly transparent.'
+  criteria_checklist:
+    visual_quality:
+      score: 28
+      max: 30
+      items:
+      - id: VQ-01
+        name: Text Legibility
+        score: 8
+        max: 8
+        passed: true
+        comment: 'All font sizes explicitly set: title 24pt, axis titles 20pt, axis/tick
+          text 16pt, legend text 16pt'
+      - id: VQ-02
+        name: No Overlap
+        score: 5
+        max: 6
+        passed: true
+        comment: Gene labels use nudge logic; threshold annotation slightly small
+          and at canvas edge
+      - id: VQ-03
+        name: Element Visibility
+        score: 5
+        max: 6
+        passed: true
+        comment: 15k points handled well with alpha=0.15 for non-significant and alpha=0.8
+          + larger size for significant
+      - id: VQ-04
+        name: Color Accessibility
+        score: 4
+        max: 4
+        passed: true
+        comment: Orange and blue are colorblind-safe with gray non-significant providing
+          good contrast
+      - id: VQ-05
+        name: Layout & Canvas
+        score: 4
+        max: 4
+        passed: true
+        comment: 16:9 aspect ratio with good canvas utilization and balanced margins
+      - id: VQ-06
+        name: Axis Labels & Title
+        score: 2
+        max: 2
+        passed: true
+        comment: 'Descriptive labels with parenthetical notation: Mean Expression
+          (A), Log2 Fold Change (M)'
+    design_excellence:
+      score: 15
+      max: 20
+      items:
+      - id: DE-01
+        name: Aesthetic Sophistication
+        score: 6
+        max: 8
+        passed: true
+        comment: Thoughtful warm/cool color scheme, intentional visual hierarchy through
+          alpha/size mapping, custom background
+      - id: DE-02
+        name: Visual Refinement
+        score: 4
+        max: 6
+        passed: true
+        comment: X-grid removed, subtle y-grid, minor grid removed, custom background,
+          legend refined
+      - id: DE-03
+        name: Data Storytelling
+        score: 5
+        max: 6
+        passed: true
+        comment: Strong visual hierarchy with three-category scheme, gene labels identify
+          key players, LOESS adds analytical depth
+    spec_compliance:
+      score: 15
+      max: 15
+      items:
+      - id: SC-01
+        name: Plot Type
+        score: 5
+        max: 5
+        passed: true
+        comment: Correct MA plot type
+      - id: SC-02
+        name: Required Features
+        score: 4
+        max: 4
+        passed: true
+        comment: 'All spec features present: highlighting, reference lines, LOESS,
+          transparency, gene labels'
+      - id: SC-03
+        name: Data Mapping
+        score: 3
+        max: 3
+        passed: true
+        comment: X=mean_expression, Y=log_fold_change correctly mapped
+      - id: SC-04
+        name: Title & Legend
+        score: 3
+        max: 3
+        passed: true
+        comment: Correct title format and clear legend labels
+    data_quality:
+      score: 15
+      max: 15
+      items:
+      - id: DQ-01
+        name: Feature Coverage
+        score: 6
+        max: 6
+        passed: true
+        comment: Shows upregulated, downregulated, non-significant, labeled outlier
+          genes, full expression range
+      - id: DQ-02
+        name: Realistic Context
+        score: 5
+        max: 5
+        passed: true
+        comment: Real gene names (BRCA1, TP53, MYC, etc.), realistic RNA-seq genomics
+          context
+      - id: DQ-03
+        name: Appropriate Scale
+        score: 4
+        max: 4
+        passed: true
+        comment: 15,000 genes realistic for whole-transcriptome, appropriate expression
+          and fold-change ranges
+    code_quality:
+      score: 9
+      max: 10
+      items:
+      - id: CQ-01
+        name: KISS Structure
+        score: 3
+        max: 3
+        passed: true
+        comment: Clean Imports-Data-Plot-Save structure, no functions or classes
+      - id: CQ-02
+        name: Reproducibility
+        score: 2
+        max: 2
+        passed: true
+        comment: np.random.seed(42) set
+      - id: CQ-03
+        name: Clean Imports
+        score: 2
+        max: 2
+        passed: true
+        comment: All imports used
+      - id: CQ-04
+        name: Code Elegance
+        score: 1
+        max: 2
+        passed: false
+        comment: Label nudge/stagger logic is verbose (~18 lines of manual iteration)
+      - id: CQ-05
+        name: Output & API
+        score: 1
+        max: 1
+        passed: true
+        comment: Saves as plot.png, current plotnine API
+    library_mastery:
+      score: 8
+      max: 10
+      items:
+      - id: LM-01
+        name: Idiomatic Usage
+        score: 5
+        max: 5
+        passed: true
+        comment: 'Expert grammar of graphics usage: ggplot+aes, layered geoms, scale_*_manual,
+          guides, theme composition'
+      - id: LM-02
+        name: Distinctive Features
+        score: 3
+        max: 5
+        passed: true
+        comment: Uses stat_smooth (LOESS), scale_alpha_manual/scale_size_manual, guide_legend
+          with override_aes
+  verdict: APPROVED
+impl_tags:
+  dependencies: []
+  techniques:
+  - annotations
+  - layer-composition
+  - custom-legend
+  patterns:
+  - data-generation
+  dataprep: []
+  styling:
+  - alpha-blending
+  - grid-styling