企业官网建设流程全解析

• 科学计算
• 科研
• 数据分析

astropy.stats的 sigma 剪切（sigma clipping）是天文数据处理中剔除离群值、估算图像背景最常用的工具之一。当面对百万级像素的科学图像或大规模时序数据时，sigma 剪切反复迭代计算中位数与标准差的成本会显著拖慢整个流水线。本篇指南基于 astropy 仓库中 docs/stats/performance.inc.rst 的性能建议章节，结合 sigma_clipping.py、nanfunctions.py 等源码实现，系统讲解两条核心提速手段——安装 bottleneck 加速内部统计计算、以及用字符串而非 NumPy 函数指定cenfunc/stdfunc——并深入剖析其背后的加速路径与精度约束，帮助你写出又快又稳的 sigma 剪切代码。

sigma 剪切为什么可能很慢

sigma 剪切是一个迭代过程：每一轮都计算数据的中心值center = cenfunc(data)与标准差std = stdfunc(data)，然后把落在center ± sigma * std之外的点剔除，再进入下一轮，直到没有新点被剔除或达到maxiters上限（参见 sigma_clipping.py 中SigmaClip的类文档）。

由此可以直观看出性能瓶颈所在：

• 中位数计算代价高昂：np.nanmedian需要对数据排序或执行选择算法，复杂度显著高于均值；而在maxiters=5或收敛前逐轮重算，成本会被放大数倍。
• NaN 与掩码处理开销：天文数据常含 NaN/inf 与掩码，每次统计都要额外遍历数据判断有效值。
• 重复复制数组：每一轮迭代都会生成新的过滤数组或掩码（见_sigmaclip_noaxis与_sigmaclip_withaxis的实现）。

因此官方性能文档给出的第一反应就是：如果发现 sigma 剪切很慢，先检查环境依赖与参数写法，这两点几乎零成本即可获得收益。

性能建议一：安装 bottleneck 加速内部统计计算

官方文档明确指出：如果还没有安装bottleneck，建议优先安装它，该包会加速 sigma 剪切内部的部分统计计算：

pip install bottleneck

安装后无需修改任何调用代码，astropy 会自动检测并使用它。检测机制位于 optional_deps.py：HAS_BOTTLENECK通过find_spec("bottleneck")判断包是否可用，属于惰性可选依赖探测。

源码实现：bottleneck 如何被接入

在 nanfunctions.py 中，astropy 为nansum、nanmin、nanmax、nanmean、nanmedian、nanstd、nanvar这 7 个函数建立了 "bottleneck 版 / NumPy 版" 双路由：

• 若检测到 bottleneck，则以functools.partial(_apply_bottleneck, bottleneck.xxx)包装；
• _apply_bottleneck还处理了 bottleneck 不支持元组轴的问题——通过_move_tuple_axes_last把需要操作的轴搬到末尾并合并成一维，再以axis=-1调用（见 nanfunctions.py）；
• 未安装 bottleneck 时，这些名字直接退化为np.nan*原版函数。

关键约束：bottleneck 仅用于 float64 计算

_DtypeDispatch类（见 nanfunctions.py）按输入数组 dtype 分流：

def __call__(self, *args, **kwargs): dt = args[0].dtype if dt.kind == "f" and dt.itemsize == 8: return bn_funcsself.func_name else: return np_funcsself.func_name

即只有float64（f8）数组走 bottleneck 路径，其余 dtype 走 NumPy 路径。注释中说明了原因：bottleneck 上游在 float32 计算上存在已知精度缺陷（源码中引用了 bottleneck 的 issue 379、462 以及 astropy 的 issue 17185、11492）。SigmaClip、sigma_clip、sigma_clipped_stats等接口的文档字符串也反复强调："To preserve accuracy, bottleneck is only used for float64 computations"（见 sigma_clipping.py）。相应地，test_sigma_clipping.py 中的test_sigma_clip_large_float32_arrays专门验证了大规模 float32 数组（如(1024, 1024)、(6388, 9576)）在该约束下统计结果仍与预期一致。因此：

• 若数据是 float64，装好 bottleneck 后性能自动提升；
• 若数据是 float32、int 等类型，bottleneck 不会介入，但sigma_clip的 C 快速路径仍会生效（见下文）；
• 不要期望 bottleneck 改变计算结果——它只负责"更快地算同一个统计量"。

性能建议二：用字符串指定 cenfunc / stdfunc，而不是传 NumPy 函数

这是官方性能文档给出的第二条、也是最具操作性的一条建议。当cenfunc和/或stdfunc使用标准统计函数时，务必以字符串形式传入，而不是传入 NumPy 函数对象：

# 推荐：字符串写法 sigma_clip(array, cenfunc='median') # doctest: +SKIP # 不推荐：直接传 NumPy 函数 sigma_clip(array, cenfunc=np.nanmedian) # doctest: +SKIP

原文的解释是："Using strings will allow the sigma-clipping algorithm to pick the fastest implementation available for finding the median"（使用字符串能让 sigma 剪切算法挑选当前环境中可用的最快实现）。

为什么字符串写法更快：源码级解析

cenfunc/stdfunc的字符串解析发生在 sigma_clipping.py 的_parse_cenfunc与_parse_stdfunc中：

# _parse_cenfunc：'median' -> nanmedian，'mean' -> nanmean # _parse_stdfunc：'std' -> nanstd，'mad_std' -> nanmadstd

