capricho 1.0.2

The ChEMBL data curator that flags issues instead of silently dropping them.

Inspired in the Portuguese word "capricho" 🔊. Doing someting with capricho means doing it meticulously, with care and attention to detail.

CAPRICHO (ChEMBL Aggregation Package with Robust Inspection and Curation Handling Options) is a Python package that streamlines fetching, curating, and aggregating ChEMBL data into a machine learning-ready format for drug discovery in a flexible and reproducible manner. Instead of making opiniated decisions on the source data, CAPRICHO curates it based on several quality control filters that can be chosen by the user. Its guiding principle is to never silently drop data. Entries that don't meet the criteria are marked, allowing the user to analyze how each curation step affects the comparability of assay readouts for the same compound.

🎯 Goals

The development of CAPRICHO is guided by two core principles:

• Transparency Above All: Data curation should never be a black box. Removed data points should be saved to be scrutinized by the user and the original data should be always preserved to ensure data integrity.
• Flexibility by Design: Every modeling project is unique. Aggregation should be stratified by ChEMBL metadata columns, aggregating repeated compound measurements only within the scope you define as comparable.

✨ Features:

• Data retrieval by any ChEMBL identifier (molecule IDs, target IDs, assay IDs, or document IDs)
• ADMET data curation support with unit conversion and non-pChEMBL aggregation
• Quality control through data flagging — never silently drops data
• Customizable filtering options with max curation standards introduced by Landrum & Riniker (2024)
• Configurable data aggregation options
• Binary classification support with censored data handling
• Save a fetching and processing recipe for reproducibility
• Command-line interface for easy use

⚙️ Installation

The most recent release can be installed from PyPI with uv:

uv pip install capricho

or with pip:

python -m pip install capricho

Alternatively, install directly from the GitHub repository with uv using the command:

uv pip install git+https://github.com/David-Araripe/Capricho.git

or with pip

python -m pip install git+https://github.com/David-Araripe/Capricho.git

🚀 Quick Start

Basic Usage

# Download ChEMBL database
capricho download

# Get bioactivity data for EGFR
capricho get --target-ids CHEMBL203 --output-path egfr_data.csv

# Get high-confidence data for multiple targets
capricho get --target-ids CHEMBL203,CHEMBL204 --confidence-scores 8,9 --output-path results.csv

Tab Completion

Our CLI supports tab completion for commands and options. To enable it, run the following command in your terminal:

capricho --install-completion

Key Features

• Five main commands: download, explore, get, prepare, binarize
• Flexible filtering: By confidence, assay type, bioactivity type
• Transparent processing: All filtering steps are logged and flagged
• Reproducible workflows: Automatic recipe generation
• Multiple backends: Local SQL or web API
• Binary classification support: Convert continuous activity values to binary labels

📖 Documentation

For comprehensive documentation including detailed CLI options, advanced usage, tutorials, and API reference, visit our full documentation.

Quick Links:

• Installation Guide
• Quick Start
• CLI Reference
• Key Concepts
• ADMET Data Guide
• API Reference

License

This project is licensed under the MIT License - see the LICENSE file for details.