@r1z4x/tezgah 1.0.0

package/skills/ai-research/20-ml-paper-writing/academic-plotting/references/data-visualization.md

@@ -0,0 +1,509 @@
+<!-- vendored from orchestra-research/AI-research-SKILLs@773a52944ba4747a18bd4ae9ade53fff041adcbc 20-ml-paper-writing/academic-plotting/references/data-visualization.md; MIT (c) Orchestra Research -->
+# Data Visualization Patterns for ML Papers
+
+Complete pattern library for generating polished, distinctive figures.
+
+## Setup and Imports
+
+```python
+import matplotlib.pyplot as plt
+import matplotlib as mpl
+import numpy as np
+import seaborn as sns
+from matplotlib.ticker import MaxNLocator, FuncFormatter
+
+# --- Publication defaults (polished, not generic) ---
+plt.rcParams.update({
+    "font.family": "serif",
+    "font.serif": ["Times New Roman", "DejaVu Serif"],
+    "font.size": 10,
+    "axes.titlesize": 11,
+    "axes.titleweight": "bold",
+    "axes.labelsize": 10,
+    "axes.labelweight": "medium",
+    "xtick.labelsize": 8.5,
+    "ytick.labelsize": 8.5,
+    "legend.fontsize": 8.5,
+    "legend.frameon": False,
+    "figure.dpi": 300,
+    "savefig.dpi": 300,
+    "savefig.bbox": "tight",
+    "savefig.pad_inches": 0.08,
+    "axes.spines.top": False,
+    "axes.spines.right": False,
+    "axes.linewidth": 0.8,
+    "xtick.major.width": 0.8,
+    "ytick.major.width": 0.8,
+    "axes.grid": True,
+    "grid.alpha": 0.15,        # Very subtle — guides the eye without competing
+    "grid.linewidth": 0.6,
+    "grid.linestyle": "-",      # Solid but faint, not dashed (less visual noise)
+    "lines.linewidth": 1.8,
+    "lines.markersize": 5,
+    "patch.edgecolor": "white",  # White borders between bars (cleaner look)
+    "patch.linewidth": 0.5,
+})
+```
+
+## Color Palettes
+
+### "Ocean Dusk" (default — professional, distinctive)
+
+```python
+COLORS = {
+    "teal":    "#264653",   # deep, authoritative
+    "cyan":    "#2A9D8F",   # fresh, modern
+    "gold":    "#E9C46A",   # warm accent
+    "orange":  "#F4A261",   # energetic
+    "coral":   "#E76F51",   # standout (use for "our method")
+    "blue":    "#0072B2",   # Okabe-Ito accessible blue
+    "sky":     "#56B4E9",   # Okabe-Ito accessible sky
+    "gray":    "#8C8C8C",   # neutral baseline
+}
+COLOR_LIST = list(COLORS.values())
+
+# Semantic colors for highlighting
+OUR_COLOR = "#E76F51"       # coral — warm, draws attention
+BASELINE_COLOR = "#B0BEC5"  # cool gray — recedes
+BEST_BASELINE = "#264653"   # deep teal — strongest competitor
+```
+
+### "Okabe-Ito" (maximum colorblind safety)
+
+```python
+OKABE_ITO = ["#E69F00", "#56B4E9", "#009E73", "#F0E442",
+             "#0072B2", "#D55E00", "#CC79A7", "#000000"]
+```
+
+### Sequential Palettes (for heatmaps)
+
+```python
+# Warm sequential (more interesting than plain Blues)
+cmap_warm = sns.color_palette("YlOrRd", as_cmap=True)
+
+# Cool sequential (clean, professional)
+cmap_cool = sns.light_palette("#264653", as_cmap=True)
+
+# Diverging (for correlation/difference, centered at 0)
+cmap_div = sns.color_palette("RdBu_r", as_cmap=True)
+
+# Perceptually uniform (for continuous scientific data)
+cmap_viridis = plt.cm.viridis
+```
+
+### Making Charts Visually Distinctive
+
+Common mistakes that make charts look "boring" and their fixes:
+
+| Boring Default | Better Version |
+|---------------|---------------|
+| Black lines, no markers | Colored lines + distinct markers per method |
+| No shading around lines | Confidence bands with `fill_between(alpha=0.12)` |
+| Generic blue bars | "Ocean Dusk" palette + white edge between bars |
+| All same color baselines | Gray baselines + coral highlight for "ours" |
+| Dashed grid lines | Very faint solid grid (`alpha=0.15`) |
+| Default tight spacing | `pad_inches=0.08`, generous axis margins |
+| No value labels on bars | Small value text above each bar |
+| Box legend with frame | Frameless legend, positioned inside plot area |
+
+## Figure Sizes by Venue
+
+```python
+# NeurIPS / ICLR (single column, 5.5in text width)
+FIG_NEURIPS_SINGLE = (5.5, 3.5)
+FIG_NEURIPS_HALF = (2.65, 2.5)
+
+# ICML (two column, 6.75in text width)
+FIG_ICML_SINGLE = (3.25, 2.5)
+FIG_ICML_FULL = (6.75, 2.5)
+
+# ACL (two column, 6.8in text width)
+FIG_ACL_SINGLE = (3.3, 2.5)
+FIG_ACL_FULL = (6.8, 3.0)
+
+# General safe default
+FIG_DEFAULT = (5, 3.5)
+```
+
+## Chart Type 1: Training Curves (Line Plot)
+
+The most common figure in ML papers. Shows loss/accuracy over training steps.
+
+```python
+def plot_training_curves(data, metric="Loss", save_path="figures/fig_training.pdf"):
+    """
+    data: dict of {method_name: (steps_array, values_array)}
+    """
+    fig, ax = plt.subplots(figsize=FIG_ICML_SINGLE)
+
+    markers = ["o", "s", "^", "D", "v", "P"]
+    for i, (method, (steps, values)) in enumerate(data.items()):
+        ax.plot(steps, values,
+                label=method,
+                color=COLOR_LIST[i],
+                linewidth=1.5,
+                marker=markers[i % len(markers)],
+                markevery=max(1, len(steps) // 8),
+                markersize=4)
+
+    ax.set_xlabel("Training Steps")
+    ax.set_ylabel(metric)
+    ax.legend(frameon=False, loc="best")
+
+    # Log scale for loss (common)
+    if "loss" in metric.lower():
+        ax.set_yscale("log")
+
+    fig.savefig(save_path)
+    fig.savefig(save_path.replace(".pdf", ".png"), dpi=300)
+    plt.close(fig)
+```
+
+### Shaded Confidence Intervals
+
+```python
+ax.plot(steps, mean_values, color=COLOR_LIST[0], linewidth=1.5, label="Our Method")
+ax.fill_between(steps, mean_values - std_values, mean_values + std_values,
+                color=COLOR_LIST[0], alpha=0.2)
+```
+
+## Chart Type 2: Grouped Bar Chart (Ablation / Comparison)
+
+```python
+def plot_ablation(categories, methods_data, ylabel="Accuracy (%)",
+                  save_path="figures/fig_ablation.pdf"):
+    """
+    categories: list of benchmark names
+    methods_data: dict of {method_name: list_of_scores}
+    """
+    fig, ax = plt.subplots(figsize=FIG_ICML_FULL)
+
+    n_methods = len(methods_data)
+    n_cats = len(categories)
+    width = 0.8 / n_methods
+    x = np.arange(n_cats)
+
+    for i, (method, scores) in enumerate(methods_data.items()):
+        offset = (i - n_methods / 2 + 0.5) * width
+        bars = ax.bar(x + offset, scores, width * 0.9,
+                      label=method, color=COLOR_LIST[i])
+        # Value labels on top
+        for bar, score in zip(bars, scores):
+            ax.text(bar.get_x() + bar.get_width() / 2, bar.get_height() + 0.3,
+                    f"{score:.1f}", ha="center", va="bottom", fontsize=7)
+
+    ax.set_xticks(x)
+    ax.set_xticklabels(categories, rotation=0)
+    ax.set_ylabel(ylabel)
+    ax.legend(frameon=False, ncol=min(n_methods, 4), loc="upper right")
+    ax.set_ylim(bottom=0)
+
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+## Chart Type 3: Heatmap (Attention / Confusion Matrix)
+
+```python
+def plot_heatmap(matrix, xlabels, ylabels, title="",
+                 save_path="figures/fig_heatmap.pdf", fmt=".2f", cmap="Blues"):
+    """
+    matrix: 2D numpy array
+    """
+    fig, ax = plt.subplots(figsize=(max(4, len(xlabels) * 0.6), max(3, len(ylabels) * 0.5)))
+
+    sns.heatmap(matrix, annot=True, fmt=fmt, cmap=cmap, ax=ax,
+                xticklabels=xlabels, yticklabels=ylabels,
+                cbar_kws={"shrink": 0.8}, linewidths=0.5, linecolor="white",
+                annot_kws={"size": 8})
+
+    ax.set_xticklabels(ax.get_xticklabels(), rotation=45, ha="right")
+    if title:
+        ax.set_title(title, pad=12)
+
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+### Diverging Heatmap (correlation)
+
+```python
+sns.heatmap(corr_matrix, annot=True, fmt=".2f", cmap="RdBu_r",
+            center=0, vmin=-1, vmax=1, ax=ax)
+```
+
+## Chart Type 4: Scatter Plot
+
+```python
+def plot_scatter(x, y, labels=None, xlabel="", ylabel="",
+                 save_path="figures/fig_scatter.pdf"):
+    fig, ax = plt.subplots(figsize=FIG_ICML_SINGLE)
+
+    scatter = ax.scatter(x, y, c=COLOR_LIST[0], s=30, alpha=0.7, edgecolors="white", linewidth=0.5)
+
+    if labels is not None:
+        for i, label in enumerate(labels):
+            ax.annotate(label, (x[i], y[i]), fontsize=7,
+                        xytext=(5, 5), textcoords="offset points")
+
+    ax.set_xlabel(xlabel)
+    ax.set_ylabel(ylabel)
+
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+### Scatter with regression line
+
+```python
+from scipy import stats
+slope, intercept, r_value, p_value, std_err = stats.linregress(x, y)
+line_x = np.linspace(min(x), max(x), 100)
+ax.plot(line_x, slope * line_x + intercept, color=COLOR_LIST[1],
+        linestyle="--", linewidth=1, label=f"$R^2$={r_value**2:.3f}")
+```
+
+## Chart Type 5: Horizontal Bar (Leaderboard)
+
+```python
+def plot_leaderboard(models, scores, highlight_idx=-1, xlabel="Score",
+                     save_path="figures/fig_leaderboard.pdf"):
+    """highlight_idx: index of 'our method' to highlight"""
+    fig, ax = plt.subplots(figsize=FIG_ICML_SINGLE)
+
+    y_pos = np.arange(len(models))
+    colors = [COLORS["gray"]] * len(models)
+    if highlight_idx >= 0:
+        colors[highlight_idx] = COLORS["red"]
+
+    bars = ax.barh(y_pos, scores, color=colors, height=0.6)
+    ax.set_yticks(y_pos)
+    ax.set_yticklabels(models)
+    ax.set_xlabel(xlabel)
+    ax.invert_yaxis()
+
+    # Value labels
+    for bar, score in zip(bars, scores):
+        ax.text(bar.get_width() + 0.3, bar.get_y() + bar.get_height() / 2,
+                f"{score:.1f}", va="center", fontsize=8)
+
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+## Chart Type 6: Multi-Panel Figure
+
+```python
+def plot_multi_panel(data_per_panel, panel_titles, save_path="figures/fig_panels.pdf"):
+    """Create a 1xN figure with shared styling."""
+    n = len(data_per_panel)
+    fig, axes = plt.subplots(1, n, figsize=(3.25 * n, 2.5), sharey=True)
+    if n == 1:
+        axes = [axes]
+
+    for ax, data, title in zip(axes, data_per_panel, panel_titles):
+        # Plot each panel (customize per use case)
+        ax.set_title(title, fontsize=10, fontweight="bold")
+
+    # Only label left y-axis
+    axes[0].set_ylabel("Metric")
+
+    # Shared x-label
+    fig.supxlabel("Training Steps", fontsize=11)
+    fig.tight_layout()
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+### Subplot label convention (a, b, c)
+
+```python
+for i, ax in enumerate(axes):
+    ax.text(-0.12, 1.05, f"({chr(97 + i)})", transform=ax.transAxes,
+            fontsize=12, fontweight="bold", va="top")
+```
+
+## Chart Type 7: Violin / Box Plot (Distribution)
+
+```python
+def plot_distributions(data_dict, ylabel="Score",
+                       save_path="figures/fig_distributions.pdf"):
+    """data_dict: {method_name: array_of_values}"""
+    fig, ax = plt.subplots(figsize=FIG_ICML_SINGLE)
+
+    positions = range(len(data_dict))
+    parts = ax.violinplot(list(data_dict.values()), positions=positions,
+                          showmeans=True, showmedians=True)
+
+    for i, pc in enumerate(parts["bodies"]):
+        pc.set_facecolor(COLOR_LIST[i])
+        pc.set_alpha(0.7)
+
+    ax.set_xticks(positions)
+    ax.set_xticklabels(list(data_dict.keys()))
+    ax.set_ylabel(ylabel)
+
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+## Chart Type 8: Stacked Horizontal Bar
+
+Preferred over pie charts in ML papers for showing proportions:
+
+```python
+def plot_stacked_bar(categories, segments, segment_labels, colors=None,
+                     save_path="figures/fig_stacked.pdf"):
+    """
+    categories: list of row labels
+    segments: list of lists (each inner list = values per segment)
+    """
+    fig, ax = plt.subplots(figsize=FIG_ICML_FULL)
+    y_pos = np.arange(len(categories))
+    colors = colors or COLOR_LIST
+
+    left = np.zeros(len(categories))
+    for i, (seg_values, label) in enumerate(zip(segments, segment_labels)):
+        ax.barh(y_pos, seg_values, left=left, height=0.6,
+                label=label, color=colors[i])
+        # Percentage labels
+        for j, v in enumerate(seg_values):
+            if v > 5:  # Only label segments > 5%
+                ax.text(left[j] + v / 2, y_pos[j], f"{v:.0f}%",
+                        ha="center", va="center", fontsize=7, color="white")
+        left += seg_values
+
+    ax.set_yticks(y_pos)
+    ax.set_yticklabels(categories)
+    ax.set_xlabel("Percentage (%)")
+    ax.legend(frameon=False, loc="upper right", ncol=2)
+    ax.invert_yaxis()
+
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+## Chart Type 9: Scaling Law Plot (Log-Log)
+
+Common in LLM papers for compute/data/parameter scaling:
+
+```python
+def plot_scaling(sizes, metrics, fit_line=True, xlabel="Parameters",
+                 ylabel="Loss", save_path="figures/fig_scaling.pdf"):
+    fig, ax = plt.subplots(figsize=FIG_ICML_SINGLE)
+
+    ax.scatter(sizes, metrics, color=COLOR_LIST[0], s=40, zorder=5)
+
+    if fit_line:
+        log_sizes = np.log(sizes)
+        log_metrics = np.log(metrics)
+        coeffs = np.polyfit(log_sizes, log_metrics, 1)
+        fit_x = np.linspace(min(log_sizes), max(log_sizes), 100)
+        ax.plot(np.exp(fit_x), np.exp(np.polyval(coeffs, fit_x)),
+                color=COLOR_LIST[1], linestyle="--", linewidth=1.5,
+                label=f"$L \\propto N^{{{coeffs[0]:.2f}}}$")
+
+    ax.set_xscale("log")
+    ax.set_yscale("log")
+    ax.set_xlabel(xlabel)
+    ax.set_ylabel(ylabel)
+    if fit_line:
+        ax.legend(frameon=False)
+
+    fig.savefig(save_path)
+    plt.close(fig)
+```
+
+## Export Best Practices
+
+### Always Export Both Formats
+
+```python
+# PDF for LaTeX (vector, crisp at any zoom)
+fig.savefig("figures/fig_name.pdf", bbox_inches="tight", pad_inches=0.05)
+
+# PNG as backup (raster, for README/slides)
+fig.savefig("figures/fig_name.png", dpi=300, bbox_inches="tight", pad_inches=0.05)
+```
+
+### LaTeX Font Matching
+
+```python
+# Option A: Use LaTeX renderer (requires texlive installation)
+plt.rcParams["text.usetex"] = True
+plt.rcParams["font.family"] = "serif"
+
+# Option B: Match sans-serif style without LaTeX
+plt.rcParams["text.usetex"] = False
+plt.rcParams["font.family"] = "sans-serif"
+plt.rcParams["font.sans-serif"] = ["Helvetica", "Arial", "DejaVu Sans"]
+
+# Option C: Computer Modern (default LaTeX font, no LaTeX needed)
+plt.rcParams["font.family"] = "serif"
+plt.rcParams["font.serif"] = ["cmr10"]
+plt.rcParams["axes.formatter.use_mathtext"] = True
+```
+
+### Math in Labels
+
+```python
+# LaTeX math in labels (works with text.usetex=True)
+ax.set_xlabel(r"$\alpha$ (learning rate)")
+ax.set_ylabel(r"$\mathcal{L}$ (loss)")
+
+# Without usetex, use mathtext
+ax.set_xlabel(r"$\alpha$ (learning rate)")  # Still works for simple math
+```
+
+## Seaborn Integration
+
+Seaborn is built on matplotlib and useful for statistical plots:
+
+```python
+# Use seaborn styling with matplotlib control
+sns.set_theme(style="whitegrid", font_scale=0.9, rc={
+    "axes.spines.top": False,
+    "axes.spines.right": False,
+})
+
+# Pair plot (for exploratory analysis, not usually in papers)
+g = sns.pairplot(df, hue="method", palette=COLOR_LIST[:3])
+
+# Joint plot (scatter + marginal distributions)
+g = sns.jointplot(data=df, x="param_count", y="accuracy",
+                  kind="reg", color=COLOR_LIST[0])
+```
+
+## Reproducibility Script Template
+
+Every figure should have a self-contained generation script:
+
+```python
+#!/usr/bin/env python3
+"""Generate Figure X: [description].
+
+Usage: python figures/gen_fig_name.py
+Output: figures/fig_name.pdf, figures/fig_name.png
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+import os
+
+# --- Publication styling ---
+plt.rcParams.update({...})  # Full rcParams block
+
+# --- Data ---
+# Either inline data or load from CSV
+data = {...}
+
+# --- Plot ---
+fig, ax = plt.subplots(figsize=(3.25, 2.5))
+# ... plotting code ...
+
+# --- Save ---
+out_dir = os.path.dirname(os.path.abspath(__file__))
+fig.savefig(os.path.join(out_dir, "fig_name.pdf"))
+fig.savefig(os.path.join(out_dir, "fig_name.png"), dpi=300)
+plt.close(fig)
+print("Saved: fig_name.pdf, fig_name.png")
+```