@brainpilot/skills 0.0.6

package/skills/13_Visualization/nature-figure/assets/figures4papers/figure_ophthal_review/plot_trend.py

@@ -0,0 +1,125 @@
+import os
+import numpy as np
+from matplotlib import pyplot as plt
+from datetime import datetime
+from dateutil.relativedelta import relativedelta
+
+
+DATA = {
+    'names': ['Methodological Contribution (Text-only)', 'Evaluation / Application (Text-only)',
+              'Methodological Contribution (Multimodal)', 'Evaluation / Application (Multimodal)'],
+    'pub_by_month': np.array(
+        [[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 2, 1, 1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 2],
+         [0, 0, 4, 0, 0, 6, 1, 3, 2, 0, 5, 0, 4, 0, 9, 1, 3, 4, 7, 6, 7, 6, 6, 1, 6, 4, 6, 2, 0, 0, 0, 1, 1],
+         [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0],
+         [0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 4, 0, 0, 0, 1, 2, 1, 0, 2, 3, 0, 1, 2, 0, 2, 0, 1, 0, 0, 0, 0, 0, 0]]
+    ),
+    # NOTE: Use `*` to move the label up in the annotation. Each `*` moves it up a bit.
+    'dates_llm': {
+        '2022-11': 'ChatGPT\n(GPT-3.5)',
+        '2023-02': 'Bard',
+        '2023-02': 'LlaMA 1',
+        '2023-03': 'GPT-4*',
+        '2025-08': 'GPT-5',
+        '2023-07': 'LlaMA 2',
+        '2024-04': 'LlaMA 3',
+        '2025-04': 'LlaMA 4',
+        '2023-12': 'Gemini 1.0',
+        '2024-02': 'Gemini 1.5',
+        '2024-12': 'Gemini 2.0',
+        '2025-06': 'Gemini 2.5*',
+    },
+    'dates_vlm': {
+        '2023-02': 'BLIP-2',
+        '2023-07': 'LlaVA 1.0',
+        '2023-9': 'GPT-4v',
+        '2023-10': 'LlaVA 1.5*',
+        '2023-12': 'Gemini 1.0',
+        '2024-02': 'Gemini 1.5',
+        '2024-12': 'Gemini 2.0',
+        '2025-06': 'Gemini 2.5',
+    }
+}
+
+def month_year_list(start_year, start_month, n_months):
+    start = datetime(start_year, start_month, 1)
+    out = []
+    for i in range(n_months):
+        d = start + relativedelta(months=i)
+        out.append(d.strftime('%Y-%m'))
+    return out
+
+def mark_events(ax, time_arr, y_curve, events, dy=0.1):
+    x_idx = {t: i for i, t in enumerate(time_arr)}
+    y0, y1 = ax.get_ylim()
+    prev_date = None
+    for date, label in events.items():
+        if prev_date is None:
+            prev_date = date
+        if date in x_idx:
+            i = x_idx[date]
+            x, y = i, y_curve[i]
+            ax.annotate(
+                label.replace('*', ''),
+                xy=(x, y),
+                xytext=(x, y + (1 + 0.8 * np.uint8(label.count('*'))) * dy * (y1 - y0)),
+                ha='center',
+                va='bottom',
+                fontsize=11,
+                arrowprops=dict(arrowstyle='-|>', lw=1.3, color='black',
+                                shrinkA=0, shrinkB=0, mutation_scale=15)
+            )
+    return
+
+def plot_curve(fig_name: str):
+    plt.rcParams['text.usetex'] = True
+    plt.rcParams['font.family'] = 'helvetica'
+    plt.rcParams['font.size'] = 15
+    plt.rcParams['axes.spines.right'] = False
+    plt.rcParams['axes.spines.top'] = False
+    plt.rcParams['axes.linewidth'] = 2
+    colors = ["#9BC8FA", "#ffa8a6", "#13457E", "#850c0a"]
+
+    os.makedirs(os.path.dirname(fig_name), exist_ok=True)
+    fig = plt.figure(figsize=(14, 8))
+    num_months = DATA['pub_by_month'].shape[1]
+
+    ax = fig.add_subplot(2, 1, 1)
+    time_arr = month_year_list(start_year=2022, start_month=11, n_months=num_months)
+    ax.fill_between(time_arr, np.zeros_like(DATA['pub_by_month'][1, :]), np.cumsum(DATA['pub_by_month'][1, :]), color=colors[1],
+                    label=DATA['names'][1])
+    ax.fill_between(time_arr, np.zeros_like(DATA['pub_by_month'][0, :]), np.cumsum(DATA['pub_by_month'][0, :]), color=colors[0],
+                    label=DATA['names'][0])
+    ax.plot(time_arr, np.cumsum(DATA['pub_by_month'][0, :]), lw=3, c=colors[2])
+    ax.plot(time_arr, np.cumsum(DATA['pub_by_month'][1, :]), lw=3, c=colors[3])
+    mark_events(ax, time_arr, np.cumsum(DATA['pub_by_month'][1, :]), DATA['dates_llm'])
+    ax.legend(frameon=False)
+    ax.set_xticks(time_arr[2::6])
+    ax.set_ylim([0, 105])
+    ax.set_ylabel('Cumulative\nPublication Count\n(Text-only)')
+
+    ax = fig.add_subplot(2, 1, 2)
+    time_arr = month_year_list(start_year=2022, start_month=11, n_months=num_months)
+    ax.fill_between(time_arr, np.zeros_like(DATA['pub_by_month'][3, :]), np.cumsum(DATA['pub_by_month'][3, :]), color=colors[1],
+                    hatch='\\\\\\', edgecolor='black', label=DATA['names'][3])
+    ax.fill_between(time_arr, np.zeros_like(DATA['pub_by_month'][3, :]), np.cumsum(DATA['pub_by_month'][3, :]), color=colors[1],
+                    facecolor='none', edgecolor='white', linewidth=2) # To visually "erase" the border.
+    ax.fill_between(time_arr, np.zeros_like(DATA['pub_by_month'][2, :]), np.cumsum(DATA['pub_by_month'][2, :]), color=colors[0],
+                    hatch='///', edgecolor='black', label=DATA['names'][2])
+    ax.fill_between(time_arr, np.zeros_like(DATA['pub_by_month'][2, :]), np.cumsum(DATA['pub_by_month'][2, :]), color=colors[0],
+                    facecolor='none', edgecolor='white', linewidth=2) # To visually "erase" the border.
+    ax.plot(time_arr, np.cumsum(DATA['pub_by_month'][2, :]), lw=3, c=colors[2])
+    ax.plot(time_arr, np.cumsum(DATA['pub_by_month'][3, :]), lw=3, c=colors[3])
+    ax.legend(frameon=False)
+    mark_events(ax, time_arr, np.cumsum(DATA['pub_by_month'][3, :]), DATA['dates_vlm'])
+    ax.set_xticks(time_arr[2::6])
+    ax.set_ylim([0, 24])
+    ax.set_ylabel('Cumulative\nPublication Count\n(Multimodal)')
+
+    fig.tight_layout(pad=2)
+    fig.savefig(fig_name, dpi=300)
+    return
+
+
+if __name__ == '__main__':
+    plot_curve('./figures/trend_by_month.png')

