Python绘制雷达图报错IndexError或ValueError排查

一、报错表现与排查切入点

雷达图（极坐标折线图）与常见的笛卡尔坐标系折线图在绘制机制上有一个关键区别：为了使多边形完全闭合，绘制线条时必须将首个顶点追加到末尾，形成 N+1 个点；而在极坐标系中指定特征名称（如刻度标签）时，特征总数依然只有 N 个。混淆这两类序列是引发报错的直接诱因。

在排查报错前，先通过终端输出的 Traceback 信息锁定报错类型与发生行：

• ValueError: x and y must have same first dimension：通常发生在调用 ax.plot(angles, values) 或 ax.fill(angles, values) 时，表示传入的角度数组 angles 与数值数组 values 长度不一致。
• ValueError: The number of tick labels must match the number of tick locations：发生在 ax.set_thetagrids(angles, labels)，说明传入的刻度点数量与文本标签数量不匹配。
• IndexError: index ... is out of bounds for axis 0 with size ...：通常出现在遍历多组数据绘制多边形、通过切片提取列指标，或者在自定义标签循环中下标越界。

二、深入剖析：“数据闭合”引发的维度陷阱

雷达图在数学上是一个极坐标多边形。假设我们要展示 5 项指标（例如：速度、力量、敏捷、智力、耐力）。计算机绘制折线时，画出 5 个点只能得到 4 条线段，首尾是断开的。为了画出封闭多边形，必须把第 1 个点追加到第 5 个点之后，形成包含 6 个坐标点的序列。

正是这个“追加首项”的动作，构成了大多数 ValueError 的温床：

1. 单边闭合失衡：很多初学者写了 values = np.append(values, values[0])，此时 values 的长度由 5 变成了 6。但角度数组 angles 仍是 np.linspace(0, 2*np.pi, 5, endpoint=False)，长度为 5。执行 ax.plot(angles, values) 时，Matplotlib 发现两者的第一维度大小不同，立刻抛出 ValueError: x and y must have same first dimension。
2. 刻度绑定使用了闭合数组：设置极坐标轴外圈标签时，使用 ax.set_thetagrids(angles * 180 / np.pi, labels)。如果此时传入的是已经追加过首项的 6 元素角度数组，而 labels 只有 5 个特征名称，就会触发 ValueError: The number of tick labels must match the number of tick locations。

三、三大高频报错场景复现与逐一修复

场景 1：ValueError: x and y must have same first dimension

错误代码重现：

import numpy as np
import matplotlib.pyplot as plt

labels = ['输出', '承伤', '机动', '辅助', '控制']
values = [80, 65, 90, 70, 85]

# 生成角度
angles = np.linspace(0, 2 * np.pi, len(labels), endpoint=False)

# 仅对数值进行了闭合！
values = np.concatenate((values, [values[0]]))

fig, ax = plt.subplots(subplot_kw=dict(polar=True))
# 此时 len(angles) 是 5，len(values) 是 6，抛出 ValueError
ax.plot(angles, values)

根因与修复：plot() 函数要求传入的 X 坐标与 Y 坐标在第 0 维大小完全一致。既然 values 追加了首元素，angles 也必须同步追加对应的首元素：

# 正确修复方案：同步闭合角度与数值
angles_closed = np.concatenate((angles, [angles[0]]))
values_closed = np.concatenate((values, [values[0]]))

ax.plot(angles_closed, values_closed)
ax.fill(angles_closed, values_closed, alpha=0.25)

场景 2：ValueError: The number of tick labels must match the number of tick locations

错误代码重现：

# 已经执行了闭合
angles_closed = np.concatenate((angles, [angles[0]]))

# 将闭合后的 6 个角度作为刻度位置传入
ax.set_thetagrids(angles_closed * 180 / np.pi, labels)
# labels 只有 5 个，locations 有 6 个，抛出 ValueError

