pytdc

PyTDC（Therapeutics Data Commons）

使用官方的 PyTDC 发行版（import tdc）发现治疗领域的 ML 任务、加载经批准的数据集、应用适合任务的数据划分、评估预测结果，并使用经过整理的基准测试组。优先使用软件包元数据，而非复制的数据集列表；构造任何加载器前，先规划网络和存储方面的影响。

已核实的快照

• 研究日期：2026-07-23
• PyPI 稳定版：PyTDC 1.1.15，发布于 2025-03-31
• 软件包／源代码仓库：mims-harvard/TDC
• 代码许可证：MIT
• PyPI 仅提供源代码发行版，且未声明 Requires-Python
• 依赖关系决定了本指南采用 CPython 3.11 作为可复现目标：cellxgene-census==1.15.0 不支持 Python 3.12，而 PyTDC 限定的 RDKit 版本没有适用于 CPython 3.13 的 wheel
• PyTDC 在运行时会导入已弃用的 pkg_resources。Setuptools 82 移除了该模块；请固定到经核实的兼容版本 setuptools 80.9.0。
• tdc.readthedocs.io 仍标注自身为 TDC 0.4.1；请将其用作 API 交叉参考，而非发行版本依据
• 上游没有发布 GitHub 标签／发行版，也没有维护更新日志。对于未记录的迁移声明，请视为不确定，并根据已安装的 1.1.15 源代码／元数据进行核实。

有关带日期的证据和已知文档冲突，请参阅 references/sources.md。

安装

请使用独立的 CPython 3.11 环境，并固定到经过审核的快照：

uv venv --python 3.11 .venv-pytdc
uv pip install --dry-run --python .venv-pytdc/bin/python \
  "setuptools==80.9.0" "PyTDC==1.1.15"
uv pip install --python .venv-pytdc/bin/python \
  "setuptools==80.9.0" "PyTDC==1.1.15"

在经过测试的 macOS ARM64 环境中，安装解析出的依赖包含 123 个软件包，其中包括大型科学计算／ML 依赖。因此，在下载任何数据之前，环境本身就可能需要传输并占用数百 MB。请先检查试运行结果和可用磁盘空间。直接依赖的固定版本用于标识经过审核的 API 快照；如果需要同时锁定所有传递依赖版本，请在用户的项目中生成适用于特定平台的 uv.lock。

对于临时命令：

uv run --python 3.11 \
  --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
  python scripts/discover_metadata.py --kind tasks

如需检查是否有更新的发行版，请查看 PyPI 的发行历史：https://pypi.org/project/pytdc/。更改固定版本前，请对比其源代码发行版、依赖项、官方仓库、任务注册表和冒烟测试；不要悄然替换为独立的 pytdc-nextml 软件包。

不可妥协的数据与网络策略

1. 先发现。 读取 tdc.metadata 或使用 scripts/discover_metadata.py 不会实例化加载器，也不会下载数据。
2. 再规划。 记录确切的任务／数据集、官方任务页面、许可证、预期大小、缓存目录、数据划分、指标和可复现性种子。
3. 下载前征求用户同意。 加载器构造函数会获取缺失的数据。某些数据集和基准测试组归档文件很大；基于模型的 oracle 可能会获取检查点；远程／对接 oracle 可能会传输分子结构。
4. 获得批准后再执行。 在捆绑的 CLI 中，--execute 表示确认执行；对于 MolGen 语料库或受支持的 oracle 检查点，还必须提供 --download。
5. 控制输出范围。 输出计数、架构和小型预览，而不要输出完整数据集、序列、预测数组或分子语料库。

缓存与成本行为

