Pandas 缺失分箱填 0 生成 heatmap 方法

本文介绍如何使用 Pandas 的分类索引与外连接（outer merge）机制，强制补全所有预定义分箱区间（如 (0,2], (2,4] 等），将无覆盖数据的空 bins 统一赋值为 0，确保热图横轴 bins 数量固定、位置对齐，避免因数据稀疏导致的可视化断层。

本文介绍如何使用 Pandas 的分类索引与外连接（outer merge）机制，强制补全所有预定义分箱区间（如 `(0,2]`, `(2,4]` 等），将无覆盖数据的空 bins 统一赋值为 0，确保热图横轴 bins 数量固定、位置对齐，避免因数据稀疏导致的可视化断层。

在构建基因组覆盖度热图（如跨转录本标准化分箱 heatmap）时，一个常见却关键的需求是：无论某段区域实际是否有测序覆盖，所有预设 bin 都必须出现在最终结果中。例如，将 1–10 bp 区间等分为 5 个左开右闭区间 [(0,2], (2,4], (4,6], (6,8], (8,10]]，若原始 coverage 数据中完全缺失 (2,4] 区间的任何位点，则默认 pd.cut + groupby 会直接跳过该 bin —— 这将导致后续 seaborn.heatmap 绘图时列数不全、坐标错位，甚至引发 ValueError: x and y must be the same length 等错误。

解决该问题的核心思路是：显式构造完整的 bin 类别集合，并通过外连接（how='outer'）将其与原始数据对齐，再用 fillna(0) 填充缺失值。以下是优化后的完整实现：

import pandas as pd

def bins_calculator(path_txt: str, start: int, end: int, n_bins: int = 10) -> pd.DataFrame:
    """
    将 coverage 数据按固定数量 bins 划分，强制补全所有区间并填 0，
    返回每 bin 的平均 coverage（含空 bin）
    """
    column_names = ["chr", "pos", "cov"]
    data = pd.read_csv(path_txt, names=column_names, sep='\t')

    # 生成等宽 bin 边界（包含 end）
    bin_edges = pd.np.linspace(start, end, n_bins + 1, dtype=int)
    # 使用 pd.cut 并显式保留分类类型（critical for .cat.categories）
    data["data_bin"] = pd.cut(data["pos"], bins=bin_edges, include_lowest=False, right=True)

    # 构造完整 bin 类别 DataFrame（每行代表一个 bin）
    all_bins = pd.DataFrame({"data_bin": data["data_bin"].cat.categories})

    # 外连接：确保每个 bin 至少出现一次（缺失则 chr/cov 为 NaN）
    merged = data.merge(all_bins, on="data_bin", how="outer")

    # 填充缺失值：chr 用前向/后向填充（保证同染色体），cov 填 0
    merged["chr"] = merged["chr"].ffill().bfill()
    merged["cov"] = merged["cov"].fillna(0).astype(int)

    # 计算每 bin 平均 coverage（注意：此时空 bin 的 cov=0，均值即为 0）
    merged["avg"] = merged.groupby("data_bin", observed=False)["cov"].transform("mean")

    # 去重并保持 bin 顺序（按 categories 自然序）
    result = merged[["chr", "data_bin", "avg"]].drop_duplicates(subset=["data_bin"])
    result = result.sort_values("data_bin").reset_index(drop=True)

    return result

✅ 关键要点说明：

• pd.cut(..., include_lowest=False, right=True) 明确指定区间为左开右闭（如 (2,4]），与问题描述一致；
• .cat.categories 是获取 CategoricalDtype 所有合法区间的唯一可靠方式，不可用 unique() 替代（后者仅返回实际出现的 bin）；
• merge(..., how="outer") 是补全逻辑的核心——它将原始数据“挂载”到完整 bin 模板上，缺失位置自动产生 NaN 行；
• ffill().bfill() 用于 chr 字段是安全的：因所有 bin 属于同一染色体（输入文件限定），首尾必有有效值；
• 最终 drop_duplicates("data_bin") 保证每个 bin 仅保留一行，且 sort_values("data_bin") 确保输出顺序与 bin 边界严格一致，这对 heatmap 的 x 轴渲染至关重要。

⚠️ 注意事项：

• 若输入数据含多个染色体（如 chr17, chrX），需先按 chr 分组处理，或在 merge 前添加 chr 到 all_bins 中（构造 (chr, data_bin) 复合键）；
• pd.np.linspace 已在新版 Pandas 中弃用，请替换为 np.linspace（需 import numpy as np）；
• 对于大规模数据，可考虑用 pd.concat([data, pd.DataFrame(...)]) + groupby(..., dropna=False) 替代 merge，性能更优。

通过此方法，你将获得结构规整、无缺失 bin 的汇总表，可直接传入 seaborn.heatmap() 或 matplotlib.pyplot.imshow()，轻松生成跨样本/转录本对齐的标准化覆盖热图。