@researai/deepscientist 1.5.17 → 1.6.0

package/src/skills/nature-figure/references/chart-types.md

@@ -0,0 +1,281 @@
+# Chart Types — Nature Figure Making
+
+Specialized chart patterns beyond basic bars and trends.
+Each section includes the key code pattern extracted from production scripts.
+
+---
+
+## Radar / Polar Chart
+
+Used when comparing multiple methods across many benchmarks simultaneously.
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+
+def plot_radar(methods, colors, subtask_names, value_matrix,
+               benchmark_radii, display_range=(45, 90)):
+    """
+    Parameters
+    ----------
+    methods        : list[str]    — one curve per method
+    colors         : list[str]
+    subtask_names  : list[str]    — one spoke per subtask (may contain '\\n')
+    value_matrix   : np.ndarray  — shape (n_subtasks, n_methods)
+    benchmark_radii: dict         — {benchmark_name: [tick1, tick2, ...]} for normalization
+    display_range  : (r_min, r_max) — polar radial display window
+    """
+    r_lo, r_hi = display_range
+    n_subtasks = len(subtask_names)
+    n_methods  = len(methods)
+
+    fig = plt.figure(figsize=(12, 10))
+    ax  = fig.add_subplot(111, projection='polar')
+
+    # Evenly spaced angles, clockwise from top
+    angles = np.linspace(2 * np.pi, 0, n_subtasks, endpoint=False)
+    angles_closed = np.append(angles, angles[0])
+
+    def _normalize(val, bench):
+        radii_list = benchmark_radii.get(bench, [0, 100])
+        span = max(radii_list) - min(radii_list)
+        if span <= 0:
+            return (r_lo + r_hi) / 2
+        frac = np.clip((val - min(radii_list)) / span, 0, 1)
+        return r_lo + (r_hi - r_lo) * frac
+
+    subtask_benchmarks = [s.split('\\n', 1)[-1] if '\\n' in s else s
+                          for s in subtask_names]
+
+    # Draw data polygons
+    for m in range(n_methods):
+        norm_vals = np.array([_normalize(value_matrix[i, m], subtask_benchmarks[i])
+                              for i in range(n_subtasks)])
+        closed = np.append(norm_vals, norm_vals[0])
+        ax.plot(angles_closed, closed, color=colors[m], lw=2, label=methods[m])
+        ax.fill(angles_closed, closed, color=colors[m], alpha=0.05)
+        ax.scatter(angles, norm_vals, color=colors[m], s=18, zorder=5)
+
+    # Style
+    ax.set_ylim(r_lo, r_hi)
+    ax.set_theta_zero_location('N')
+    for spine in ax.spines.values():
+        spine.set_visible(False)
+    ax.grid(False)
+
+    # Outer boundary ring
+    ax.plot(angles_closed, np.full_like(angles_closed, r_hi),
+            color='k', lw=0.8, zorder=4)
+
+    # Radial spokes
+    for a in angles:
+        ax.plot([a, a], [r_lo, r_hi], color='gray', lw=0.5, zorder=4)
+
+    # Benchmark-level contour polygons
+    max_levels = max(len(v) for v in benchmark_radii.values())
+    for k in range(max_levels):
+        disp = np.array([_normalize(benchmark_radii.get(b, [0,100])[
+                            min(k, len(benchmark_radii.get(b,[0,100]))-1)], b)
+                         for b in subtask_benchmarks])
+        ax.plot(angles_closed, np.append(disp, disp[0]),
+                color='k', lw=0.6, zorder=4)
+
+    ax.set_yticks([r_hi])
+    ax.set_yticklabels([])
+    ax.set_xticks(angles)
+    ax.set_xticklabels([])
+
+    # Spoke labels (outside outer ring)
+    for angle, label in zip(angles, subtask_names):
+        r_label = r_hi + 8 + 10 * abs(np.sin(angle))
+        ax.text(angle, r_label, label, fontsize=14,
+                ha='center', va='center',
+                transform=ax.transData, clip_on=False)
+
+    ax.legend(loc='upper right', bbox_to_anchor=(1.40, 0.05),
+              fontsize=15, frameon=False)
+    return fig, ax
+```
+
+**Key settings:**
+- `ax.set_theta_zero_location('N')` — top-start convention
+- Remove all default spines/grid; draw custom spokes + contour polygons manually
+- Normalize each spoke independently using per-benchmark tick lists
+- Legend placed **outside** the plot at `bbox_to_anchor=(1.40, 0.05)`
+
+---
+
+## 3D Sphere / Conceptual Illustration
+
+Used for geometric conceptual diagrams (e.g., embedding space visualization).
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+
+def draw_shaded_sphere(ax, light_dir=(-0.5, 0.5, 0.8),
+                       resolution=512, alpha=1.0,
+                       extent=(-1, 1, -1, 1)):
+    """Draw a 2D shaded disk that mimics a 3D sphere using ray-casting."""
+    xs = np.linspace(extent[0], extent[1], resolution)
+    ys = np.linspace(extent[2], extent[3], resolution)
+    x, y = np.meshgrid(xs, ys)
+    r2 = x**2 + y**2
+    mask = r2 <= 1.0
+
+    z = np.zeros_like(x)
+    z[mask] = np.sqrt(1.0 - r2[mask])
+
+    # Surface normals
+    nx, ny, nz = x.copy(), y.copy(), z.copy()
+    nrm = np.sqrt(nx**2 + ny**2 + nz**2) + 1e-6
+    nx, ny, nz = nx/nrm, ny/nrm, nz/nrm
+
+    # Lambertian shading
+    ld = np.array(light_dir, dtype=float)
+    ld /= np.linalg.norm(ld)
+    intensity = np.maximum(0, nx*ld[0] + ny*ld[1] + nz*ld[2])
+
+    img = np.ones_like(x)
+    img[mask] = np.clip(0.2 + 0.9 * intensity[mask], 0, 1)
+
+    ax.imshow(img, cmap='gray',
+              extent=list(extent),
+              vmin=0, vmax=1, alpha=alpha)
+    ax.set_axis_off()
+    return ax
+
+
+def plot_3d_scatter_with_arrows(ax, points, grad_vectors,
+                                point_color='#0c2458', arrow_color='#b64342'):
+    """3D scatter plot with gradient arrow annotations."""
+    from mpl_toolkits.mplot3d import proj3d
+    from matplotlib.patches import FancyArrowPatch
+
+    class Arrow3D(FancyArrowPatch):
+        def __init__(self, xs, ys, zs, *args, **kwargs):
+            super().__init__((0,0), (0,0), *args, **kwargs)
+            self._verts3d = xs, ys, zs
+        def do_3d_projection(self, renderer=None):
+            xs, ys, zs = proj3d.proj_transform(*self._verts3d, self.axes.get_proj())
+            self.set_positions((xs[0], ys[0]), (xs[1], ys[1]))
+            return np.min(zs)
+
+    ax.scatter(points[:, 0], points[:, 1], points[:, 2],
+               s=80, color=point_color, alpha=0.5)
+    for p, g in zip(points, grad_vectors):
+        arrow = Arrow3D([p[0], p[0]+g[0]], [p[1], p[1]+g[1]], [p[2], p[2]+g[2]],
+                        mutation_scale=16, lw=4, arrowstyle='->',
+                        color=arrow_color, alpha=0.8)
+        ax.add_artist(arrow)
+
+    # Clean 3D axes
+    ax.grid(False)
+    ax.xaxis.pane.set_visible(False)
+    ax.yaxis.pane.set_visible(False)
+    ax.zaxis.pane.set_visible(False)
+    ax.set_xticks([])
+    ax.set_yticks([])
+    ax.set_zticks([])
+```
+
+---
+
+## Scatter Plot with Color-Coded Clusters
+
+```python
+def make_scatter(ax, x, y, labels_or_colors,
+                 size=50, alpha=0.7, edgecolors='none'):
+    """Single or multi-cluster scatter."""
+    import numpy as np
+    ax.scatter(x, y, c=labels_or_colors, s=size,
+               alpha=alpha, edgecolors=edgecolors)
+    ax.set_axis_off()   # for conceptual diagrams; remove for data plots
+```
+
+---
+
+## Fill-Between Area Chart (Stacked trend)
+
+Used for cumulative publication counts, stacked contributions, etc.
+
+```python
+# Filled area (stacked) with hatch for print safety
+ax.fill_between(x, 0, y_bottom,
+                color='#ffa8a6', label='Category A')
+ax.fill_between(x, 0, y_top,
+                color='#9BC8FA',
+                hatch='///',               # hatch for grayscale print
+                edgecolor='black',
+                label='Category B')
+# Erase border artifacts
+ax.fill_between(x, 0, y_top,
+                facecolor='none',
+                edgecolor='white',
+                linewidth=2)
+
+# Overlay the trend line for exact values
+ax.plot(x, y_top, lw=3, color='#13457E')
+ax.plot(x, y_bottom, lw=3, color='#850c0a')
+```
+
+---
+
+## Log-Scale Bar Chart
+
+```python
+ax.set_yscale('log')
+ymin, ymax = ax.get_ylim()
+ax.set_ylim(ymin, ymax * 20)   # expand top for annotations
+
+# Annotate values above bars
+for i, val in enumerate(values):
+    ax.text(i, val * 1.1, f'{val:.3f}',
+            ha='center', va='bottom', fontsize=16)
+```
+
+---
+
+## GridSpec Multi-Panel Layout
+
+```python
+from matplotlib import gridspec
+
+# 2-row, 4-column layout
+fig = plt.figure(figsize=(36, 12))
+gs = gridspec.GridSpec(2, 4)
+
+ax_top_left  = fig.add_subplot(gs[0, 0])
+ax_top_right = fig.add_subplot(gs[0, 1:3])   # span columns 1-2
+ax_legend    = fig.add_subplot(gs[0, 3])     # legend panel
+ax_bottom    = fig.add_subplot(gs[1, :])     # full-width bottom
+```
+
+---
+
+## Scientific Notation on Y-Axis
+
+```python
+ax.ticklabel_format(axis='y', style='sci', scilimits=(0, 0))
+```
+
+---
+
+## Custom Spine Positioning
+
+```python
+# Move bottom spine to y=0 (for negative values)
+ax.spines['bottom'].set_position(('data', 0))
+ax.xaxis.set_ticks_position('bottom')
+ax.spines['left'].set_bounds(0, y_max)
+```
+
+---
+
+## Related files
+
+- [SKILL.md](../SKILL.md) — When to use this skill
+- [api.md](api.md) — PALETTE and core helper signatures
+- [common-patterns.md](common-patterns.md) — Bar, trend, and layout patterns
+- [design-theory.md](design-theory.md) — Rationale and color theory
+- [tutorials.md](tutorials.md) — Full end-to-end walkthroughs