• 普通加载器默认使用 path="./data"，并将文件保存在该路径下。 捆绑脚本则默认使用明确的 .pytdc-* 目录。
• 当本地文件名不存在时，核心下载会使用 Harvard Dataverse 文件端点。较新的资源类可能使用其他上游服务。
• 当 <path>/<group> 不存在时，admet_group(path=...) 和其他基准组构造函数会下载并解压组存档。
• 基于下载的 Oracle(...) 构造会在内部使用 ./oracle。捆绑的 Oracle CLI 会在执行获准调用前切换到安全的运行目录。
• PyTDC 1.1.15 未提供通用缓存配额、淘汰策略或覆盖整个数据集的校验和清单。请使用 scripts/cache_audit.py 并明确管理磁盘保留。
• 网络传输、本地存储、解压缩、解析、特征生成、对接以及外部服务调用都可能产生时间或金钱成本。

PyTDC 代码采用 MIT 许可证。数据集／任务的许可证各不相同：官方任务页面列出的数据集条款包括 Creative Commons 许可证、非商业限制或“未指定”。下载、再分发、发布或商业使用前，请核实具体数据集页面及原始来源条款。请同时引用 TDC 和原始数据集。

从仅元数据发现开始

在此技能目录中：

uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
  python scripts/discover_metadata.py --kind datasets --task ADME --limit 50

uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
  python scripts/discover_metadata.py --kind benchmarks --limit 50

uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
  python scripts/discover_metadata.py --kind evaluators --limit 100

包 API 也仅返回元数据：

from tdc.utils import retrieve_dataset_names, retrieve_benchmark_names

adme_names = retrieve_dataset_names("ADME")
admet_benchmarks = retrieve_benchmark_names("admet_group")

请使用返回的确切名称。PyTDC 会在内部进行模糊匹配，但显式匹配可避免悄然选错数据集／预言机。

数据集工作流

在不下载的情况下规划拆分：

uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
  python scripts/load_and_split_data.py \
  --task ADME --dataset Caco2_Wang --method scaffold \
  --seed 42 --data-dir .pytdc-data

用户批准数据集、许可证、传输和存储后：

uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
  python scripts/load_and_split_data.py \
  --task ADME --dataset Caco2_Wang --method scaffold \
  --seed 42 --data-dir .pytdc-data --execute

已验证的公开导入模式包括：

from tdc.single_pred import ADME, Tox
from tdc.multi_pred import DDI, DTI
from tdc.generation import MolGen, Reaction, RetroSyn

构造函数会访问数据，因此未经批准请勿运行：

data = ADME(name="Caco2_Wang", path=".pytdc-data")
frame = data.get_data(format="df")
split = data.get_split(
    method="scaffold",
    seed=42,
    frac=[0.7, 0.1, 0.2],
)
# split keys are: train, valid, test

选择任务或数据集前，请阅读 references/datasets.md。

选择拆分方式，但不要夸大其防止数据泄漏的能力

• random：加载器的默认方式；默认种子为 42，比例为 0.7/0.1/0.2。
• scaffold：针对基于分子的 ADME、Tox 和 HTS，文档说明了通用支持。PyTDC 会对 RDKit Bemis–Murcko 骨架字符串进行分组（禁用手性），但这并不能证明不存在类似物、重复项、标签、时间或来源泄漏。
• cold_split：多实例 API。传入确切的数据帧列，例如 method="cold_split", column_name=["Drug", "Target"]。多列拆分可能会丢弃跨分区行，也不一定保留所请求的行比例。
• combination：内置的 DrugSyn 组合拆分。
• time：需要 time_column 的配对加载器 API；已验证的内置案例是使用 Year 列的 BindingDB_Patent。API 中的拼写是 time，不是 temporal。

请勿使用未经文档说明的 cold_drug_target、temporal 或 stratified=True 示例。对于每种拆分，请记录 PyTDC 版本、参数、行数以及精确的实体重叠审计结果。PyTDC 1.1.15 的随机拆分器使用提供的种子进行测试集采样，但验证集采样使用固定的 random_state=1；请勿描述所有分区都会随种子独立变化。

详细语义和注意事项见 references/utilities.md。

评估器

请使用已安装评估器注册表中的确切名称：

from tdc import Evaluator

