Python statistics.quantiles 怎样计算分位数并处理边界

Python 计算分位数时，可以直接使用标准库 statistics.quantiles()。它把输入数据划分为 n 个等概率区间，并返回中间的 n - 1 个切点：默认得到三个四分位数切点，设置 n=10 得到九个十分位数切点，设置 n=100 得到九十九个百分位数切点。

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

我在报表和延迟摘要里最容易踩到的坑，不是函数不会调用，而是没有先判断数据代表“抽样样本”还是“已经包含总体两端的观测值”。前者通常用默认的 exclusive，后者才考虑 inclusive；空数据、n 太大和 NaN 也要在入口处处理。

quantiles 返回的是切点，不是分组结果

quantiles() 的职责是计算切分位置。它不会返回四个列表，也不会替你把原始数据分桶。比如 n=4 时返回三个值，它们把排序后的数据概念上分成四段；如果要统计每段数量，还需要把切点用于后续分类。

from statistics import quantiles


def quartile_cuts(values: list[float]) -> list[float]:
    # quantiles 默认 n=4，返回 Q1、Q2、Q3 三个切点。
    if not values:
        raise ValueError("分位数计算至少需要一个数据点")
    return quantiles(values)


cuts = quartile_cuts([12, 4, 9, 20, 7, 15, 3, 11])
# cuts 是切点列表，不是按四个区间分组后的数据。
print(cuts)

输入不要求事先排序，函数会按自己的计算逻辑处理可迭代对象。对工程代码而言，建议在调用前把“切点用于展示”还是“切点用于分桶”写进变量名或注释，避免把返回列表误当成分组数据。

样本数据和总体数据要选不同 method

method 决定切点如何解释两端数据。默认的 exclusive 面向从总体中抽取的样本，假设总体中可能还有比样本最小值更小、比样本最大值更大的值；inclusive 则适合已知样本包含总体极值，或者把当前数据本身作为总体描述的场景。

from statistics import quantiles


values = [8, 10, 11, 13, 15, 18, 21, 22, 25]

# 抽样数据使用默认 exclusive，切点不把样本两端强行当成总体边界。
sample_cuts = quantiles(values, n=4, method="exclusive")

# 当前数据覆盖总体两端时，可以使用 inclusive。
population_cuts = quantiles(values, n=4, method="inclusive")

print(sample_cuts)
print(population_cuts)

这两个结果都可能是合法数字，差异来自统计假设而不是函数故障。我的判断方式是先问“这组数据只是观测窗口，还是完整总体的边界已经确定”，再决定方法；不要看到两个结果不同就随意取较大的一个。

用 n 控制四分位数、十分位数和百分位数

n 表示等概率区间的数量，返回长度固定为 n-1。因此四分位数使用 n=4，十分位数使用 n=10，百分位数使用 n=100。如果业务只要 P95，可以计算百分位数后取对应切点，也可以选择更适合业务报表的分组数量。

from statistics import quantiles


def percentile_cuts(values: list[float], n: int) -> list[float]:
    # n 必须表示至少一个区间；函数返回 n-1 个边界。
    if n 

官方文档要求 n 至少为 1，但想得到有意义的内部切点，业务代码通常应把它限制为至少 2。对于样本数量，文档也提醒数据点数量应大于 n；如果只有很少的观测值，却要求百分位数，结果的解释价值会很弱。

空数据、过小样本和 NaN 要在入口处理

空数据会触发 StatisticsError；n 不合法也会触发同类异常。除此之外，包含 NaN 的数据不适合直接交给会排序的统计函数，官方文档明确提醒这会带来令人意外或未定义的行为。生产代码应在统计前统一清洗缺失值，并明确“没有可用数据”是返回空结果还是抛出业务异常。

import math
from statistics import StatisticsError, quantiles


def safe_quantiles(values: list[float], n: int = 4) -> list[float]:
    # 先过滤 NaN；不要把缺失值当成正常的排序元素。
    clean = [value for value in values if not math.isnan(value)]
    if not clean:
        return []
    if n 

如果数据类型可能是 Decimal 或 Fraction，不要在清洗环节无意中混入 float。统计模块支持多种数值类型，但混合类型的行为并不适合作为稳定契约；入口层应先统一数值类型，再进行分位数计算。

把 method、n 和样本量写进调用约定

这张表里的“建议”不是对所有统计任务的强制结论，而是让调用方能复查假设。尤其是 P95、P99 这类指标，除了函数参数，还要在指标说明中记录样本窗口、清洗规则和 method，否则不同服务很容易算出无法比较的结果。

我会怎样在项目里落地

如果只是一次性查看数据，我会直接调用 quantiles()，并在旁边标注 n 和 method。如果它进入接口指标或定时报表，我会再封装一层入口：统一数值类型、过滤 NaN、检查样本量、记录统计假设，并把空结果与异常告警分开。

这样做的重点不是把标准库包装得很复杂，而是让未来维护者能回答三个问题：这些数据是不是样本、切点要分成多少段、样本不足时系统应该怎样表达“没有可靠结果”。

小结

statistics.quantiles() 计算的是等概率区间的内部切点。默认 n=4 返回三个四分位数切点；exclusive 适合普通抽样数据，inclusive 适合已知覆盖总体两端的场景。调用前处理空数据、过小样本和 NaN，并把统计假设写进调用约定，结果才有可比较的工程含义。

相关问题

quantiles 为什么返回 n-1 个值？
因为 n 个区间只需要 n-1 个内部边界，返回值是切点列表，不是已经分组的数据。

exclusive 和 inclusive 可以随便替换吗？
不建议。它们表达的总体边界假设不同，应根据数据是抽样样本还是已知完整总体来选择。

数据量小于 n 还能不能计算？
标准库文档要求数据点数量大于 n 才有意义；业务代码应在入口拒绝或降级，而不是把不稳定切点当成可靠指标。

quantiles 遇到 NaN 怎么办？
先按业务规则删除或替换 NaN，再调用统计函数；不要让缺失值参与排序。