Metadata-Version: 2.4
Name: pydompekeygen
Version: 1.0.0
Summary: A Python implementation of DompéKeys
Author-email: "Olivier J. M. Béquignon" <olivier.bequignon.maintainer@gmail.com>
Maintainer-email: "Olivier J. M. Béquignon" <olivier.bequignon.maintainer@gmail.com>
License-Expression: MIT
Project-URL: homepage, https://github.com/OlivierBeq/PyDompeKeyGen
Project-URL: repository, https://github.com/OlivierBeq/PyDompeKeyGen
Keywords: qsar,cheminformatics,fingerprint,dompé
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rdkit
Dynamic: license-file

# PyDompeKeyGen

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](pyproject.toml)
[![Status](https://img.shields.io/badge/status-beta-orange.svg)](pyproject.toml)
[![Paper](https://img.shields.io/badge/DOI-10.1186%2Fs13321--024--00813--4-blue.svg)](https://doi.org/10.1186/s13321-024-00813-4)

A lightweight Python / [RDKit](https://www.rdkit.org/) implementation of **DompéKeys** — a set of 1,064 SMARTS-based structural keys for mapping chemical space, built for use as an interpretable molecular fingerprint.

DompéKeys were originally developed by scientists at [Dompé farmaceutici](https://www.dompe.com/) as part of the [EXSCALATE](https://exscalate.eu/) drug-discovery platform and published in the *Journal of Cheminformatics* ([Manelfi, Tazzari, et al., 2024](https://doi.org/10.1186/s13321-024-00813-4)). This package provides a small, dependency-light way to generate the corresponding fingerprint for any RDKit molecule.

## ✨ Features

- 🧬 **1,064 curated SMARTS keys** spanning amino acids, acids, metal binders, toxicophores, ring systems, and generic pharmacophoric features (H-bond donors/acceptors, etc.), organized across 5 complexity levels.
- 🎯 **Single-class API** — one object, one method, one RDKit `ExplicitBitVect` out.
- ⚡ **Fast startup** — the SMARTS catalog is compiled once and cached to disk (`smarts.pkl`), and automatically rebuilt if your installed RDKit version changes.
- 🔍 **Interpretable** — every set bit maps back to a named, human-readable substructure.

## 📦 Installation

PyDompeKeyGen is not yet published to PyPI. Install it directly from GitHub:

```bash
pip install git+https://github.com/OlivierBeq/PyDompeKeyGen.git
```

Or clone and install locally for development:

```bash
git clone https://github.com/OlivierBeq/PyDompeKeyGen.git
cd PyDompeKeyGen
pip install -e .
```

Requires Python ≥ 3.10 and [RDKit](https://pypi.org/project/rdkit/) (installed automatically as a dependency).

## 🚀 Quick start

```python
from rdkit import Chem
from pydompekeygen import PyDompeKeys

# Load the DompéKeys catalog (built once, then cached on disk)
dompekeys = PyDompeKeys()

# Generate a fingerprint for a molecule
mol = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O")  # aspirin
fingerprint = dompekeys.GetFingerprint(mol)

print(f"{fingerprint.GetNumOnBits()} / {dompekeys.num_bits} keys matched")
```

See the [usage guide](docs/usage.md) for similarity calculations, converting fingerprints to NumPy arrays, batch processing, and inspecting which named keys matched.

## 📚 Documentation

| Document | Description |
|---|---|
| [docs/usage.md](docs/usage.md) | Practical guide: similarity search, NumPy conversion, batch processing, introspecting matched keys |
| [docs/api.md](docs/api.md) | API reference for the `PyDompeKeys` class |
| [docs/background.md](docs/background.md) | What DompéKeys are, the 5 complexity levels, and how to cite the original paper |

## 📖 Citation

If you use PyDompeKeyGen in published work, please cite the original DompéKeys paper:

> Manelfi, C., Tazzari, V., Lunghini, F. *et al.* "DompeKeys": a set of novel substructure-based descriptors for efficient chemical space mapping, development and structural interpretation of machine learning models, and indexing of large databases. *J Cheminform* **16**, 21 (2024). https://doi.org/10.1186/s13321-024-00813-4

See [docs/background.md](docs/background.md) for a BibTeX entry.

## 🤝 Contributing

Issues and pull requests are welcome at [github.com/OlivierBeq/PyDompeKeyGen](https://github.com/OlivierBeq/PyDompeKeyGen).

## ⚖️ License

Released under the [MIT License](LICENSE).
