references/api.md
# API Reference
This document specifies the conventions, constants, and function signatures that implementations should follow for publication-style figures. Implement these in your own code or adapt from the [figure_* demos](demos.md).
---
## Constants
### PALETTE
Semantic color map for publication figures.
```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": "#CFCECE", "highlight": "#FFD700",
"teal": "#42949E", "violet": "#9A4D8E",
}
```
Use blues for key/proposed methods, greens for improvements, reds for baselines/contrasts, neutral for background.
### DEFAULT_COLORS
Ordered list of colors used when `colors` is not passed to plot helpers: `[blue_main, green_3, red_strong, teal, violet, neutral]`.
---
## FigureStyle
```python
@dataclass(frozen=True)
class FigureStyle:
font_size: int = 16
axes_linewidth: float = 2.5
use_tex: bool = False
font_family: tuple[str, ...] = ("DejaVu Sans", "Helvetica", "Arial", "sans-serif")
```
- **font_size:** Base font size (use 24 for large bar panels, 15-16 for compact plots).
- **axes_linewidth:** Spine width (3 for big bars, 2 for compact).
- **use_tex:** Set `True` only when LaTeX is installed and math labels are required.
- **font_family:** Fallback list for sans-serif fonts.
---
## Style and Layout
### apply_publication_style(style=None)
Configures matplotlib rcParams: spines (top/right off), frameless legend, font family/size, vector export options. Call once before creating figures.
```python
apply_publication_style(FigureStyle(font_size=24, axes_linewidth=3))
```
### create_subplots(nrows=1, ncols=1, figsize=None, **kwargs)
Returns `(fig, axes)` with `axes` a flattened 1D array of Axes. Pass `figsize=(width, height)` in inches.
```python
fig, axes = create_subplots(2, 2, figsize=(12, 8))
```
### finalize_figure(fig, out_path, formats=None, dpi=300, close=True, pad=0.05, **kwargs)
Saves the figure to one or more formats (e.g. `['png', 'pdf']`). If `formats` is None, uses extension of `out_path` or defaults to pdf/svg/eps. Creates parent directories. Returns list of saved `Path`s.
```python
finalize_figure(fig, "output/result", formats=["png", "pdf"], dpi=300, pad=0.06)
```
---
## Plot Helpers
### make_grouped_bar(ax, categories, series, labels, ylabel='Value', colors=None, annotate=False)
Renders grouped bars. `categories`: list of x labels; `series`: list of arrays (one per group), same length as categories; `labels`: legend labels. Returns the last `BarContainer` (for use with `annotate_bars`).
```python
make_grouped_bar(ax, ["A", "B", "C"], [[1,2,3], [2,1,2]], ["X", "Y"], ylabel="Score", annotate=True)
```
### annotate_bars(ax, bars, fmt='{:.2f}', fontsize=10, padding=3)
Adds text above each bar in a `BarContainer`.
```python
bars = make_grouped_bar(ax, cats, series, labels, annotate=False)
annotate_bars(ax, bars, fmt="{:.1f}", fontsize=12)
```
### make_trend(ax, x, y_series, labels, colors=None, ylabel=None, xlabel=None, show_shadow=True)
Plots multiple lines with optional uncertainty band. `y_series`: list of 1D arrays (same length as `x`).
```python
make_trend(ax, epochs, [acc_a, acc_b], ["Model A", "Model B"], ylabel="Accuracy", show_shadow=True)
```
### make_heatmap(ax, matrix, x_labels=None, y_labels=None, cmap='magma', cbar_label=None, annotate=False)
Renders a 2D heatmap. Optionally adds colorbar label and cell annotations.
```python
make_heatmap(ax, corr_matrix, x_labels=names, y_labels=names, cbar_label="Correlation")
```
### make_scatter(ax, x, y, label=None, color=None, size=50, alpha=0.7)
Single-series scatter. `x`, `y` must be same-length 1D arrays.
```python
make_scatter(ax, x_vals, y_vals, label="Samples", color=PALETTE["blue_main"])
```
### make_sphere_illustration(ax, light_dir=(-0.5, 0.5, 0.8), resolution=128, alpha=0.6)
Draws a shaded 2D disk to mimic a 3D sphere. Use for conceptual diagrams.
```python
make_sphere_illustration(ax, light_dir=(-0.55, 0.65, 0.55), resolution=280)
```
---
## Validation Rules
- All numeric sequences are converted to numpy arrays; 1D/2D and length checks are enforced.
- `make_grouped_bar`: `len(categories)` must equal number of columns in `series`.
- `make_trend`: each series must have same length as `x`.
- `finalize_figure`: supported formats are pdf, svg, eps, png, jpg, jpeg, tif, tiff.
See [design-theory.md](design-theory.md) for visual and export conventions.
## Conventions
- Save script outputs under a project `figures/` directory (or the path the user gives) with stable basenames; `finalize_figure` creates parent directories as needed.
- In batch or headless runs, set a non-interactive backend before `import matplotlib.pyplot` (for example `matplotlib.use("Agg")`).
- When comparisons, panel count, color roles, resolution, or data layout are underspecified in a way that would change the figure, confirm with the user before finalizing.
## Related files
- [SKILL.md](../SKILL.md) — When to load this skill
- [demos.md](demos.md) — Canonical `figure_*` repo links
- [common-patterns.md](common-patterns.md) — Layout, legend panel, print-safe encoding
- [design-theory.md](design-theory.md) — Rationale and rcParams-style presets
- [tutorials.md](tutorials.md) — End-to-end examples and pointers beyond the three core tutorials
references/common-patterns.md
# Common Patterns for Publication Figures
These patterns are used across the repository for consistent, publication-ready figures. Apply them when building bar charts, multi-panel layouts, and print-safe graphics. Step-by-step flows that use many of these ideas are in [tutorials.md](tutorials.md); for chart types not covered there, use the closing section of that file and [demos.md](demos.md).
---
## Ultra-wide aspect for multi-metric panels
For 3-4 metrics or many categories in a single row, use a wide canvas so bars/labels don't crowd vertically.
- **Example:** `figsize=(45, 12)` or `(28, 6)`.
- **Rule:** Width often 3-4× height for comparison bars.
- **Why:** Lets the reader scan left-to-right without squinting; keeps y-axis and legend readable.
---
## Dedicated legend panel
When multiple curves or groups make the legend large, put it in its own subplot so it doesn't cover data.
- **Steps:**
1. Create one extra subplot (e.g. last in the grid).
2. Call `ax.set_axis_off()` on that axis.
3. Build the legend on that axis (e.g. gather handles/labels from other axes and call `ax.legend(handles, labels)` there), or use a single legend that you place in the extra axis.
- **Result:** Data panels stay clean; legend is fully visible.
---
## Categorical bars without x-tick labels
When the x-axis is "method" or "condition" and the legend already identifies them, hide x ticks and rely on the legend/title.
- **Code:** `ax.set_xticks([])` or set tick labels to empty.
- **Use when:** Many methods across multiple metrics; names are in the legend or panel title.
---
## Dynamic y-axis scaling
Tighten y-limits to the relevant range so differences are visible instead of squashed.
- **Idea:** Use something like `data.min() - margin` to `data.max() + margin` (e.g. margin = small fraction of range or one std).
- **Avoid:** Fixed 0-100 when all values are in 85-95; use e.g. 80-100 instead.
---
## Bar edge and hatch for print-safe separation
Bars that differ only by fill can blur in grayscale. Use edges and optional hatching.
- **Edges:** `edgecolor='black'`, `linewidth=1.5`-`3` for clear separation.
- **Hatch:** Same color with different hatch (e.g. `'/'`, `'\\'`, `'.'`) for ablation or subgroups so they remain distinct in print.
---
## Semantic color mapping
Stick to the skill palette so "proposed vs baseline" is consistent across figures.
- **Blues:** Proposed method / key result.
- **Greens:** Improvements / positive variants.
- **Reds:** Baselines / contrasts / alternatives.
- **Neutral:** Reference or background categories.
- **Highlight:** Single callout only.
See [design-theory.md](design-theory.md) for the full palette and [api.md](api.md) for `PALETTE` and `DEFAULT_COLORS`.
## Related files
- [SKILL.md](../SKILL.md) — When to load this skill
- [api.md](api.md) — `PALETTE`, helpers, validation
- [demos.md](demos.md) — Real scripts mirroring these patterns
- [design-theory.md](design-theory.md) — Visual and color theory
- [tutorials.md](tutorials.md) — Walkthroughs that apply these patterns
references/demos.md
# Real-World Demos and Figure Scripts
The design theory, patterns, and guidance in this skill are derived from the figure-making scripts in the [figures4papers](https://github.com/ChenLiu-1996/figures4papers) repository. Those scripts are the canonical demos for this skill.
**Repository:** [https://github.com/ChenLiu-1996/figures4papers](https://github.com/ChenLiu-1996/figures4papers)
## Project folders (demos)
Each folder contains Python scripts and (in `figures/`) outputs that follow the skill's house style. Use them as references for bar charts, trend and line panels, heatmaps, radar or polar comparisons, and multi-panel layouts.
| Project | Link | Notes |
|--------|------|--------|
| **figure_ImmunoStruct** | [figures4papers/figure_ImmunoStruct](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_ImmunoStruct) | Bar plots for quantitative comparison |
| **figure_CellSpliceNet** | [figures4papers/figure_CellSpliceNet](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_CellSpliceNet) | Bar comparison, ablation |
| **figure_Brainteaser** | [figures4papers/figure_Brainteaser](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_Brainteaser) | Bar composition breakdown |
| **figure_VIGIL** | [figures4papers/figure_VIGIL](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_VIGIL) | Radar plots, line plots |
| **figure_ophthal_review** | [figures4papers/figure_ophthal_review](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_ophthal_review) | Trend plots |
| **figure_RNAGenScape** | [figures4papers/figure_RNAGenScape](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_RNAGenScape) | Heat maps |
| **figure_Dispersion** | [figures4papers/figure_Dispersion](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_Dispersion) | 3D-style spheres, performance plots |
| **figure_Cflows** | [figures4papers/figure_Cflows](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_Cflows) | Comparison, ablation, trajectory plots |
For full scripts, outputs, and data, clone or browse the repo. The figure_* folders are the canonical implementations of this skill's style.
## Related files
- [SKILL.md](../SKILL.md) — When to load this skill
- [api.md](api.md) — Constants, helpers, validation
- [common-patterns.md](common-patterns.md) — Layout and legend patterns
- [design-theory.md](design-theory.md) — Style theory and reproduction rules
- [tutorials.md](tutorials.md) — Step-by-step figure builds
references/design-theory.md
# Publication Figure Design Theory (Derived from Repository Scripts)
This theory is inferred from the Python plotting scripts in the [figures4papers](https://github.com/ChenLiu-1996/figures4papers) repository (the `figure_*` project folders). See [demos.md](demos.md) for links to those demos.
## 1) Core Matplotlib Style System
The dominant house style is minimalist, high-contrast, and publication-oriented:
- Typography:
- Primary: `font.family = 'helvetica'` (used in 16 scripts).
- Secondary exception: `font.family = 'sans-serif'` (2 scripts, mostly geometric illustrations).
- Practical portability recommendation: prefer fallback stack `['Arial', 'Helvetica', 'DejaVu Sans', 'sans-serif']`.
- Size hierarchy:
- Large-panel bar/comparison figures: `font.size = 24`, `axes.linewidth = 3`.
- Paper subfigures/compact analytic plots: `font.size = 15-16`, `axes.linewidth = 2`.
- Axes cleanup:
- `axes.spines.right = False`
- `axes.spines.top = False`
- LaTeX usage:
- `text.usetex = True` appears in TeX-heavy scripts (6 files), especially when math-rich labels are needed.
- Vector text:
- `svg.fonttype = 'none'` appears when preserving editable text in vector exports.
## 2) Export and Output Policy
- DPI defaults:
- Standard: `dpi=300` (dominant: 23 save calls).
- Very dense bar panels: `dpi=600` (used in ImmunoStruct bars).
- Layout finalization:
- `fig.tight_layout(pad=2)` is the default finishing pass (21 occurrences).
- `pad=1` is used for compact multi-panel plots.
- Mostly opaque white-background output; occasional `bbox_inches='tight'` with explicit `pad_inches` for edge-to-edge composites.
## 3) Color Theory and Palette Structure
The repository uses a consistent semantic palette family:
- Anchor/brand blue:
- `#0F4D92` and `#3775BA` (method-of-interest / reference baseline).
- Green performance bands (often incremental gains):
- `#DDF3DE`, `#AADCA9`, `#8BCF8B`.
- Warm red/pink comparator bands:
- `#F6CFCB`, `#E9A6A1`, `#B64342`.
- Neutral support grays:
- `#CFCECE`, `#767676`, `#4D4D4D`, `#272727`.
- Occasional accent/highlight colors:
- Gold `#FFD700`, magenta-like `#EA84DD`, teal `#42949E`, violet `#9A4D8E`.
Design intent:
- Use blue for "proposed" or key method.
- Use green shades for related positives/improvements.
- Use pink/red shades for alternatives or contrasts.
- Keep neutrals for baselines and background categories.
## 4) Layout and Composition Logic
Common geometric/layout decisions:
- **Ultra-Wide Aspect Ratios:** For multi-metric comparisons (e.g., 3-4 metrics), the repository uses extremely wide canvases (e.g., `figsize=(45, 12)` or `(28, 6)`). This prevents vertical crowding and allows metrics to be read as a narrative from left to right.
- **Dedicated Legend Panels:** In complex multi-axis figures, a sub-plot is often dedicated solely to the legend (`ax.set_axis_off()`). This keeps the data panels clean and prevents legend boxes from overlapping critical data regions.
- **Categorical Abstracting:** Category bars usually hide x-tick labels (`ax.set_xticks([])`) and rely on legends/titles instead. This is particularly effective when comparing many methods across multiple metrics.
- **Dynamic Y-Axis Scaling:** Y-limits are manually tightened to relevant ranges (often derived from `data.min() - data.std()`), emphasizing comparative differences rather than absolute values.
- **Consistency over Embellishment:** Multi-panel consistency is favored over per-axis embellishment. All subplots in a row share the same font sizes, linewidths, and color semantic mapping.
## 5) Bar Encoding Strategy
For publication-grade grouped/ablation bars:
- **In-Place Annotation:** Scientific values are often printed directly above bars (`ax.text`) with large fonts (36pt) to make exact numbers readable without a grid.
- **Manual Tick Positioning:** Uses `FixedLocator` for precise control over Y-axis granularity.
- **Strong edge treatment:** Bars use black edges (`edgecolor='black'`) with `linewidth=1.5-3` for sharp separation.
- **Alpha-Based Ablation:** Ablation studies often use the same primary color (e.g., `blue_secondary`) with varying `alpha` levels (0.2 to 1.0) to represent the "completeness" of a method.
- **Hatch Encoding:** Optional hatch channels (slashes/backslashes/dots) are used for subtype overlays to remain readable in grayscale print.
## 6) Trend/Line Encoding Strategy
- Limited line count per axis (usually 2-4 primary curves).
- Use consistent line width around `2-3` with controlled alpha.
- Use `fill_between` for uncertainty when needed.
- Keep grid minimal or absent; rely on axis ticks and direct legend reading.
**Polar / radar:** Keep the number of series readable at publication size; use the same line-weight and label discipline as Cartesian trends. Repository examples live under `figure_VIGIL` (see [demos.md](demos.md)).
## 7) Scatter/Illustration Encoding Strategy
- Dense geometric scenes use lowered alpha and muted fills.
- Important trajectories/relations use saturated warm accents with arrows.
- Axis ticks often removed for conceptual diagrams.
## 8) Recommended Reusable rcParams Preset
```python
PUBLICATION_RCPARAMS = {
"font.family": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
"font.size": 16, # use 24 for large comparison bars
"axes.spines.right": False,
"axes.spines.top": False,
"axes.linewidth": 2.5, # 3 for big bars, 2 for compact figures
"legend.frameon": False,
"svg.fonttype": "none",
}
```
## 9) Recommended Default 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": "#CFCECE",
"highlight": "#FFD700",
}
```
## 10) Reproduction Rules
To match the repository's visual identity for new figures:
1. Apply minimalist spines (top/right off), frameless legends, and explicit y-limits.
2. Use Helvetica/Arial-like sans fonts with larger sizing for bars.
3. Choose colors from the blue-green-red-neutral family above; avoid unrelated palettes.
4. Finalize with `tight_layout(pad=2)` and export at `dpi=300` (or `600` for dense bar panels).
5. Use hatch/edge encodings for print-safe category separation when bars overlap in hue.
## Related files
- [SKILL.md](../SKILL.md) — When to load this skill
- [api.md](api.md) — Formal `PALETTE` and function contracts
- [demos.md](demos.md) — Repository scripts this theory summarizes
- [common-patterns.md](common-patterns.md) — Operational patterns from the theory
- [tutorials.md](tutorials.md) — Hands-on flows grounded in this theory
references/tutorials.md
# Tutorials: End-to-End Publication Figures
Implement the API described in [api.md](api.md) in your own code (constants, style, plot helpers, finalize). This repository does not currently ship a tracked shared Python module that defines `apply_publication_style`, `make_grouped_bar`, or the other helpers directly; their signatures and behavior are specified in [api.md](api.md) and should be implemented or adapted per project. For real-world scripts that follow this style, see [demos.md](demos.md) (links to the [figures4papers](https://github.com/ChenLiu-1996/figures4papers) `figure_*` folders).
If venue, approximate dimensions, or export formats are missing and they would change layout or DPI, ask before locking choices. For unattended scripts, set a non-interactive matplotlib backend (for example `matplotlib.use("Agg")`) before importing `pyplot`. Finish with `finalize_figure` as in [api.md](api.md).
---
## Tutorial 1: Grouped bar chart
**Goal:** One grouped bar chart: several series compared on the same categorical x-axis (metrics, conditions, tasks, or similar), optional value annotations, and export via `finalize_figure`.
**Checklist:**
- [ ] Load or define data: shared category list for the x-axis; one numeric array per series (each aligned with those categories); legend label per series.
- [ ] Call `apply_publication_style` with a style (e.g. `FigureStyle(font_size=24, axes_linewidth=3)` for a large panel).
- [ ] Create figure and one axis; widen `figsize` when there are many categories so ticks and labels stay readable.
- [ ] Call `make_grouped_bar(ax, categories, series, labels, ylabel="...", annotate=True)` (or `annotate=False` and use `annotate_bars` separately per [api.md](api.md)).
- [ ] Set y-limits to a range that fits the data (tighten when values sit in a narrow band).
- [ ] Call `finalize_figure(fig, "output/comparison", formats=["png", "pdf"], dpi=300)`.
**Example flow** (illustrative counts; implement helpers per [api.md](api.md)):
```python
import matplotlib.pyplot as plt
# Assume you have implemented: apply_publication_style, FigureStyle, make_grouped_bar, finalize_figure, PALETTE (see api.md)
apply_publication_style(FigureStyle(font_size=24, axes_linewidth=3))
fig, ax = plt.subplots(figsize=(16, 5))
categories = ["Metric A", "Metric B", "Metric C", "Metric D"] # length K
series = [ # one list per series, each length K
[0.92, 0.88, 0.85, 0.90],
[0.85, 0.82, 0.88, 0.84],
[0.78, 0.80, 0.82, 0.79],
]
labels = ["Ours", "Baseline X", "Baseline Y"] # same length as series
make_grouped_bar(
ax, categories, series, labels,
ylabel="Score", colors=[PALETTE["blue_main"], PALETTE["green_3"], PALETTE["red_strong"]],
annotate=True,
)
ax.set_ylim(0.7, 1.0)
finalize_figure(fig, "output/method_comparison", formats=["png", "pdf"], dpi=300)
```
---
## Tutorial 2: Multi-panel trend with shared legend
**Goal:** Two trend panels (e.g. train and validation curves) and a third panel used only for the legend.
**Checklist:**
- [ ] Apply style; create 1×3 subplots (or 2×2 with last axis for legend).
- [ ] Plot trends on the first axes; collect legend handles/labels from one of them.
- [ ] On the last axis, call `ax.set_axis_off()` and add a legend using the collected handles/labels.
- [ ] Set y-limits and titles on data panels.
- [ ] Call `finalize_figure`.
**Example flow** (implement helpers per [api.md](api.md)):
```python
import numpy as np
import matplotlib.pyplot as plt
apply_publication_style(FigureStyle(font_size=14, axes_linewidth=2))
fig, axes = create_subplots(1, 3, figsize=(14, 4))
x = np.linspace(0, 10, 50)
y1 = 0.5 + 0.4 * (1 - np.exp(-x / 3))
y2 = 0.45 + 0.35 * (1 - np.exp(-x / 4))
make_trend(axes[0], x, [y1, y2], ["Model A", "Model B"], ylabel="Loss", xlabel="Step")
axes[0].set_title("Training")
make_trend(axes[1], x, [y1 * 1.1, y2 * 1.05], ["Model A", "Model B"], ylabel="Loss", xlabel="Step")
axes[1].set_title("Validation")
# Legend-only panel
handles, labels = axes[0].get_legend_handles_labels()
axes[2].set_axis_off()
axes[2].legend(handles, labels, loc="center")
finalize_figure(fig, "output/trends", formats=["png", "pdf"], dpi=300)
```
---
## Tutorial 3: Heatmap with labels and colorbar
**Goal:** A correlation or score matrix with row/column labels and a colorbar.
**Checklist:**
- [ ] Apply style; create one axis.
- [ ] Prepare 2D matrix and optional x_labels, y_labels.
- [ ] Call `make_heatmap(ax, matrix, x_labels=..., y_labels=..., cmap="magma", cbar_label="...")`.
- [ ] Call `finalize_figure`.
**Example flow** (implement helpers per [api.md](api.md)):
```python
import numpy as np
import matplotlib.pyplot as plt
apply_publication_style(FigureStyle(font_size=12, axes_linewidth=2))
fig, ax = plt.subplots(figsize=(8, 6))
np.random.seed(42)
matrix = np.random.rand(5, 5)
matrix = (matrix + matrix.T) / 2 # symmetric
labels = [f"F{i+1}" for i in range(5)]
make_heatmap(ax, matrix, x_labels=labels, y_labels=labels, cmap="magma", cbar_label="Correlation")
finalize_figure(fig, "output/heatmap", formats=["png", "pdf"], dpi=300)
```
---
## Chart types beyond these walkthroughs
These tutorials cover grouped bars, multi-panel trends with a legend column, and heatmaps. For other house-style figures, open the closest match in [demos.md](demos.md), then align constants and `finalize_figure` with [api.md](api.md) and typography or export rules in [design-theory.md](design-theory.md).
- **Radar or polar comparisons:** `figure_VIGIL` (for example `plot_comparison_radar.py`).
- **Comparison or post-training line panels:** `figure_VIGIL`, `figure_ophthal_review`, or `figure_Cflows`, depending on layout.
- **Scatter-heavy or schematic panels:** `figure_Dispersion` and `figure_VIGIL` concept plots are good starting points.
- **Bar-style quantitative comparisons:** `figure_CellSpliceNet`, `figure_ImmunoStruct`, and `figure_Brainteaser`.
- **Heatmap-focused examples:** `figure_RNAGenScape`.
For more layout ideas (ultra-wide panels, legend-only axes, print-safe bars), see [common-patterns.md](common-patterns.md).
## Related files
- [SKILL.md](../SKILL.md) — When to load this skill
- [api.md](api.md) — API this tutorial assumes
- [demos.md](demos.md) — Production scripts in figures4papers
- [common-patterns.md](common-patterns.md) — Layout and print-safe details
- [design-theory.md](design-theory.md) — Why the style choices exist
SKILL.md
---
name: scientific-figure-making
description: >-
Covers publication-ready matplotlib figures for academic papers, slides, and
reports—bars, trends, scatter, heatmaps, and multi-panel layouts—with this
repository’s house style, print/vector export conventions, and parity with
figures4papers demos. Use when the user is finalizing or creating such figures
in matplotlib. Do not use for interactive dashboards or web viz (Plotly, Altair,
Bokeh), exploratory-only plots without a publication target, dominant 3D or
geographic mapping, or Illustrator/Figma-first infographic workflows.
---
# Scientific figure making
Open `references/` only as needed; do not preload every file. Start from the table below, then follow links inside the document you opened (and into `figure_*` code via [references/demos.md](references/demos.md)) instead of loading the full reference set up front.
## When to load this skill
- Matplotlib figures for **papers, slides, or reports** that must match **this repo’s publication look** (fonts, palette, spines, legends, export).
- Requests involving **grouped bars, trend lines, heatmaps, multi-panel grids**, or **PDF/SVG/high-DPI** output in a scientific-figure context.
- References to **figures4papers** `figure_*` projects or “same style as the repo figures.”
## When not to load
- **Plotly, Altair, Bokeh**, or other interactive / web-first plotting.
- **EDA-only** plots where seaborn or pandas is enough until there is a publication target.
- Primary workflow is **3D, GIS**, or **non-matplotlib** tooling.
- **Illustrator / Figma–first** layout or infographic (not matplotlib data plots).
## Related files
| File | Open when |
|------|-----------|
| [references/tutorials.md](references/tutorials.md) | End-to-end walkthroughs (bar, trends, heatmap) |
| [references/api.md](references/api.md) | Function signatures, `PALETTE`, validation rules |
| [references/common-patterns.md](references/common-patterns.md) | Layout patterns, legend panel, print-safe bars |
| [references/design-theory.md](references/design-theory.md) | Typography, export policy, palette rationale |
| [references/demos.md](references/demos.md) | Canonical `figure_*` demo links in figures4papers |