CellPhoneDB 技能

此版本为Python 版本。使用 CellPhoneDB v5 指导用户完成细胞间通信（cell-cell communication, CCC）分析，即从单细胞数据中推断配体-受体（ligand-receptor, LR）相互作用。CellPhoneDB 使用人工整理的数据库，包含异源多聚体复合物注释，并支持基于置换的统计检验。

何时适合使用 CellPhoneDB

需要高置信度、人工整理的相互作用，并希望正确处理异源多聚体复合物。
需要对 LR 相互作用进行基于置换的统计显著性检验。
数据来自人类；CellPhoneDB 使用人类基因，鼠数据须先转换为人类同源基因。
希望使用基于 DEG 的方法（无需置换，直接使用已有 DEG）。
希望计算相互作用评分（v5 特异性评分，0-100）。

在编写代码前，先确认用户的物种（人类或小鼠）、基因 ID 类型（ensembl / gene_name / hgnc_symbol），以及是否已有 DEG。这三个答案决定分析方法及关键参数。

运行前检查清单

在开始分析前，必须确认以下三项，否则分析可能失败或返回零结果：

[ ] 确认物种
- CellPhoneDB 仅支持人类基因
- 小鼠数据必须先转换为人类同源基因
[ ] 确认基因 ID 类型
- 检查表达矩阵使用的是 ensembl / gene_name / hgnc_symbol
- 最常见错误：使用基因符号但忘记设置 counts_data='hgnc_symbol'
[ ] 确认数据预处理
- 表达矩阵必须是 log 标准化数据（如 log1p(normalized_counts)）
- 不要进行 z-score 标准化（会导致评分失效）

安装与数据库配置

pip install cellphonedb

from cellphonedb.utils import db_utils

# 下载数据库（创建 ./db/cellphonedb.zip）
db_utils.download_database('./db', 'v5.0.0')

→ verify：检查数据库文件是否生成

import os
assert os.path.exists('db/v5/cellphonedb.zip'), "数据库下载失败"

注意：v5 软件包必须搭配 v5 数据库，不要将旧版本数据库 ZIP 与 v5 代码混用。

三种分析方法

默认推荐 方法 2（统计分析），适合发表级分析。若用户已有筛选后的 DEG，或置换检验不稳定，使用方法 3。方法 1 适合快速查看平均表达，不提供统计检验。

方法 1：基础平均表达分析（无统计检验）

from cellphonedb.src.core.methods import cpdb_analysis_method

# 确保输出目录存在
os.makedirs('results', exist_ok=True)

cpdb_results = cpdb_analysis_method.call(
    cpdb_file_path='db/v5/cellphonedb.zip',
    meta_file_path='data/metadata.tsv',
    counts_file_path='data/normalised_log_counts.h5ad',
    counts_data='hgnc_symbol',          # 'ensembl' | 'gene_name' | 'hgnc_symbol'
    output_path='results/',
    score_interactions=True,            # 启用 v5 特异性评分
    threshold=0.1,                      # 基因最小表达细胞比例
    threads=4,
)
# 返回：means_result、deconvoluted、deconvoluted_percents、interaction_scores

→ verify：检查输出文件和基本结果

# 验证：输出文件是否生成
assert os.path.exists('results/means.csv'), "means.csv 未生成"
# 验证：找到相互作用
assert len(cpdb_results['means']) > 0, "未找到任何相互作用，检查 counts_data 参数"

方法 2：统计分析（置换检验）- 最常用

from cellphonedb.src.core.methods import cpdb_statistical_analysis_method

# 确保输出目录存在
os.makedirs('results', exist_ok=True)

cpdb_results = cpdb_statistical_analysis_method.call(
    cpdb_file_path='db/v5/cellphonedb.zip',
    meta_file_path='data/metadata.tsv',
    counts_file_path='data/normalised_log_counts.h5ad',
    counts_data='hgnc_symbol',
    output_path='results/',
    score_interactions=True,
    iterations=1000,                    # 置换次数；测试时可用 100
    threshold=0.1,
    threads=4,
    debug_seed=42,                      # 可复现性；仅限单线程
    pvalue=0.05,
)
# 返回：means、pvalues、significant_means、deconvoluted、
#       deconvoluted_percents、interaction_scores

