273 lines
6.7 KiB
Markdown
273 lines
6.7 KiB
Markdown
# ChEMBL Web Services API Reference
|
|
|
|
## Overview
|
|
|
|
ChEMBL is a manually curated database of bioactive molecules with drug-like properties maintained by the European Bioinformatics Institute (EBI). It contains information about compounds, targets, assays, bioactivity data, and approved drugs.
|
|
|
|
The ChEMBL database contains:
|
|
- Over 2 million compound records
|
|
- Over 1.4 million assay records
|
|
- Over 19 million activity values
|
|
- Information on 13,000+ drug targets
|
|
- Data on 16,000+ approved drugs and clinical candidates
|
|
|
|
## Python Client Installation
|
|
|
|
```bash
|
|
pip install chembl_webresource_client
|
|
```
|
|
|
|
## Key Resources and Endpoints
|
|
|
|
ChEMBL provides access to 30+ specialized endpoints:
|
|
|
|
### Core Data Types
|
|
|
|
- **molecule** - Compound structures, properties, and synonyms
|
|
- **target** - Protein and non-protein biological targets
|
|
- **activity** - Bioassay measurement results
|
|
- **assay** - Experimental assay details
|
|
- **drug** - Approved pharmaceutical information
|
|
- **mechanism** - Drug mechanism of action data
|
|
- **document** - Literature sources and references
|
|
- **cell_line** - Cell line information
|
|
- **tissue** - Tissue types
|
|
- **protein_class** - Protein classification
|
|
- **target_component** - Target component details
|
|
- **compound_structural_alert** - Structural alerts for toxicity
|
|
|
|
## Query Patterns and Filters
|
|
|
|
### Filter Operators
|
|
|
|
The API supports Django-style filter operators:
|
|
|
|
- `__exact` - Exact match
|
|
- `__iexact` - Case-insensitive exact match
|
|
- `__contains` - Contains substring
|
|
- `__icontains` - Case-insensitive contains
|
|
- `__startswith` - Starts with prefix
|
|
- `__endswith` - Ends with suffix
|
|
- `__gt` - Greater than
|
|
- `__gte` - Greater than or equal
|
|
- `__lt` - Less than
|
|
- `__lte` - Less than or equal
|
|
- `__range` - Value in range
|
|
- `__in` - Value in list
|
|
- `__isnull` - Is null/not null
|
|
- `__regex` - Regular expression match
|
|
- `__search` - Full text search
|
|
|
|
### Example Filter Queries
|
|
|
|
**Molecular weight filtering:**
|
|
```python
|
|
molecules.filter(molecule_properties__mw_freebase__lte=300)
|
|
```
|
|
|
|
**Name pattern matching:**
|
|
```python
|
|
molecules.filter(pref_name__endswith='nib')
|
|
```
|
|
|
|
**Multiple conditions:**
|
|
```python
|
|
molecules.filter(
|
|
molecule_properties__mw_freebase__lte=300,
|
|
pref_name__endswith='nib'
|
|
)
|
|
```
|
|
|
|
## Chemical Structure Searches
|
|
|
|
### Substructure Search
|
|
Search for compounds containing a specific substructure using SMILES:
|
|
|
|
```python
|
|
from chembl_webresource_client.new_client import new_client
|
|
similarity = new_client.similarity
|
|
results = similarity.filter(smiles='CC(=O)Oc1ccccc1C(=O)O', similarity=70)
|
|
```
|
|
|
|
### Similarity Search
|
|
Find compounds similar to a query structure:
|
|
|
|
```python
|
|
similarity = new_client.similarity
|
|
results = similarity.filter(smiles='CC(=O)Oc1ccccc1C(=O)O', similarity=85)
|
|
```
|
|
|
|
## Common Data Retrieval Patterns
|
|
|
|
### Get Molecule by ChEMBL ID
|
|
```python
|
|
molecule = new_client.molecule.get('CHEMBL25')
|
|
```
|
|
|
|
### Get Target Information
|
|
```python
|
|
target = new_client.target.get('CHEMBL240')
|
|
```
|
|
|
|
### Get Activity Data
|
|
```python
|
|
activities = new_client.activity.filter(
|
|
target_chembl_id='CHEMBL240',
|
|
standard_type='IC50',
|
|
standard_value__lte=100
|
|
)
|
|
```
|
|
|
|
### Get Drug Information
|
|
```python
|
|
drug = new_client.drug.get('CHEMBL1234')
|
|
```
|
|
|
|
## Response Formats
|
|
|
|
The API supports multiple response formats:
|
|
- JSON (default)
|
|
- XML
|
|
- YAML
|
|
|
|
## Caching and Performance
|
|
|
|
The Python client automatically caches results locally:
|
|
- **Default cache duration**: 24 hours
|
|
- **Cache location**: Local file system
|
|
- **Lazy evaluation**: Queries execute only when data is accessed
|
|
|
|
### Configuration Settings
|
|
|
|
```python
|
|
from chembl_webresource_client.settings import Settings
|
|
|
|
# Disable caching
|
|
Settings.Instance().CACHING = False
|
|
|
|
# Adjust cache expiration (in seconds)
|
|
Settings.Instance().CACHE_EXPIRE = 86400 # 24 hours
|
|
|
|
# Set timeout
|
|
Settings.Instance().TIMEOUT = 30
|
|
|
|
# Set retries
|
|
Settings.Instance().TOTAL_RETRIES = 3
|
|
```
|
|
|
|
## Molecular Properties
|
|
|
|
Common molecular properties available:
|
|
|
|
- `mw_freebase` - Molecular weight
|
|
- `alogp` - Calculated LogP
|
|
- `hba` - Hydrogen bond acceptors
|
|
- `hbd` - Hydrogen bond donors
|
|
- `psa` - Polar surface area
|
|
- `rtb` - Rotatable bonds
|
|
- `ro3_pass` - Rule of 3 compliance
|
|
- `num_ro5_violations` - Lipinski rule of 5 violations
|
|
- `cx_most_apka` - Most acidic pKa
|
|
- `cx_most_bpka` - Most basic pKa
|
|
- `molecular_species` - Molecular species
|
|
- `full_mwt` - Full molecular weight
|
|
|
|
## Bioactivity Data Fields
|
|
|
|
Key bioactivity fields:
|
|
|
|
- `standard_type` - Activity type (IC50, Ki, Kd, EC50, etc.)
|
|
- `standard_value` - Numerical activity value
|
|
- `standard_units` - Units (nM, uM, etc.)
|
|
- `pchembl_value` - Normalized activity value (-log scale)
|
|
- `activity_comment` - Activity annotations
|
|
- `data_validity_comment` - Data validity flags
|
|
- `potential_duplicate` - Duplicate flag
|
|
|
|
## Target Information Fields
|
|
|
|
Target data includes:
|
|
|
|
- `target_chembl_id` - ChEMBL target identifier
|
|
- `pref_name` - Preferred target name
|
|
- `target_type` - Type (PROTEIN, ORGANISM, etc.)
|
|
- `organism` - Target organism
|
|
- `tax_id` - NCBI taxonomy ID
|
|
- `target_components` - Component details
|
|
|
|
## Advanced Query Examples
|
|
|
|
### Find Kinase Inhibitors
|
|
```python
|
|
# Get kinase targets
|
|
targets = new_client.target.filter(
|
|
target_type='SINGLE PROTEIN',
|
|
pref_name__icontains='kinase'
|
|
)
|
|
|
|
# Get activities for these targets
|
|
activities = new_client.activity.filter(
|
|
target_chembl_id__in=[t['target_chembl_id'] for t in targets],
|
|
standard_type='IC50',
|
|
standard_value__lte=100
|
|
)
|
|
```
|
|
|
|
### Retrieve Drug Mechanisms
|
|
```python
|
|
mechanisms = new_client.mechanism.filter(
|
|
molecule_chembl_id='CHEMBL25'
|
|
)
|
|
```
|
|
|
|
### Get Compound Bioactivities
|
|
```python
|
|
activities = new_client.activity.filter(
|
|
molecule_chembl_id='CHEMBL25',
|
|
pchembl_value__isnull=False
|
|
)
|
|
```
|
|
|
|
## Image Generation
|
|
|
|
ChEMBL can generate SVG images of molecular structures:
|
|
|
|
```python
|
|
from chembl_webresource_client.new_client import new_client
|
|
image = new_client.image
|
|
svg = image.get('CHEMBL25')
|
|
```
|
|
|
|
## Pagination
|
|
|
|
Results are paginated automatically. To iterate through all results:
|
|
|
|
```python
|
|
activities = new_client.activity.filter(target_chembl_id='CHEMBL240')
|
|
for activity in activities:
|
|
print(activity)
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
Common errors:
|
|
- **404**: Resource not found
|
|
- **503**: Service temporarily unavailable
|
|
- **Timeout**: Request took too long
|
|
|
|
The client automatically retries failed requests based on `TOTAL_RETRIES` setting.
|
|
|
|
## Rate Limiting
|
|
|
|
ChEMBL has fair usage policies:
|
|
- Be respectful with query frequency
|
|
- Use caching to minimize repeated requests
|
|
- Consider bulk downloads for large datasets
|
|
|
|
## Additional Resources
|
|
|
|
- Official API documentation: https://www.ebi.ac.uk/chembl/api/data/docs
|
|
- Python client GitHub: https://github.com/chembl/chembl_webresource_client
|
|
- ChEMBL interface docs: https://chembl.gitbook.io/chembl-interface-documentation/
|
|
- Example notebooks: https://github.com/chembl/notebooks
|