Claude Skill

alterlab-pytdc

Loads Therapeutics Data Commons (TDC, PyTDC) AI-ready drug-discovery datasets and benchmarks — ADME, toxicity, drug-target interaction (DTI), scaffold splits, and molecular oracles for therapeutic ML and pharmacological prediction. Use when fetching a standardized benchmark datas

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download AlterLab-IEU-AlterLab-Academic-Skills-skills_cheminformatics_alterlab-pytdc-3ab6d03.zip · 28 KB

Install

skills CLI npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/cheminformatics/alterlab-pytdc
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
Git git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

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

Does NOT Trigger

Scenario Use Instead
Featurizing the loaded molecules and training/evaluating models alterlab-deepchem (models) or alterlab-molfeat (features)
Pulling raw bioactivity records (IC50/Ki) for a target beyond TDC's curated sets alterlab-chembl
Measured binding affinities for a protein target alterlab-bindingdb
Querying the PrimeKG knowledge graph itself (drug–disease paths) alterlab-primekg

Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-deepchem) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.

Installation & Setup

Give PyTDC its own virtual environment:

uv venv --python 3.12        # PyTDC 1.1.15 resolves on Python 3.10-3.12, not 3.13
uv pip install PyTDC         # 1.1.15 is the latest release (Mar 2025)

PyTDC 1.1.15 hard-pins an older stack — numpy<2, pandas<3, rdkit<2024.3.1, transformers<4.51, datasets<2.20 — and pulls heavy extras such as cellxgene-census and tiledbsoma, so it cannot share an environment with current RDKit 2026.x, numpy 2.x, pandas 3.x, or transformers 5.x. Export the splits to CSV/Parquet and featurize/train in a separate environment if you need newer libraries.

Quick Start

The basic pattern for accessing any TDC dataset follows this structure:

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:

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.

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.

from tdc.single_pred import Tox
data = Tox(name='hERG')  # Cardiotoxicity
# Other datasets: AMES, DILI, Carcinogens_Lagunin, etc.

Common toxicity datasets:

  • hERG - Cardiac toxicity
  • AMES - Mutagenicity
  • DILI - Drug-induced liver injury
  • Carcinogens - Carcinogenicity
  • ClinTox - Clinical trial toxicity

3. HTS (High-Throughput Screening)

Bioactivity predictions from screening data.

from tdc.single_pred import HTS
data = HTS(name='SARSCoV2_Vitro_Touret')

4. QM (Quantum Mechanics)

Quantum mechanical properties of molecules.

from tdc.single_pred import QM
data = QM(name='QM7')

5. Other Single Prediction Tasks

  • Yields: Chemical reaction yield prediction
  • Epitope: Epitope prediction for biologics
  • Develop: Development-stage predictions
  • CRISPROutcome: Gene editing outcome prediction

Data Format

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)

Multi-Instance Prediction Tasks

Multi-instance prediction involves forecasting properties of interactions between multiple biomedical entities.

Available Task Categories

1. DTI (Drug-Target Interaction)

Predict binding affinity between drugs and protein targets.

from tdc.multi_pred import DTI
data = DTI(name='BindingDB_Kd')
split = data.get_split()
# Cold-drug split (test set has only unseen drugs):
cold = data.get_split(method='cold_split', column_name='Drug')

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.

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.multi_pred import PPI
data = PPI(name='HuRI')

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.

from tdc.generation import MolGen
data = MolGen(name='ChEMBL_V29')
split = data.get_split()

Use with oracles to optimize for specific properties:

from tdc import Oracle
oracle = Oracle(name='GSK3B')
score = oracle('CC(C)Cc1ccc(cc1)C(C)C(O)=O')  # Evaluate SMILES

See references/oracles.md for all available oracle functions.

2. Retrosynthesis (RetroSyn)

Predict reactants needed to synthesize a target molecule.

from tdc.generation import RetroSyn
data = RetroSyn(name='USPTO')
split = data.get_split()

Dataset contains 1,939,253 reactions from USPTO database.

3. Paired Molecule Generation

Generate molecule pairs (e.g., prodrug-drug pairs).

from tdc.generation import PairMolGen
data = PairMolGen(name='Prodrug')

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

from tdc.benchmark_group import admet_group
group = admet_group(path='data/')

