pytdc-therapeutics-data-commons

PyTDC（Therapeutics Data Commons）

概览

PyTDC 是一个开放科学平台，提供适用于 AI 的药物发现数据集和基准。它将治疗领域的数据分为三类：单实例预测（分子／蛋白质属性）、多实例预测（药物-靶点相互作用）和生成（分子设计、逆合成）。所有数据集都配有标准化的数据划分、评估指标以及分子 Oracle。

适用场景

• 加载经过整理的 ADME、毒性或生物活性数据集，用于训练 ML 模型
• 使用标准化的 5 个随机种子评估方案对药物发现模型进行基准测试
• 使用恰当的冷启动划分评估来预测药物-靶点或药物-药物相互作用
• 生成新分子，并使用分子 Oracle（QED、SA、DRD2、GSK3B）为其评分
• 获取基于骨架或时间划分的训练集／测试集，用于制药领域的 ML
• 转换分子表示形式（SMILES 转 PyG 图、ECFP 指纹、SELFIES）
• 对于化学数据库查询（化合物搜索、生物活性），请改用 chembl-database-bioactivity
• 对于超出格式转换范围的分子特征化，请改用 molfeat

先决条件

uv pip install PyTDC
# Core deps: numpy, pandas, scikit-learn, tqdm, fuzzywuzzy
# Optional: rdkit (scaffold splits), torch-geometric (PyG conversion)

API 说明：TDC 会在首次访问时下载数据集（每个数据集约 10-500 MB）。指定 path='data/' 可控制下载位置。无需 API 密钥。

快速开始

from tdc.single_pred import ADME
from tdc import Evaluator

# Load dataset with scaffold split
data = ADME(name='Caco2_Wang')
split = data.get_split(method='scaffold', seed=42, frac=[0.7, 0.1, 0.2])
train, valid, test = split['train'], split['valid'], split['test']
print(f"Train: {len(train)}, Valid: {len(valid)}, Test: {len(test)}")
# Train: ~640, Valid: ~91, Test: ~182

# Evaluate predictions
evaluator = Evaluator(name='MAE')
# score = evaluator(test['Y'].values, predictions)

核心 API

模块 1：单实例预测 — 数据集访问

加载用于预测单个分子或蛋白质属性的数据集。

from tdc.single_pred import ADME, Tox, HTS, QM

# ADME — pharmacokinetic properties
data = ADME(name='Caco2_Wang')       # Intestinal permeability (regression)
data = ADME(name='BBB_Martins')       # Blood-brain barrier (binary)
data = ADME(name='Lipophilicity_AstraZeneca')  # LogD (regression)
data = ADME(name='Solubility_AqSolDB')         # Aqueous solubility

# Toxicity — adverse effects
data = Tox(name='hERG')              # Cardiotoxicity (binary)
data = Tox(name='AMES')              # Mutagenicity (binary)
data = Tox(name='DILI')              # Drug-induced liver injury
data = Tox(name='ClinTox')           # Clinical trial toxicity

# Access data as DataFrame
df = data.get_data(format='df')
print(df.columns.tolist())
# ['Drug_ID', 'Drug', 'Y'] — Drug is SMILES, Y is target label
print(f"Dataset size: {len(df)}, Label range: [{df['Y'].min():.2f}, {df['Y'].max():.2f}]")

其他单预测任务：HTS（筛选）、QM（量子力学）、Yields、Epitope、Develop、CRISPROutcome。

模块 2：多实例预测 — 相互作用数据集

加载用于预测成对生物医学实体之间相互作用的数据集。

from tdc.multi_pred import DTI, DDI, PPI

# Drug-Target Interaction — binding affinity
data = DTI(name='BindingDB_Kd')      # 52,284 pairs, Kd values
data = DTI(name='DAVIS')             # 30,056 pairs, kinase binding
data = DTI(name='KIBA')              # 118,254 pairs, kinase bioactivity

# Drug-Drug Interaction — interaction type prediction
data = DDI(name='DrugBank')           # 191,808 pairs, 86 interaction types

# Protein-Protein Interaction
data = PPI(name='HuRI')

# Multi-instance data format
df = data.get_data(format='df')
print(df.columns.tolist())
# ['Drug_ID', 'Drug', 'Target_ID', 'Target', 'Y']
# Drug=SMILES, Target=protein sequence, Y=binding affinity or class

其他多实例任务：GDA、DrugRes、DrugSyn、PeptideMHC、AntibodyAff、MTI、Catalyst、TrialOutcome。

模块 3：生成任务 — 分子设计

加载用于分子生成和逆合成的训练集与 Oracle。

from tdc.generation import MolGen, RetroSyn, PairMolGen
from tdc import Oracle

