\n \n
\n \n\n\n```\n\n---\n\n## Chart.js 常用图表类型\n\n| type 值 | 图表类型 |\n|---------|---------|\n| `'line'` | 折线图 |\n| `'bar'` | 条形图（纵向） |\n| `'bar'` + `indexAxis: 'y'` | 横向条形图 |\n| `'pie'` | 饼图（慎用） |\n| `'doughnut'` | 环形图 |\n| `'scatter'` | 散点图 |\n| `'bubble'` | 气泡图 |\n| `'radar'` | 雷达图 |\n\n---\n\n## 多系列条形图示例\n\n```javascript\nnew Chart(ctx, {\n type: 'bar',\n data: {\n labels: ['Q1', 'Q2', 'Q3', 'Q4'],\n datasets: [\n {\n label: 'PC端',\n data: [3200, 4100, 3800, 5200],\n backgroundColor: '#3b82f6'\n },\n {\n label: '移动端',\n data: [5100, 6200, 7100, 8900],\n backgroundColor: '#10b981'\n }\n ]\n },\n options: {\n responsive: true,\n plugins: {\n title: { display: true, text: '各渠道季度订单量' }\n },\n scales: { y: { beginAtZero: true } }\n }\n});\n```\n\n---\n\n## 注意事项\n\n- Canvas 渲染依赖网络加载 Chart.js CDN，离线环境需本地引入\n- 数据量大时（>1000 点），建议先聚合再渲染，避免卡顿\n- 中文字体在 Canvas 中需要系统已安装对应字体\n- 复杂统计图（箱线图、小提琴图）建议用 Python matplotlib 生成图片，再展示\n\nFile v1.0.0:references/chart-selection.md\n\n# 图表选型决策指南\n\n## 核心问题：你想表达什么？\n\n拿到数据后，先问自己这个问题，再选图表。\n\n---\n\n## 决策树\n\n```\n数据是什么关系？\n│\n├── 随时间变化？\n│ ├── 连续时间序列 → 折线图\n│ ├── 离散时间点比较 → 分组条形图\n│ └── 累计/占比随时间变化 → 堆叠面积图\n│\n├── 分类之间比较？\n│ ├── 类别 ≤ 10 → 纵向条形图\n│ ├── 类别 > 10 或名称较长 → 横向条形图\n│ ├── 多组对比 → 分组条形图\n│ └── 排名展示 → 横向条形图（降序）\n│\n├── 整体中各部分占比？\n│ ├── 类别 ≤ 5 → 堆叠条形图（推荐）或饼图\n│ ├── 类别 > 5 → 矩形树图（Treemap）\n│ └── 占比随时间变化 → 堆叠面积图（百分比）\n│\n├── 数值分布？\n│ ├── 单变量分布 → 直方图\n│ ├── 多组分布对比 → 箱线图 / 小提琴图\n│ └── 密度估计 → KDE 图\n│\n├── 两变量关系？\n│ ├── 相关性探索 → 散点图\n│ ├── 带趋势线 → 回归散点图\n│ └── 多变量相关矩阵 → 热力图\n│\n├── 地理分布？\n│ └── 地图（Choropleth / 气泡地图）\n│\n├── 流向/转化？\n│ ├── 用户转化漏斗 → 漏斗图\n│ └── 流量流向 → 桑基图（Sankey）\n│\n└── 单一关键指标？\n └── 大数字 KPI 卡片（不需要图表）\n```\n\n---\n\n## 常见场景速查\n\n| 业务场景 | 推荐图表 | 示例 |\n|---------|---------|------|\n| 日/周/月销售趋势 | 折线图 | 近 30 天 GMV |\n| 各品类销售额对比 | 横向条形图 | Top 10 品类 |\n| 用户地区分布 | 横向条形图 / 地图 | 各省用户数 |\n| 订单金额分布 | 直方图 | 0-100/100-500/500+ |\n| 各渠道转化率对比 | 分组条形图 | PC vs 移动端 |\n| 用户留存率 | 热力图（Cohort） | 按注册周分组 |\n| 指标相关性 | 热力图 | 价格/销量/评分 |\n| 漏斗转化 | 漏斗图 | 曝光→点击→购买 |\n| 月度环比增长 | 折线图 + 柱状图组合 | 销售额 + 增长率 |\n| 市场份额 | 堆叠条形图 | 各品牌占比 |\n\n---\n\n## 反模式（常见错误）\n\n### ❌ 饼图滥用\n```\n错误：用饼图展示 10 个品类的销售占比\n原因：人眼无法准确比较扇形大小\n正确：横向条形图，按值排序\n```\n\n### ❌ 双 Y 轴滥用\n```\n错误：左轴销售额（万元），右轴增长率（%），两条线看起来相关\n原因：双 Y 轴可以通过调整比例制造任意\"相关性\"\n正确：分两张图，或用散点图展示真实相关性\n```\n\n### ❌ 截断 Y 轴\n```\n错误：条形图 Y 轴从 95 开始，让微小差异看起来很大\n原因：视觉误导\n正确：Y 轴从 0 开始；如果确实需要放大差异，用折线图并明确标注\n```\n\n### ❌ 3D 图表\n```\n错误：3D 饼图、3D 条形图\n原因：透视变形导致读值不准\n正确：永远用 2D\n```\n\n### ❌ 彩虹配色\n```\n错误：每个柱子用不同颜色，没有语义\n原因：颜色应该传达信息，不是装饰\n正确：同类数据用同色；用颜色高亮重点数据\n```\n\nFile v1.0.0:references/dashboard.md\n\n# 多图面板 / Dashboard\n\n适用场景：需要在一张图里展示多个维度，或生成完整的数据报告。\n\n---\n\n## matplotlib 多图面板\n\n```python\nimport matplotlib.pyplot as plt\nimport matplotlib.gridspec as gridspec\nimport seaborn as sns\nimport pandas as pd\nimport numpy as np\n\nplt.rcParams['font.sans-serif'] = ['SimHei', 'Microsoft YaHei']\nplt.rcParams['axes.unicode_minus'] = False\n\nfig = plt.figure(figsize=(16, 10))\nfig.suptitle('业务数据周报', fontsize=20, fontweight='bold', y=0.98)\n\n# 使用 GridSpec 灵活布局\ngs = gridspec.GridSpec(2, 3, figure=fig, hspace=0.4, wspace=0.35)\n\n# ── 左上（跨2列）：趋势折线图 ──\nax1 = fig.add_subplot(gs[0, :2])\nax1.plot(df_trend['date'], df_trend['orders'], color='#3b82f6', linewidth=2)\nax1.fill_between(df_trend['date'], df_trend['orders'], alpha=0.1, color='#3b82f6')\nax1.set_title('近30天订单量趋势', fontweight='bold')\nax1.grid(axis='y', alpha=0.3)\nax1.spines['top'].set_visible(False)\nax1.spines['right'].set_visible(False)\nax1.tick_params(axis='x', rotation=45)\n\n# ── 右上：KPI 卡片 ──\nax2 = fig.add_subplot(gs[0, 2])\nax2.axis('off')\nkpis = [\n ('总订单量', '12,450', '+8.3%', '#10b981'),\n ('总营收', '¥234万', '+12.1%', '#10b981'),\n ('客单价', '¥188', '-2.4%', '#ef4444'),\n]\nfor i, (label, value, change, color) in enumerate(kpis):\n y_pos = 0.85 - i * 0.3\n ax2.text(0.1, y_pos, label, fontsize=10, color='#6b7280', transform=ax2.transAxes)\n ax2.text(0.1, y_pos - 0.1, value, fontsize=18, fontweight='bold', transform=ax2.transAxes)\n ax2.text(0.7, y_pos - 0.1, change, fontsize=12, color=color, transform=ax2.transAxes)\nax2.set_title('核心指标', fontweight='bold')\n\n# ── 左下：品类条形图 ──\nax3 = fig.add_subplot(gs[1, 0])\ndf_cat_sorted = df_cat.sort_values('value', ascending=True)\nax3.barh(df_cat_sorted['name'], df_cat_sorted['value'], color='#3b82f6', height=0.6)\nax3.set_title('品类销售额 Top 5', fontweight='bold')\nax3.spines['top'].set_visible(False)\nax3.spines['right'].set_visible(False)\n\n# ── 中下：金额分布直方图 ──\nax4 = fig.add_subplot(gs[1, 1])\nax4.hist(df_orders['amount'], bins=20, color='#f59e0b', edgecolor='white')\nax4.set_title('订单金额分布', fontweight='bold')\nax4.set_xlabel('金额（元）')\nax4.spines['top'].set_visible(False)\nax4.spines['right'].set_visible(False)\n\n# ── 右下：渠道占比堆叠 ──\nax5 = fig.add_subplot(gs[1, 2])\nbottom = np.zeros(len(df_channel))\nfor col, color in zip(['pc', 'mobile', 'mini'], ['#3b82f6', '#10b981', '#f59e0b']):\n ax5.bar(df_channel['month'], df_channel[col], bottom=bottom,\n label=col, color=color, edgecolor='white')\n bottom += df_channel[col].values\nax5.legend(fontsize=8)\nax5.set_title('渠道构成', fontweight='bold')\nax5.spines['top'].set_visible(False)\nax5.spines['right'].set_visible(False)\n\nplt.savefig('weekly_report.png', dpi=150, bbox_inches='tight')\nprint(\"报告已保存：weekly_report.png\")\n```\n\n---\n\n## 自动化报告生成（SQL → 图表 → PDF）\n\n```python\nimport pandas as pd\nimport matplotlib.pyplot as plt\nfrom matplotlib.backends.backend_pdf import PdfPages\nimport sqlite3\nfrom datetime import datetime\n\nplt.rcParams['font.sans-serif'] = ['SimHei', 'Microsoft YaHei']\nplt.rcParams['axes.unicode_minus'] = False\n\nconn = sqlite3.connect('mydb.sqlite')\n\n# 查询数据\ndf_trend = pd.read_sql(\"\"\"\n SELECT DATE(created_at) as date, COUNT(*) as orders, SUM(amount) as revenue\n FROM orders WHERE created_at >= DATE('now', '-30 days')\n GROUP BY DATE(created_at) ORDER BY date\n\"\"\", conn)\n\ndf_cat = pd.read_sql(\"\"\"\n SELECT category, SUM(amount) as revenue\n FROM orders WHERE created_at >= DATE('now', '-30 days')\n GROUP BY category ORDER BY revenue DESC LIMIT 10\n\"\"\", conn)\n\nconn.close()\n\n# 生成 PDF 报告\nwith PdfPages(f'report_{datetime.now().strftime(\"%Y%m%d\")}.pdf') as pdf:\n\n # 第1页：趋势\n fig, ax = plt.subplots(figsize=(12, 5))\n ax.plot(pd.to_datetime(df_trend['date']), df_trend['revenue'],\n color='#3b82f6', linewidth=2)\n ax.set_title('近30天营收趋势', fontsize=14, fontweight='bold')\n ax.grid(axis='y', alpha=0.3)\n plt.tight_layout()\n pdf.savefig(fig)\n plt.close()\n\n # 第2页：品类排名\n fig, ax = plt.subplots(figsize=(10, 7))\n df_sorted = df_cat.sort_values('revenue', ascending=True)\n ax.barh(df_sorted['category'], df_sorted['revenue'], color='#10b981')\n ax.set_title('品类营收排名', fontsize=14, fontweight='bold')\n plt.tight_layout()\n pdf.savefig(fig)\n plt.close()\n\n # PDF 元数据\n d = pdf.infodict()\n d['Title'] = '业务数据报告'\n d['Author'] = 'SQL DataViz'\n d['CreationDate'] = datetime.now()\n\nprint(f\"PDF 报告已生成：report_{datetime.now().strftime('%Y%m%d')}.pdf\")\n```\n\n---\n\n## 布局建议\n\n| 图表数量 | 推荐布局 | figsize |\n|---------|---------|---------|\n| 2 张 | 1×2 或 2×1 | (14, 5) 或 (8, 10) |\n| 4 张 | 2×2 | (14, 10) |\n| 6 张 | 2×3 或 3×2 | (16, 10) |\n| 混合（大+小） | GridSpec 自定义 | 按需 |\n\n**原则：** 最重要的图放左上角（视线自然落点），KPI 卡片放右上角，细节图放下方。\n\nFile v1.0.0:references/distribution.md\n\n# 分布图 — 直方图、箱线图、小提琴图、密度图\n\n适用场景：展示数值分布、识别异常值、多组分布对比。\n\n---\n\n## 核心问题：你想展示什么样的分布？\n\n| 问题 | 推荐图表 |\n|------|---------|\n| 单变量分布频率？ | 直方图 |\n| 中位数、四分位、异常值？ | 箱线图 |\n| 分布形状 + 密度？ | 小提琴图 / KDE |\n| 多组分布对比？ | 箱线图 / 小提琴图 |\n| 分布是否正态？ | 直方图 + KDE + QQ图 |\n\n---\n\n## 一、直方图（Histogram）\n\n### 基础直方图\n\n```python\nimport matplotlib.pyplot as plt\nimport numpy as np\n\nplt.rcParams['font.sans-serif'] = ['SimHei', 'Microsoft YaHei']\nplt.rcParams['axes.unicode_minus'] = False\n\nfig, ax = plt.subplots(figsize=(10, 6))\n\n# 自动 bins 或指定\nn, bins, patches = ax.hist(df['value'], bins=30,\n color='#3b82f6', edgecolor='white', alpha=0.8)\n\nax.set_title('订单金额分布', fontsize=15, fontweight='bold', pad=12)\nax.set_xlabel('金额（元）')\nax.set_ylabel('频数')\nax.grid(axis='y', alpha=0.3, linestyle='--')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('histogram.png', dpi=150, bbox_inches='tight')\n```\n\n### Bins 数量选择\n\n```python\n# 方法1：Sturges 公式（适合正态分布）\nbins_sturges = int(np.log2(len(df)) + 1)\n\n# 方法2：Freedman-Diaconis 公式（适合偏态分布，推荐）\nq75, q25 = np.percentile(df['value'], [75, 25])\niqr = q75 - q25\nbin_width = 2 * iqr / (len(df) ** (1/3))\nbins_fd = int((df['value'].max() - df['value'].min()) / bin_width)\n\n# 方法3：Square root（简单快速）\nbins_sqrt = int(np.sqrt(len(df)))\n\nprint(f\"Sturges: {bins_sturges}, FD: {bins_fd}, Sqrt: {bins_sqrt}\")\n```\n\n**生产级建议：**\n- 数据量 < 100：bins = 10~15\n- 数据量 100~10000：使用 FD 公式\n- 数据量 > 10000：bins = 50~100，或使用 KDE\n\n### 直方图 + KDE（密度曲线）\n\n```python\nimport seaborn as sns\n\nfig, ax = plt.subplots(figsize=(10, 6))\n\n# 直方图（密度归一化）\nsns.histplot(df['value'], bins=30, kde=True,\n color='#3b82f6', edgecolor='white', alpha=0.6, ax=ax)\n\nax.set_title('用户年龄分布（含密度曲线）', fontsize=15, fontweight='bold')\nax.set_xlabel('年龄')\nax.set_ylabel('密度')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('hist_kde.png', dpi=150, bbox_inches='tight')\n```\n\n### 分组直方图对比\n\n```python\nfig, ax = plt.subplots(figsize=(12, 6))\n\n# 多组数据叠加\nsns.histplot(data=df, x='value', hue='group',\n bins=30, alpha=0.5, edgecolor='white', ax=ax)\n\nax.set_title('不同渠道订单金额分布对比', fontsize=15, fontweight='bold')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('hist_grouped.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 二、箱线图（Box Plot）\n\n### 标准箱线图\n\n```python\nfig, ax = plt.subplots(figsize=(10, 6))\n\nbp = ax.boxplot(df['value'],\n patch_artist=True,\n widths=0.5,\n showfliers=True, # 显示异常值\n flierprops=dict(marker='o', markerfacecolor='#ef4444',\n markersize=6, alpha=0.6))\n\n# 美化\nbp['boxes'][0].set_facecolor('#3b82f6')\nbp['boxes'][0].set_alpha(0.7)\nbp['medians'][0].set_color('#ef4444')\nbp['medians'][0].set_linewidth(2)\n\nax.set_title('响应时间分布', fontsize=15, fontweight='bold', pad=12)\nax.set_ylabel('响应时间（ms）')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('boxplot.png', dpi=150, bbox_inches='tight')\n```\n\n### 多组箱线图对比（最常用）\n\n```python\nfig, ax = plt.subplots(figsize=(12, 6))\n\n# 按类别分组\ngroups = df.groupby('category')['value'].apply(list).to_dict()\nlabels = list(groups.keys())\ndata = [groups[k] for k in labels]\n\nbp = ax.boxplot(data, patch_artist=True, labels=labels,\n showfliers=True, widths=0.6)\n\n# 多色填充\nPALETTE = ['#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#8b5cf6']\nfor i, box in enumerate(bp['boxes']):\n box.set_facecolor(PALETTE[i % len(PALETTE)])\n box.set_alpha(0.7)\nfor median in bp['medians']:\n median.set_color('#1f2937')\n median.set_linewidth(2)\n\nax.set_title('各品类订单金额分布', fontsize=15, fontweight='bold')\nax.set_xlabel('品类')\nax.set_ylabel('金额（元）')\nax.grid(axis='y', alpha=0.3, linestyle='--')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('boxplot_grouped.png', dpi=150, bbox_inches='tight')\n```\n\n### 使用 Seaborn 简化\n\n```python\nfig, ax = plt.subplots(figsize=(12, 6))\n\nsns.boxplot(data=df, x='category', y='value',\n palette=PALETTE, width=0.6, ax=ax)\n\nax.set_title('各区域用户消费分布', fontsize=15, fontweight='bold')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('boxplot_seaborn.png', dpi=150, bbox_inches='tight')\n```\n\n### 横向箱线图\n\n```python\nfig, ax = plt.subplots(figsize=(10, 8))\n\nsns.boxplot(data=df, y='category', x='value',\n palette=PALETTE, width=0.6, ax=ax)\n\nax.set_title('各区域用户消费分布', fontsize=15, fontweight='bold')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('boxplot_horizontal.png', dpi=150, bbox_inches='tight')\n```\n\n### 隐藏异常值\n\n```python\n# 场景：异常值过多影响主分布展示\nfig, ax = plt.subplots(figsize=(12, 6))\n\nsns.boxplot(data=df, x='category', y='value',\n showfliers=False, # 隐藏异常值\n palette=PALETTE, ax=ax)\n\nax.set_title('各品类订单金额分布（隐藏极端值）', fontsize=15, fontweight='bold')\n\nplt.tight_layout()\nplt.savefig('boxplot_no_fliers.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 三、小提琴图（Violin Plot）\n\n小提琴图 = 箱线图 + KDE，同时展示分布形状和统计量。\n\n### 标准小提琴图\n\n```python\nfig, ax = plt.subplots(figsize=(12, 6))\n\nsns.violinplot(data=df, x='category', y='value',\n palette=PALETTE, inner='box', ax=ax)\n# inner: 'box', 'quartile', 'point', 'stick', None\n\nax.set_title('各渠道用户年龄分布', fontsize=15, fontweight='bold')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('violin.png', dpi=150, bbox_inches='tight')\n```\n\n### 小提琴图 + 箱线图叠加\n\n```python\nfig, ax = plt.subplots(figsize=(12, 6))\n\n# 小提琴（半透明）\nsns.violinplot(data=df, x='category', y='value',\n palette=PALETTE, inner=None, alpha=0.4, ax=ax)\n\n# 箱线图叠加\nsns.boxplot(data=df, x='category', y='value',\n width=0.2, color='white', ax=ax,\n boxprops=dict(zorder=10))\n\nax.set_title('各渠道用户年龄分布（小提琴+箱线）', fontsize=15, fontweight='bold')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('violin_box.png', dpi=150, bbox_inches='tight')\n```\n\n### 分组小提琴图\n\n```python\nfig, ax = plt.subplots(figsize=(14, 6))\n\nsns.violinplot(data=df, x='region', y='value', hue='gender',\n split=True, # 左右分割\n palette=['#3b82f6', '#ef4444'], ax=ax)\n\nax.set_title('各地区男女消费分布对比', fontsize=15, fontweight='bold')\nax.legend(title='性别')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('violin_grouped.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 四、核密度图（KDE）\n\n### 单变量 KDE\n\n```python\nfig, ax = plt.subplots(figsize=(10, 6))\n\nsns.kdeplot(df['value'], fill=True, color='#3b82f6', alpha=0.6, ax=ax)\n\nax.set_title('用户年龄密度分布', fontsize=15, fontweight='bold')\nax.set_xlabel('年龄')\nax.set_ylabel('密度')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('kde.png', dpi=150, bbox_inches='tight')\n```\n\n### 多组 KDE 对比\n\n```python\nfig, ax = plt.subplots(figsize=(12, 6))\n\nfor group, color in zip(['A', 'B', 'C'], PALETTE[:3]):\n subset = df[df['group'] == group]['value']\n sns.kdeplot(subset, fill=True, alpha=0.4, label=group, color=color, ax=ax)\n\nax.legend(title='渠道')\nax.set_title('各渠道订单金额密度对比', fontsize=15, fontweight='bold')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('kde_grouped.png', dpi=150, bbox_inches='tight')\n```\n\n### 双变量 KDE（2D 密度图）\n\n```python\nfig, ax = plt.subplots(figsize=(10, 8))\n\nsns.kdeplot(data=df, x='feature_a', y='feature_b',\n fill=True, cmap='Blues', thresh=0.1, levels=10, ax=ax)\n\nax.set_title('用户行为特征二维密度分布', fontsize=15, fontweight='bold')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('kde_2d.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 五、高级场景\n\n### 直方图 + 统计线（均值/中位数）\n\n```python\nfig, ax = plt.subplots(figsize=(10, 6))\n\nax.hist(df['value'], bins=30, color='#3b82f6', edgecolor='white', alpha=0.7)\n\nmean_val = df['value'].mean()\nmedian_val = df['value'].median()\n\nax.axvline(mean_val, color='#ef4444', linestyle='--', linewidth=2, label=f'均值: {mean_val:.1f}')\nax.axvline(median_val, color='#10b981', linestyle='-.', linewidth=2, label=f'中位数: {median_val:.1f}')\n\nax.legend()\nax.set_title('订单金额分布（含统计线）', fontsize=15, fontweight='bold')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('hist_stats.png', dpi=150, bbox_inches='tight')\n```\n\n### 箱线图 + 散点叠加（展示原始数据）\n\n```python\nfig, ax = plt.subplots(figsize=(12, 6))\n\n# 箱线图\nsns.boxplot(data=df, x='category', y='value',\n palette=PALETTE, width=0.5, ax=ax)\n\n# 散点叠加（带抖动）\nsns.stripplot(data=df, x='category', y='value',\n size=3, alpha=0.3, color='#1f2937', ax=ax)\n\nax.set_title('各品类订单金额分布（含原始数据点）', fontsize=15, fontweight='bold')\nax.spines['top'].set_visible(False)\nax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('box_strip.png', dpi=150, bbox_inches='tight')\n```\n\n### 分布对比：直方图 vs 箱线图 vs 小提琴图\n\n```python\nfig, axes = plt.subplots(1, 3, figsize=(15, 5))\n\n# 直方图\naxes[0].hist(df['value'], bins=30, color='#3b82f6', edgecolor='white', alpha=0.7)\naxes[0].set_title('直方图')\naxes[0].set_xlabel('值')\naxes[0].set_ylabel('频数')\n\n# 箱线图\naxes[1].boxplot(df['value'], patch_artist=True)\naxes[1].set_title('箱线图')\naxes[1].set_ylabel('值')\n\n# 小提琴图\nsns.violinplot(y=df['value'], ax=axes[2], color='#3b82f6')\naxes[2].set_title('小提琴图')\naxes[2].set_ylabel('值')\n\nfor ax in axes:\n ax.spines['top'].set_visible(False)\n ax.spines['right'].set_visible(False)\n\nplt.tight_layout()\nplt.savefig('distribution_compare.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 六、强制规范\n\n### ✅ MUST DO\n\n- **直方图必须指定 bins 或让算法自动选择**，避免使用默认值\n- **箱线图必须标注异常值定义**（默认 1.5×IQR，可调整）\n- **多组分布对比时，使用相同的 Y 轴范围**\n- **中位数线必须清晰可见**（颜色对比、线宽）\n- **直方图柱子之间必须有白色边框**（避免视觉混淆）\n- **KDE 曲线必须有标签说明**（密度 vs 概率）\n\n### ❌ MUST NOT\n\n- 不在直方图上省略 X 轴标签（值范围）\n- 不用箱线图展示类别 > 20 的数据（改为聚合或筛选）\n- 不在小提琴图中隐藏统计量（至少显示中位数）\n- 不用 3D 直方图\n- 不忽略异常值的解释（是什么原因？是否需要排除？）\n- 不在密度图中使用 fill=False（无法直观比较）\n\n---\n\n## 七、行业最佳实践\n\n### 电商：订单金额分布\n\n```python\n# 典型电商订单金额呈长尾分布，用对数 X 轴\nfig, ax = plt.subplots(figsize=(10, 6))\n\nax.hist(df['order_amount'], bins=50, color='#3b82f6', edgecolor='white', alpha=0.7)\nax.set_xscale('log') # 对数轴\n\nax.set_title('订单金额分布（对数轴）', fontsize=15, fontweight='bold')\nax.set_xlabel('金额（元，对数刻度）')\nax.set_ylabel('订单数')\n\nplt.tight_layout()\nplt.savefig('order_amount_log.png', dpi=150, bbox_inches='tight')\n```\n\n### 金融：收益率分布\n\n```python\n# 收益率通常接近正态，检查肥尾\nfig, ax = plt.subplots(figsize=(10, 6))\n\nsns.histplot(df['return'], bins=50, kde=True, color='#3b82f6', ax=ax)\n\n# 添加正态分布参考\nfrom scipy import stats\nx = np.linspace(df['return'].min(), df['return'].max(), 100)\ny = stats.norm.pdf(x, df['return'].mean(), df['return'].std())\nax.plot(x, y * len(df) * (x[1] - x[0]), 'r--', label='正态分布参考')\n\nax.legend()\nax.set_title('日收益率分布 vs 正态分布', fontsize=15, fontweight='bold')\n\nplt.tight_layout()\nplt.savefig('return_distribution.png', dpi=150, bbox_inches='tight')\n```\n\n### 运维：响应时间分布\n\n```python\n# P50, P90, P99 分位线\nfig, ax = plt.subplots(figsize=(10, 6))\n\nax.hist(df['response_time'], bins=50, color='#3b82f6', edgecolor='white', alpha=0.7)\n\np50 = df['response_time'].quantile(0.5)\np90 = df['response_time'].quantile(0.9)\np99 = df['response_time'].quantile(0.99)\n\nax.axvline(p50, color='#10b981', linestyle='--', linewidth=2, label=f'P50: {p50:.0f}ms')\nax.axvline(p90, color='#f59e0b', linestyle='--', linewidth=2, label=f'P90: {p90:.0f}ms')\nax.axvline(p99, color='#ef4444', linestyle='--', linewidth=2, label=f'P99: {p99:.0f}ms')\n\nax.legend()\nax.set_title('API 响应时间分布', fontsize=15, fontweight='bold')\nax.set_xlabel('响应时间（ms）')\nax.set_ylabel('请求数')\n\nplt.tight_layout()\nplt.savefig('response_time_p99.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 八、常见问题与解决方案\n\n| 问题 | 原因 | 解决方案 |\n|------|------|---------|\n| 直方图柱子太少/太多 | bins 不合适 | 使用 FD 公式或手动调整 |\n| 箱线图异常值过多 | 数据本身有极端值 | 检查数据质量；可调高异常阈值 |\n| 多组分布无法比较 | Y 轴范围不同 | 设置 `sharey=True` 或手动统一 |\n| KDE 曲线超出数据范围 | 核密度估计外推 | 设置 `clip=(min, max)` |\n| 小提琴图太拥挤 | 类别太多 | 改用箱线图或分面展示 |\n| 直方图右偏严重 | 长尾分布 | 使用对数 X 轴 |\n\nFile v1.0.0:references/heatmap.md\n\n# 热力图 — 相关性矩阵、时间热图、表格热图\n\n适用场景：相关性分析、时间序列密度、分类数据对比、矩阵数据可视化。\n\n---\n\n## 核心问题：你想展示什么类型的热力图？\n\n| 场景 | 推荐类型 |\n|------|---------|\n| 特征之间的相关性？ | 相关性矩阵热力图 |\n| 随时间变化的强度？ | 时间热力图（Calendar/Activity） |\n| 分类数据对比？ | 分类热力图 |\n| 表格数据可视化？ | 表格热力图 |\n| 地理位置密度？ | 地理热力图（需地图数据，见地理图表） |\n\n---\n\n## 一、相关性矩阵热力图\n\n相关性热力图是最常用的场景，用于发现变量之间的关系。\n\n### 基础相关性热力图\n\n```python\nimport matplotlib.pyplot as plt\nimport seaborn as sns\nimport numpy as np\nimport pandas as pd\n\nplt.rcParams['font.sans-serif'] = ['SimHei', 'Microsoft YaHei']\nplt.rcParams['axes.unicode_minus'] = False\n\nfig, ax = plt.subplots(figsize=(12, 10))\n\n# 计算相关性矩阵\ncorr = df[['col1', 'col2', 'col3', 'col4', 'col5']].corr()\n\n# 绘制热力图\nmask = np.zeros_like(corr) # 可选：只显示下三角 mask = np.triu(np.ones_like(corr, dtype=bool))\n\nsns.heatmap(corr,\n annot=True, # 显示数值\n fmt='.2f', # 数值格式\n cmap='RdYlGn', # 颜色映射：红-黄-绿（正相关绿，负相关红）\n center=0, # 0 为中心\n square=True, # 正方形格子\n linewidths=0.5, # 格子间隔线\n cbar_kws={'shrink': 0.8, 'label': '相关系数'},\n ax=ax)\n\nax.set_title('特征相关性矩阵', fontsize=15, fontweight='bold', pad=15)\nplt.xticks(rotation=45, ha='right')\nplt.yticks(rotation=0)\n\nplt.tight_layout()\nplt.savefig('corr_heatmap.png', dpi=150, bbox_inches='tight')\n```\n\n### 只显示下三角（避免重复信息）\n\n```python\nfig, ax = plt.subplots(figsize=(12, 10))\n\n# 上三角遮罩\nmask = np.triu(np.ones_like(corr, dtype=bool))\n\nsns.heatmap(corr, mask=mask,\n annot=True, fmt='.2f',\n cmap='RdYlGn', center=0,\n square=True, linewidths=0.5,\n cbar_kws={'shrink': 0.8},\n ax=ax)\n\nax.set_title('特征相关性矩阵（下三角）', fontsize=15, fontweight='bold', pad=15)\nplt.xticks(rotation=45, ha='right')\nplt.yticks(rotation=0)\n\nplt.tight_layout()\nplt.savefig('corr_heatmap_lower.png', dpi=150, bbox_inches='tight')\n```\n\n### 高级：带聚类的相关性热力图\n\n```python\n# 使用 clustermap 进行层次聚类排序\ng = sns.clustermap(corr,\n method='ward', # 聚类方法\n cmap='RdYlGn',\n center=0,\n annot=True,\n fmt='.2f',\n linewidths=0.5,\n figsize=(12, 10),\n dendrogram_ratio=(.1, .1),\n cbar_pos=(0.02, 0.8, 0.03, 0.15))\n\ng.fig.suptitle('特征相关性矩阵（含聚类）', fontsize=15, fontweight='bold', y=1.02)\ng.savefig('corr_clustermap.png', dpi=150, bbox_inches='tight')\nplt.close()\n```\n\n### 标注显著性（p-value）\n\n```python\nfrom scipy import stats\n\ndef corr_with_pvalue(df):\n cols = df.columns\n n = len(cols)\n corr = np.zeros((n, n))\n pval = np.zeros((n, n))\n for i in range(n):\n for j in range(n):\n if i == j:\n corr[i, j] = 1.0\n pval[i, j] = 0\n else:\n r, p = stats.pearsonr(df.iloc[:, i], df.iloc[:, j])\n corr[i, j] = r\n pval[i, j] = p\n return pd.DataFrame(corr, index=cols, columns=cols), pd.DataFrame(pval, index=cols, columns=cols)\n\ncorr_matrix, pval_matrix = corr_with_pvalue(df)\n\nfig, ax = plt.subplots(figsize=(12, 10))\n\n# 显著性标注（* p<0.05, ** p<0.01, *** p<0.001）\nannot = corr_matrix.round(2).copy()\nfor i in range(len(pval_matrix)):\n for j in range(len(pval_matrix)):\n p = pval_matrix.iloc[i, j]\n if p < 0.001:\n annot.iloc[i, j] = f'{corr_matrix.iloc[i, j]:.2f}***'\n elif p < 0.01:\n annot.iloc[i, j] = f'{corr_matrix.iloc[i, j]:.2f}**'\n elif p < 0.05:\n annot.iloc[i, j] = f'{corr_matrix.iloc[i, j]:.2f}*'\n\nsns.heatmap(corr_matrix, annot=annot, fmt='',\n cmap='RdYlGn', center=0,\n square=True, linewidths=0.5,\n ax=ax)\n\nax.set_title('相关性矩阵（* p<0.05, ** p<0.01, *** p<0.001）', fontsize=15, fontweight='bold')\nplt.tight_layout()\nplt.savefig('corr_pvalue.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 二、时间热力图\n\n### GitHub 风格贡献热力图\n\n```python\nfig, ax = plt.subplots(figsize=(14, 6))\n\n# 重塑为周×天的矩阵（周一=0，周日=6）\ndf['date'] = pd.to_datetime(df['date'])\ndf['week'] = df['date'].dt.isocalendar().week\ndf['dayofweek'] = df['date'].dt.dayofweek\n\n# 按周和星期聚合\npivot = df.groupby(['week', 'dayofweek'])['value'].sum().unstack(fill_value=0)\n\n# 绘制热力图\nsns.heatmap(pivot, cmap='YlGnBu', linewidths=0.5,\n square=False, cbar_kws={'label': '活跃度'},\n ax=ax)\n\n# Y 轴标签改为星期\nax.set_yticklabels(['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'])\nax.set_xticklabels([f'W{int(w)}' for w in ax.get_xticks()], rotation=45, ha='right', fontsize=8)\nax.set_title('每日活跃热力图', fontsize=15, fontweight='bold')\nax.set_xlabel('周数')\nax.set_ylabel('')\n\nplt.tight_layout()\nplt.savefig('calendar_heatmap.png', dpi=150, bbox_inches='tight')\n```\n\n### Seaborn 内置 Calendar Heatmap（年视图）\n\n```python\n# 使用 calmap 库（更专业）\nimport calmap\n\nfig, ax = plt.subplots(figsize=(15, 6))\n\n# 设置日期索引\ndf_indexed = df.set_index('date')['value']\n\ncalmap.yearplot(df_indexed, year=2026, ax=ax, cmap='YlGnBu')\n\nax.set_title('2026 年度活跃热力图', fontsize=15, fontweight='bold')\nplt.tight_layout()\nplt.savefig('year_heatmap.png', dpi=150, bbox_inches='tight')\n```\n\n### 月度时间热力图（小时 × 天）\n\n```python\n# 场景：用户活跃时间段分析\nfig, ax = plt.subplots(figsize=(14, 8))\n\n# 创建小时×星期的矩阵\ndf['hour'] = df['timestamp'].dt.hour\ndf['weekday'] = df['timestamp'].dt.dayofweek\npivot = df.groupby(['weekday', 'hour'])['value'].sum().unstack(fill_value=0)\n\n# 绘制\nsns.heatmap(pivot, cmap='Blues', linewidths=0.5,\n xticklabels=range(24), yticklabels=['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],\n cbar_kws={'label': '活动量'}, ax=ax)\n\nax.set_title('用户活跃时段分布（小时 × 星期）', fontsize=15, fontweight='bold')\nax.set_xlabel('小时')\nax.set_ylabel('星期')\nplt.xticks(rotation=0)\nplt.yticks(rotation=0)\n\nplt.tight_layout()\nplt.savefig('hour_weekday_heatmap.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 三、分类热力图\n\n### 分组数据热力图\n\n```python\nfig, ax = plt.subplots(figsize=(14, 8))\n\n# 创建 品类×月份 的数据矩阵\npivot = df.pivot_table(values='sales',\n index='category',\n columns='month',\n aggfunc='sum',\n fill_value=0)\n\nsns.heatmap(pivot, cmap='Blues', linewidths=0.5,\n annot=True, fmt=',.0f',\n cbar_kws={'label': '销售额（万元）'},\n ax=ax)\n\nax.set_title('各品类月度销售额', fontsize=15, fontweight='bold')\nplt.xticks(rotation=45, ha='right')\nplt.yticks(rotation=0)\n\nplt.tight_layout()\nplt.savefig('category_month_heatmap.png', dpi=150, bbox_inches='tight')\n```\n\n### 百分比热力图（按行归一化）\n\n```python\nfig, ax = plt.subplots(figsize=(14, 8))\n\n# 按行归一化（每行之和为 100%）\npivot_pct = pivot.div(pivot.sum(axis=1), axis=0) * 100\n\nsns.heatmap(pivot_pct, cmap='Blues', linewidths=0.5,\n annot=True, fmt='.1f',\n cbar_kws={'label': '占比（%）'},\n ax=ax)\n\nax.set_title('各品类月度销售额占比（%）', fontsize=15, fontweight='bold')\nplt.xticks(rotation=45, ha='right')\nplt.yticks(rotation=0)\n\nplt.tight_layout()\nplt.savefig('category_month_pct.png', dpi=150, bbox_inches='tight')\n```\n\n### 发散型热力图（展示增减变化）\n\n```python\nfig, ax = plt.subplots(figsize=(14, 8))\n\n# 计算环比变化\npivot_diff = pivot.pct_change(axis=1) * 100 # 月度环比增长率\n\n# 发散型 colormap（正=绿，负=红）\ncmap = sns.diverging_palette(10, 130, as_cmap=True) # 红-白-绿\n\nsns.heatmap(pivot_diff, cmap=cmap, center=0,\n linewidths=0.5, fmt='+.1f',\n annot=True, vmin=-50, vmax=50,\n cbar_kws={'label': '环比增长率（%）'},\n ax=ax)\n\nax.set_title('各品类月度销售额环比变化（%）', fontsize=15, fontweight='bold')\nplt.xticks(rotation=45, ha='right')\nplt.yticks(rotation=0)\n\nplt.tight_layout()\nplt.savefig('pivot_diverging.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 四、Cohort 留存热力图\n\n用户留存分析的标准可视化。\n\n```python\ndef cohort_heatmap(df, cohort_col, period_col, value_col='user_id', metric='count'):\n \"\"\"\n 生成 Cohort 留存热力图\n df: 包含用户首次行为日期和当前行为日期的数据\n cohort_col: 首次行为日期列\n period_col: 当前行为日期列\n \"\"\"\n df = df.copy()\n df[cohort_col] = pd.to_datetime(df[cohort_col])\n df[period_col] = pd.to_datetime(df[period_col])\n\n # Cohort 周期（月份）\n df['cohort_month'] = df[cohort_col].dt.to_period('M')\n df['period_month'] = df[period_col].dt.to_period('M')\n\n # 计算相对月份\n df['period_number'] = (df['period_month'].astype(int) - df['cohort_month'].astype(int))\n\n # 统计每个 Cohort × Period 的用户数\n cohort_data = df.groupby(['cohort_month', 'period_number'])[value_col].nunique().reset_index()\n cohort_table = cohort_data.pivot(index='cohort_month', columns='period_number', values=value_col)\n\n # 计算留存率\n cohort_size = cohort_table.iloc[:, 0]\n retention_table = cohort_table.divide(cohort_size, axis=0) * 100\n\n return cohort_table, retention_table\n\n# 生成数据\ncohort_table, retention_table = cohort_heatmap(df, 'first_date', 'activity_date')\n\n# 绘制热力图\nfig, ax = plt.subplots(figsize=(16, 10))\n\nsns.heatmap(retention_table, cmap='YlGnBu', linewidths=0.5,\n annot=True, fmt='.0f', vmin=0, vmax=100,\n cbar_kws={'label': '留存率（%）'},\n ax=ax)\n\nax.set_title('Cohort 用户留存率（%）', fontsize=15, fontweight='bold')\nax.set_xlabel('距首次活跃月数')\nax.set_ylabel('Cohort（首次活跃月份）')\nplt.xticks(rotation=0)\nplt.yticks(rotation=0)\n\nplt.tight_layout()\nplt.savefig('cohort_retention.png', dpi=150, bbox_inches='tight')\n```\n\n### Cohort 热力图进阶：同时显示人数和留存率\n\n```python\n# 创建双层热力图：人数 + 留存率\nfig, axes = plt.subplots(1, 2, figsize=(20, 10))\n\n# 左图：绝对人数\nsns.heatmap(cohort_table, cmap='Blues', linewidths=0.5,\n annot=True, fmt=',.0f', ax=axes[0])\naxes[0].set_title('Cohort 用户数', fontsize=14, fontweight='bold')\naxes[0].set_xlabel('距首次活跃月数')\n\n# 右图：留存率\nsns.heatmap(retention_table, cmap='YlGnBu', linewidths=0.5,\n annot=True, fmt='.0f', vmin=0, vmax=100, ax=axes[1])\naxes[1].set_title('Cohort 留存率（%）', fontsize=14, fontweight='bold')\naxes[1].set_xlabel('距首次活跃月数')\n\nfor ax in axes:\n ax.set_ylabel('')\n\nplt.suptitle('用户 Cohort 分析', fontsize=16, fontweight='bold', y=1.02)\nplt.tight_layout()\nplt.savefig('cohort_combined.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 五、表格热力图\n\n### 普通表格热力图\n\n```python\nfig, ax = plt.subplots(figsize=(14, 8))\n\n# 创建表格数据\ntable_data = df.pivot_table(values='sales',\n index='region',\n columns='product',\n aggfunc='sum',\n fill_value=0)\n\nsns.heatmap(table_data, cmap='Oranges', linewidths=1,\n annot=True, fmt=',.0f',\n cbar_kws={'label': '销售额（万元）'},\n ax=ax, annot_kws={'size': 10})\n\nax.set_title('各区域各产品销售额', fontsize=15, fontweight='bold')\nplt.xticks(rotation=45, ha='right', fontsize=10)\nplt.yticks(rotation=0, fontsize=10)\n\nplt.tight_layout()\nplt.savefig('table_heatmap.png', dpi=150, bbox_inches='tight')\n```\n\n### 带格式化文本的热力图\n\n```python\nfig, ax = plt.subplots(figsize=(14, 8))\n\n# 自定义格式化函数\ndef fmt(val):\n if val == 0:\n return '-'\n elif val >= 10000:\n return f'{val/10000:.1f}万'\n elif val >= 1000:\n return f'{val/1000:.0f}千'\n else:\n return f'{val:.0f}'\n\nannot = table_data.applymap(fmt)\n\nsns.heatmap(table_data, cmap='YlOrRd', linewidths=1,\n annot=annot, fmt='', cbar=False, ax=ax)\n\nax.set_title('各区域各产品销售额', fontsize=15, fontweight='bold')\nplt.xticks(rotation=45, ha='right')\nplt.yticks(rotation=0)\n\nplt.tight_layout()\nplt.savefig('table_heatmap_fmt.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 六、颜色映射选择指南\n\n### 何时用哪种 Colormap\n\n| Colormap | 类型 | 适用场景 |\n|----------|------|---------|\n| `RdYlGn` | 发散型 | 相关性、变化率（中心=0） |\n| `RdBu` | 发散型 | 正负对比（金融涨跌） |\n| `seismic` | 发散型 | 地震/极端正负值 |\n| `Blues` / `YlGnBu` | 顺序型 | 单向递增（销售额、用户数） |\n| `Oranges` / `Reds` | 顺序型 | 热度、风险、强度 |\n| `viridis` / `plasma` | 顺序型 | 科学数据、色盲友好 |\n| `coolwarm` | 发散型 | 温度、情感分析 |\n| `cubehelix` | 顺序型 | 亮度渐变、打印友好 |\n\n### 发散型 vs 顺序型\n\n```python\n# 发散型：数据有正负对比\ncmap_div = sns.diverging_palette(10, 130, as_cmap=True) # 红-白-绿\n\n# 顺序型：数据单向递增\ncmap_seq = sns.color_palette('Blues', as_cmap=True)\n\n# 自定义边界\nimport matplotlib.colors as mcolors\ncmap_custom = mcolors.LinearSegmentedColormap.from_list(\n 'custom', ['#f7fbff', '#3b82f6', '#1e3a5f'])\n```\n\n### 色盲友好建议\n\n```python\n# 推荐色盲友好的 colormap\ncbar_kws={'label': '值', 'cmap': 'viridis'} # 默认最优\ncbar_kws={'label': '值', 'cmap': 'cividis'} # 更深的对比\n```\n\n---\n\n## 七、高级场景\n\n### 热力图 + 树状图（层次聚类排序）\n\n```python\ng = sns.clustermap(df.corr(),\n method='average',\n metric='correlation',\n cmap='RdYlGn',\n center=0,\n annot=True,\n fmt='.2f',\n linewidths=0.5,\n figsize=(12, 10),\n dendrogram_ratio=(0.2, 0.2),\n cbar_pos=(0.02, 0.8, 0.03, 0.15),\n tree_kws={'linewidths': 0.5})\n\ng.fig.suptitle('相关性矩阵（层次聚类）', fontsize=15, fontweight='bold', y=1.02)\nplt.savefig('heatmap_clustered.png', dpi=150, bbox_inches='tight')\nplt.close()\n```\n\n### 带缺失值的热力图\n\n```python\nfig, ax = plt.subplots(figsize=(14, 8))\n\n# NaN 显示为灰色\ncmap = sns.diverging_palette(10, 130, as_cmap=True)\n\nsns.heatmap(table_data, cmap=cmap, center=0,\n linewidths=0.5, fmt='.1f',\n annot=True, ax=ax,\n mask=table_data.isna(), # 遮罩缺失值\n na_rep='N/A')\n\nax.set_title('数据热力图（含缺失值显示为 N/A）', fontsize=15, fontweight='bold')\nplt.tight_layout()\nplt.savefig('heatmap_na.png', dpi=150, bbox_inches='tight')\n```\n\n### 热力图边框和单元格大小控制\n\n```python\nfig, ax = plt.subplots(figsize=(14, 8))\n\n# 调整单元格比例\nsns.heatmap(table_data, cmap='Blues',\n linewidths=2, # 加粗边框\n linecolor='white', # 白色分隔线\n square=True, # 正方形格子\n ax=ax)\n\nax.set_title('单元格热力图', fontsize=15, fontweight='bold')\nplt.tight_layout()\nplt.savefig('heatmap_square.png', dpi=150, bbox_inches='tight')\n```\n\n### 热力图 + 散点叠加（双层信息）\n\n```python\nfig, ax = plt.subplots(figsize=(14, 8))\n\n# 底色热力图\nsns.heatmap(table_data, cmap='Blues', alpha=0.3,\n annot=False, linewidths=0, ax=ax)\n\n# 叠加数值散点\nfor i, row_idx in enumerate(table_data.index):\n for j, col_idx in enumerate(table_data.columns):\n val = table_data.loc[row_idx, col_idx]\n if pd.notna(val):\n ax.scatter(j + 0.5, i + 0.5, s=val/10,\n c='red' if val > table_data.median().median() else 'blue',\n alpha=0.6, zorder=10)\n\nax.set_title('热力图 + 散点叠加', fontsize=15, fontweight='bold')\nplt.tight_layout()\nplt.savefig('heatmap_scatter.png', dpi=150, bbox_inches='tight')\n```\n\n---\n\n## 八、强制规范\n\n### ✅ MUST DO\n\n- **相关性热力图必须标注数值**（annot=True）\n- **发散型 colormap 必须设置 center=0**\n- **colormap 必须有 colorbar 和标签**\n- **长标签必须旋转**（rotation=45）保证可读\n- **单元格大小应与数据量匹配**：数据多格子小，数据少格子大\n- **缺失值必须处理**：mask 或 na_rep\n\n### ❌ MUST NOT\n\n- 不用 `jet` / `rainbow` 等非色盲友好 colormap\n- 不在正负数据上使用单向 colormap（如 Blues）\n- 不省略 colorbar（无法判断颜色对应数值）\n- 不在过小的格子里显示长数字（改用颜色深浅）\n- 不用 3D 热力图（无法准确读值）\n- 不在类别过多时使用热力图（改用条形图或表格）\n\n---\n\n## 九、行业最佳实践\n\n### 电商：品类×时间 销售热力图\n\n```python\n# 月度销售趋势热力图\nfig, ax = plt.subplots(figsize=(16, 10))\n\npivot = df.pivot_table(values='gmv',\n index='category',\n columns='month',\n aggfunc='sum',\n fill_value=0)\n\n# 使用聚类排序\ng = sns.clustermap(pivot, cmap='YlGnBu',","readmeExcerpt":"Skill: SQL Dataviz Owner: moniq888 Summary: Convert SQL query results into production-grade visual charts including bar, line, pie, map, KPI, AI insights, and interactive HTML dashboards with base64 PN... Tags: latest:1.0.1 Version history: v1.0.1 | 2026-03-27T10:33:33.832Z | user - 修正协作工具名称，将“report-generator”统一为“sql-report-generator”以匹配实际 Skill 名称 - 数据分析流程示意图和协作流程文档细节微调，增强 Skill 协作关系说明 - 文档其余内容未变，功能和接口保持不变 v1.0.0 |","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"skillhub_install install_skill sql-dataviz"},{"language":"text","snippet":"┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐\n│ sql-master │ ──► │ sql-dataviz │ ──► │ sql-report-generator │\n│ (数据层) │ │ (可视化层) │ │ (报告层) │\n└─────────────┘ └──────────────┘ └────────────────────────┘\n │ │ │\n ▼ ▼ ▼\n SQL 查询 图表生成 HTML 报告\n 数据获取 PNG/HTML AI 洞察\n 格式转换 Dashboard 数据表格"},{"language":"python","snippet":"from scripts.unified_pipeline import UnifiedPipeline\n\nresult = (\n UnifiedPipeline(\"销售分析\")\n .from_file(\"sales.csv\") # sql-master: 数据获取\n .query(\"SELECT region, SUM(sales) as total FROM data GROUP BY region\")\n .interactive_chart(\"bar\", x_col=\"region\", y_col=\"total\") # sql-dataviz: 可视化\n .insights(value_cols=[\"total\"]) # AI 洞察\n .report(title=\"销售报告\", output=\"report.html\") # sql-report-generator: 报告\n)"},{"language":"text","snippet":"你需要什么？\n├─ 仅图表可视化 → sql-dataviz 单独使用\n├─ SQL + 图表 → sql-master + sql-dataviz\n├─ 图表 + 报告（无 SQL）→ sql-dataviz + sql-report-generator\n└─ 完整分析报告 → sql-master + sql-dataviz + sql-report-generator ✅ 推荐"},{"language":"python","snippet":"from scripts.interactive_charts import InteractiveChartFactory, DashboardBuilder\n\nfactory = InteractiveChartFactory(theme=\"powerbi\")\n\n# 12 种图表类型\nhtml = factory.create_line(data) # 折线图\nhtml = factory.create_bar(data) # 柱形图\nhtml = factory.create_pie(data) # 饼图（环形）\nhtml = factory.create_scatter(data) # 散点图\nhtml = factory.create_heatmap(data) # 热力图\nhtml = factory.create_funnel(data) # 漏斗图\nhtml = factory.create_area(data) # 面积图\nhtml = factory.create_treemap(data) # 树状图\nhtml = factory.create_gauge(data) # 仪表盘\nhtml = factory.create_combo(data) # 组合图（柱+折线）\nhtml = factory.create_table(data) # 交互式表格\nhtml = factory.create_kpi_cards(data) # KPI 卡片组\n\nfactory.save_html(html, \"chart.html\")\n\n# 多图表 Dashboard\nbuilder = DashboardBuilder(title=\"销售看板\", theme=\"powerbi\")\nbuilder.add_kpi_cards([{\"title\":\"GMV\",\"value\":\"¥1,234万\",\"change\":\"+18%\"}])\nbuilder.add_chart(factory.create_line(...), title=\"月度趋势\", cols=2)\nbuilder.add_chart(factory.create_bar(...), title=\"区域对比\", cols=1)\nbuilder.build(\"dashboard.html\")"},{"language":"python","snippet":"from sql_dataviz.charts import ChartFactory, ChartConfig, Theme\n\n# 1. 创建工厂\nfactory = ChartFactory()\n\n# 2. 设置主题（可选）\nfactory.set_theme('powerbi') # 或 'alibaba', 'tencent', 'bytedance'\n\n# 3. 准备数据\ndata = {\n 'categories': ['Q1', 'Q2', 'Q3', 'Q4'],\n 'series': [\n {'name': '销售额', 'data': [100, 150, 120, 200]},\n {'name': '成本', 'data': [60, 80, 70, 100]}\n ]\n}\n\n# 4. 生成图表（base64 PNG）\nchart_b64 = factory.create_clustered_column(data)\n\n# 5. 嵌入到 HTML\nhtml = f'\n \n
\n \n\n\n```\n\n---\n\n## Chart.js 常用图表类型\n\n| type 值 | 图表类型 |\n|---------|---------|\n| `'line'` | 折线图 |\n| `'bar'` | 条形图（纵向） |\n| `'bar'` + `indexAxis: 'y'` | 横向条形图 |\n| `'pie'` | 饼图（慎用） |\n| `'doughnut'` | 环形图 |\n| `'scatter'` | 散点图 |\n| `'bubble'` | 气泡图 |\n| `'radar'` | 雷达图 |\n\n---\n\n## 多系列条形图示例\n\n```javascript\nnew Chart(ctx, {\n type: 'bar',\n data: {\n labels: ['Q1', 'Q2', 'Q3', 'Q4'],\n datasets: [\n {\n label: 'PC端',\n data: [3200, 4100, 3800, 5200],\n backgroundColor: '#3b82f6'\n },\n {\n label: '移动端',\n data: [5100, 6200, 7100, 8900],\n backgroundColor: '#10b981'\n }\n ]\n },\n options: {\n responsive: true,\n plugins: {\n title: { display: true, text: '各渠道季度订单量' }\n },\n scales: { y: { beginAtZero: true } }\n }\n});\n```\n\n---\n\n## 注意事项\n\n- Canvas 渲染依赖网络加载 Chart.js CDN，离线环境需本地引入\n- 数据量大时（>1000 点），建议先聚合再渲染，避免卡顿\n- 中文字体在 Canvas 中需要系统已安装对应字体\n- 复杂统计图（箱线图、小提琴图）建议用 Python matplotlib 生成图片，再展示"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Convert SQL query results into production-grade visual charts including bar, line, pie, map, KPI, AI insights, and interactive HTML dashboards with base64 PN... Skill: SQL Dataviz Owner: moniq888 Summary: Convert SQL query results into production-grade visual charts including bar, line, pie, map, KPI, AI insights, and interactive HTML dashboards with base64 PN... Tags: latest:1.0.1 Version history: v1.0.1 | 2026-03-27T10:33:33.832Z | user - 修正协作工具名称，将“report-generator”统一为“sql-report-generator”以匹配实际 Skill 名称 - 数据分析流程示意图和协作流程文档细节微调，增强 Skill 协作关系说明 - 文档其余内容未变，功能和接口保持不变 v1.0.0 |","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":787,"uniquenessScore":58,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T21:34:47.045Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T21:34:47.045Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-13T06:52:19.121Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}