predictions_list = []
for seed in [1, 2, 3, 4, 5]:
    benchmark = group.get('Caco2_Wang')
    name = benchmark['name']
    # train_val is split into train/valid per seed; test is FIXED across seeds.
    train_val, test = benchmark['train_val'], benchmark['test']
    train, valid = group.get_train_valid_split(
        benchmark=name, split_type='default', seed=seed
    )
    # Train model here, then predict on `test`
    predictions = {name: model.predict(test)}  # dict keyed by benchmark name
    predictions_list.append(predictions)

# Evaluate across the 5 seeds → {'caco2_wang': [mean, std]}
results = group.evaluate_many(predictions_list)

Note the structure: group.get(name) returns a dict with keys name, train_val, test (NOT one keyed by seed). The per-seed train/valid split comes from group.get_train_valid_split(...); the test set is held fixed. Each seed's predictions go into a dict keyed by the benchmark name; collect those dicts in a list and pass to group.evaluate_many(...). (Use group.evaluate(predictions) only for a single-seed submission dict.)

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:

# Scaffold split (default for most tasks)
split = data.get_split(method='scaffold', seed=1, frac=[0.7, 0.1, 0.2])

# Random split
split = data.get_split(method='random', seed=42, frac=[0.8, 0.1, 0.1])

# Cold split (for DTI/DDI tasks) — pick the held-out entity via column_name
split = data.get_split(method='cold_split', column_name='Drug', seed=1)    # Unseen drugs in test
split = data.get_split(method='cold_split', column_name='Target', seed=1)  # Unseen targets in test
# Pass a list to hold out multiple entities: column_name=['Drug', 'Target']

Available split strategies:

  • random: Random shuffling
  • scaffold: Scaffold-based (Bemis-Murcko, for chemical diversity)
  • cold_split: For DTI/DDI tasks — set column_name to the entity ('Drug', 'Target', or a list) you want unseen in test
  • combination: For drug-combination datasets

2. Model Evaluation

Use standardized metrics for evaluation:

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:

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:

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'])

For complete oracle documentation, see references/oracles.md.

Advanced Features

Retrieve Available Datasets

from tdc.utils import retrieve_dataset_names

# Get all ADME datasets
adme_datasets = retrieve_dataset_names('ADME')

# Get all DTI datasets
dti_datasets = retrieve_dataset_names('DTI')

Label Transformations

from tdc.utils import get_label_map
label_map = get_label_map(name='DrugBank', task='DDI')

# Unit/log conversion is done via methods ON the dataset object, not a standalone import:
data = DTI(name='DAVIS')
data.convert_to_log(form='binding')   # e.g. Kd (nM) -> pKd; convert_from_log() reverses it

Database Queries

from tdc.utils import cid2smiles, uniprot2seq

# Convert PubChem CID to SMILES
smiles = cid2smiles(2244)

# Convert UniProt ID to amino acid sequence
sequence = uniprot2seq('P12345')

Common Workflows

Workflow 1: Train a Single Prediction Model

See scripts/load_and_split_data.py for a complete example:

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'])

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

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:

scripts/

  • 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

references/

  • 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

Additional Resources

Part of the AlterLab Academic Skills suite.