# Molecule generation — training data
data = MolGen(name='ChEMBL_V29')     # 1.6M drug-like SMILES
split = data.get_split()
train_smiles = split['train']['Drug'].tolist()

# Oracle scoring — evaluate generated molecules
oracle = Oracle(name='GSK3B')         # GSK3B inhibition predictor (0-1)
score = oracle('CC(C)Cc1ccc(cc1)C(C)C(O)=O')
print(f"GSK3B score: {score:.4f}")

# Batch evaluation
scores = oracle(['CCO', 'c1ccccc1', 'CC(=O)O'])
print(f"Batch scores: {scores}")

# Retrosynthesis — reaction prediction
data = RetroSyn(name='USPTO')         # 1.9M reactions
split = data.get_split()

# Paired generation — prodrug design
data = PairMolGen(name='Prodrug')

模块 4：数据划分与评估

应用有意义的数据划分和标准化评估指标。

from tdc.single_pred import ADME
from tdc.multi_pred import DTI
from tdc import Evaluator

# Scaffold split — ensures chemical diversity between sets
data = ADME(name='Caco2_Wang')
split = data.get_split(method='scaffold', seed=42, frac=[0.7, 0.1, 0.2])

# Cold splits — for DTI (unseen drugs/targets in test set)
data = DTI(name='BindingDB_Kd')
cold_drug = data.get_split(method='cold_drug', seed=1)
cold_target = data.get_split(method='cold_target', seed=1)

# Verify no overlap in cold split
train_drugs = set(cold_drug['train']['Drug_ID'])
test_drugs = set(cold_drug['test']['Drug_ID'])
print(f"Drug overlap: {len(train_drugs & test_drugs)}")  # 0

# Evaluation metrics
eval_mae = Evaluator(name='MAE')
eval_auc = Evaluator(name='ROC-AUC')
eval_spearman = Evaluator(name='Spearman')
# score = eval_mae(y_true, y_pred)

可用划分方法：random、scaffold（Bemis-Murcko）、cold_drug、cold_target、cold_drug_target、temporal。

可用指标：分类 — ROC-AUC、PR-AUC、F1、Accuracy、Kappa。回归 — RMSE、MAE、R2、MSE。排序 — Spearman、Pearson。多标签 — Micro-F1、Macro-F1。

模块 5：基准组

运行标准化的多随机种子评估方案，以比较模型。

from tdc.benchmark_group import admet_group

# Load ADMET benchmark (22 datasets)
group = admet_group(path='data/')

# Standard 5-seed evaluation protocol
benchmark = group.get('Caco2_Wang')
predictions = {}

for seed in [1, 2, 3, 4, 5]:
    train_df = benchmark['train']
    valid_df = benchmark['valid']
    test_df = benchmark['test']
    # Train your model on train_df, tune on valid_df
    # predictions[seed] = model.predict(test_df['Drug'])
    predictions[seed] = test_df['Y'].values  # placeholder

# Get benchmark results
results = group.evaluate(predictions)
print(f"Mean MAE: {results['Caco2_Wang'][0]:.4f} ± {results['Caco2_Wang'][1]:.4f}")

核心概念

数据集组织方式

类别	导入路径	任务示例	数据格式
单实例	tdc.single_pred	ADME、Tox、HTS、QM	Drug（SMILES）+ Y（标签）
多实例	tdc.multi_pred	DTI、DDI、PPI、DrugSyn	Drug + Target + Y
生成	tdc.generation	MolGen、RetroSyn	SMILES 集合
基准	tdc.benchmark_group	admet_group	整理后的划分

Oracle 类别

类别	示例	速度	输出范围
生化	DRD2、GSK3B、JNK3、5HT2A	中等（ML）	0-1 概率
理化	QED、SA、LogP、MW	快（基于规则）	因指标而异
组合	Isomer_Meta、Median1/2、Rediscovery	中等	0-1 组合值
专用	ASKCOS、Docking、Vina	慢（外部）	因指标而异

数据处理实用工具

实用工具	功能	示例
格式转换	MolConvert(src, dst)	SMILES → PyG、ECFP、SELFIES、DGL
分子过滤器	MolFilter(filters)	PAINS、BMS、Glaxo、药物相似性
标签二值化	label_transform()	连续值 → 按阈值转换为二值
单位转换	label_transform(from_unit, to_unit)	nM → pIC50
ID 解析	cid2smiles()、uniprot2seq()	PubChem CID → SMILES
数据集列表	retrieve_dataset_names(task)	列出所有 ADME 数据集

常见工作流

工作流 1：多随机种子 ADME 模型评估

