Python statistics.kde 怎样按样本构造密度函数

如果手里只有一组离散测量值，想观察它大致集中在哪些位置，可以用 Python 标准库的 statistics.kde 把样本转换成一个可调用的概率密度函数。它不会直接返回一张图，而是返回类似 pdf(x) 的函数；你再给它一组横坐标，就能得到对应的密度值。

官方地址：https://docs.python.org/3/library/statistics.html

kde(data, h, kernel='normal', cumulative=False) 的核心是样本、带宽 h 和核函数。h 越小越强调局部细节，越大越平滑；cumulative=True 时返回的是累计分布函数。

把样本变成可调用的密度函数

kde 的输入是一组数值样本和正向的平滑尺度 h。返回值本身是函数，所以适合与网格、表格或其他绘图工具组合。下面的例子只展示标准库的计算关系，未把图形库混进来：

from statistics import kde

# 样本应保持同一量纲；这里把它看成一组测量结果
samples = [1.2, 1.5, 1.7, 2.0, 2.1, 2.4, 2.8]

# h 控制平滑程度；返回值是可以反复调用的密度函数
pdf = kde(samples, h=0.35)

# 用等距横坐标取值，便于后续表格或绘图工具消费
x_grid = [1.0 + i * 0.2 for i in range(11)]
density = [pdf(x) for x in x_grid]

# 只输出坐标和密度，不把输出误认为原始样本频数
for x, y in zip(x_grid, density):
    print(f"{x:.1f}: {y:.6f}")

这里的 density 与样本列表不是一一对应的频数表，而是估计出的连续函数在指定位置的函数值。横坐标网格越密，得到的观察点越多，但不会改变 kde 本身的估计规则。

带宽 h 决定局部细节和整体平滑

在 KDE 中，h 是最值得先调的参数。较小的 h 会让每个样本点附近的特征更突出，可能保留更多局部起伏；较大的 h 会把相邻样本的影响摊得更开，曲线更平滑，但过大时可能掩盖数据中的峰。

可以固定样本和横坐标，只比较不同带宽返回的函数：

from statistics import kde

samples = [10, 11, 11.5, 12, 18, 18.5, 19]
x = 12.0

# 同一位置比较两个带宽，观察局部细节与平滑程度的取舍
for h in (0.5, 2.0):
    pdf = kde(samples, h=h, kernel="normal")
    print(f"h={h}: density({x})={pdf(x):.6f}")

这个比较只能说明参数带来的形态差异，不能单凭某一个点的密度值判断模型“更准确”。实际使用时应结合样本量、测量噪声和下游任务选择 h，并保持比较时的样本与横坐标一致。

kernel 与 cumulative 参数分别改变什么

kernel 决定每个样本点对附近位置如何分配权重。官方文档列出了 normal、logistic、sigmoid 等会影响所有样本位置的核，也列出了 uniform、triangular、parabolic、quartic、triweight 和 cosine 等只在带宽范围内产生影响的核。通常先固定一个合适的 h，再有目的地比较核函数，避免同时改动两个变量。

如果需要的是“截至某个 x 的累计比例”，可把返回语义切换为 CDF：

from statistics import kde

samples = [2.0, 2.5, 3.0, 3.2, 4.1, 4.8]

# cumulative=True 返回累计分布函数，而不是密度函数
cdf = kde(samples, h=0.4, cumulative=True)

# 这些值用于回答“样本分布估计中有多少落在 x 左侧”
for x in (2.5, 3.0, 4.0):
    print(f"P(X 

因此，PDF 更适合观察分布形状，CDF 更适合读取某个阈值左侧的累计概率。两者都来自同一组样本和带宽，但不能把 CDF 的值当成某个点的密度。

空输入、类型和版本边界

空数据会触发 StatisticsError，所以在接收外部数据时应先决定“空批次是跳过、补采样还是报错”，不要让它在函数调用深处才暴露。statistics 文档还说明，标准库统计函数通常支持 int、float、Decimal 和 Fraction；混合类型的行为不应依赖，输入最好先统一成同一种数值类型。

kde 是 Python 3.13 加入的能力。如果部署环境低于这个版本，不能只把导入语句复制过去就期待标准库存在；应先确认运行时版本，再决定升级 Python 或使用项目允许的第三方统计方案。本文不把第三方库的接口与 statistics.kde 混用。

常见问题

h 越小是不是一定越好？

不是。小带宽能保留更多局部变化，也更容易把噪声当成结构；大带宽更平滑，也可能抹掉窄峰。应在固定数据和下游目标的前提下比较，而不是只追求曲线细节。

kde 返回的是数组吗？

不是，它返回一个可调用对象。需要数组时，先准备自己的 x_grid，再逐点调用返回函数收集结果。

什么时候用 cumulative=True？

当问题是“估计有多少样本不超过某个阈值”时使用；如果问题是观察分布峰值和形状，保留默认的 PDF 语义更合适。

小结：先把样本统一成数值序列，再用 kde 得到可调用函数；优先理解 h 对平滑程度的影响，最后根据问题选择普通密度或累计分布。