根因与修复：set_thetagrids 要求位置序列与标签文本严格一一对应。由于 0° 和 360° 在圆周上是同一个轴，闭合点不需要重复设置标签。刻度设置必须使用未闭合的基础角度：

# 正确修复方案：只用未闭合的原始 angles 设置标签
ax.set_thetagrids(angles * 180 / np.pi, labels)

场景 3：IndexError: index ... is out of bounds for axis 0

在批量绘制多角色、多团队或通过 Pandas DataFrame 读取数据时，IndexError 往往表现为下标超出数组边界。常见触发原因包括：

• 特征列与循环变量错位：例如 DataFrame 包含了额外的“名字（Name）”或“分组（Group）”非数值列，在切片提取特征时使用了错误的列范围，导致列数与标签列表长度不一致。
• 矩阵转置方向错误：当使用二维 NumPy 数组组织多行数据时，通过 data[i] 遍历行，但矩阵实际形状为 (features, samples) 而非 (samples, features)，造成行数小于迭代次数。
• 循环中手动用下标访问标签：在为每个顶点添加数值标注（ax.text）时，循环范围设置成了 range(len(values_closed))（6次），但试图索引 labels[i]，当 i=5 时发生 IndexError: list index out of range。

四、规范的防御性雷达图实现模板

为了从根本上避免此类报错，建议采用清晰分层的函数式模板，在数据进入绘图前加入断言（assert）检查：

import numpy as np
import matplotlib.pyplot as plt

def plot_radar_chart(categories, values_dict, title="综合能力评估"):
    """
    安全绘制雷达图模板函数
    :param categories: 维度标签列表，长度为 N
    :param values_dict: 数据字典 {"样本名": [数值1, 数值2, ...]}，每个列表长度必须等于 N
    """
    N = len(categories)
    
    # 1. 严格检查入参长度
    for name, vals in values_dict.items():
        if len(vals) != N:
            raise ValueError(f"样本 '{name}' 数据长度 ({len(vals)}) 与标签数量 ({N}) 不一致！")

    # 2. 计算未闭合的基础角度（弧度制）
    angles_base = np.linspace(0, 2 * np.pi, N, endpoint=False)
    
    # 3. 构造用于折线与填充的闭合序列 (长度 N+1)
    angles_closed = np.concatenate((angles_base, [angles_base[0]]))

    # 4. 初始化极坐标画布
    fig, ax = plt.subplots(figsize=(6, 6), subplot_kw=dict(polar=True))
    
    # 设置起始角度在正上方 (北方向)，顺时针排列
    ax.set_theta_offset(np.pi / 2)
    ax.set_theta_direction(-1)

    # 5. 设置坐标轴刻度与标签（关键：只传基础角度与标签，长度严格为 N）
    ax.set_thetagrids(angles_base * 180 / np.pi, categories)

    # 6. 遍历绘制各组数据（关键：数值与角度均使用闭合序列）
    for name, vals in values_dict.items():
        vals_closed = np.concatenate((vals, [vals[0]]))
        ax.plot(angles_closed, vals_closed, linewidth=2, label=name)
        ax.fill(angles_closed, vals_closed, alpha=0.2)

    # 7. 设置径向范围与图例
    ax.set_ylim(0, 100)
    ax.legend(loc="upper right", bbox_to_anchor=(1.25, 1.1))
    ax.set_title(title, y=1.08, fontweight="bold")
    
    return fig, ax

# 验证调用
labels = ['代码规范', '算法效率', '工程架构', '测试覆盖', '文档完整']
data = {
    '工程师 A': [88, 92, 75, 80, 85],
    '工程师 B': [70, 85, 90, 88, 78]
}

fig, ax = plot_radar_chart(labels, data)
plt.show()

五、总结：雷达图防错自检清单

在日常开发与数据分析中，只要遵循以下自检闭环，就能确保雷达图代码一次性通过且稳定运行：