from tdc.single_pred import ADME
from tdc import Evaluator
import numpy as np

data = ADME(name='Caco2_Wang')
evaluator = Evaluator(name='MAE')

results = []
for seed in [1, 2, 3, 4, 5]:
    split = data.get_split(method='scaffold', seed=seed)
    train, valid, test = split['train'], split['valid'], split['test']
    # model.fit(train['Drug'], train['Y'])
    # preds = model.predict(test['Drug'])
    preds = test['Y'].values + np.random.normal(0, 0.1, len(test))  # placeholder
    score = evaluator(test['Y'].values, preds)
    results.append(score)
    print(f"Seed {seed}: MAE = {score:.4f}")

print(f"Mean MAE: {np.mean(results):.4f} ± {np.std(results):.4f}")

工作流 2：多目标分子评分

from tdc import Oracle
import numpy as np

# Define multi-objective scoring
oracles = {
    'QED': (Oracle(name='QED'), 0.3),      # drug-likeness
    'SA': (Oracle(name='SA'), 0.3),         # synthetic accessibility
    'GSK3B': (Oracle(name='GSK3B'), 0.4),   # target activity
}

test_smiles = ['CC(C)Cc1ccc(cc1)C(C)C(O)=O', 'c1ccc2c(c1)cc1ccc3cccc4ccc2c1c34']

for smi in test_smiles:
    scores = {}
    weighted_sum = 0
    for name, (oracle, weight) in oracles.items():
        score = oracle(smi)
        scores[name] = score
        weighted_sum += score * weight
    print(f"SMILES: {smi[:30]}...")
    print(f"  Scores: {scores}")
    print(f"  Weighted: {weighted_sum:.4f}")

工作流 3：冷启动划分 DTI 评估（仅文本）

1. 加载 DTI 数据集 — DTI(name='BindingDB_Kd')（核心 API 模块 2）
2. 应用 cold_drug 划分 — data.get_split(method='cold_drug', seed=seed)（核心 API 模块 4）
3. 确认训练集与测试集之间没有药物重叠（模块 4 重叠检查）
4. 使用训练集训练模型，并在测试集上进行预测
5. 使用 Spearman 相关性进行评估 — Evaluator(name='Spearman')（模块 4）
6. 对 5 个随机种子重复此过程，并报告均值 ± 标准差（与工作流 1 相同）

关键参数

参数	函数/模块	默认值	范围/选项	作用
method	get_split()	'scaffold'	random、scaffold、cold_drug、cold_target、temporal	训练集/测试集划分策略
seed	get_split()	42	基准测试使用 1-5	保证可复现性；基准测试使用 5 个随机种子
frac	get_split()	[0.7, 0.1, 0.2]	总和必须为 1.0	训练集/验证集/测试集比例
name	Evaluator()	—	MAE、RMSE、ROC-AUC、Spearman 等	评估指标
name	Oracle()	—	QED、SA、GSK3B、DRD2 等	分子评分函数
src/dst	MolConvert()	—	SMILES、SELFIES、PyG、DGL、ECFP4	分子表示格式
path	admet_group()	'data/'	任意目录	数据集下载/缓存位置
format	get_data()	'df'	'df'、'dict'	输出数据格式

最佳实践

1. 分子性质预测始终使用 scaffold 划分 — 随机划分会泄露结构信息并夸大性能指标
2. 报告 5 个随机种子的评估结果，并给出均值 ± 标准差 — 单个随机种子的结果不适合用于方法比较
3. 交互预测使用冷启动划分 — cold_drug 用于测试对未见药物的泛化能力，cold_target 用于测试对未见靶点的泛化能力
4. 尽早使用 MolFilter 过滤分子（PAINS、药物相似性），在训练前去除有问题的化合物
5. 适当归一化 Oracle — QED 的取值为 0-1，SA 的取值为 1-10（越低越好），结合分数的范围各不相同。组合前请查看 Oracle 文档
6. 通过指定持久化的 path 缓存数据集 — 避免在不同会话中重复下载大型数据集

常见方案

方案 1：数据集探索与统计

from tdc.single_pred import ADME
from tdc.utils import retrieve_dataset_names

# List all ADME datasets
datasets = retrieve_dataset_names('ADME')
print(f"Available ADME datasets: {datasets}")

# Load and inspect
data = ADME(name='Caco2_Wang')
df = data.get_data(format='df')
print(f"Size: {len(df)}")
print(f"Label stats: mean={df['Y'].mean():.2f}, std={df['Y'].std():.2f}")
print(f"SMILES example: {df['Drug'].iloc[0]}")

方案 2：分子格式转换流程

from tdc.chem_utils import MolConvert