mae = Evaluator(name="MAE")(y_true, y_pred)
auroc = Evaluator(name="ROC-AUC")(y_true_binary, predicted_scores)
pcc = Evaluator(name="PCC")(y_true, y_pred)

已注册的 Pearson 相关系数名称是 PCC，而不是 Pearson。多分类注册表名称为 micro-f1、macro-f1 和 kappa。阈值二分类指标的默认值为 0.5。指标方向和输入形状因指标而异；请使用官方任务／基准指标，不要仅根据任务类型来选择。

基准组

请使用专用类。顶层的 from tdc import BenchmarkGroup 仅作为已弃用的兼容路径保留于 1.1.15 中。

from tdc.benchmark_group import admet_group

# Run only after approval: construction may download the group archive.
group = admet_group(path=".pytdc-benchmarks")
benchmark = group.get("Caco2_Wang")
train_val = benchmark["train_val"]
test = benchmark["test"]
train, valid = group.get_train_valid_split(
    seed=1,
    benchmark=benchmark["name"],
    split_type="default",
)

单次运行时，group.evaluate({name: test_predictions}) 会返回指标结果。汇总排行榜时，请将至少五个预测字典组成的列表传递给 group.evaluate_many(...)。不要按种子索引 group.get(...)，也不要根据测试标签推导虚假预测。

请使用 scripts/benchmark_evaluation.py，在下载任何基准组之前验证有界 JSON 预测计划。确切的 JSON 格式和 API 行为请参阅 references/utilities.md。

分子生成与预言机

PyTDC 提供分子语料库、评估器和预言机；核心工作流不会训练或提供通用分子生成器。请发现当前可用的名称：

uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
  python scripts/discover_metadata.py --kind oracles --limit 100

规划有界的本地 QED 评分：

uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
  python scripts/molecular_generation.py score --oracle QED --smiles CCO

审核后再添加 --execute。在 1.1.15 中，LogP 和 SA 会调用可下载的 fpscores 构件；它们以及 DRD2/GSK3B/JNK3/CYP3A4_Veith 还需要 --download。此帮助工具会有意拒绝远程服务、分子对接、分布式计算和复合预言机。它会保留输入顺序，且不会假设分数方向。

调用任何预言机之前，请阅读 references/oracles.md。

捆绑资源

脚本

• scripts/discover_metadata.py — 无需下载即可发现软件包注册信息
• scripts/load_and_split_data.py — 面向任务的拆分计划／显式执行
• scripts/benchmark_evaluation.py — 预测验证与显式评估
• scripts/molecular_generation.py — 有界本地／检查点评分与 MolGen 计划
• scripts/cache_audit.py — 只读的有界缓存清单

所有 CLI 均使用惰性可选导入、安全的相对输出／缓存路径、JSON 摘要和有界输出，且不会隐式下载数据集／模型。

参考资料

• references/datasets.md — 任务发现、数据访问、缓存行为和许可
• references/utilities.md — 拆分、评估器和基准组 API
• references/oracles.md — 预言机类别、副作用和安全执行
• references/sources.md — 带日期的权威来源和尚未解决的上游问题

Agent 操作流程

1. 检查环境。 确认网络访问权限、API 密钥（如需要），以及数据库当前的 API 文档和速率限制。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会影响结果的值都应询问，不要猜测。
3. 先运行小规模版本。 获取一条已知记录，并在批量查询前检查响应格式。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 确认标识符可解析、报告记录数，并记录数据库版本或访问日期。
6. 报告结果。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
出现 HTTP 429 或 5xx 错误	通过退避重试和批量请求遵守速率限制，并如实报告部分结果。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），调整做法，并告知用户。切勿虚构 API。
必要的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

诚信规则

• 切勿伪造结果、参数、标识符、引用或统计数据。如果某项内容无法运行或验证，请直言说明。
• 切勿编造登录号、ID 或记录；若未找到，请报告“未找到”。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，执行前必须征得同意。

相关技能

• deepchem：使用多种特征化器和预构建数据集进行分子机器学习。