pytdc · diff
git:20260611.1b8fae3 to v1.1
210 added, 370 removed. Audit A to A.
---
name: pytdc
- description: Therapeutics Data Commons. AI-ready drug discovery datasets (ADME, toxicity, DTI), benchmarks, scaffold splits, molecular oracles, for therapeutic ML and pharmacological prediction.
- license: MIT license
- metadata: {"version": "1.0", "skill-author": "K-Dense Inc."}
+ description: Use Therapeutics Data Commons through the PyTDC Python package for registry discovery, approved dataset access, task-aware splits, evaluator metrics, benchmark groups, and bounded molecular-oracle workflows.
+ license: MIT
+ allowed-tools: Read, Write, Edit, Bash
+ compatibility: Requires uv, CPython 3.11, PyTDC 1.1.15, and setuptools 80.9.0 for its legacy pkg_resources runtime import. Dataset, benchmark, checkpoint, and remote-oracle operations require network/storage review and explicit user approval.
+ metadata:
+ version: "1.1"
+ skill-author: K-Dense Inc.
---
# PyTDC (Therapeutics Data Commons)
- ## Overview
-
- PyTDC is an open-science platform providing AI-ready datasets and benchmarks for drug discovery and development. Access curated datasets spanning the entire therapeutics pipeline with standardized evaluation metrics and meaningful data splits, organized into three categories: single-instance prediction (molecular/protein properties), multi-instance prediction (drug-target interactions, DDI), and generation (molecule generation, retrosynthesis).
-
- ## When to Use This Skill
+ 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.
- This skill should be used when:
- - Working with drug discovery or therapeutic ML datasets
- - Benchmarking machine learning models on standardized pharmaceutical tasks
- - Predicting molecular properties (ADME, toxicity, bioactivity)
- - Predicting drug-target or drug-drug interactions
- - Generating novel molecules with desired properties
- - Accessing curated datasets with proper train/test splits (scaffold, cold-split)
- - Using molecular oracles for property optimization
+ ## Verified snapshot
- ## Installation & Setup
+ - Research date: **2026-07-23**
+ - PyPI stable: **PyTDC 1.1.15**, released 2025-03-31
+ - Package/source repository: `mims-harvard/TDC`
+ - Code license: MIT
+ - PyPI supplies only a source distribution and declares no `Requires-Python`
+ - The dependency graph makes **CPython 3.11** the reproducible target used here:
+ `cellxgene-census==1.15.0` excludes Python 3.12, and PyTDC's constrained
+ RDKit release has no CPython 3.13 wheel
+ - PyTDC imports deprecated `pkg_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 evidence
+ - Upstream publishes no GitHub tags/releases or maintained changelog. Treat
+ undocumented migration claims as uncertainty and verify against the installed
+ 1.1.15 source/metadata.
- Install PyTDC using pip:
+ See [references/sources.md](references/sources.md) for dated evidence and known
+ documentation conflicts.
- ```bash
- uv pip install PyTDC
- ```
+ ## Installation
- To upgrade to the latest version:
+ Use an isolated CPython 3.11 environment and pin the reviewed snapshot:
```bash
- uv pip install PyTDC --upgrade
- ```
-
- Core dependencies (automatically installed):
- - numpy, pandas, tqdm, seaborn, scikit_learn, fuzzywuzzy
-
- Additional packages are installed automatically as needed for specific features.
-
- ## Quick Start
-
- The basic pattern for accessing any TDC dataset follows this structure:
-
- ```python
- from tdc.<problem> import <Task>
- data = <Task>(name='<Dataset>')
- split = data.get_split(method='scaffold', seed=1, frac=[0.7, 0.1, 0.2])
- df = data.get_data(format='df')
- ```
-
- Where:
- - `<problem>`: One of `single_pred`, `multi_pred`, or `generation`
- - `<Task>`: Specific task category (e.g., ADME, DTI, MolGen)
- - `<Dataset>`: Dataset name within that task
-
- **Example - Loading ADME data:**
-
- ```python
- from tdc.single_pred import ADME
- data = ADME(name='Caco2_Wang')
- split = data.get_split(method='scaffold')
- # Returns dict with 'train', 'valid', 'test' DataFrames
- ```
-
- ## Single-Instance Prediction Tasks
-
- Single-instance prediction involves forecasting properties of individual biomedical entities (molecules, proteins, etc.).
-
- ### Available Task Categories
-
- #### 1. ADME (Absorption, Distribution, Metabolism, Excretion)
-
- Predict pharmacokinetic properties of drug molecules.
-
- ```python
- from tdc.single_pred import ADME
- data = ADME(name='Caco2_Wang') # Intestinal permeability
- # Other datasets: HIA_Hou, Bioavailability_Ma, Lipophilicity_AstraZeneca, etc.
- ```
-
- **Common ADME datasets:**
- - Caco2 - Intestinal permeability
- - HIA - Human intestinal absorption
- - Bioavailability - Oral bioavailability
- - Lipophilicity - Octanol-water partition coefficient
- - Solubility - Aqueous solubility
- - BBB - Blood-brain barrier penetration
- - CYP - Cytochrome P450 metabolism
-
- #### 2. Toxicity (Tox)
-
- Predict toxicity and adverse effects of compounds.
-
- ```python
- from tdc.single_pred import Tox
- data = Tox(name='hERG') # Cardiotoxicity
- # Other datasets: AMES, DILI, Carcinogens_Lagunin, etc.
+ 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"
```
- **Common toxicity datasets:**
- - hERG - Cardiac toxicity
- - AMES - Mutagenicity
- - DILI - Drug-induced liver injury
- - Carcinogens - Carcinogenicity
- - ClinTox - Clinical trial toxicity
-
- #### 3. HTS (High-Throughput Screening)
+ 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.
- Bioactivity predictions from screening data.
+ For an ephemeral command:
- ```python
- from tdc.single_pred import HTS
- data = HTS(name='SARSCoV2_Vitro_Touret')
+ ```bash
+ uv run --python 3.11 \
+ --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
+ python scripts/discover_metadata.py --kind tasks
```
- #### 4. QM (Quantum Mechanics)
-
- Quantum mechanical properties of molecules.
-
- ```python
- from tdc.single_pred import QM
- data = QM(name='QM7')
- ```
+ 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.
- #### 5. Other Single Prediction Tasks
+ ## Non-negotiable data and network policy
- - **Yields**: Chemical reaction yield prediction
- - **Epitope**: Epitope prediction for biologics
- - **Develop**: Development-stage predictions
- - **CRISPROutcome**: Gene editing outcome prediction
+ 1. **Discover first.** Reading `tdc.metadata` or using
+ `scripts/discover_metadata.py` does not instantiate a loader or download data.
+ 2. **Plan second.** Record the exact task/dataset, official task page, license,
+ expected size, cache directory, split, metric, and reproducibility seed.
+ 3. **Ask the user before downloading.** Loader constructors fetch missing data.
+ Some datasets and benchmark-group archives are large; model-backed oracles can
+ fetch checkpoints; remote/docking oracles can transmit molecular structures.
+ 4. **Execute only after approval.** In bundled CLIs, `--execute` acknowledges
+ execution and `--download` is additionally required for MolGen corpora or
+ supported oracle checkpoints.
+ 5. **Keep outputs bounded.** Emit counts, schema, and small previews rather than
+ full datasets, sequences, prediction arrays, or molecule corpora.
- ### Data Format
+ ### Cache and cost behavior
- Single prediction datasets typically return DataFrames with columns:
- - `Drug_ID` or `Compound_ID`: Unique identifier
- - `Drug` or `X`: SMILES string or molecular representation
- - `Y`: Target label (continuous or binary)
+ - Ordinary loaders default to `path="./data"` and save files beneath that path.
+ The bundled scripts instead default to explicit `.pytdc-*` directories.
+ - Core downloads use Harvard Dataverse file endpoints when a local filename is
+ absent. Newer resource classes may use other upstream services.
+ - `admet_group(path=...)` and other benchmark-group constructors download and
+ extract the group archive when `<path>/<group>` is absent.
+ - Download-backed `Oracle(...)` construction uses `./oracle` internally. The
+ bundled oracle CLI changes into a safe runtime directory before approved calls.
+ - PyTDC 1.1.15 does not provide a universal cache quota, eviction policy, or
+ dataset-wide checksum manifest. Use `scripts/cache_audit.py` and manage disk
+ retention explicitly.
+ - Network transfer, local storage, decompression, parsing, feature generation,
+ docking, and external service calls can all incur time or monetary cost.
- ## Multi-Instance Prediction Tasks
+ 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.
- Multi-instance prediction involves forecasting properties of interactions between multiple biomedical entities.
+ ## Start with metadata-only discovery
- ### Available Task Categories
+ From this skill directory:
- #### 1. DTI (Drug-Target Interaction)
+ ```bash
+ 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
- Predict binding affinity between drugs and protein targets.
+ uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
+ python scripts/discover_metadata.py --kind benchmarks --limit 50
- ```python
- from tdc.multi_pred import DTI
- data = DTI(name='BindingDB_Kd')
- split = data.get_split()
+ uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
+ python scripts/discover_metadata.py --kind evaluators --limit 100
```
- **Available datasets:**
- - BindingDB_Kd - Dissociation constant (52,284 pairs)
- - BindingDB_IC50 - Half-maximal inhibitory concentration (991,486 pairs)
- - BindingDB_Ki - Inhibition constant (375,032 pairs)
- - DAVIS, KIBA - Kinase binding datasets
-
- **Data format:** Drug_ID, Target_ID, Drug (SMILES), Target (sequence), Y (binding affinity)
-
- #### 2. DDI (Drug-Drug Interaction)
-
- Predict interactions between drug pairs.
+ The package API is also metadata-only:
```python
- from tdc.multi_pred import DDI
- data = DDI(name='DrugBank')
- split = data.get_split()
- ```
-
- Multi-class classification task predicting interaction types. Dataset contains 191,808 DDI pairs with 1,706 drugs.
-
- #### 3. PPI (Protein-Protein Interaction)
-
- Predict protein-protein interactions.
+ from tdc.utils import retrieve_dataset_names, retrieve_benchmark_names
- ```python
- from tdc.multi_pred import PPI
- data = PPI(name='HuRI')
+ adme_names = retrieve_dataset_names("ADME")
+ admet_benchmarks = retrieve_benchmark_names("admet_group")
```
- #### 4. Other Multi-Prediction Tasks
-
- - **GDA**: Gene-disease associations
- - **DrugRes**: Drug resistance prediction
- - **DrugSyn**: Drug synergy prediction
- - **PeptideMHC**: Peptide-MHC binding
- - **AntibodyAff**: Antibody affinity prediction
- - **MTI**: miRNA-target interactions
- - **Catalyst**: Catalyst prediction
- - **TrialOutcome**: Clinical trial outcome prediction
-
- ## Generation Tasks
-
- Generation tasks involve creating novel biomedical entities with desired properties.
-
- ### 1. Molecular Generation (MolGen)
-
- Generate diverse, novel molecules with desirable chemical properties.
+ Use exact returned names. PyTDC performs fuzzy matching internally, but explicit
+ matching avoids silently selecting the wrong dataset/oracle.
- ```python
- from tdc.generation import MolGen
- data = MolGen(name='ChEMBL_V29')
- split = data.get_split()
- ```
+ ## Dataset workflow
- Use with oracles to optimize for specific properties:
+ Plan a split without downloading:
- ```python
- from tdc import Oracle
- oracle = Oracle(name='GSK3B')
- score = oracle('CC(C)Cc1ccc(cc1)C(C)C(O)=O') # Evaluate SMILES
+ ```bash
+ 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
```
- See `references/oracles.md` for all available oracle functions.
-
- ### 2. Retrosynthesis (RetroSyn)
-
- Predict reactants needed to synthesize a target molecule.
+ After the user approves the dataset, license, transfer, and storage:
- ```python
- from tdc.generation import RetroSyn
- data = RetroSyn(name='USPTO')
- split = data.get_split()
+ ```bash
+ 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
```
- Dataset contains 1,939,253 reactions from USPTO database.
-
- ### 3. Paired Molecule Generation
-
- Generate molecule pairs (e.g., prodrug-drug pairs).
+ Verified public import patterns include:
```python
- from tdc.generation import PairMolGen
- data = PairMolGen(name='Prodrug')
+ from tdc.single_pred import ADME, Tox
+ from tdc.multi_pred import DDI, DTI
+ from tdc.generation import MolGen, Reaction, RetroSyn
```
- For detailed oracle documentation and molecular generation workflows, refer to `references/oracles.md` and `scripts/molecular_generation.py`.
-
- ## Benchmark Groups
-
- Benchmark groups provide curated collections of related datasets for systematic model evaluation.
-
- ### ADMET Benchmark Group
+ Constructors perform data access, so do not run them before approval:
```python
- from tdc.benchmark_group import admet_group
- group = admet_group(path='data/')
-
- # Get benchmark datasets
- benchmark = group.get('Caco2_Wang')
- predictions = {}
-
- for seed in [1, 2, 3, 4, 5]:
- train, valid = benchmark['train'], benchmark['valid']
- # Train model here
- predictions[seed] = model.predict(benchmark['test'])
-
- # Evaluate with required 5 seeds
- results = group.evaluate(predictions)
+ 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
```
- **ADMET Group includes 22 datasets** covering absorption, distribution, metabolism, excretion, and toxicity.
-
- ### Other Benchmark Groups
-
- Available benchmark groups include collections for:
- - ADMET properties
- - Drug-target interactions
- - Drug combination prediction
- - And more specialized therapeutic tasks
-
- For benchmark evaluation workflows, see `scripts/benchmark_evaluation.py`.
-
- ## Data Functions
-
- TDC provides comprehensive data processing utilities organized into four categories.
-
- ### 1. Dataset Splits
-
- Retrieve train/validation/test partitions with various strategies:
+ Read [references/datasets.md](references/datasets.md) before choosing a task or
+ dataset.
- ```python
- # Scaffold split (default for most tasks)
- split = data.get_split(method='scaffold', seed=1, frac=[0.7, 0.1, 0.2])
+ ## Split selection without overclaiming leakage control
- # Random split
- split = data.get_split(method='random', seed=42, frac=[0.8, 0.1, 0.1])
+ - `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`.
- # Cold split (for DTI/DDI tasks)
- split = data.get_split(method='cold_drug', seed=1) # Unseen drugs in test
- split = data.get_split(method='cold_target', seed=1) # Unseen targets in test
- ```
+ 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.
- **Available split strategies:**
- - `random`: Random shuffling
- - `scaffold`: Scaffold-based (for chemical diversity)
- - `cold_drug`, `cold_target`, `cold_drug_target`: For DTI tasks
- - `temporal`: Time-based splits for temporal datasets
+ Detailed semantics and caveats are in
+ [references/utilities.md](references/utilities.md).
- ### 2. Model Evaluation
+ ## Evaluators
- Use standardized metrics for evaluation:
+ Use exact names from the installed evaluator registry:
```python
from tdc import Evaluator
- # For binary classification
- evaluator = Evaluator(name='ROC-AUC')
- score = evaluator(y_true, y_pred)
-
- # For regression
- evaluator = Evaluator(name='RMSE')
- score = evaluator(y_true, y_pred)
- ```
-
- **Available metrics:** ROC-AUC, PR-AUC, F1, Accuracy, RMSE, MAE, R2, Spearman, Pearson, and more.
-
- ### 3. Data Processing
-
- TDC provides 11 key processing utilities:
-
- ```python
- from tdc.chem_utils import MolConvert
-
- # Molecule format conversion
- converter = MolConvert(src='SMILES', dst='PyG')
- pyg_graph = converter('CC(C)Cc1ccc(cc1)C(C)C(O)=O')
- ```
-
- **Processing utilities include:**
- - Molecule format conversion (SMILES, SELFIES, PyG, DGL, ECFP, etc.)
- - Molecule filters (PAINS, drug-likeness)
- - Label binarization and unit conversion
- - Data balancing (over/under-sampling)
- - Negative sampling for pair data
- - Graph transformation
- - Entity retrieval (CID to SMILES, UniProt to sequence)
-
- For comprehensive utilities documentation, see `references/utilities.md`.
-
- ### 4. Molecule Generation Oracles
-
- TDC provides 17+ oracle functions for molecular optimization:
-
- ```python
- from tdc import Oracle
-
- # Single oracle
- oracle = Oracle(name='DRD2')
- score = oracle('CC(C)Cc1ccc(cc1)C(C)C(O)=O')
-
- # Multiple oracles
- oracle = Oracle(name='JNK3')
- scores = oracle(['SMILES1', 'SMILES2', 'SMILES3'])
+ 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)
```
- For complete oracle documentation, see `references/oracles.md`.
+ `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.
- ## Advanced Features
+ ## Benchmark groups
- ### Retrieve Available Datasets
+ Use specialized classes. Top-level `from tdc import BenchmarkGroup` is retained
+ only as a deprecated compatibility path in 1.1.15.
```python
- from tdc.utils import retrieve_dataset_names
-
- # Get all ADME datasets
- adme_datasets = retrieve_dataset_names('ADME')
+ from tdc.benchmark_group import admet_group
- # Get all DTI datasets
- dti_datasets = retrieve_dataset_names('DTI')
+ # 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",
+ )
```
- ### Label Transformations
-
- ```python
- # Get label mapping
- label_map = data.get_label_map(name='DrugBank')
-
- # Convert labels
- from tdc.chem_utils import label_transform
- transformed = label_transform(y, from_unit='nM', to_unit='p')
- ```
+ 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.
- ### Database Queries
+ Use `scripts/benchmark_evaluation.py` to validate a bounded JSON prediction plan
+ before any group download. See [references/utilities.md](references/utilities.md)
+ for the exact JSON shape and API behavior.
- ```python
- from tdc.utils import cid2smiles, uniprot2seq
+ ## Molecular generation and oracles
- # Convert PubChem CID to SMILES
- smiles = cid2smiles(2244)
+ PyTDC supplies molecule corpora, evaluators, and oracles; it does not train or
+ provide a generic molecule generator in the core workflow. Discover current names:
- # Convert UniProt ID to amino acid sequence
- sequence = uniprot2seq('P12345')
+ ```bash
+ uv run --python 3.11 --with "setuptools==80.9.0" --with "PyTDC==1.1.15" \
+ python scripts/discover_metadata.py --kind oracles --limit 100
```
- ## Common Workflows
-
- ### Workflow 1: Train a Single Prediction Model
-
- See `scripts/load_and_split_data.py` for a complete example:
-
- ```python
- from tdc.single_pred import ADME
- from tdc import Evaluator
-
- # Load data
- data = ADME(name='Caco2_Wang')
- split = data.get_split(method='scaffold', seed=42)
-
- train, valid, test = split['train'], split['valid'], split['test']
-
- # Train model (user implements)
- # model.fit(train['Drug'], train['Y'])
+ Plan bounded local QED scoring:
- # Evaluate
- evaluator = Evaluator(name='MAE')
- # score = evaluator(test['Y'], predictions)
+ ```bash
+ 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
```
- ### Workflow 2: Benchmark Evaluation
-
- See `scripts/benchmark_evaluation.py` for a complete example with multiple seeds and proper evaluation protocol.
-
- ### Workflow 3: Molecular Generation with Oracles
-
- See `scripts/molecular_generation.py` for an example of goal-directed generation using oracle functions.
-
- ## Resources
-
- This skill includes bundled resources for common TDC workflows:
+ 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.
- ### scripts/
+ Read [references/oracles.md](references/oracles.md) before any oracle call.
- - `load_and_split_data.py`: Template for loading and splitting TDC datasets with various strategies
- - `benchmark_evaluation.py`: Template for running benchmark group evaluations with proper 5-seed protocol
- - `molecular_generation.py`: Template for molecular generation using oracle functions
+ ## Bundled resources
- ### references/
+ ### Scripts
- - `datasets.md`: Comprehensive catalog of all available datasets organized by task type
- - `oracles.md`: Complete documentation of all 17+ molecule generation oracles
- - `utilities.md`: Detailed guide to data processing, splitting, and evaluation utilities
+ - `scripts/discover_metadata.py` — download-free package registry discovery
+ - `scripts/load_and_split_data.py` — task-aware split plan/explicit execution
+ - `scripts/benchmark_evaluation.py` — prediction validation and explicit evaluation
+ - `scripts/molecular_generation.py` — bounded local/checkpoint scoring and MolGen plan
+ - `scripts/cache_audit.py` — read-only bounded cache manifest
- ## Additional Resources
+ Every CLI uses lazy optional imports, safe relative output/cache paths, JSON
+ summaries, bounded output, and no implicit dataset/model download.
- - **Official Website**: https://tdcommons.ai
- - **Documentation**: https://tdc.readthedocs.io
- - **GitHub**: https://github.com/mims-harvard/TDC
- - **Paper**: NeurIPS 2021 - "Therapeutics Data Commons: Machine Learning Datasets and Tasks for Drug Discovery and Development"
+ ### References
+ - [references/datasets.md](references/datasets.md) — task discovery, data access,
+ cache behavior, and licensing
+ - [references/utilities.md](references/utilities.md) — splits, evaluators, and
+ benchmark-group APIs
+ - [references/oracles.md](references/oracles.md) — oracle categories, side effects,
+ and safe execution
+ - [references/sources.md](references/sources.md) — dated authoritative sources and
+ unresolved upstream gaps