→ verify：检查统计结果和显著相互作用

# 验证：统计输出文件是否生成
assert os.path.exists('results/significant_means.csv'), "significant_means.csv 未生成"
# 验证：找到显著的相互作用
assert len(cpdb_results['significant_means']) > 0, "未找到显著相互作用，检查数据和参数"
# 验证：p值在合理范围内
pvals = cpdb_results['pvalues']
assert pvals['pvalue'].min() >= 0 and pvals['pvalue'].max() <= 1, "p值范围异常"

方法 3：基于 DEG 的分析（无置换）

from cellphonedb.src.core.methods import cpdb_degs_analysis_method

# 确保输出目录存在
os.makedirs('results', exist_ok=True)

cpdb_results = cpdb_degs_analysis_method.call(
    cpdb_file_path='db/v5/cellphonedb.zip',
    meta_file_path='data/metadata.tsv',
    counts_file_path='data/normalised_log_counts.h5ad',
    degs_file_path='data/DEGs.tsv',     # 两列：cell_type、gene（必须预先筛选）
    counts_data='hgnc_symbol',
    output_path='results/',
    score_interactions=True,
    threshold=0.1,
    threads=4,
)
# 返回：means、relevant_interactions、significant_means、deconvoluted 等

→ verify：检查 DEG 分析结果

# 验证：输出文件是否生成
assert os.path.exists('results/relevant_interactions.csv'), "relevant_interactions.csv 未生成"
# 验证：找到基于 DEG 的相互作用
assert len(cpdb_results['relevant_interactions']) > 0, "未找到相关相互作用，检查 DEG 文件"

必需输入格式

表达矩阵文件：推荐 .h5ad；也可用 .h5、.txt/.tsv、10x 文件夹或内存中的 AnnData。
- 数据预处理要求：必须是 log 标准化数据（推荐 log1p(normalized_counts)）
- 不要使用：z-score 标准化（会破坏评分算法）
元数据文件：两列 TSV：barcode_sample、cell_type。条形码必须与表达矩阵匹配。
DEG 文件（仅方法 3）：两列 TSV：cell_type、gene。传入前必须完成显著性筛选；CellPhoneDB 不会自行过滤。
微环境文件（可选）：两列 TSV：cell_type、microenvironment。仅测试位于同一微环境的细胞类型对。

关键参数

| 参数 | 默认值 | 说明 | |---|---:|---| | counts_data | 'ensembl' | ⚠️ 最常出错参数：必须与基因 ID 类型一致。使用基因符号时必须设为 'hgnc_symbol' | | threshold | 0.1 | 基因最小表达细胞比例。 | | iterations | 1000 | 置换次数；测试时可用 100。 | | pvalue | 0.05 | significant_means 的显著性阈值。 | | score_interactions | False | 启用 v5 的 0-100 特异性评分。 | | debug_seed | -1 | 设为大于等于 0 以保证可复现性；须使用 threads=1。 |

查询结果

from cellphonedb.utils import search_utils

hits = search_utils.search_analysis_results(
    query_cell_types_1=['CellA', 'CellB'],
    query_cell_types_2=['CellC', 'CellD'],
    query_genes=['TGFBR1', 'CSF1R'],
    query_interactions=['CSF1_CSF1R'],
    query_classifications=['TGF-beta signaling'],
    query_minimum_score=50,
    significant_means=cpdb_results['significant_means'],
    deconvoluted=cpdb_results['deconvoluted'],
    interaction_scores=cpdb_results['interaction_scores'],
    long_format=True,                   # 长表格式，移除 NaN 行
)

可视化（ktplotspy）

