like-sci-figures 0.0.0-stage → 1.0.0

package/scripts/palettes.py

@@ -0,0 +1,461 @@
+#!/usr/bin/env python3
+"""
+Palette library for LIKE Sci Figures.
+
+A collection of 34 curated scientific color palettes, covering:
+  - 10 original 科研配色方案 poster series (wx01–wx10)
+  - 10 journal/medical series (wx11–wx20): Lancet, Nature, NEJM, Science, JAMA, JCO, BMJ, Cell, clinical status
+  - 3 colorblind-safe classics (wx21–wx23): Okabe-Ito, Paul Tol, Tableau10
+  - 4 perceptually-uniform continuous (wx24–wx27): Viridis, Magma, SciCo Tokyo, Cividis
+  - 2 finance series (wx28–wx29): Bloomberg Terminal, Financial Institutional
+  - 2 engineering/materials (wx30–wx31): IEEE/Springer, Advanced Materials
+  - 3 ColorBrewer classics (wx32–wx34): Set2, Spectral, Dark2
+
+Each palette ships with:
+  - a slug (ASCII, for CLI use)
+  - a Chinese display name
+  - a "kind": qualitative | sequential | diverging
+  - a "domain": list of suitable academic fields
+  - an ordered list of hex colors
+
+Usage from other modules:
+    from palettes import list_palettes, get_palette, palette_colormap
+
+CLI:
+    --palette wx06_amber_navy      # by slug
+    --palette p6                   # by short id
+    --palette 6                    # by index
+    --palette "#F26A1D,#1E5FA8"    # raw comma-separated hex list
+"""
+import numpy as np
+
+# ── The 34 palettes ─────────────────────────────────────────────────────
+# Order matters: it defines the natural progression of the palette.
+PALETTES = {
+    "wx01_blue_red": {
+        "zh": "01 深海蓝→中国红（蓝红发散）",
+        "kind": "diverging",
+        "domain": ["跨学科通用", "热力图", "相关性分析"],
+        "desc": "对称蓝红发散，适合热图/相关性矩阵/正负对比，也可作分组配色。",
+        "colors": [
+            "#104E8B", "#376B9E", "#5F89B1", "#AFC3D8", "#C9E9E3",
+            "#D7E1EB", "#F2DADA", "#E5B5B5", "#D89090", "#B22222",
+        ],
+    },
+    "wx02_soft_pink": {
+        "zh": "02 柔粉灰（低饱和）",
+        "kind": "qualitative",
+        "domain": ["临床医学", "心理学", "社会科学研究"],
+        "desc": "低饱和粉/灰/奶油色，柔和高级，适合多组对比但不抢眼。",
+        "colors": ["#F4C7C7", "#E6ECF2", "#E57373", "#F29A8E", "#7FB3B0", "#FFF1D6"],
+    },
+    "wx03_sunset_blue": {
+        "zh": "03 暖橙→蓝紫（日落渐变）",
+        "kind": "sequential",
+        "domain": ["跨学科通用", "数据科学", "趋势分析"],
+        "desc": "暖到冷的连续渐变，适合折线/堆叠/热图，分组配色很有层次。",
+        "colors": [
+            "#F37252", "#F7935A", "#FCB461", "#FED297", "#FFF0DC",
+            "#E3F5F6", "#ABE0E4", "#7FC6D3", "#779FC6", "#6F78B9",
+        ],
+    },
+    "wx04_macaron": {
+        "zh": "04 马卡龙（柔和多色）",
+        "kind": "qualitative",
+        "domain": ["生命科学", "环境科学", "生态学"],
+        "desc": "9 色柔和马卡龙，粉橙黄绿青蓝齐备，适合分类/花瓣图/多组散点。",
+        "colors": [
+            "#FEB8B4", "#FEB07A", "#FFEDAE", "#88D485", "#FFDBDB",
+            "#FFEBE4", "#D2F2ED", "#A6F6EE", "#B9D8F6",
+        ],
+    },
+    "wx05_coral_blue": {
+        "zh": "05 珊瑚粉→钢蓝（红蓝发散·8色）",
+        "kind": "diverging",
+        "domain": ["跨学科通用", "统计学", "回归分析"],
+        "desc": "8 色红蓝发散，红端柔和、蓝端沉静，适合气泡/热图/回归。",
+        "colors": ["#FCE8E6", "#FFC6BC", "#F8B9B8", "#FFADA2",
+                   "#D6DFEF", "#A5CDE2", "#5FA3CB", "#668FCA"],
+    },
+    "wx06_amber_navy": {
+        "zh": "06 琥珀橙→藏青（橙蓝对比）",
+        "kind": "sequential",
+        "domain": ["跨学科通用", "数据科学", "分布分析"],
+        "desc": "橙到深蓝的强对比渐变，主次分明，适合折线/堆叠/分布。",
+        "colors": ["#F26A1D", "#F7B891", "#FFF3E6", "#DCE6F2", "#6EA6D6", "#1E5FA8"],
+    },
+    "wx07_teal_blue_red": {
+        "zh": "07 青蓝→暖红（青蓝红）",
+        "kind": "qualitative",
+        "domain": ["跨学科通用", "热力图", "多面板组合"],
+        "desc": "青绿+蓝+红点缀，清爽专业，热图与多组图通用。",
+        "colors": ["#E8F2F2", "#C3DFDD", "#69BAA2", "#82C1D3", "#80B2C8", "#E79295", "#D55E57"],
+    },
+    "wx08_amber_indigo": {
+        "zh": "08 琥珀→靛蓝（暖冷渐变·8色）",
+        "kind": "sequential",
+        "domain": ["环境科学", "数据科学", "聚类分析"],
+        "desc": "8 色暖冷连续渐变，青蓝段过渡自然，适合堆叠/趋势/聚类热图。",
+        "colors": ["#F16D4E", "#FDB863", "#FDEBCF", "#E6F3F7",
+                   "#B7E3EA", "#89CBD4", "#6E8FC7", "#6A6FBE"],
+    },
+    "wx09_pastel_mix": {
+        "zh": "09 柔彩综合（8色）",
+        "kind": "qualitative",
+        "domain": ["生物信息学", "统计学", "多面板分析"],
+        "desc": "黄绿粉青橙红综合柔和色，兼容火山图/热图/多面板。",
+        "colors": ["#E0ECCC", "#DACCE2", "#F1C0C0", "#E1E09C",
+                   "#94C584", "#EEB56D", "#75C1D0", "#DC7C7D"],
+    },
+    "wx10_vivid_contrast": {
+        "zh": "10 高饱和对比（6色）",
+        "kind": "qualitative",
+        "domain": ["跨学科通用", "强调对比", "关键结果"],
+        "desc": "红橙青蓝紫深蓝，高饱和高区分度，适合强调关键结果的对比图。",
+        "colors": ["#D23918", "#E5A84B", "#5DA39D", "#4182A4", "#7B357D", "#354E6B"],
+    },
+
+    # ── Medical / Top-Journal series (ggsci-extracted) ────────────────────
+    "wx11_lancet_gradient": {
+        "zh": "11 Lancet 2024 渐变（蓝→绿→暖色·11色）",
+        "kind": "sequential",
+        "domain": ["临床医学", "流行病学", "公共卫生"],
+        "desc": "Lancet 2024 年最新配色，从蓝到暖色自然渐变，适合折线/堆叠/趋势图。",
+        "colors": [
+            "#7B95C6", "#49C2D9", "#A1D8E8", "#67A583", "#A2C986",
+            "#D0E2C0", "#FDED95", "#FFC1A6", "#F59C7C", "#F47254",
+            "#C85E62",
+        ],
+    },
+    "wx12_lancet": {
+        "zh": "12 Lancet 经典（蓝红主调·9色）",
+        "kind": "qualitative",
+        "domain": ["临床医学", "流行病学", "卫生政策"],
+        "desc": "Lancet Oncology 经典配色，深蓝+正红为主，庄重大气，适合临床分组/流行病学。",
+        "colors": [
+            "#00468B", "#ED0000", "#42B540", "#0099B4", "#925E9F",
+            "#FDAF91", "#AD002A", "#ADB6B6", "#1B1919",
+        ],
+    },
+    "wx13_nature_npg": {
+        "zh": "13 Nature 旗舰（NPG·10色）",
+        "kind": "qualitative",
+        "domain": ["自然科学通用", "生物医学", "地球科学"],
+        "desc": "Nature Publishing Group 旗舰配色，饱和稳重，多组对比通用首选。",
+        "colors": [
+            "#E64B35", "#4DBBD5", "#00A087", "#3C5488", "#F39B7F",
+            "#8491B4", "#91D1C2", "#DC0000", "#7E6148", "#B09C85",
+        ],
+    },
+    "wx14_nejm": {
+        "zh": "14 NEJM 经典（红蓝层次·8色）",
+        "kind": "qualitative",
+        "domain": ["临床医学", "生存分析", "药物研发"],
+        "desc": "新英格兰医学杂志经典配色，红蓝层次分明，适合临床数据/生存分析曲线。",
+        "colors": [
+            "#BC3C29", "#0072B5", "#E18727", "#20854E",
+            "#7876B1", "#6F99AD", "#FFDC91", "#EE4C97",
+        ],
+    },
+    "wx15_aaas_science": {
+        "zh": "15 AAAS/Science（偏暖·10色）",
+        "kind": "qualitative",
+        "domain": ["多学科通用", "物理学", "工程学"],
+        "desc": "Science 期刊配色，偏暖调，多学科对比通用。",
+        "colors": [
+            "#3B4992", "#EE0000", "#008B45", "#631879", "#008280",
+            "#BB0021", "#5F559B", "#A20056", "#808180", "#1B1919",
+        ],
+    },
+    "wx16_jama": {
+        "zh": "16 JAMA 经典（冷暖平衡·7色）",
+        "kind": "qualitative",
+        "domain": ["医学统计", "临床对比", "循证医学"],
+        "desc": "美国医学会杂志配色，冷暖平衡，适合医学统计图/临床对比。",
+        "colors": [
+            "#374E55", "#DF8F44", "#00A1D5", "#B24745",
+            "#79AF97", "#6A6599", "#80796B",
+        ],
+    },
+    "wx17_jco": {
+        "zh": "17 JCO 临床肿瘤（蓝黄对比·10色）",
+        "kind": "qualitative",
+        "domain": ["肿瘤学", "临床肿瘤", "色盲安全"],
+        "desc": "Journal of Clinical Oncology 配色，色盲安全，临床肿瘤数据首选。",
+        "colors": [
+            "#0073C2", "#EFC000", "#868686", "#CD534C", "#7AA6DC",
+            "#003C67", "#8F7700", "#3B3B3B", "#A73030", "#4A6990",
+        ],
+    },
+    "wx18_bmj": {
+        "zh": "18 BMJ 简约（4色克制）",
+        "kind": "qualitative",
+        "domain": ["临床医学", "公共卫生", "少量分组"],
+        "desc": "BMJ 简约配色，仅 4 色，克制专业，适合少量分组对比。",
+        "colors": ["#C2D0EA", "#0070B8", "#00B3B0", "#D40D8C"],
+    },
+    "wx19_cell": {
+        "zh": "19 Cell 多彩（鲜艳·7色）",
+        "kind": "qualitative",
+        "domain": ["细胞生物学", "分子生物学", "发育生物学"],
+        "desc": "Cell Press 配色，鲜艳多彩，适合细胞/分子生物学可视化。",
+        "colors": [
+            "#85B373", "#FF9FA0", "#373737", "#367FBD",
+            "#BD324C", "#092DF1", "#FC2704",
+        ],
+    },
+    "wx20_clinical_status": {
+        "zh": "20 临床状态（医学·5色）",
+        "kind": "qualitative",
+        "domain": ["临床医学", "患者管理", "不良反应分析"],
+        "desc": "医学临床状态配色：正常/监测/高危/未知/不适用，适合患者流程/不良反应图。",
+        "colors": ["#0072B2", "#E69F00", "#D55E00", "#999999", "#E6E6E6"],
+    },
+
+    # ── Colorblind-safe classics (international standards) ────────────────
+    "wx21_okabe_ito": {
+        "zh": "21 Okabe-Ito 色盲安全（8色·国际标准）",
+        "kind": "qualitative",
+        "domain": ["跨学科通用", "色盲安全", "Nature Methods推荐"],
+        "desc": "Okabe & Ito 2002 设计，色盲安全黄金标准，Nature Methods 推荐。",
+        "colors": [
+            "#000000", "#E69F00", "#56B4E9", "#009E73",
+            "#F0E442", "#0072B2", "#D55E00", "#CC79A7",
+        ],
+    },
+    "wx22_paul_tol": {
+        "zh": "22 Paul Tol Bright（印刷安全·7色）",
+        "kind": "qualitative",
+        "domain": ["物理学", "天文学", "印刷出版"],
+        "desc": "Paul Tol 设计，CMYK 印刷安全，物理/天文领域广泛使用。",
+        "colors": [
+            "#4477AA", "#EE6677", "#228833", "#CCBB44",
+            "#66CCEE", "#AA3377", "#BBBBBB",
+        ],
+    },
+    "wx23_tableau10": {
+        "zh": "23 Tableau10 现代默认（10色）",
+        "kind": "qualitative",
+        "domain": ["跨学科通用", "数据可视化", "Dashboard"],
+        "desc": "Tableau/Matplotlib 现代默认配色，广泛认知，dashboard 通用。",
+        "colors": [
+            "#1F77B4", "#FF7F0E", "#2CA02C", "#D62728", "#9467BD",
+            "#8C564B", "#E377C2", "#7F7F7F", "#BCBD22", "#17BECF",
+        ],
+    },
+
+    # ── Perceptually-uniform continuous (heatmap/density) ─────────────────
+    "wx24_viridis": {
+        "zh": "24 Viridis 感知均匀（8色·热力图首选）",
+        "kind": "sequential",
+        "domain": ["数据科学", "跨学科通用", "热力图"],
+        "desc": "感知均匀色盲安全，matplotlib 默认，热力图/密度图最佳实践。",
+        "colors": [
+            "#440154", "#46327E", "#365C8D", "#277F8E",
+            "#1FA187", "#4AC16D", "#A0DA39", "#FDE725",
+        ],
+    },
+    "wx25_magma": {
+        "zh": "25 Magma 暗紫→暖黄（8色）",
+        "kind": "sequential",
+        "domain": ["数据科学", "天文物理", "高端可视化"],
+        "desc": "暗紫到暖黄渐变，感知均匀，高端数据可视化。",
+        "colors": [
+            "#000004", "#1B0C41", "#4A0C6B", "#781C6D",
+            "#A52C60", "#CB4760", "#E87461", "#F59563",
+        ],
+    },
+    "wx26_scico_tokyo": {
+        "zh": "26 SciCo Tokyo（Fabio Crameri·8色）",
+        "kind": "sequential",
+        "domain": ["地理信息", "气候科学", "地图学"],
+        "desc": "Fabio Crameri 设计，感知均匀，地图/热图/连续数据高端选择。",
+        "colors": [
+            "#3B445B", "#476C81", "#5892AB", "#71AEAB",
+            "#8FC29B", "#B6D485", "#DCE867", "#F7F799",
+        ],
+    },
+    "wx27_cividis": {
+        "zh": "27 Cividis 色盲安全（8色）",
+        "kind": "sequential",
+        "domain": ["跨学科通用", "色盲安全", "连续数据"],
+        "desc": "色盲安全感知均匀，深蓝到暖黄，适合需要高对比的连续数据。",
+        "colors": [
+            "#00224E", "#123570", "#3B496C", "#5C5762",
+            "#7C6B5B", "#A3895A", "#D3A658", "#F6D771",
+        ],
+    },
+
+    # ── Finance / Investment series ────────────────────────────────────────
+    "wx28_bloomberg": {
+        "zh": "28 Bloomberg 终端（深色·7色）",
+        "kind": "qualitative",
+        "domain": ["金融分析", "投资研究", "量化交易"],
+        "desc": "Bloomberg Terminal 风格，深底+琥珀+涨跌红绿，金融数据可视化专业级。",
+        "colors": [
+            "#0A0E1A", "#11172A", "#1A2138", "#FFA02F",
+            "#00B96B", "#F23645", "#5E6680",
+        ],
+    },
+    "wx29_institutional": {
+        "zh": "29 金融机构（低明度高纯度·5色）",
+        "kind": "qualitative",
+        "domain": ["金融", "银行", "资产管理"],
+        "desc": "金融领域机构配色：海军蓝+板岩灰+香槟金+警示橙，权威专业。",
+        "colors": [
+            "#002366", "#708090", "#D4AF37", "#FF8C00", "#F0F8FF",
+        ],
+    },
+
+    # ── Engineering / Materials Science ────────────────────────────────────
+    "wx30_ieee_springer": {
+        "zh": "30 IEEE/Springer（深蓝灰·4色）",
+        "kind": "qualitative",
+        "domain": ["工程学", "计算机科学", "工科论文"],
+        "desc": "IEEE/Springer 工程期刊配色，深蓝+深灰，低饱和稳重，工科论文首选。",
+        "colors": ["#1F497D", "#404040", "#1E1E1E", "#8FA0B8"],
+    },
+    "wx31_adv_mater": {
+        "zh": "31 Advanced Materials（丰富层次·12色）",
+        "kind": "qualitative",
+        "domain": ["材料科学", "纳米技术", "先进制造"],
+        "desc": "Advanced Materials 配色，12 色丰富层次，材料/工程/纳米领域。",
+        "colors": [
+            "#0A6DAF", "#A72061", "#926AAD", "#059244",
+            "#AC5326", "#848385", "#D4E5F4", "#FBB9BA",
+            "#F5EBF4", "#C2E3D0", "#F6E4D0", "#C9C9C9",
+        ],
+    },
+
+    # ── ColorBrewer classics ───────────────────────────────────────────────
+    "wx32_set2": {
+        "zh": "32 ColorBrewer Set2（柔和·8色）",
+        "kind": "qualitative",
+        "domain": ["跨学科通用", "堆叠图", "饼图"],
+        "desc": "ColorBrewer 经典柔和色，大面积填充友好，适合堆叠/饼图。",
+        "colors": [
+            "#66C2A5", "#FC8D62", "#8DA0CB", "#E78AC3",
+            "#A6D854", "#FFD92F", "#E5C494", "#B3B3B3",
+        ],
+    },
+    "wx33_spectral": {
+        "zh": "33 ColorBrewer Spectral（红蓝发散·11色）",
+        "kind": "diverging",
+        "domain": ["生物信息学", "差异表达分析", "正负对比"],
+        "desc": "ColorBrewer 红蓝双向发散，适合相关矩阵/正负值/差异表达分析。",
+        "colors": [
+            "#9E0142", "#D53E4F", "#F46D43", "#FDAE61", "#FEE08B",
+            "#FFFFBF", "#E6F598", "#ABDDA4", "#66C2A5", "#3288BD",
+            "#5E4FA2",
+        ],
+    },
+    "wx34_dark2": {
+        "zh": "34 ColorBrewer Dark2（深色系·8色）",
+        "kind": "qualitative",
+        "domain": ["跨学科通用", "高密度数据", "小标记图表"],
+        "desc": "ColorBrewer 深色系，适合细线条/小标记/高密度数据。",
+        "colors": [
+            "#1B9E77", "#D95F02", "#7570B3", "#E7298A",
+            "#66A61E", "#E6AB02", "#A6761D", "#666666",
+        ],
+    },
+}
+
+# Short aliases: index and pN and wxN
+_ALIASES = {}
+for _i, _slug in enumerate(PALETTES.keys(), start=1):
+    _ALIASES[str(_i)] = _slug
+    _ALIASES[f"p{_i}"] = _slug
+    _ALIASES[f"wx{_i}"] = _slug
+    _ALIASES[f"wx{_i:02d}"] = _slug
+    _ALIASES[_slug] = _slug
+    _ALIASES[_slug.split("_", 1)[0]] = _slug  # e.g. "wx01"
+
+
+def _is_hex_list(text):
+    parts = [p.strip() for p in text.split(",") if p.strip()]
+    if len(parts) < 2:
+        return None
+    for p in parts:
+        if not (p.startswith("#") and len(p) in (4, 7)):
+            return None
+    return parts
+
+
+def _sample(colors, n):
+    """Evenly sample n colors across the palette (endpoints included)."""
+    if n is None or n <= 0 or n >= len(colors):
+        return list(colors)
+    idx = np.linspace(0, len(colors) - 1, n).round().astype(int)
+    out = []
+    for i in idx:
+        c = colors[i]
+        if c not in out:  # avoid duplicates on tiny palettes
+            out.append(c)
+    return out
+
+
+def list_palettes():
+    """Return the list of palette slugs."""
+    return list(PALETTES.keys())
+
+
+def palette_info(name):
+    """Return the metadata dict for a palette (or None)."""
+    slug = _ALIASES.get(str(name).lower().strip())
+    if slug is None:
+        return None
+    info = dict(PALETTES[slug])
+    info["slug"] = slug
+    return info
+
+
+def get_palette(name, n=None):
+    """
+    Resolve a palette name to a list of hex colors.
+
+    Args:
+        name: slug ("wx06_amber_navy"), alias ("p6", "6", "wx06"),
+              or a raw comma-separated hex list.
+        n:    optional number of colors to evenly sample from the palette.
+    Returns:
+        list[str] of hex colors (raises ValueError if name is unknown).
+    """
+    raw = _is_hex_list(str(name))
+    if raw:
+        return _sample(raw, n)
+
+    slug = _ALIASES.get(str(name).lower().strip())
+    if slug is None:
+        raise ValueError(
+            f"Unknown palette '{name}'. Available: {', '.join(list_palettes())} "
+            f"(aliases: 1-{len(PALETTES)}, p1-p{len(PALETTES)}, wx1-wx{len(PALETTES)})"
+        )
+    return _sample(PALETTES[slug]["colors"], n)
+
+
+def palette_colormap(name):
+    """
+    Build a matplotlib Colormap from a palette (for heatmap/contour/surface).
+    Returns None if the palette name is unknown / not a hex list.
+    """
+    from matplotlib.colors import LinearSegmentedColormap
+    try:
+        colors = get_palette(name)
+    except ValueError:
+        return None
+    return LinearSegmentedColormap.from_list("sf_" + str(name), colors, N=256)
+
+
+def print_palette_table():
+    """Pretty-print all palettes with their hex codes (for docs / --list-palettes)."""
+    lines = []
+    for slug, meta in PALETTES.items():
+        domain_str = "/".join(meta.get("domain", []))
+        lines.append(f"{slug}  [{meta['kind']}]  {meta['zh']}  适用:{domain_str}")
+        lines.append("    " + " ".join(meta["colors"]))
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    print(print_palette_table())

