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 用のホイールがありません
• 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 環境では、サイズの大きい科学／ML 依存関係を含む 123 個のパッケージがインストールされました。そのため、データセットをダウンロードする前でも、環境の転送と保存に数百 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. ダウンロードする前にユーザーに確認します。 ローダーのコンストラクターは、不足しているデータを取得します。一部のデータセットやベンチマークグループのアーカイブは大容量です。モデルを利用するオラクルではチェックポイントが取得される場合があり、リモート／ドッキングオラクルでは分子構造が送信される場合があります。
4. 承認を得てから実行します。 同梱 CLI では、--execute により実行を承認し、MolGen コーパスまたはサポート対象のオラクルチェックポイントをダウンロードするには、さらに --download が必要です。
5. 出力を適切な量に抑えます。 データセット全体、配列、予測配列、分子コーパスではなく、件数、スキーマ、小規模なプレビューを出力してください。

キャッシュとコストの動作

• 通常のローダーはデフォルトで path="./data" を使用し、そのパス配下にファイルを保存します。 同梱スクリプトでは、代わりに明示的な .pytdc-* ディレクトリがデフォルトで使用されます。
• ローカルファイルが存在しない場合、コアのダウンロードでは Harvard Dataverse のファイルエンドポイントが使用されます。新しいリソースクラスでは、別のアップストリームサービスが使用される場合があります。
• admet_group(path=...) やその他のベンチマークグループのコンストラクターは、<path>/<group> が存在しない場合、グループのアーカイブをダウンロードして展開します。
• ダウンロードを伴う Oracle(...) の構築では、内部で ./oracle が使用されます。同梱のオラクル CLI は、承認済みの呼び出しを行う前に、安全なランタイムディレクトリに移動します。
• PyTDC 1.1.15 には、汎用のキャッシュ容量制限、削除ポリシー、データセット全体を対象とするチェックサムマニフェストはありません。scripts/cache_audit.py を使用し、ディスク上の保持対象を明示的に管理してください。
• ネットワーク転送、ローカルストレージ、展開、解析、特徴量生成、ドッキング、外部サービスの呼び出しでは、時間や金銭的なコストが発生する場合があります。

PyTDC のコードは MIT ライセンスです。データセット／タスクのライセンスはさまざまで、公式タスクページには、クリエイティブ・コモンズライセンスから非商用利用の制限、「Not Specified」まで、データセットごとに異なる条件が記載されています。ダウンロード、再配布、公開、商用利用の前に、該当するデータセットのページと元のソースの利用条件を確認してください。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 での表記は temporal ではなく time です。

文書化されていない 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)

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",
)

1 回の実行では、group.evaluate({name: test_predictions}) はメトリクスの結果を返します。リーダーボードで集計する場合は、少なくとも 5 個の予測辞書のリストを 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 を追加してください。LogP と SA は 1.1.15 でダウンロード可能な 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 — 日付付きの信頼できる情報源と 未解決の上流の問題

エージェントの操作手順

1. 環境を確認します。 ネットワークに接続できること、API キー（必要な場合）、データベースの最新の API ドキュメントとレート制限を確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果が変わる値は推測せず、質問してください。
3. まず小規模に実行します。 既知のレコードを1件取得し、一括クエリの前にレスポンス形式を確認します。
4. 上記の手順と参考情報を使用して、タスク全体を実行します。
5. 結果を検証します。 識別子が解決され、レコード数が報告され、データベースのバージョンまたはアクセス日が記録されていることを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確認の事項を伝えます。

このような場合	実行すること
HTTP 429 または 5xx エラーが発生した場合	バックオフを適用してレート制限を守り、リクエストをバッチ処理し、部分的な結果を正直に報告します。
これらの手順に記載された関数、フラグ、またはエンドポイントがインストール済みのバージョンにない場合	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適応し、ユーザーに伝えます。API を決して捏造しないでください。
必須の入力、識別子、またはパラメーターが曖昧な場合	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計を決して捏造しないでください。実行または検証できないことは、明確に伝えてください。
• アクセッション番号、ID、レコードを決して捏造せず、見つからない場合は「見つかりません」と報告してください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認してください。
• 金銭がかかる操作、共有 GPU またはクラウドのクォータを消費する操作、個人データや患者データを扱う操作、または取り消せない操作の前には、許可を求めてください。

関連スキル

• deepchem：多様な特徴量化器と構築済みデータセットを使った分子 ML。