Improving reproducibility of cheminformatics workflows with chembl-downloader

Abstract: Many modern cheminformatics workflows derive datasets from ChEMBL, but few of these datasets are published with accompanying code for their generation. Consequently, their methodologies (e.g., selection, filtering, aggregation) are opaque, reproduction is difficult, and interpretation of results therefore lacks important context. Further, such static datasets quickly become out-of-date. For example, the current version of ChEMBL is v35 (as of December 2024), but ExCAPE-DB uses v20, Deep Confidence uses v23, the consensus dataset from Isigkeit et al. (2022) uses v28, and Papyrus uses v30. Therefore, there is a need for tools that provide reproducible bulk access to the latest (or a given) version of ChEMBL in order to enable researchers to make their derived datasets more transparent, updatable, and trustworthy. This article introduces chembl-downloader, a Python package for the reproducible acquisition, access, and manipulation of ChEMBL data through its FTP server. It can be downloaded under the MIT license from https://github.com/cthoyt/chembl-downloader and installed from PyPI with pip install chembl-downloader.

• The paper introduces chembl-downloader, a Python package that automates reproducible ChEMBL dataset generation with explicit version control.
• It implements low-, mid-, and high-level utilities to streamline data acquisition, preprocessing, and querying from ChEMBL resources.
• The tool enhances reproducibility and transparency in cheminformatics workflows, enabling straightforward updates and community collaboration.

Enhancing Reproducibility in Cheminformatics with chembl-downloader

Motivation and Problem Statement

The paper addresses a critical challenge in cheminformatics: the lack of reproducibility and transparency in workflows that derive datasets from ChEMBL. While ChEMBL is a foundational resource for bioactivity data, most derived datasets are distributed as static files without accompanying code or clear documentation of the data generation process. This opacity impedes reproducibility, hinders methodological scrutiny, and results in datasets that rapidly become outdated as ChEMBL evolves. The paper highlights that widely used datasets such as ExCAPE-DB, Deep Confidence, and Papyrus are based on outdated ChEMBL versions, further exacerbating these issues.

Existing Access Methods and Limitations

ChEMBL can be accessed via several modalities: RESTful APIs, a Python client, RDF endpoints, and bulk FTP downloads. However, the API and its wrappers are inefficient for large-scale data extraction, and bulk access via FTP is cumbersome due to the need for manual download, decompression, and local database setup. Third-party platforms like KNIME and Pipeline Pilot offer alternative access but are often proprietary, inflexible, or not easily extensible. These limitations collectively create barriers to reproducible, scalable, and up-to-date data workflows in cheminformatics.

chembl-downloader: Architecture and Functionality

The chembl-downloader Python package is introduced as a solution to these challenges, providing a reproducible, version-agnostic, and extensible interface to ChEMBL's FTP resources. Its architecture is stratified into three levels:

Low-Level Utilities

• Acquisition and Preprocessing: Utilizes the pystow package and custom logic to automate downloading, decompressing, and organizing ChEMBL resources (e.g., SQLite dumps, SDF/TSV molecule lists, binary fingerprints, XML monomer libraries, UniProt mappings).
• Version Control: Supports retrieval of both the latest and specific historical ChEMBL releases, ensuring reproducibility across time.

Mid-Level Utilities

• Data Access Abstractions: Provides functions for querying SQLite databases (via sqlite3 and pandas), parsing SDFs (via RDKit), handling TSVs (via pandas), loading fingerprints (via chemfp), and parsing XML monomer libraries.
• Extensibility: Designed to be minimal and composable, enabling users to build custom workflows atop the provided primitives.

High-Level Utilities

• Task-Specific Functions: Includes pre-formatted SQL queries for common tasks such as retrieving bioactivities for assays/targets, extracting compounds from publications/patents, and listing compound names.
• Workflow Integration: Facilitates rapid prototyping and integration into larger data processing pipelines.

Empirical Evaluation and Case Studies

The utility of chembl-downloader is demonstrated through several case studies:

• Dataset Reproduction: The package enables exact reproduction and updating of datasets such as those from Cortés-Ciriano & Bender (2019), revealing methodological issues (e.g., arithmetic vs. geometric mean aggregation of pIC₅₀) and quantifying the impact of new ChEMBL releases on dataset composition.
• Identifier Mapping: Automated scripts leveraging chembl-downloader and Gilda identified 4,266 candidate ChEMBL–ChEBI mappings for curation, streamlining identifier harmonization workflows.
• Community Adoption: The tool has been integrated into codebases of prominent cheminformatics blogs and repositories, improving reproducibility and ChEMBL-version agnosticism in published analyses. Pull requests to projects such as the RDKit Blog and PatWalters/sfi demonstrate practical impact.

Implementation and Usage

chembl-downloader is distributed via PyPI and source code is available on GitHub, with documentation and interactive Jupyter notebooks provided. The package is designed for seamless integration into Python-based data science workflows, leveraging standard libraries (pandas, sqlite3, RDKit, chemfp) for data manipulation. The modular design allows users to script end-to-end dataset generation, from acquisition to preprocessing and analysis, with explicit versioning and provenance tracking.

Example Usage

from chembl_downloader import download_sqlite, get_sqlite_path import sqlite3 import pandas as pd download_sqlite(version="35") db_path = get_sqlite_path(version="35") with sqlite3.connect(db_path) as conn: df = pd.read_sql_query( "SELECT * FROM activities WHERE standard_type='IC50' AND target_chembl_id='CHEMBLXXXX'", conn )

This example demonstrates reproducible acquisition and querying of ChEMBL data, with explicit version control.

Implications and Future Directions

The introduction of chembl-downloader has several implications:

• Reproducibility: By automating dataset generation and providing explicit versioning, the package addresses a major reproducibility gap in cheminformatics.
• Transparency: Workflows become auditable, facilitating methodological scrutiny and enabling the community to track the provenance of derived datasets.
• Updatability: Researchers can easily refresh datasets as ChEMBL evolves, supporting longitudinal studies and meta-analyses.
• Community Standards: The adoption of such tools may catalyze a shift toward code-first, version-controlled data sharing practices in cheminformatics and related fields.

Future developments could include tighter integration with workflow management systems (e.g., Snakemake, Nextflow), support for additional data modalities, and expanded high-level utilities for common cheminformatics tasks. There is also potential for extending the approach to other bioinformatics resources with similar reproducibility challenges.

Conclusion

chembl-downloader provides a robust, extensible, and reproducible framework for accessing and manipulating ChEMBL data. By addressing the limitations of existing access methods and enabling transparent, version-controlled workflows, it represents a significant step toward higher standards of reproducibility and methodological rigor in cheminformatics. The package's design and demonstrated utility position it as a foundational tool for both individual researchers and the broader community engaged in data-driven drug discovery and bioactivity modeling.