package/scripts/registry.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Central chart-type registry for like-sci-figures.
+
+Why this exists
+---------------
+Before this file existed, the mapping "chart type -> example file" and the
+Chinese display names were duplicated across five places:
+
+    gen_figure.py            EXAMPLE_MAP
+    palette_picker.py        EXAMPLES + ZH_NAME
+    showcase.py              CHART_EXAMPLES + ZH_NAME
+    tests/test_examples.py   CHART_EXAMPLES
+    SKILL.md                 chart-type table
+
+Every new chart type required editing four Python files plus the docs. This
+module is the single source of truth: one entry per chart type, and every
+other script imports from here. Adding a new chart type is now a three-step
+task (generator module + GENERATORS entry in gen_figure.py + one line here).
+
+Fields per entry
+----------------
+    type      canonical slug used by --type
+    zh        Chinese display name
+    example   filename inside examples/ (None if no standalone example)
+    kind      statistical | relational | specialized  (grouping for docs)
+    aliases   other slugs that resolve to this canonical type
+
+Public API
+----------
+    from registry import CHART_EXAMPLES, ZH_NAME, CHART_TYPES, ALIASES
+
+    CHART_EXAMPLES = {"bar": "bar.json", ...}       # for --verify-all / tests
+    ZH_NAME        = {"bar": "柱状图", ...}          # for posters / docs
+    CHART_TYPES    = ["area", "bar", ...]           # sorted canonical list
+    ALIASES        = {"grouped_bar": "bar", ...}    # alias -> canonical
+    resolve(t)     -> canonical type (follows aliases)
+    example_path(t) -> absolute path under examples/ or None
+"""
+import os
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+EXAMPLES_DIR = os.path.join(SCRIPT_DIR, "..", "examples")
+
+# ── Canonical registry ─────────────────────────────────────────────────────
+# One row per chart type. Order is irrelevant; CHART_TYPES is sorted on load.
+_REGISTRY = [
+    # (type,              zh,              example,            kind,         aliases)
+    ("bar",               "柱状图",       "bar.json",         "statistics",  ("grouped_bar",)),
+    ("stacked_bar",       "堆叠柱状图",   "stacked_bar.json", "statistics",  ("stacked",)),
+    ("heatmap",           "热力图",       "heatmap.json",     "relational",  ()),
+    ("scatter",           "散点图",       "scatter.csv",      "relational",  ()),
+    ("line",              "折线图",       "line.json",        "relational",  ()),
+    ("box",               "箱线图",       "box.json",         "statistics",  ("boxplot",)),
+    ("violin",            "小提琴图",     "violin.json",      "statistics",  ()),
+    ("forest",            "森林图",       "forest.json",      "statistics",  ()),
+    ("histogram",         "直方图",       "histogram.json",   "statistics",  ()),
+    ("density",           "密度图",       "density.json",     "statistics",  ()),
+    ("pie",               "饼图",         "pie.json",         "relational",  ("donut",)),
+    ("radar",             "雷达图",       "radar.json",       "relational",  ()),
+    ("surface",           "3D曲面",       "surface.json",     "relational",  ()),
+    ("contour",           "等高线",       "contour.json",     "relational",  ()),
+    ("scatter3d",         "3D散点",       "scatter3d.json",   "relational",  ()),
+    ("bubble",            "气泡图",       "bubble.json",      "statistics",  ()),
+    ("area",              "面积图",       "area.json",        "statistics",  ()),
+    ("errorbar",          "误差棒图",     "errorbar.json",    "statistics",  ()),
+    ("venn",              "韦恩图",       "venn.json",        "specialized", ()),
+    ("pca",               "PCA双标图",    "pca.json",         "specialized", ()),
+    ("windrose",          "风玫瑰图",     "windrose.json",    "specialized", ()),
+    ("taylor",            "Taylor图",     "taylor.json",      "specialized", ()),
+    ("sankey",            "桑基图",       "sankey.json",      "specialized", ()),
+    ("subplots",          "子图组合",     "panels.json",      "specialized", ()),
+    ("volcano",           "火山图",       "volcano.json",     "statistics",  ()),
+    ("manhattan",         "曼哈顿图",     "manhattan.json",   "specialized", ()),
+    ("kaplan_meier",      "KM生存曲线",   "kaplan_meier.json", "statistics", ()),
+    ("roc",               "ROC曲线",      "roc.json",         "statistics",  ()),
+    ("ridge",             "岭图",         "ridge.json",       "statistics",  ()),
+    ("ternary",           "三元相图",     "ternary.json",     "specialized", ()),
+    ("dot_plot",          "点图",         "dot_plot.json",    "statistics",  ()),
+    ("dendrogram",        "树状图",       "dendrogram.json",  "specialized", ()),
+    ("slope",             "斜率图",       "slope.json",       "relational",  ()),
+    ("waterfall",         "瀑布图",       "waterfall.json",   "statistics",  ()),
+    ("bode",              "博德图",       "bode.json",        "specialized", ()),
+    ("periodogram",       "周期图",       "periodogram.json", "specialized", ()),
+    ("corr_matrix",       "相关矩阵",     "corr_matrix.json", "relational",  ()),
+    ("hexbin",            "六边形分箱密度图", "hexbin.json",   "relational",  ()),
+    ("ecdf",              "经验累积分布", "ecdf.json",        "statistics",  ()),
+    ("bland_altman",      "Bland-Altman图", "bland_altman.json", "statistics", ()),
+]
+
+# ── Derived lookups ────────────────────────────────────────────────────────
+CHART_EXAMPLES = {row[0]: row[2] for row in _REGISTRY if row[2]}
+ZH_NAME = {row[0]: row[1] for row in _REGISTRY}
+CHART_TYPES = sorted(row[0] for row in _REGISTRY)
+ALIASES = {}
+for _t, _zh, _ex, _kind, _aliases in _REGISTRY:
+    for _a in _aliases:
+        ALIASES[_a] = _t
+
+_KIND = {row[0]: row[3] for row in _REGISTRY}
+_KNOWN = {row[0] for row in _REGISTRY} | set(ALIASES)
+
+
+def resolve(type_name):
+    """Resolve a chart type name (alias or canonical) to its canonical slug.
+
+    Returns the canonical slug if the name is known, or the input unchanged
+    (so unknown custom types still pass through to GENERATORS for validation).
+    """
+    if type_name in _KNOWN:
+        return ALIASES.get(type_name, type_name)
+    return type_name
+
+
+def kind_of(type_name):
+    """Return the category (statistics / relational / specialized) or None."""
+    return _KIND.get(resolve(type_name))
+
+
+def example_path(type_name):
+    """Absolute path to the example file for this chart type, or None."""
+    fname = CHART_EXAMPLES.get(resolve(type_name))
+    if not fname:
+        return None
+    return os.path.abspath(os.path.join(EXAMPLES_DIR, fname))
+
+
+def example_name(type_name):
+    """Bare filename of the example for this chart type, or None."""
+    return CHART_EXAMPLES.get(resolve(type_name))
+
+
+def example_types():
+    """Sorted list of chart types that have an example file."""
+    return sorted(t for t, ex in CHART_EXAMPLES.items() if ex)
+
+
+def __repr__():
+    return "registry(%d types, %d aliases)" % (len(_REGISTRY), len(ALIASES))