ChEMBL Webresource Client

The client provides a convenient interface for accessing ChEMBL data, abstracting away HTTPS and network-related tasks. It is designed around the Django QuerySet interface and features:

• Lazy Evaluation: Requests for data are only evaluated when a value is actually required, reducing unnecessary network requests.
• Caching: Results are cached in the local file system for faster retrieval.
• Django-like Interface: Supports common lookup types for filtering data.

Install the official ChEMBL Python client library using pip to access ChEMBL data and cheminformatics tools without needing to write SQL or interact directly with REST APIs.

pip install chembl_webresource_client

To modify client behavior, import the Settings singleton. You must import and configure settings before initializing or using the client.

Important Options:

• CACHING: Whether results should be cached locally (default: True).
• CACHE_EXPIRE: Cache expiry time in seconds (default: 24 hours).
• CACHE_NAME: Name of the .sqlite file used for the cache.
• TOTAL_RETRIES: Number of total retries per HTTP request (default: 3).
• CONCURRENT_SIZE: Total number of concurrent requests (default: 50).
• FAST_SAVE: Speeds up cache saving by up to 50x but carries a risk of data loss (default: True).

from chembl_webresource_client.settings import Settings

# Example: Set the request timeout
Settings.Instance().TIMEOUT = 10

You can retrieve molecule records using several different methods:

By preferred name:

mols = new_client.molecule.filter(pref_name__iexact='aspirin')

By synonyms:

mols = new_client.molecule.filter(molecule_synonyms__molecule_synonym__iexact='viagra').only('molecule_chembl_id')

By ChEMBL ID:

m1 = new_client.molecule.filter(chembl_id='CHEMBL192').only(['molecule_chembl_id', 'pref_name', 'molecule_structures'])

By a list of ChEMBL IDs:

mols = new_client.molecule.filter(molecule_chembl_id__in=['CHEMBL25', 'CHEMBL192', 'CHEMBL27']).only(['molecule_chembl_id', 'pref_name'])

By Standard InChI Key:

mol = new_client.molecule.filter(molecule_structures__standard_inchi_key='BSYNRYMUTXBXSQ-UHFFFAOYSA-N').only(['molecule_chembl_id', 'pref_name', 'molecule_structures'])

You can discover which data resources (entities) are available through the new_client by inspecting its attributes. This is useful for identifying available endpoints like molecule, target, activity, etc.

from chembl_webresource_client.new_client import new_client

available_resources = [resource for resource in dir(new_client) if not resource.startswith('_')]
print(available_resources)

You can link activities to specific targets or filter activities by type.

Get all IC50 activities for a specific target:

target = new_client.target.filter(pref_name__iexact='Voltage-gated inwardly rectifying potassium channel KCNH2').only('target_chembl_id')[0]
herg_activities = new_client.activity.filter(target_chembl_id=target['target_chembl_id']).filter(standard_type="IC50")

Get activities for a target with a specific assay type (e.g., 'B' for binding):

res = new_client.activity.filter(target_chembl_id='CHEMBL3938', assay_type='B')

Filter activities by pChEMBL value presence:

res = new_client.activity.filter(molecule_chembl_id="CHEMBL25", pchembl_value__isnull=False)

The only method allows you to limit the results to a specific set of fields. This improves performance by reducing bandwidth usage and allowing the API to optimize SQL joins.

Usage: Pass a single argument: a list of field names that exist in the endpoint.

Limitations:

• Nested Fields: only ignores nested fields. For example, only(['molecule_properties__alogp']) is treated as only(['molecule_properties']).
• Many-to-Many: For many-to-many relationships, only may not trigger SQL join optimizations.

The client supports most standard Django QuerySet lookup types for filtering results. Use these to refine your data requests:

- exact
- iexact
- contains
- icontains
- in
- gt
- gte
- lt
- lte
- startswith
- istartswith
- endswith
- iendswith
- range
- isnull
- regex
- iregex
- search

The .only() method allows you to specify a list of fields to be included in the response. This reduces bandwidth usage and improves API performance by minimizing data transfer and optimizing SQL joins on the server side.

Limitations:

• It does not support nested fields (e.g., only(['molecule_properties__alogp']) is treated as only(['molecule_properties'])).
• For many-to-many relationships, it may not trigger SQL join optimizations.

# Example: Get only the ChEMBL ID and preferred name for a molecule
mols = molecule.filter(pref_name__iexact='aspirin').only(['molecule_chembl_id', 'pref_name'])

You can find compounds similar to a specific SMILES string or a ChEMBL ID using the similarity resource. You can specify a similarity threshold (e.g., 70).

Search by SMILES:

similarity = new_client.similarity
res = similarity.filter(smiles="CO[C@@H](CCC#C\C=C/CCCC(C)CCCCC=C)C(=O)[O-]", similarity=70).only(['molecule_chembl_id', 'similarity'])

Search by ChEMBL ID:

similarity = new_client.similarity
res = similarity.filter(chembl_id='CHEMBL25', similarity=70).only(['molecule_chembl_id', 'pref_name', 'similarity'])

The image resource allows you to fetch molecule images. You can set the format (e.g., 'svg') before retrieving the image for a specific ChEMBL ID.

from IPython.display import SVG

image = new_client.image
image.set_format('svg')
SVG(image.get('CHEMBL25'))