AnnData基于索引左连接adata.obs与DataFrame出现NaN的解决方法

连接后全为NaN本质是两侧索引没有成功匹配，按以下顺序排查即可定位根因：

• 检查索引数据类型是否一致
  这是最高发的原因：比如一侧索引是字符串类型、另一侧是整数类型，或者一侧是分类（Categorical）类型另一侧是普通object类型，pandas做连接时不会抛出类型不匹配的报错，会直接判定无匹配值填充NaN。
  执行以下代码检查基础信息：

  # 查看两侧索引类型、样本值
  print("adata.obs索引类型：", adata.obs.index.dtype)
  print("adata.obs索引前5个值：", adata.obs.index[:5].tolist())
  print("df索引类型：", df.index.dtype)
  print("df索引前5个值：", df.index[:5].tolist())
  # 统计实际重合的索引数量
  match_count = len(set(adata.obs.index) & set(df.index))
  print("两侧实际重合索引数：", match_count)
  

  如果重合索引数远小于预期，继续检查索引值是否存在隐形格式问题：比如前后带空格、不可见特殊字符、10X单细胞barcode缺批次后缀（比如adata里是AAACCTGAGAAACCAT-1，df里是AAACCTGAGAAACCAT）。
• 检查连接参数是否正确
  用pd.merge做索引连接时必须显式传入left_index=True, right_index=True参数，否则pandas会默认按两表的同名列做连接，若两表无同名列就会出现匹配异常。直接调用adata.obs.join(df)理论上是按索引连接，但旧版本AnnData的obs对象做DataFrame方法调用时偶尔会出现索引隐式转换的问题，不推荐直接链式调用。

最稳定、不会打乱细胞顺序的实现方式是用reindex做显式对齐，完全等价于以adata.obs为左表的左连接，还能避免连接后细胞顺序和表达矩阵错位的问题：

1. 先清洗统一两侧索引格式

# 统一转字符串、去除前后空白字符
adata.obs_names = adata.obs_names.astype(str).str.strip()
df.index = df.index.astype(str).str.strip()

# 若存在10X barcode后缀不匹配问题，按需执行
# adata.obs_names = [x.split('-')[0] for x in adata.obs_names]

2. 按adata的观测顺序重排注释表，再合并入adata.obs

# 严格按adata的细胞顺序对齐注释，缺失值自动填充NaN
df_aligned = df.reindex(adata.obs.index)
# 横向合并列，完成注释添加
adata.obs = pd.concat([adata.obs, df_aligned], axis=1)

3. 校验结果

# 统计完全未匹配到注释的细胞数
na_cell_count = adata.obs[df.columns].isna().all(axis=1).sum()
print(f"未匹配到注释的细胞数量：{na_cell_count}")

内容的提问来源于stack exchange，提问作者yippingAppa