statistics

对数值数组计算描述性统计、分位数和双变量关系。

版本 1.0.0 · C / xlang · 无扩展库依赖

当前发布版的 C 边界与范例通过，但 XLang statistics.count(var array) 在外来数组投影处断言失败；下方语言示例尚未完成本轮验收，完整 AOT 阶段也未执行。

快速开始

import statistics

var values = [2, 4, 4, 4, 5, 5, 7, 9]
println(statistics.mean(values))
println(statistics.median(values))
println(statistics.stdev(values))

上述结果分别为 5、4.5、2。除 count 外，输入必须是非空的有限数值数组；count 只统计有限数值，忽略非数值与 NaN/无穷大。

接口与边界

入口	用途
`count / sum / mean / median / mode / min / max / range`	计数和单变量汇总；并列众数取最小值。
`variance / stdev / varianceSample / stdevSample`	总体和样本方差/标准差。
`percentile(values, p) / quartiles / iqr / mad`	线性插值分位数、四分位距和平均绝对偏差；p 为 0–100。
`geomean / harmmean`	几何与调和平均数；前者要求正值，后者要求非零。
`covariance / covarianceSample / correlation / linearFit`	同长度数组的协方差、Pearson 相关系数和最小二乘拟合。
`histogram(values, bins)`	1–100000 个等宽分箱的计数数组。

样本计算至少需要两个元素；常量输入不能计算相关系数或斜率。无效元素、非有限输入与无法表示为有限 float64 的结果会报错。求和、均值及分位数在安全区间保留次正规数，不因逐项缩放提前下溢；极值求和与均值共用缩放补偿累加，并单独保留缩放后可能下溢的小项。C/XLang 测试覆盖 [DBL_MAX, 1, -DBL_MAX] 及极值抵消后均值中的次正规残差，但不承诺任意输入的正确舍入。极值均值在恢复尺度前除以样本数，并把舍入结果限制在输入范围内；三个最大有限值的均值仍为最大有限值。方差和平均绝对偏差先缩放偏差再聚合；标准差独立计算，即使方差不可表示，只要标准差可表示，仍返回有限结果。调和平均数缩放倒数项，避免极小非零输入的中间溢出；倒数和为零仍报错。count 对非数组输入返回 0。

调和平均数的缩放倒数使用补偿求和；[1e-16, 1, -1e-16] 的有限结果不会因大项抵消而误报未定义。倒数和确实为零仍报错。

C 对照

#define XRT_MODULE_VALUE_CONTAINER
#include "xrt.h"
#include "statistics_native.h"

int main(void)
{
    xvalue* values = xrtValueArray();
    xrtValueArrayAppendNew(values, xrtValueFloat(2.0));
    xrtValueArrayAppendNew(values, xrtValueFloat(4.0));
    xvalue* average = xstat_mean(values);
    double number = 0;
    int ok = average && xrtValueGetFloat(average, &number) && number == 3.0;
    xrtValueRelease(average);
    xrtValueRelease(values);
    return ok ? 0 : 1;
}

C 结果由调用方 xrtValueRelease；失败返回 XRT null 值并设置错误。参数/定义域错误为 XERR_VALUE，分配失败为 XERR_MEMORY，XLang 分别抛出 ValueError 与 MemoryError。min/max/range 逐项校验并扫描极值，不复制整份输入数组；除结果外只用常量额外内存。完整双语对照范例位于 release/extlibs/statistics/examples/。

失败后可直接重试；后续成功的单数组、双数组或 count 调用会清除本线程旧的 XRT 错误。

验证状态

2026-10-29修复大基数小波动的共享中心化误差：先平移到首元素附近，再求偏差均值，单变量/双变量复用。160项明确预期与1,024组精确有理数参照覆盖方差、标准差、MAD、协方差、相关及拟合，不新增堆分配或改变API，但增加部分扫描，不承诺任意浮点输入的正确舍入。新增measurement_offsets C/XLang测量范例；正常语言数组仍受M1投影阻断，C结果通过不能代替双语闭环验收。

powershell -NoProfile -ExecutionPolicy Bypass -File release/extlibs/statistics/test/check.ps1 -SkipAot
bash release/extlibs/statistics/test/check.sh

三份 C 范例可直接使用 xl run release/extlibs/statistics/examples/statistics_c.c、xl run release/extlibs/statistics/examples/trend_c.c 和 xl run release/extlibs/statistics/examples/distribution_c.c 运行；第三组展示众数、离散度、几何/调和平均数与协方差。Windows/Linux 门禁设计为将其输出与 GCC 编译运行及 XLang 范例逐字对照；本轮 Windows 测试尚未走到双语对照。Linux 门禁还运行 C ASan/UBSan、XLang 数值与分配边界。count 结果与 histogram 箱数使用跨平台 int64_t ABI，C 范例用 PRId64 可移植打印。极值方差、标准差、平均绝对偏差、次正规数求和/均值/插值、大数抵消、极小调和平均数及分配失败分类均有定向测试；另用 512 组有符号整数数组的独立模型对照聚合、分位数、众数与直方图。当前语言数组投影失败，完整 AOT 未执行，尚未签收发布门禁。