BC — Bias Correction（偏差校正）

BC 是降水偏差校正模块，基于观测和模式历史期拟合逐日序分位数映射， 对历史期和未来期降水进行校正。当前仅支持降水。

from klimapy.downscaling.bcsd import bias_correct, close_result

bc_result = bias_correct(
    obs_path='obs_daily.nc',
    gcm_hist_path='model_historical.nc',
    gcm_fut_path='model_future.nc',
    model_name='example_model',
    ref_start_year=1981,
    ref_end_year=2010,
)
if bc_result is None:
    raise RuntimeError('BC 偏差校正失败，请检查日志')

# 可以单独使用校正后的粗网格降水。
historical = bc_result['corrected_hist_pr']
future = bc_result['corrected_fut_pr']

也可以直接导入函数：

from klimapy.downscaling.bcsd import bias_correct

输入和参数

六个参数均需显式提供：

观测降水支持 pr/pre/precip/precipitation 等名称；模式文件也通过同一套变量名识别。 时间和空间坐标支持 time/lat/lon 或 Time/Lat/Lon，输入维度顺序会归一为时间、纬度、经度，输出坐标统一为 time/lat/lon。 经纬度至少各有两个格点。已识别的降水通量单位会转换为 mm/day。

返回值

成功返回字典，失败记录日志并返回 None；strict=True 时抛出异常。BC 不自动保存中间文件。

与 SD 连接

将完整的 bc_result 传给 SD，并提供相同的观测文件和参考期。 BC 的计算代码位于 src/klimapy/downscaling/bcsd/bias_correction.py，与 SD 分开维护。 日历、单位转换和诊断工具放在 _core/common.py。

当前算法保持原实现：先将观测聚合到模式网格，再按日序滑动窗口构造样本， 使用三次平滑样条拟合分位数映射；超出拟合区间的数值使用边界夹持。

日期匹配、缓存和内存

拟合样本为参考期内观测/模式的年月日交集；每个请求年份须存在。 历史输出保留完整模式时段。滑动窗口按日历日序循环，跨年窗口也正确匹配。 源/目标网格权重和各日序样本索引只构建一次。

可选参数：strict=False、time_chunk_size=128、work_dir=None、 window_size=None（默认使用 WINDOW_SIZE）、n_quantiles=None（默认使用 N_QUANTILES）。 work_dir 可让校正结果使用磁盘映射，调用者负责在消费并释放数组后清理该目录。 未设置时输出仍在内存中；参考观测按时间块读取，模式按纬度行读取。 返回的 diagnostics 记录实际匹配天数、拟合/未拟合传递函数数目和参考期。

使用磁盘映射时，消费结果后可调用 close_result(bc_result, remove_work_files=True)， 关闭并删除该结果自己的 backing 文件；此前提取的数组视图在关闭后不得继续使用。 process_models 和一体化 BCSD 入口会在 SD 结束后自动释放这些中间文件。

输入也可使用 Field。样条未达到目标平滑度时会报告近似拟合警告， 并计入 diagnostics.approximate_functions；不把未达到平滑目标伪装成精确拟合。 其他拟合错误会使严格流程失败。关闭 close_result 后不要再访问原 memmap 视图。

日期与质量控制

参考样本按观测与模式的真实年月日交集匹配。不同日历没有对应的日期不凭空补成配对样本，例如 360_day 的 2 月 30 日不会与公历观测强行配对；可使用循环窗口内其他匹配日期拟合。所有请求基准年份必须存在，缺测天数和有效传递函数数量记录在 diagnostics。拟合只使用参考期，历史输出保留模式完整历史时段。

strict=True 时输入、拟合或文件错误直接抛出异常；默认模式记录错误并返回 None。