# SMILES to multiple representations
smiles = 'CC(C)Cc1ccc(cc1)C(C)C(O)=O'

converter_ecfp = MolConvert(src='SMILES', dst='ECFP4')
converter_selfies = MolConvert(src='SMILES', dst='SELFIES')

ecfp = converter_ecfp(smiles)
selfies = converter_selfies(smiles)
print(f"ECFP4 shape: {ecfp.shape}")    # (1024,) binary fingerprint
print(f"SELFIES: {selfies}")

方案 3：带约束满足的自定义 Oracle

from tdc import Oracle

# Define property constraints
constraints = {
    'QED': (Oracle(name='QED'), 0.5, 1.0),       # min, max
    'SA': (Oracle(name='SA'), 1.0, 4.0),
    'LogP': (Oracle(name='LogP'), -0.5, 5.0),
}

def check_constraints(smiles):
    """Check if molecule satisfies all property constraints."""
    results = {}
    all_pass = True
    for name, (oracle, lo, hi) in constraints.items():
        score = oracle(smiles)
        passed = lo <= score <= hi
        results[name] = {'score': score, 'passed': passed}
        all_pass = all_pass and passed
    return all_pass, results

passed, details = check_constraints('CC(C)Cc1ccc(cc1)C(C)C(O)=O')
for name, info in details.items():
    status = "PASS" if info['passed'] else "FAIL"
    print(f"{name}: {info['score']:.3f} [{status}]")

故障排除

问题	原因	解决方案
ModuleNotFoundError: tdc	未安装软件包	uv pip install PyTDC
Scaffold 拆分失败	缺少 RDKit 依赖项	执行 uv pip install rdkit 以进行 scaffold 分解
数据集下载超时	数据集较大或连接较慢	设置 path='data/' 以使用持久缓存；然后重试
数据集名称触发 KeyError	名称或任务类别有误	使用 retrieve_dataset_names('ADME') 列出有效名称
Oracle 返回 NaN	SMILES 无效或 RDKit 解析失败	先使用 RDKit 的 MolFromSmiles() 验证 SMILES
Cold split 测试集为空	唯一实体数量太少	对较大的数据集使用 frac=[0.7, 0.1, 0.2]
基准评估出错	预测格式有误	传入以种子为键的 dict：{1: preds1, 2: preds2, ...}
大型数据集出现内存错误	整个数据集都加载到了内存中	分块处理，或使用较小的拆分比例
PyG 转换失败	未安装 torch-geometric	执行 uv pip install torch-geometric 以进行图转换

捆绑资源

references/datasets_catalog.md

涵盖：按任务类别（单实例、多实例、生成）整理的所有 TDC 数据集完整目录，包含数据集名称、大小、标签类型和数据来源。已内联迁移：将顶部 ADME/Tox/DTI 数据集及代码示例整合到核心 API 模块 1-2。省略：无——目录中保留了所有数据集条目。

references/oracles_utilities.md

涵盖：详尽的 oracle 文档（全部 17 种以上 oracle 的参数、速度等级、输出范围、自定义 oracle 模板）和数据处理工具（格式转换目标、分子筛选类型、标签转换、实体解析）。由原始 oracles.md + utilities.md 整合而成。已内联迁移：快速入门中的 oracle 用法模式、主要评估指标、拆分方法、MolConvert 模式 → 核心 API 模块 3-4。省略：分布学习 KS 检验示例——属于小众统计比较；排行榜提交指南——特定于平台。

脚本处置

• load_and_split_data.py（215 行）：scaffold/cold 拆分模式 → 核心 API 模块 4；自定义拆分比例 → 关键参数；评估示例 → 工作流 1。对 get_split() 和 Evaluator() 的轻量封装。
• benchmark_evaluation.py（328 行）：5 种子协议 → 核心 API 模块 5 + 工作流 1；多数据集评估 → 工作流 1 模式；排行榜指南 → 已省略（特定于平台）。
• molecular_generation.py（405 行）：单次/批量 oracle 用法 → 核心 API 模块 3；多目标评分 → 工作流 2；约束满足 → 配方 3；分布学习 → 已省略（小众）。

相关技能

• chembl-database-bioactivity — 用于直接查询 ChEMBL 化合物/靶标/活性数据
• molfeat — 用于进行超出 TDC 内置 MolConvert 功能的高级分子特征化
• rdkit-cheminformatics — 用于分子操作、子结构搜索和描述符计算

参考资料

• TDC 官方网站：https://tdcommons.ai
• TDC 文档：https://tdc.readthedocs.io
• GitHub 仓库：https://github.com/mims-harvard/TDC
• Huang 等人。《Therapeutics Data Commons》，NeurIPS 2021 数据集与基准