package/src/skills/nature-figure/references/common-patterns.md

@@ -0,0 +1,349 @@
+# Common Patterns — Nature Figure Making
+
+Reusable layout and encoding patterns used across publication-grade scripts.
+
+---
+
+## Pattern 1: Ultra-wide multi-metric bar panel
+
+For 3–4 metrics compared across many methods, use a wide canvas so bars and labels don't crowd.
+
+```python
+fig = plt.figure(figsize=(45, 12))   # or (28, 6) for fewer metrics
+gs = gridspec.GridSpec(1, n_metrics)
+
+for i, metric in enumerate(metrics):
+    ax = fig.add_subplot(gs[i])
+    ax.bar(x, values[metric], color=colors, ...)
+    ax.set_ylabel(metric, fontsize=54, labelpad=12)
+    ax.set_xticks([])
+
+# Last panel: legend only
+ax_leg = fig.add_subplot(gs[-1])
+ax_leg.legend(handles, labels, fontsize=38, loc='center', frameon=False)
+ax_leg.set_axis_off()
+
+fig.tight_layout(pad=2)
+```
+
+**Rule**: Width often 3–4× height. Allows left-to-right narrative scanning.
+
+---
+
+## Pattern 2: Dedicated legend panel
+
+When the legend is large, give it its own axis so data panels stay clean.
+
+```python
+fig, axes = plt.subplots(1, n_data + 1, figsize=(...))
+
+for i, ax in enumerate(axes[:-1]):
+    bars = ax.bar(...)
+    if i == 0:
+        handles, labels = ax.get_legend_handles_labels()
+
+# Legend-only panel
+axes[-1].legend(handles, labels, fontsize=28, loc='center', frameon=False)
+axes[-1].set_axis_off()
+```
+
+---
+
+## Pattern 3: Categorical bars without x-tick labels
+
+When methods are named in the legend, hide x-ticks entirely.
+
+```python
+ax.set_xticks([])        # removes ticks and labels
+# Alternatively:
+ax.set_xticklabels([])   # keeps tick marks, removes labels
+```
+
+---
+
+## Pattern 4: Dynamic y-axis tightening
+
+Never use 0–100 when all values are in 80–95.
+
+```python
+margin = (values.max() - values.min()) * 0.1   # 10% padding
+ax.set_ylim([values.min() - margin, values.max() + margin])
+
+# Manual ticks at clean round numbers
+ax.set_yticks([0.75, 0.80, 0.85, 0.90])
+ax.tick_params(axis='y', labelsize=36, length=10, width=2)
+```
+
+---
+
+## Pattern 5: Alpha-graduated ablation bars (same color, varying opacity)
+
+```python
+import numpy as np
+
+blue_rgb = (0.215686, 0.458824, 0.729412)   # #3775BA as float tuple
+n_ablations = len(ablation_configs)
+alphas = np.linspace(0.2, 1.0, n_ablations)
+colors = [(blue_rgb[0], blue_rgb[1], blue_rgb[2], a) for a in alphas]
+# Full method → alpha=1.0, most ablated → alpha=0.2
+```
+
+---
+
+## Pattern 6: Hatch encoding for print-safe grayscale
+
+Add hatching so bars remain distinct when printed in black-and-white.
+
+```python
+hatches = ['/', '\\\\', '.', 'x', 'o', '+']
+for bar_container, hatch in zip(grouped_bars, hatches):
+    for patch in bar_container:
+        patch.set_hatch(hatch)
+        patch.set_edgecolor('black')
+        patch.set_linewidth(1.5)
+```
+
+---
+
+## Pattern 7: Semantic or family color mapping
+
+Always map colors consistently across all panels in a figure:
+
+```python
+method_colors = {
+    'ResNet1d18': '#484878',   # baseline_dark
+    'ResNet1d34': '#7884B4',   # baseline_mid
+    'ECGFounder': '#B4C0E4',   # baseline_soft
+    'CSFM-Tiny':  '#E4E4F0',   # ours_tiny
+    'CSFM-Base':  '#E4CCD8',   # ours_base
+    'CSFM-Large': '#F0C0CC',   # ours_large
+}
+colors = [method_colors[m] for m in methods]
+```
+
+Prefer coherent hue families over alternating saturated blue/green/red just because categories differ.
+Green and red should usually be reserved for **directional annotations**, not primary series identity:
+
+```python
+ax.scatter(x_gain, y_gain, marker='^', color='#2E9E44', s=90, zorder=6)  # improvement
+ax.scatter(x_drop, y_drop, marker='v', color='#E53935', s=90, zorder=6)  # degradation
+```
+
+---
+
+## Pattern 8: In-bar text with luminance-aware color
+
+```python
+def annotate_bars(ax, bars, colors, fmt='{:.2f}', fontsize=32, offset=-0.10):
+    for bar, color in zip(bars, colors):
+        c = color.lstrip('#')
+        r, g, b = int(c[0:2],16)/255, int(c[2:4],16)/255, int(c[4:6],16)/255
+        lum = 0.299*r + 0.587*g + 0.114*b
+        textcolor = 'white' if lum < 0.5 else 'black'
+        value = bar.get_height()
+        ax.text(bar.get_x() + bar.get_width()/2,
+                value + offset,
+                fmt.format(value),
+                ha='center', va='bottom',
+                fontsize=fontsize, color=textcolor)
+```
+
+---
+
+## Pattern 9: Fill-between trend with hatch (print-safe)
+
+```python
+ax.fill_between(x, 0, cumsum_series,
+                color=fill_color,
+                hatch='\\\\\\',   # triple backslash for dense hatch
+                edgecolor='black',
+                label=label_name)
+# Visually erase the border artifacts:
+ax.fill_between(x, 0, cumsum_series,
+                facecolor='none',
+                edgecolor='white',
+                linewidth=2)
+```
+
+---
+
+## Pattern 10: Annotate events on trend lines
+
+```python
+def mark_events(ax, x_labels, y_cumsum, events_dict, dy_fraction=0.1):
+    """Add labeled arrows at event dates on a trend line."""
+    x_index = {label: i for i, label in enumerate(x_labels)}
+    y_lo, y_hi = ax.get_ylim()
+    dy = dy_fraction * (y_hi - y_lo)
+    for date, label in events_dict.items():
+        if date not in x_index:
+            continue
+        i = x_index[date]
+        stars = label.count('*')
+        clean_label = label.replace('*', '')
+        y_data = y_cumsum[i]
+        ax.annotate(
+            clean_label,
+            xy=(i, y_data),
+            xytext=(i, y_data + (1 + 0.8 * stars) * dy),
+            ha='center', va='bottom', fontsize=11,
+            arrowprops=dict(arrowstyle='-|>', lw=1.3, color='black',
+                            shrinkA=0, shrinkB=0, mutation_scale=15)
+        )
+```
+
+---
+
+## Pattern 11: Grouped bars across multiple datasets (grouped-within-grouped)
+
+```python
+num_methods = len(methods)
+xtick_positions = []
+
+for dataset_idx, dataset_name in enumerate(datasets):
+    x_start = dataset_idx * (num_methods + 1)   # gap of 1 between groups
+    ax.bar(
+        np.arange(num_methods) + x_start,
+        values[dataset_name],
+        color=method_colors,
+        label=methods if dataset_idx == 0 else ['_nolegend_'] * num_methods,
+    )
+    xtick_positions.append(np.mean(np.arange(num_methods)) + x_start)
+
+ax.set_xticks(xtick_positions)
+ax.set_xticklabels(datasets)
+```
+
+---
+
+## Pattern 12: Schematic hero panel with supporting quant row
+
+Use when one mechanism or fabrication story needs to lead, with 2–4 smaller evidence plots below.
+
+```python
+fig = plt.figure(figsize=(7.2, 6.2))
+gs = fig.add_gridspec(
+    2, 4,
+    height_ratios=[2.2, 1.0],
+    hspace=0.18, wspace=0.28,
+)
+
+ax_top = fig.add_subplot(gs[0, :])    # hero schematic
+ax_b = fig.add_subplot(gs[1, 0])
+ax_c = fig.add_subplot(gs[1, 1:3])
+ax_d = fig.add_subplot(gs[1, 3])
+
+# top panel should carry the main palette and the main visual narrative
+```
+
+Rules:
+
+- Allocate `45–60%` of total height to the hero schematic.
+- Reuse softened versions of the same colors in the lower plots.
+- Keep support plots quieter than the hero panel.
+
+---
+
+## Pattern 13: Dark image plate with repeated views
+
+Use for microscopy, volume rendering, or fluorescence-heavy panels.
+
+```python
+fig = plt.figure(figsize=(7.2, 6.5))
+gs = fig.add_gridspec(3, 5, hspace=0.08, wspace=0.04)
+
+for r in range(3):
+    for c in range(5):
+        ax = fig.add_subplot(gs[r, c])
+        ax.set_facecolor('black')
+        ax.set_xticks([])
+        ax.set_yticks([])
+        for spine in ax.spines.values():
+            spine.set_visible(False)
+```
+
+Rules:
+
+- Use black only within the image plate cells.
+- Put channel labels, scale bars and small crop guides directly on the plate.
+- Keep crop geometry and scale-bar placement consistent across the grid.
+
+---
+
+## Pattern 14: Clinical triptych
+
+Use for outcome-over-time figures that combine trajectories, effect sizes, and summary proportions.
+
+```python
+fig = plt.figure(figsize=(7.2, 6.8))
+gs = fig.add_gridspec(
+    3, 3,
+    height_ratios=[1.0, 1.35, 0.8],
+    hspace=0.28, wspace=0.32,
+)
+
+axes_top = [fig.add_subplot(gs[0, i]) for i in range(3)]
+axes_mid = [fig.add_subplot(gs[1, i]) for i in range(3)]
+axes_bot = [fig.add_subplot(gs[2, i]) for i in range(3)]
+
+# Put one shared legend strip above axes_top rather than repeating legends.
+```
+
+Rules:
+
+- Keep the three columns semantically parallel.
+- Use a dashed vertical reference line in the forest-plot row.
+- Group shading in the forest-plot row should be pale and subordinate.
+
+---
+
+## Pattern 15: Asymmetric hero panel
+
+Use when one panel is conceptually central and should dominate.
+
+```python
+fig = plt.figure(figsize=(7.2, 5.8))
+gs = fig.add_gridspec(3, 4, hspace=0.25, wspace=0.28)
+
+ax_a = fig.add_subplot(gs[0, :2])
+ax_b = fig.add_subplot(gs[0, 2])
+ax_c = fig.add_subplot(gs[1, :2])
+ax_d = fig.add_subplot(gs[1, 2])
+ax_e = fig.add_subplot(gs[:, 3])      # hero panel spans all rows
+ax_f = fig.add_subplot(gs[2, :2])
+```
+
+Rule: do not normalize every subplot to the same size if the science does not have equal importance.
+
+---
+
+## Pattern 16: Direct labels inside filled regions
+
+Use when the same categorical structure repeats and a legend would become too large.
+
+```python
+for x_text, y_text, text, color in label_specs:
+    ax.text(
+        x_text, y_text, text,
+        color=color,
+        ha='center', va='center',
+        fontsize=9, fontweight='bold',
+    )
+```
+
+Rules:
+
+- Keep labels inside stable, visually large regions.
+- Use a small white or black stroke if the fill varies strongly underneath.
+- Prefer direct labels over a mega-legend for repeated stacked-area or phase diagrams.
+
+---
+
+## Related files
+
+- [SKILL.md](../SKILL.md) — When to use this skill
+- [api.md](api.md) — Helper function signatures and PALETTE
+- [design-theory.md](design-theory.md) — Rationale behind every pattern above
+- [nature-2026-observations.md](nature-2026-observations.md) — Real Nature page archetypes behind these patterns
+- [tutorials.md](tutorials.md) — End-to-end walkthroughs
+- [chart-types.md](chart-types.md) — Radar, 3D, scatter patterns