字符串被映射到的nanmedian、nanmean、nanstd等并不是np.nan*原函数，而是 nanfunctions.py 中经过 bottleneck 包装的加速版本。也就是说，字符串写法让cenfunc='median'在安装了 bottleneck 的 float64 环境下自动走 bottleneck.nanmedian；而传np.nanmedian则绕过了这一层，只能使用较慢的 NumPy 实现。这正是"字符串能让算法挑选最快实现"的机制所在。

除此之外，字符串写法还会触发 sigma 剪切的C 级快速路径。在SigmaClip.__call__中（见 sigma_clipping.py）存在一个捷径判断：

if ( self.cenfunc in ("mean", "median") and self.stdfunc in ("std", "mad_std") and axis is not None and not self.grow ): return self._sigmaclip_fast(...)

即当cenfunc取内置字符串"mean"/"median"、stdfunc取"std"/"mad_std"、且指定了axis、未启用grow时，会直接进入_sigmaclip_fast，调用用 C 编写的 ufunc_sigma_clip_fast。该扩展由 setup_package.py 编译，源码包括 fast_sigma_clip.c、compute_bounds.c与wirth_select.c（从文件名可推断其中使用了 Wirth 选择算法实现中位数计算），以 NumPy gufunc 形式一次性迭代并返回上下界，避免逐轮在 Python 层排序求中位数。测试见 test_fast_sigma_clip.py。

因此推荐写法的收益是双重的：既能在统计函数层面接入 bottleneck，又能在满足条件时进入 C 快速路径。

合法的字符串取值与错误处理

cenfunc只接受'median'、'mean'两个内置字符串；stdfunc只接受'std'、'mad_std'两个内置字符串。传入其他字符串会抛出ValueError（例如_parse_cenfunc中raise ValueError(f"{cenfunc} is an invalid cenfunc.")），这一点在升级脚本时值得留意。

什么情况下可以传可调用对象

字符串写法不是万能的。当你的中心值或标准差需要自定义统计量（如分位数、稳健估计）时，可以传入可调用对象。源码文档给出了明确的约束（见 sigma_clipping.py）：

• 若同时使用axis关键字，可调用对象必须能忽略 NaN（如np.nanmean）；
• 必须支持axis参数，以便返回去掉对应维度后的数组；
• 一个字符串、一个自定义可调用对象的混搭也是允许的，但此时部分路径无法进入 C 快速实现。

需要留意的是，一旦传入可调用对象（哪怕它是np.nanmedian），就放弃了上述两类加速机制，_parse_*会原样保留该对象而不做任何映射。官方文档同时提示：若两者之一是字符串而另一个是自定义可调用对象，安装 bottleneck 有时反而能带来更明显的收益——这正是"字符串 + bottleneck"组合的互补关系。

综合实战：一整套快速 sigma 剪切示例

下面把两个性能建议整合进完整流程，数据取自官方文档示例并补充参数说明：

import numpy as np from astropy.stats import sigma_clip, sigma_clipped_stats, SigmaClip # 1) 生成含离群点的高斯样本 rng = np.random.default_rng(0) data = rng.normal(0, 1, (10000,)) data[::500] += 100.0 # 制造离群点 # 2) 推荐写法：字符串 + bottleneck（若已安装），中位数居中、5 轮迭代 filtered = sigma_clip(data, sigma=3, maxiters=5, cenfunc='median', stdfunc='std') # 3) 一行拿到 sigma 剪切后的均值、中位数、标准差 mean, median, stddev = sigma_clipped_stats(data, sigma=3, maxiters=5, cenfunc='median', stdfunc='std') # 4) 面向对象写法，便于复用配置 sigclip = SigmaClip(sigma=3, maxiters=5, cenfunc='median', stdfunc='std') filtered2 = sigclip(data)

sigma_clip/SigmaClip核心参数及默认值（来自 sigma_clipping.py 与函数签名）：

更多功能说明可参见 docs/stats/index.rst 与 docs/stats/robust.rst。值得留意的是，performance.inc.rst是以.. include::方式嵌入 stats 文档页尾的（见 docs/stats/index.rst），因此文档顶部还保留了一段给维护者的说明：若这段内容被拆分为独立页面，需要把标题下划线从===改为***、扩展名从.inc.rst改为.rst并加入子包 toctree。

性能检查清单

对 sigma 剪切做一次快速体检，按优先级执行：

1. 确认 bottleneck 已安装：pip install bottleneck，float64 数据即可自动获益；
2. 把内置统计参数写成字符串：cenfunc='median'、stdfunc='std'等，替换掉np.nanmedian之类的函数对象；
3. 为大规模数据显式指定axis：满足cenfunc/stdfunc为内置字符串、axis is not None、grow=False时，自动进入 C 实现的_sigmaclip_fast快速路径；
4. 保持 float64 精度语义：bottleneck 只对 float64 生效，不要为了"提速"把数据降成 float32 而牺牲准确性；
5. 仅在确有自定义统计需求时传可调用对象，并确认其满足 NaN 忽略与axis关键字约束。

遵循以上做法，你可以在不改动任何业务逻辑的前提下，让astropy.stats的 sigma 剪切在统计函数层面（bottleneck）与算法层面（C gufunc）同时获得加速，这对动辄数千万像素的科学图像处理管线尤为关键。

• 科学计算
• 科研
• 数据分析