# 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 dataset, applying scaffold or cold-split evaluation, or sourcing labeled molecules for ADMET, toxicity, or DTI modeling. Sou…

- **Type:** Skill
- **Install:** `agentstack add skill-alterlab-ieu-alterlab-academic-skills-alterlab-pytdc`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AlterLab-IEU](https://agentstack.voostack.com/s/alterlab-ieu)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AlterLab-IEU](https://github.com/AlterLab-IEU)
- **Source:** https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/cheminformatics/alterlab-pytdc
- **Website:** https://alterlab-ieu.github.io/AlterLab-Academic-Skills/

## Install

```sh
agentstack add skill-alterlab-ieu-alterlab-academic-skills-alterlab-pytdc
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

## Installation & Setup

Install PyTDC using pip:

```bash
uv pip install PyTDC
```

To upgrade to the latest version:

```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. import 
data = (name='')
split = data.get_split(method='scaffold', seed=1, frac=[0.7, 0.1, 0.2])
df = data.get_data(format='df')
```

Where:
- ``: One of `single_pred`, `multi_pred`, or `generation`
- ``: Specific task category (e.g., ADME, DTI, MolGen)
- ``: 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"

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AlterLab-IEU](https://github.com/AlterLab-IEU)
- **Source:** [AlterLab-IEU/AlterLab-Academic-Skills](https://github.com/AlterLab-IEU/AlterLab-Academic-Skills)
- **License:** MIT
- **Homepage:** https://alterlab-ieu.github.io/AlterLab-Academic-Skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-alterlab-ieu-alterlab-academic-skills-alterlab-pytdc
- Seller: https://agentstack.voostack.com/s/alterlab-ieu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.