CellPhoneDB 不自带绘图功能，使用 ktplotspy：

import ktplotspy as kpy
import anndata as ad

adata = ad.read_h5ad('data/normalised_log_counts.h5ad')

# 热图：每个细胞类型对中显著相互作用的数量
kpy.plot_cpdb_heatmap(
    pvals=cpdb_results['pvalues'],
    degs_analysis=False,
    figsize=(5, 5),
    title="显著相互作用数量",
)

# 点图：展示指定细胞类型对中的特定相互作用
kpy.plot_cpdb(
    adata=adata,
    cell_type1="CellA|CellB",
    cell_type2="CellC|CellD",
    means=cpdb_results['means'],
    pvals=cpdb_results['pvalues'],
    celltype_key="cell_labels",
    genes=["TGFB2", "CSF1R"],
    figsize=(10, 3),
    degs_analysis=False,
    standard_scale=True,
    interaction_scores=cpdb_results['interaction_scores'],
    scale_alpha_by_interaction_scores=True,
)

输出表格

所有表格均包含注释列（每行代表一个相互作用）和细胞类型对列（如 cellA|cellB）。

| 表格 | 内容 | |---|---| | means | 每个细胞类型对中相互作用的平均表达。 | | pvalues | 置换检验 p 值（方法 2）。 | | significant_means | p 值小于阈值的平均表达；其他值为 NaN。 | | relevant_interactions | 二元 0/1 相关性结果（方法 3）。 | | deconvoluted | 复合物中各基因的平均表达明细。 | | deconvoluted_percents | 各基因的表达细胞百分比。 | | interaction_scores | 特异性评分 0-100（启用评分时生成）。 |

常见致命错误（TOP 3）

1. counts_data 参数错误 → 零相互作用

症状：分析运行完成但 significant_means 为空
原因：使用基因符号但忘记设置 counts_data='hgnc_symbol'，默认值 'ensembl' 不匹配
解决：在调用方法前检查基因ID类型，设置正确的参数

2. 使用 z-score 标准化 → 评分失效

症状：interaction_scores 全为零或不合理
原因：评分要求 log 标准化数据（零值保持为零），z-score 破坏了这个条件
解决：使用 log1p(normalized_counts) 进行标准化

3. 小鼠数据未转换 → 基因不匹配

症状：大部分基因被过滤，结果稀少
原因：CellPhoneDB 仅支持人类基因，小鼠基因名无法匹配
解决：使用同源基因转换工具将小鼠基因映射到人类

其他常见问题

仅支持人类基因 - 小鼠数据必须先转换为人类同源基因
运行前必须创建输出目录 - CellPhoneDB 不会自动创建
细胞类型名称不能是纯数字 - 例如 0、1、2；请使用字符串标签
条形码中不要含有连字符 - 细胞名称中的连字符存在已知问题
DEG 方法不会过滤基因 - DEG 文件中的所有基因都会被视为显著，必须在外部预筛选
相互作用方向具有不对称性 - A|B 中 IL12_IL12R 表示受体位于 B；与 B|A 不同
评分与显著性可能不一致 - 高评分但不显著表示广泛表达；显著但低评分表示特异但表达低
debug_seed 仅在单线程下有效 - 若需要可复现性，设置 threads=1
v5 软件包必须使用 v5 数据库 - 不要混用旧数据库 ZIP 与 v5 代码

工作流程概览

确认分析前提 → verify: 物种正确、基因ID类型明确、DEG可用性已知
准备数据文件 → verify: counts.h5ad 为log标准化、metadata.tsv 格式正确（字符串标签，条形码不含连字符）
下载并配置数据库 → verify: v5数据库ZIP文件存在、输出目录已创建
运行分析方法 → verify: 选择合适的方法、设置正确的 counts_data 参数
检查结果质量 → verify: 输出文件完整、显著相互作用数量合理、p值范围正常
查询和可视化 → 使用 search_analysis_results 查询、使用 ktplotspy 绘制热图和点图