Files (alterlab-academic-skills)
  • evals
    • evals.json 4.1 KB
      Loading…
  • references
    • datasets.md 8.6 KB
      Loading…
    • oracles.md 9.8 KB
      Loading…
    • utilities.md 15.4 KB
      Loading…
  • scripts
    • benchmark_evaluation.py 9.9 KB
      Loading…
    • load_and_split_data.py 6.2 KB
      Loading…
    • molecular_generation.py 11.1 KB
      Loading…
  • SKILL.md 15.6 KB
    ---
    name: alterlab-pytdc
    description: Loads Therapeutics Data Commons (TDC, PyTDC) AI-ready drug-discovery datasets and benchmarks — ADME, toxicity, drug-target interaction (DTI), scaffold splits, and molecular oracles for therapeutic ML and pharmacological prediction. Use when fetching a standardized benchmark dataset, applying scaffold or cold-split evaluation, or sourcing labeled molecules for ADMET, toxicity, or DTI modeling. Sources data, splits, and oracles only — defer molecular featurization (ECFP/fingerprints), model training, and transformers to alterlab-deepchem or alterlab-molfeat. Part of the AlterLab Academic Skills suite.
    license: MIT
    allowed-tools: Read Write Edit Bash(python:*) Bash(uv:*)
    compatibility: "Self-contained, no API key or account. PyTDC 1.1.15 needs its own environment on Python 3.10-3.12 (pins numpy<2, pandas<3, rdkit<2024.3.1, transformers<4.51); datasets download from the TDC servers on first use."
    metadata:
        skill-author: AlterLab
        version: "1.0.1"
        last_updated: "2026-09-23"
    ---
    
    # 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
    
    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
    
    ### Does NOT Trigger
    
    | Scenario | Use Instead |
    |----------|-------------|
    | Featurizing the loaded molecules and training/evaluating models | `alterlab-deepchem` (models) or `alterlab-molfeat` (features) |
    | Pulling raw bioactivity records (IC50/Ki) for a target beyond TDC's curated sets | `alterlab-chembl` |
    | Measured binding affinities for a protein target | `alterlab-bindingdb` |
    | Querying the PrimeKG knowledge graph itself (drug–disease paths) | `alterlab-primekg` |
    
    **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-deepchem`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
    
    ## Installation & Setup
    
    Give PyTDC its own virtual environment:
    
    ```bash
    uv venv --python 3.12        # PyTDC 1.1.15 resolves on Python 3.10-3.12, not 3.13
    uv pip install PyTDC         # 1.1.15 is the latest release (Mar 2025)
    ```
    
    PyTDC 1.1.15 hard-pins an older stack — `numpy<2`, `pandas<3`, `rdkit<2024.3.1`, `transformers<4.51`, `datasets<2.20` — and pulls heavy extras such as `cellxgene-census` and `tiledbsoma`, so it cannot share an environment with current RDKit 2026.x, numpy 2.x, pandas 3.x, or transformers 5.x. Export the splits to CSV/Parquet and featurize/train in a separate environment if you need newer libraries.
    
    ## 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.
    ```
    
    **Common toxicity datasets:**
    - hERG - Cardiac toxicity
    - AMES - Mutagenicity
    - DILI - Drug-induced liver injury
    - Carcinogens - Carcinogenicity
    - ClinTox - Clinical trial toxicity
    
    #### 3. HTS (High-Throughput Screening)
    
    Bioactivity predictions from screening data.
    
    ```python
    from tdc.single_pred import HTS
    data = HTS(name='SARSCoV2_Vitro_Touret')
    ```
    
    #### 4. QM (Quantum Mechanics)
    
    Quantum mechanical properties of molecules.
    
    ```python
    from tdc.single_pred import QM
    data = QM(name='QM7')
    ```
    
    #### 5. Other Single Prediction Tasks
    
    - **Yields**: Chemical reaction yield prediction
    - **Epitope**: Epitope prediction for biologics
    - **Develop**: Development-stage predictions
    - **CRISPROutcome**: Gene editing outcome prediction
    
    ### Data Format
    
    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)
    
    ## Multi-Instance Prediction Tasks
    
    Multi-instance prediction involves forecasting properties of interactions between multiple biomedical entities.
    
    ### Available Task Categories
    
    #### 1. DTI (Drug-Target Interaction)
    
    Predict binding affinity between drugs and protein targets.
    
    ```python
    from tdc.multi_pred import DTI
    data = DTI(name='BindingDB_Kd')
    split = data.get_split()
    # Cold-drug split (test set has only unseen drugs):
    cold = data.get_split(method='cold_split', column_name='Drug')
    ```
    
    **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.
    
    ```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.
    
    ```python
    from tdc.multi_pred import PPI
    data = PPI(name='HuRI')
    ```
    
    #### 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.
    
    ```python
    from tdc.generation import MolGen
    data = MolGen(name='ChEMBL_V29')
    split = data.get_split()
    ```
    
    Use with oracles to optimize for specific properties:
    
    ```python
    from tdc import Oracle
    oracle = Oracle(name='GSK3B')
    score = oracle('CC(C)Cc1ccc(cc1)C(C)C(O)=O')  # Evaluate SMILES
    ```
    
    See `references/oracles.md` for all available oracle functions.
    
    ### 2. Retrosynthesis (RetroSyn)
    
    Predict reactants needed to synthesize a target molecule.
    
    ```python
    from tdc.generation import RetroSyn
    data = RetroSyn(name='USPTO')
    split = data.get_split()
    ```
    
    Dataset contains 1,939,253 reactions from USPTO database.
    
    ### 3. Paired Molecule Generation
    
    Generate molecule pairs (e.g., prodrug-drug pairs).
    
    ```python
    from tdc.generation import PairMolGen
    data = PairMolGen(name='Prodrug')
    ```
    
    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
    
    ```python
    from tdc.benchmark_group import admet_group
    group = admet_group(path='data/')
    
    predictions_list = []
    for seed in [1, 2, 3, 4, 5]:
        benchmark = group.get('Caco2_Wang')
        name = benchmark['name']
        # train_val is split into train/valid per seed; test is FIXED across seeds.
        train_val, test = benchmark['train_val'], benchmark['test']
        train, valid = group.get_train_valid_split(
            benchmark=name, split_type='default', seed=seed
        )
        # Train model here, then predict on `test`
        predictions = {name: model.predict(test)}  # dict keyed by benchmark name
        predictions_list.append(predictions)
    
    # Evaluate across the 5 seeds → {'caco2_wang': [mean, std]}
    results = group.evaluate_many(predictions_list)
    ```
    
    Note the structure: `group.get(name)` returns a dict with keys `name`, `train_val`, `test` (NOT one keyed by seed). The per-seed train/valid split comes from `group.get_train_valid_split(...)`; the `test` set is held fixed. Each seed's predictions go into a dict keyed by the benchmark name; collect those dicts in a list and pass to `group.evaluate_many(...)`. (Use `group.evaluate(predictions)` only for a single-seed submission dict.)
    
    **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:
    
    ```python
    # Scaffold split (default for most tasks)
    split = data.get_split(method='scaffold', seed=1, frac=[0.7, 0.1, 0.2])
    
    # Random split
    split = data.get_split(method='random', seed=42, frac=[0.8, 0.1, 0.1])
    
    # Cold split (for DTI/DDI tasks) — pick the held-out entity via column_name
    split = data.get_split(method='cold_split', column_name='Drug', seed=1)    # Unseen drugs in test
    split = data.get_split(method='cold_split', column_name='Target', seed=1)  # Unseen targets in test
    # Pass a list to hold out multiple entities: column_name=['Drug', 'Target']
    ```
    
    **Available split strategies:**
    - `random`: Random shuffling
    - `scaffold`: Scaffold-based (Bemis-Murcko, for chemical diversity)
    - `cold_split`: For DTI/DDI tasks — set `column_name` to the entity (`'Drug'`, `'Target'`, or a list) you want unseen in test
    - `combination`: For drug-combination datasets
    
    ### 2. Model Evaluation
    
    Use standardized metrics for evaluation:
    
    ```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'])
    ```
    
    For complete oracle documentation, see `references/oracles.md`.
    
    ## Advanced Features
    
    ### Retrieve Available Datasets
    
    ```python
    from tdc.utils import retrieve_dataset_names
    
    # Get all ADME datasets
    adme_datasets = retrieve_dataset_names('ADME')
    
    # Get all DTI datasets
    dti_datasets = retrieve_dataset_names('DTI')
    ```
    
    ### Label Transformations
    
    ```python
    from tdc.utils import get_label_map
    label_map = get_label_map(name='DrugBank', task='DDI')
    
    # Unit/log conversion is done via methods ON the dataset object, not a standalone import:
    data = DTI(name='DAVIS')
    data.convert_to_log(form='binding')   # e.g. Kd (nM) -> pKd; convert_from_log() reverses it
    ```
    
    ### Database Queries
    
    ```python
    from tdc.utils import cid2smiles, uniprot2seq
    
    # Convert PubChem CID to SMILES
    smiles = cid2smiles(2244)
    
    # Convert UniProt ID to amino acid sequence
    sequence = uniprot2seq('P12345')
    ```
    
    ## 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'])
    
    # Evaluate
    evaluator = Evaluator(name='MAE')
    # score = evaluator(test['Y'], predictions)
    ```
    
    ### 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:
    
    ### scripts/
    
    - `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
    
    ### references/
    
    - `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
    
    ## Additional Resources
    
    - **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"
    
    Part of the AlterLab Academic Skills suite.
    
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.