skills/pytdc/SKILL.md
Use the official PyTDC distribution (import tdc) to discover therapeutic ML
tasks, load approved datasets, apply task-appropriate splits, evaluate predictions,
and work with curated benchmark groups. Prefer package metadata over copied dataset
lists, and plan network/storage effects before constructing any loader.
mims-harvard/TDCRequires-Pythoncellxgene-census==1.15.0 excludes Python 3.12, and PyTDC's constrained
RDKit release has no CPython 3.13 wheelpkg_resources at runtime. Setuptools 82 removed that
module; pin the verified compatibility release setuptools 80.9.0.tdc.readthedocs.io still identifies itself as TDC 0.4.1; use it as API
cross-reference, not as release-version evidenceSee references/sources.md for dated evidence and known documentation conflicts.
Use an isolated CPython 3.11 environment and pin the reviewed snapshot:
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"
The tested macOS ARM64 resolution installed 123 packages, including large
scientific/ML dependencies, so the environment itself can transfer and occupy
hundreds of megabytes before any dataset is downloaded. Review the dry run and
available disk first. The direct pins identify the reviewed API snapshot; generate
a platform-specific uv.lock in the user's project when every transitive version
must also be frozen.
For an ephemeral command:
uv run --python 3.11 \
--with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
python scripts/discover_metadata.py --kind tasks
To check for a newer release, inspect the PyPI release history at
https://pypi.org/project/pytdc/. Before changing the pin, compare its source
distribution, dependencies, official repository, task registries, and smoke tests;
do not silently substitute the separate pytdc-nextml package.
tdc.metadata or using
scripts/discover_metadata.py does not instantiate a loader or download data.--execute acknowledges
execution and --download is additionally required for MolGen corpora or
supported oracle checkpoints.path="./data" and save files beneath that path.
The bundled scripts instead default to explicit .pytdc-* directories.admet_group(path=...) and other benchmark-group constructors download and
extract the group archive when <path>/<group> is absent.Oracle(...) construction uses ./oracle internally. The
bundled oracle CLI changes into a safe runtime directory before approved calls.scripts/cache_audit.py and manage disk
retention explicitly.The PyTDC code is MIT. Dataset/task licenses are heterogeneous: official task pages include per-dataset terms ranging from Creative Commons licenses to non-commercial restrictions or “Not Specified.” Verify the exact dataset's page and original source terms before download, redistribution, publication, or commercial use. Cite both TDC and the original dataset.
From this skill directory:
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
The package API is also metadata-only:
from tdc.utils import retrieve_dataset_names, retrieve_benchmark_names
adme_names = retrieve_dataset_names("ADME")
admet_benchmarks = retrieve_benchmark_names("admet_group")
Use exact returned names. PyTDC performs fuzzy matching internally, but explicit matching avoids silently selecting the wrong dataset/oracle.
Plan a split without downloading:
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
After the user approves the dataset, license, transfer, and storage:
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
Verified public import patterns include:
from tdc.single_pred import ADME, Tox
from tdc.multi_pred import DDI, DTI
from tdc.generation import MolGen, Reaction, RetroSyn
Constructors perform data access, so do not run them before approval:
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
Read references/datasets.md before choosing a task or dataset.
random: default for loaders; default seed 42 and fractions 0.7/0.1/0.2.scaffold: documented generic support for molecule-based ADME, Tox, and HTS.
PyTDC groups RDKit Bemis–Murcko scaffold strings (chirality disabled), but that
does not prove absence of analog, duplicate, label, temporal, or provenance
leakage.cold_split: multi-instance API. Pass exact dataframe columns, for example
method="cold_split", column_name=["Drug", "Target"]. Multi-column splitting can
discard cross-partition rows and need not preserve requested row fractions.combination: built-in DrugSyn combination split.time: pair-loader API requiring time_column; the verified built-in case is
BindingDB_Patent with its Year column. The API spelling is time, not
temporal.Do not use undocumented cold_drug_target, temporal, or stratified=True
examples. For every split, record PyTDC version, parameters, row counts, and exact
entity overlap audits. PyTDC 1.1.15's random splitter uses the supplied seed for
test sampling but a fixed random_state=1 for validation sampling; do not describe
all partitions as independently varying with the seed.
Detailed semantics and caveats are in references/utilities.md.
Use exact names from the installed evaluator registry:
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 is the registered Pearson-correlation name; Pearson is not. Multi-class
registry names are micro-f1, macro-f1, and kappa. Thresholded binary metrics
default to 0.5. Metric direction and input shape are metric-specific; use the
official task/benchmark metric rather than choosing from task type alone.
Use specialized classes. Top-level from tdc import BenchmarkGroup is retained
only as a deprecated compatibility path in 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",
)
For one run, group.evaluate({name: test_predictions}) returns metric results.
For leaderboard aggregation, pass a list of at least five prediction
dictionaries to group.evaluate_many(...). Do not index group.get(...) by
seed, and do not derive dummy predictions from test labels.
Use scripts/benchmark_evaluation.py to validate a bounded JSON prediction plan
before any group download. See references/utilities.md
for the exact JSON shape and API behavior.
PyTDC supplies molecule corpora, evaluators, and oracles; it does not train or provide a generic molecule generator in the core workflow. Discover current names:
uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
python scripts/discover_metadata.py --kind oracles --limit 100
Plan bounded local QED scoring:
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
Add --execute only after review. LogP and SA call the downloadable fpscores
artifact in 1.1.15; they and DRD2/GSK3B/JNK3/CYP3A4_Veith also require
--download. The helper intentionally refuses remote services, docking,
distribution, and composite oracles. It preserves input order and never assumes
score direction.
Read references/oracles.md before any oracle call.
scripts/discover_metadata.py — download-free package registry discoveryscripts/load_and_split_data.py — task-aware split plan/explicit executionscripts/benchmark_evaluation.py — prediction validation and explicit evaluationscripts/molecular_generation.py — bounded local/checkpoint scoring and MolGen planscripts/cache_audit.py — read-only bounded cache manifestEvery CLI uses lazy optional imports, safe relative output/cache paths, JSON summaries, bounded output, and no implicit dataset/model download.