package/skills/13_Visualization/nature-figure/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "skill_name": "nature-figure",
+  "evals": [
+    {
+      "id": "backend-exclusivity-r-missing-runtime",
+      "prompt": "Use R to remake the provided ecological heatmap plus taxonomy-flow figure in Nature style with simulated data. Assume R/Rscript is not installed locally.",
+      "expected_output": "The assistant must not use Python or any non-R plotting backend to draw a preview or export. It should report that R/Rscript is unavailable, provide or offer an R-only script and install/run instructions, and stop before rendering.",
+      "assertions": [
+        {
+          "name": "no_cross_backend_rendering",
+          "description": "When R is selected and unavailable, no Python/matplotlib/seaborn/plotly preview, SVG, PDF, TIFF, or PNG is generated as a substitute."
+        },
+        {
+          "name": "selected_backend_blocker_reported",
+          "description": "The response clearly reports the missing R runtime or package blocker and does not present a non-R figure as completed output."
+        }
+      ],
+      "files": []
+    },
+    {
+      "id": "backend-exclusivity-python-missing-package",
+      "prompt": "Use Python to make a Nature-style multi-panel heatmap and flow figure with simulated data. Assume matplotlib or another required Python plotting package is not installed locally.",
+      "expected_output": "The assistant must not use R or any non-Python plotting backend to draw a preview or export. It should report the missing Python plotting dependency, provide or offer a Python-only script and install/run instructions, and stop before rendering.",
+      "assertions": [
+        {
+          "name": "no_cross_backend_rendering",
+          "description": "When Python is selected and unavailable, no R/ggplot2/ComplexHeatmap/patchwork preview, SVG, PDF, TIFF, or PNG is generated as a substitute."
+        },
+        {
+          "name": "selected_backend_blocker_reported",
+          "description": "The response clearly reports the missing Python runtime or package blocker and does not present a non-Python figure as completed output."
+        }
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/13_Visualization/nature-figure/manifest.yaml

@@ -0,0 +1,57 @@
+name: nature-figure
+version: 2.0.0
+description: >
+  Declarative manifest for the static/dynamic split. SKILL.md uses this to
+  decide which fragments to load for a given figure request. The main axis is
+  the plotting backend (Python or R), which is a blocking gate: it must be
+  chosen explicitly before any figure is drawn. The large body of design,
+  API, pattern, and QA material stays in on-demand references.
+
+always_load:
+  # Skill-local core (figure does not use the prose-oriented _shared layer)
+  - static/core/contract.md
+  - static/core/stance.md
+
+axes:
+  backend:
+    detect: |
+      BLOCKING GATE. Determine the plotting backend from an explicit user
+      choice or a clearly language-specific input file/workflow. If the user
+      has NOT explicitly chosen Python or R, ask exactly one concise question —
+      "Python or R?" — and stop. Do not default, do not guess, do not generate
+      mock data or scripts before the answer. Only recommend a backend when the
+      user explicitly asks you to choose; in that case use
+      references/backend-selection.md, state the reason, then proceed.
+      Once selected, the backend is exclusive for all drawing, previewing,
+      exporting, and visual QA.
+    values:
+      python:  static/fragments/backend/python.md
+      r:       static/fragments/backend/r.md
+    multi: false
+
+references:
+  on_demand:
+    - condition: convert a user request into core conclusion, evidence hierarchy, panel map, and review-risk checks
+      path: references/figure-contract.md
+    - condition: user has not chosen Python/R, asks for a recommendation, or a mixed Python/R workflow is possible
+      path: references/backend-selection.md
+    - condition: user chooses R or provides R scripts/templates/data
+      path: references/r-workflow.md
+    - condition: adapt a user-provided or private R template collection without exposing source paths
+      path: references/r-template-index.md
+    - condition: before final delivery, revision package, microscopy/blot figure, or journal-specific audit
+      path: references/qa-contract.md
+    - condition: typography, color theory, layout rationale, export policy
+      path: references/design-theory.md
+    - condition: Python PALETTE, helper function signatures, validation rules
+      path: references/api.md
+    - condition: "Python layout patterns: hero panels, legend-only axes, dark image plates, asymmetric layouts"
+      path: references/common-patterns.md
+    - condition: "real Nature page archetypes: schematic-led composites, dark image plates, clinical triptychs, asymmetric hero layouts"
+      path: references/nature-2026-observations.md
+    - condition: "end-to-end walkthroughs: bars, trends, heatmaps"
+      path: references/tutorials.md
+    - condition: "radar, 3D sphere, fill_between, scatter patterns"
+      path: references/chart-types.md
+    - condition: bundled figures4papers Python scripts and output previews for concrete pattern adaptation
+      path: references/demos.md

package/skills/13_Visualization/nature-figure/references/api.md

@@ -0,0 +1,428 @@
+# API Reference — Nature Figure Making
+
+Conventions, constants, and reusable code blocks. Implement in your script or adapt as needed.
+
+---
+
+## Constants
+
+### PALETTE
+
+```python
+PALETTE = {
+    "blue_main":      "#0F4D92",
+    "blue_secondary": "#3775BA",
+    "green_1": "#DDF3DE",
+    "green_2": "#AADCA9",
+    "green_3": "#8BCF8B",
+    "red_1":   "#F6CFCB",
+    "red_2":   "#E9A6A1",
+    "red_strong": "#B64342",
+    "neutral_light": "#CFCECE",
+    "neutral_mid":   "#767676",
+    "neutral_dark":  "#4D4D4D",
+    "neutral_black": "#272727",
+    "gold":   "#FFD700",
+    "teal":   "#42949E",
+    "violet": "#9A4D8E",
+    "magenta":"#EA84DD",
+}
+
+DEFAULT_COLORS = [
+    PALETTE["blue_main"],
+    PALETTE["green_3"],
+    PALETTE["red_strong"],
+    PALETTE["teal"],
+    PALETTE["violet"],
+    PALETTE["neutral_light"],
+]
+
+PALETTE_NMI_PASTEL = {
+    "baseline_dark": "#484878",
+    "baseline_mid":  "#7884B4",
+    "baseline_soft": "#B4C0E4",
+    "ours_tiny":  "#E4E4F0",
+    "ours_base":  "#E4CCD8",
+    "ours_large": "#F0C0CC",
+    "bg_lilac": "#E0E0F0",
+    "bg_aqua":  "#E0F0F0",
+    "bg_peach": "#F0E0D0",
+    "neutral_light": "#D8D8D8",
+    "neutral_mid":   "#A8A8A8",
+    "neutral_dark":  "#606060",
+    "delta_up":   "#2E9E44",
+    "delta_down": "#E53935",
+}
+
+DEFAULT_COLORS_NMI_PASTEL = [
+    PALETTE_NMI_PASTEL["baseline_dark"],
+    PALETTE_NMI_PASTEL["baseline_mid"],
+    PALETTE_NMI_PASTEL["baseline_soft"],
+    PALETTE_NMI_PASTEL["ours_tiny"],
+    PALETTE_NMI_PASTEL["ours_base"],
+    PALETTE_NMI_PASTEL["ours_large"],
+]
+
+PALETTE_NATURE_IMAGING = {
+    "bg": "#000000",
+    "context": "#B8B8B8",
+    "cyan": "#22D7E6",
+    "magenta": "#FF2AD4",
+    "white": "#FFFFFF",
+}
+
+PALETTE_NATURE_MATERIAL = {
+    "aqua": "#77D7D1",
+    "teal": "#33B5A5",
+    "lilac": "#B9A7E8",
+    "violet": "#7C6CCF",
+    "callout_red": "#E53935",
+    "neutral": "#D9D9D9",
+}
+
+PALETTE_NATURE_CLINICAL = {
+    "baseline": "#272727",
+    "week6": "#E28E2C",
+    "week13": "#D24B40",
+    "week26": "#5B8FD6",
+    "year1": "#7BAA5B",
+    "year2": "#C45AD6",
+    "group_band": "#F2E6D9",
+}
+
+PALETTE_NATURE_GENOMICS = {
+    "neutral_light": "#D8D8D8",
+    "neutral_mid": "#8F8F8F",
+    "wave1": "#D9544D",
+    "wave2": "#5B7FCA",
+    "wave3": "#B89BD9",
+    "outline": "#4D4D4D",
+}
+```
+
+Use `DEFAULT_COLORS` when color itself carries explicit semantic meaning (`hero`, `baseline`, `positive variant`).
+Use `DEFAULT_COLORS_NMI_PASTEL` when several compared methods belong to one or two related families and the page
+should feel visually unified.
+
+---
+
+## MANDATORY font + SVG rules (always first, no exceptions)
+
+These three lines are **non-negotiable** and must appear at the top of every script,
+before any figure is created. They guarantee editable text in SVG output:
+
+```python
+plt.rcParams['font.family'] = 'sans-serif'
+plt.rcParams['font.sans-serif'] = ['Arial', 'DejaVu Sans', 'Liberation Sans']
+plt.rcParams['svg.fonttype'] = 'none'   # keeps text as <text> nodes, not paths
+```
+
+**Why `svg.fonttype = 'none'`**: matplotlib's default (`'path'`) converts every
+glyph to a bezier path, making text unselectable, unsearchable, and impossible to
+re-align in Illustrator / Inkscape. With `'none'`, text stays as SVG `<text>` elements
+and font substitution happens at render time.
+
+**Output format**: always save as `.svg` (primary). PNG/PDF are optional secondary
+exports. Never use `.png` alone when the figure contains text that may need adjustment.
+
+---
+
+## apply_publication_style()
+
+```python
+def apply_publication_style(font_size=16, axes_linewidth=2.5, use_tex=False):
+    """Apply Nature-style rcParams. Call once before creating any figures."""
+    # ── MANDATORY: editable SVG text ──────────────────────────────────────────
+    plt.rcParams['font.family'] = 'sans-serif'
+    plt.rcParams['font.sans-serif'] = ['Arial', 'DejaVu Sans', 'Liberation Sans']
+    plt.rcParams['svg.fonttype'] = 'none'
+    # ── Layout & style ────────────────────────────────────────────────────────
+    plt.rcParams['font.size'] = font_size
+    plt.rcParams['axes.spines.right'] = False
+    plt.rcParams['axes.spines.top'] = False
+    plt.rcParams['axes.linewidth'] = axes_linewidth
+    plt.rcParams['legend.frameon'] = False
+    if use_tex:
+        plt.rcParams['text.usetex'] = True
+```
+
+**Presets:**
+- Large bar panels: `apply_publication_style(font_size=24, axes_linewidth=3)`
+- Compact figures: `apply_publication_style(font_size=15, axes_linewidth=2)`
+- Dense journal-width multi-panels: `apply_publication_style(font_size=8, axes_linewidth=1)`
+- LaTeX labels: `apply_publication_style(use_tex=True)`
+
+---
+
+## is_dark(hex_color, threshold=128)
+
+```python
+def is_dark(hex_color, threshold=128):
+    """Return True if hex color is dark (use white text on it)."""
+    c = hex_color.lstrip('#')
+    r, g, b = int(c[0:2], 16), int(c[2:4], 16), int(c[4:6], 16)
+    return (0.299*r + 0.587*g + 0.114*b) < threshold
+```
+
+---
+
+## add_panel_label(ax, label, ...)
+
+```python
+def add_panel_label(ax, label, x=-0.06, y=1.02, fontsize=14,
+                    color='black', fontweight='bold'):
+    """Place a Nature-style panel label near the top-left edge."""
+    ax.text(
+        x, y, label,
+        transform=ax.transAxes,
+        fontsize=fontsize,
+        fontweight=fontweight,
+        color=color,
+        ha='left',
+        va='bottom',
+    )
+```
+
+For dark image plates, move the label inside the panel and switch to white:
+`add_panel_label(ax, 'a', x=0.01, y=0.98, color='white')`
+
+---
+
+## style_dark_image_ax(ax, ...)
+
+```python
+def style_dark_image_ax(ax, facecolor='black'):
+    """Prepare an axes for microscopy / rendering plates."""
+    ax.set_facecolor(facecolor)
+    ax.set_xticks([])
+    ax.set_yticks([])
+    for spine in ax.spines.values():
+        spine.set_visible(False)
+    return ax
+```
+
+---
+
+## make_grouped_bar(ax, categories, series, labels, ...)
+
+```python
+def make_grouped_bar(ax, categories, series, labels,
+                     ylabel='Value', colors=None,
+                     annotate=False, bar_width=0.8,
+                     error_kw=None):
+    """
+    Grouped bar chart.
+
+    Parameters
+    ----------
+    ax         : matplotlib Axes
+    categories : list[str]  — x-axis category names (length K)
+    series     : list[array] — one array per group (each length K)
+    labels     : list[str]  — legend label per group
+    ylabel     : str
+    colors     : list[str] | None  — defaults to DEFAULT_COLORS; override with
+                                     DEFAULT_COLORS_NMI_PASTEL for unified-family figures
+    annotate   : bool  — print value above each bar
+    bar_width  : float — total width for all bars in one category
+    error_kw   : dict  — passed to ax.bar as error_kw
+
+    Returns
+    -------
+    list[BarContainer]
+    """
+    import numpy as np
+    if colors is None:
+        colors = DEFAULT_COLORS
+    if error_kw is None:
+        error_kw = {'elinewidth': 2, 'capthick': 2, 'capsize': 10}
+    n_groups = len(series)
+    n_cats = len(categories)
+    w = bar_width / n_groups
+    x = np.arange(n_cats)
+    containers = []
+    for i, (vals, label, color) in enumerate(zip(series, labels, colors)):
+        offset = (i - (n_groups - 1) / 2) * w
+        bars = ax.bar(x + offset, vals, width=w, label=label,
+                      color=color, edgecolor='black', linewidth=1.5,
+                      error_kw=error_kw)
+        containers.append(bars)
+        if annotate:
+            for bar, val in zip(bars, vals):
+                ax.text(bar.get_x() + bar.get_width() / 2,
+                        bar.get_height() + 0.01,
+                        f'{val:.2f}', ha='center', va='bottom', fontsize=10)
+    ax.set_xticks(x)
+    ax.set_xticklabels(categories)
+    ax.set_ylabel(ylabel)
+    ax.legend()
+    return containers
+```
+
+---
+
+## make_trend(ax, x, y_series, labels, ...)
+
+```python
+def make_trend(ax, x, y_series, labels,
+               colors=None, ylabel=None, xlabel=None,
+               show_shadow=False, shadow_alpha=0.15,
+               lw=2.5, marker='o', markersize=8):
+    """
+    Multi-line trend plot.
+
+    Parameters
+    ----------
+    x        : array-like   — shared x values
+    y_series : list[array]  — one 1D array per line
+    labels   : list[str]
+    show_shadow : bool  — fill_between ± std if y_series contains 2D arrays (rows=runs)
+    """
+    import numpy as np
+    if colors is None:
+        colors = DEFAULT_COLORS
+    for y, label, color in zip(y_series, labels, colors):
+        y = np.asarray(y)
+        if y.ndim == 2:
+            mean, std = y.mean(0), y.std(0)
+        else:
+            mean, std = y, None
+        ax.plot(x, mean, color=color, lw=lw, marker=marker,
+                markersize=markersize, label=label)
+        if show_shadow and std is not None:
+            ax.fill_between(x, mean - std, mean + std,
+                            color=color, alpha=shadow_alpha)
+    if ylabel:
+        ax.set_ylabel(ylabel)
+    if xlabel:
+        ax.set_xlabel(xlabel)
+    ax.legend()
+```
+
+---
+
+## make_forest_plot(ax, labels, estimates, ci_low, ci_high, ...)
+
+```python
+def make_forest_plot(ax, labels, estimates, ci_low, ci_high,
+                     colors=None, ref=0.0, xlabel=None, xlim=None,
+                     marker='o', markersize=5, lw=1.5):
+    """
+    Minimal forest plot helper for Nature-style clinical/statistical panels.
+    """
+    import numpy as np
+    y = np.arange(len(labels))[::-1]
+    if colors is None:
+        colors = ['#B64342'] * len(labels)
+    for yi, est, lo, hi, color in zip(y, estimates, ci_low, ci_high, colors):
+        ax.plot([lo, hi], [yi, yi], color=color, lw=lw)
+        ax.plot(est, yi, marker=marker, ms=markersize, color=color)
+    ax.axvline(ref, color='#767676', linestyle='--', linewidth=1.2, alpha=0.8)
+    ax.set_yticks(y)
+    ax.set_yticklabels(labels)
+    if xlabel:
+        ax.set_xlabel(xlabel)
+    if xlim is not None:
+        ax.set_xlim(xlim)
+    ax.spines['right'].set_visible(False)
+    ax.spines['top'].set_visible(False)
+```
+
+Use pale `ax.axhspan(...)` bands behind contiguous label groups when you need the
+clinical-triptych look from `Nature`.
+
+---
+
+## make_heatmap(ax, matrix, ...)
+
+```python
+def make_heatmap(ax, matrix, x_labels=None, y_labels=None,
+                 cmap='magma', cbar_label=None, annotate=False,
+                 fmt='{:.2f}', fontsize=12):
+    """
+    2D heatmap with optional colorbar and cell annotations.
+    """
+    import numpy as np
+    import matplotlib as mpl
+    im = ax.imshow(matrix, cmap=cmap, aspect='auto')
+    if cbar_label:
+        cbar = ax.figure.colorbar(im, ax=ax)
+        cbar.set_label(cbar_label)
+    if x_labels:
+        ax.set_xticks(range(len(x_labels)))
+        ax.set_xticklabels(x_labels, rotation=30, ha='right')
+    if y_labels:
+        ax.set_yticks(range(len(y_labels)))
+        ax.set_yticklabels(y_labels)
+    if annotate:
+        norm = mpl.colors.Normalize(vmin=matrix.min(), vmax=matrix.max())
+        cm_obj = plt.get_cmap(cmap)
+        for (i, j), val in np.ndenumerate(matrix):
+            r, g, b, _ = cm_obj(norm(val))
+            lum = 0.299*r + 0.587*g + 0.114*b
+            color = 'white' if lum < 0.5 else 'black'
+            ax.text(j, i, fmt.format(val), ha='center', va='center',
+                    fontsize=fontsize, color=color)
+    ax.set_frame_on(False)
+```
+
+---
+
+## finalize_figure(fig, out_path, ...)
+
+```python
+def finalize_figure(fig, out_path, formats=None, dpi=300,
+                    pad=2, bbox_inches=None, close=True):
+    """
+    Apply tight_layout and save figure.
+
+    Parameters
+    ----------
+    out_path : str   — path without extension, or with extension
+    formats  : list  — e.g. ['png', 'pdf']. If None, uses extension of out_path.
+    dpi      : int   — 300 standard, 600 for dense bar panels
+    pad      : float — tight_layout pad (2 default, 1 for compact multi-panel)
+    """
+    import os
+    from pathlib import Path
+    fig.tight_layout(pad=pad)
+    base = Path(out_path)
+    os.makedirs(base.parent, exist_ok=True)
+    if formats is None:
+        formats = [base.suffix.lstrip('.') or 'png']
+        base = base.with_suffix('')
+    saved = []
+    for fmt in formats:
+        p = str(base) + f'.{fmt}'
+        kw = {}
+        if bbox_inches is not None:
+            kw['bbox_inches'] = bbox_inches
+        fig.savefig(p, dpi=dpi, **kw)
+        saved.append(p)
+    if close:
+        plt.close(fig)
+    return saved
+```
+
+---
+
+## Validation Rules
+
+- `make_grouped_bar`: `len(categories)` must equal length of each array in `series`.
+- `make_trend`: each array in `y_series` must have same length as `x`.
+- `make_heatmap`: `matrix` must be 2D; `x_labels` length = `matrix.shape[1]`; `y_labels` length = `matrix.shape[0]`.
+- `finalize_figure`: supported formats — `png`, `pdf`, `svg`, `eps`, `jpg`, `tif`.
+
+---
+
+## Conventions
+
+- Save outputs under `./figures/` (or path given by user); `finalize_figure` creates parent dirs.
+- In headless / batch runs, set non-interactive backend before importing pyplot:
+  ```python
+  import matplotlib
+  matplotlib.use('Agg')
+  import matplotlib.pyplot as plt
+  ```
+- Always `plt.close(fig)` after saving to free memory.
+- For multi-panel figures, prefer one baseline family plus one hero family; reserve green/red for delta cues.
+- When color roles, resolution, or layout are underspecified and would change the figure, confirm with user before finalizing.