Repository files navigation

Reproducibly download, open, parse, and query ChEMBL.

Don't worry about downloading/extracting ChEMBL or versioning - just usechembl_downloader to write code that knows how to download it and use itautomatically.

Download an extract the SQLite dump using the following:

importchembl_downloaderpath=chembl_downloader.download_extract_sqlite(version='28')

After it's been downloaded and extracted once, it's smart and does not need todownload again. It gets stored usingpystow automatically in the~/.data/chembl directory.

Full technical documentation can be found onReadTheDocs. Tutorials can be foundin Jupyter notebooks in thenotebooks/ directory of therepository.

You can modify the previous code slightly by omitting theversion keywordargument to automatically find the latest version of ChEMBL:

importchembl_downloaderpath=chembl_downloader.download_extract_sqlite()

Theversion keyword argument is available for all functions in this package(e.g., includingconnect(),cursor(), andquery()), but will be omittedbelow for brevity.

Inside the archive is a single SQLite database file. Normally, people manuallyuntar this folder then do something with the resulting file. Don't do this, it'snot reproducible! Instead, the file can be downloaded and a connection can beopened automatically with:

importchembl_downloaderwithchembl_downloader.connect()asconn:withconn.cursor()ascursor:cursor.execute(...)# run your query stringrows=cursor.fetchall()# get your results

Thecursor() function provides a convenient wrapper around this operation:

importchembl_downloaderwithchembl_downloader.cursor()ascursor:cursor.execute(...)# run your query stringrows=cursor.fetchall()# get your results

The most powerful function isquery() which builds on the previousconnect()function in combination withpandas.read_sqlto make a query and load the results into a pandas DataFrame for any downstreamuse.

importchembl_downloadersql="""SELECT    MOLECULE_DICTIONARY.chembl_id,    MOLECULE_DICTIONARY.pref_nameFROM MOLECULE_DICTIONARYJOIN COMPOUND_STRUCTURES ON MOLECULE_DICTIONARY.molregno == COMPOUND_STRUCTURES.molregnoWHERE molecule_dictionary.pref_name IS NOT NULLLIMIT 5"""df=chembl_downloader.query(sql)df.to_csv(...,sep='\t',index=False)

Suggestion 1: usepystow to make a reproducible file path that's portable toother people's machines (e.g., it doesn't have your username in the path).

Suggestion 2: RDKit is now pip-installable withpip install rdkit-pypi, whichmeans most users don't have to muck around with complicated conda environmentsand configurations. One of the powerful but understated tools in RDKit is therdkit.Chem.PandasToolsmodule.

This example is a bit more fit-for-purpose than the last two. Thesupplier()function makes sure that the latest SDF dump is downloaded and loads it from thegzip file into ardkit.Chem.ForwardSDMolSupplier using a context manager tomake sure the file doesn't get closed until after parsing is done. Like theprevious examples, it can also explicitly take aversion.

fromrdkitimportChemimportchembl_downloaderwithchembl_downloader.supplier()assuppl:data= []fori,molinenumerate(suppl):ifmolisNoneormol.GetNumAtoms()>50:continuefp=Chem.PatternFingerprint(mol,fpSize=1024,tautomerFingerprints=True)smi=Chem.MolToSmiles(mol)data.append((smi,fp))

This example was adapted from Greg Landrum's RDKit blog post ongeneralized substructure search.

This example uses thesupplier() method and RDKit to get SMILES strings frommolecules in ChEMBL's SDF file. If you want direct access to the RDKit moleculeobjects, usesupplier().

importchembl_downloaderforsmilesinchembl_downloader.iterate_smiles():print(smiles)

Building on thesupplier() function, theget_substructure_library() makesthe preparation of asubstructure libraryautomated and reproducible. Additionally, it caches the results of the build,which takes on the order of tens of minutes, only has to be done once and futureloading from a pickle object takes on the order of seconds.

The implementation was inspired by Greg Landrum's RDKit blog post,Some new features in the SubstructLibrary.The following example shows how it can be used to accomplish some of the firsttasks presented in the post:

fromrdkitimportChemimportchembl_downloaderlibrary=chembl_downloader.get_substructure_library()query=Chem.MolFromSmarts('[O,N]=C-c:1:c:c:n:c:c:1')matches=library.GetMatches(query)

ChEMBL makes a file containing pre-computed 2048 bit radius 2 morganfingerprints for each molecule available. It can be downloaded using:

importchembl_downloaderpath=chembl_downloader.download_fps()

Theversion and other keyword arguments are also valid for this function.

The following wraps thedownload_fps function withchemfp's fingerprintloader:

importchembl_downloaderarena=chembl_downloader.chemfp_load_fps()

Theversion and other keyword arguments are also valid for this function. Moreinformation on working with thearena object can be foundhere.

After installing, run the following CLI command to ensure it and send the pathto stdout

$chembl_downloader

Use--test to show two example queries

$chembl_downloader --test

If you want to store the data elsewhere usingpystow (e.g., inpyobo I also keep a copy of this file), youcan use theprefix argument.

importchembl_downloader# It gets downloaded/extracted to# ~/.data/pyobo/raw/chembl/29/chembl_29/chembl_29_sqlite/chembl_29.dbpath=chembl_downloader.download_extract_sqlite(prefix=['pyobo','raw','chembl'])

See thepystowdocumentation onconfiguring the storage location further.

Theprefix keyword argument is available for all functions in this package(e.g., includingconnect(),cursor(), andquery()).

The most recent release can be installed fromPyPI with uv:

$uv pip install chembl_downloader

or with pip:

$python3 -m pip install chembl_downloader

The most recent code and data can be installed directly from GitHub with uv:

$uv --preview pip install git+https://github.com/cthoyt/chembl-downloader.git

or with pip:

$UV_PREVIEW=1 python3 -m pip install git+https://github.com/cthoyt/chembl-downloader.git

Note that this requires settingUV_PREVIEW mode enabled until the uv buildbackend becomes a stable feature.

Seewho's usingchembl-downloader.

chembl-downloader is compatible with all versions of ChEMBL. However, somefiles are not available for all versions. For example, the SQLite version of thedatabase was first added in release 21 (2015-02-12).

Contributions, whether filing an issue, making a pull request, or forking, areappreciated. SeeCONTRIBUTING.mdfor more information on getting involved.

The code in this package is licensed under the MIT License.

This package was created with@audreyfeldroy'scookiecutter package using@cthoyt'scookiecutter-snekpacktemplate.

$git clone git+https://github.com/cthoyt/chembl-downloader.git$cd chembl-downloader$uv --preview pip install -e.

$UV_PREVIEW=1 python3 -m pip install -e.

$cruft update

$tox -e py

$git clone git+https://github.com/cthoyt/chembl-downloader.git$cd chembl-downloader$tox -e docs$open docs/build/html/index.html

$uv tool install keyring$keyringset https://upload.pypi.org/legacy/ __token__$keyringset https://test.pypi.org/legacy/ __token__

$tox -e finish