harmonsmile 0.2.5

Toolkit for harmonizing SMILES strings to canonical + isomeric + Kekulized convention (RDKit)

HARMONSMILE: Harmonize SMILES Strings for Cheminformatics and Machine Learning

---

Description

HARMONSMILE solves a common problem in cheminformatics: SMILES strings for the same molecule look different depending on the source (PubChem, ChEMBL, COCONUT, in-house databases). This inconsistency breaks comparisons, deduplication, and machine learning pipelines that expect a uniform molecular representation.

It is intended for computational chemists, cheminformatics researchers, ML practitioners preparing molecular datasets, and maintainers integrating PubChem, ChEMBL, and in-house sources.

---

Purpose

The primary objective of HARMONSMILE is to automate the preparation of molecular datasets for cheminformatics workflows and phase 1 machine learning applications within the computational drug discovery pipeline.

The platform enables:

• Data Harmonization: Standardizes SMILES strings to a consistent format - canonical + isomeric + Kekulized - ensuring that the same molecule is represented identically across different datasets and sources. It follows the RDKit convention for canonicalization, which is widely adopted in the cheminformatics community.

---

Installation

pip install harmonsmile

RDKit is required and installed automatically (rdkit>=2022.09).

---

Quick Start

Python API

Standardize a single SMILES string:

from harmonsmile import RDKitStandardizer

std = RDKitStandardizer()
print(std.to_iso_kek("c1ccccc1"))    # canonical + isomeric + Kekulized
print(std.to_conn_kek("c1ccccc1"))   # canonical + connectivity-only + Kekulized

Fetch properties from PubChem and harmonize:

from harmonsmile import PubChemIngest, PubChemConfig, save_table

cfg = PubChemConfig(
    input_path="examples/example_pubchem.csv",   # requires: id, PubChem CID
)
df = PubChemIngest(cfg).run()
save_table(df, "results/example_pubchem_harmonized.csv")

Fetch properties from ChEMBL and harmonize:

from harmonsmile import ChEMBLIngest, ChEMBLConfig, save_table

cfg = ChEMBLConfig(
    input_path="examples/example_chembl.csv",    # requires: id, ChEMBL ID
)
df = ChEMBLIngest(cfg).run()
save_table(df, "results/example_chembl_harmonized.csv")

Harmonize any file with a SMILES column (COCONUT, in-house, etc.):

from harmonsmile import SMILESPrep, SMILESConfig, save_table

cfg = SMILESConfig(
    input_path="examples/example_smiles.csv",
    smiles_col="SMILES",                      # any column name
)
df = SMILESPrep(cfg).run()
save_table(df, "results/example_smiles_harmonized.csv")

Command-Line Interface

# PubChem pipeline
harmonsmile --pubchem-in examples/database1.csv --pubchem-out results/database1_harmonized.csv

# SMILES pipeline (COCONUT, independent, etc.)
harmonsmile --smiles-in examples/database2.csv --smiles-col canonical_smiles \
            --smiles-out results/database2_harmonized.csv

# Both pipelines in one run
harmonsmile \
  --pubchem-in examples/database1.csv --pubchem-out results/database1_harmonized.csv \
  --smiles-in  examples/database2.csv --smiles-col  canonical_smiles \
  --smiles-out results/database2_harmonized.csv

# Single Entry - fetch one compound by ID
harmonsmile --pubchem-cid 2723949
harmonsmile --chembl-id CHEMBL294199

# Check version
harmonsmile --version

Also available as a Python module:

python -m harmonsmile --pubchem-in examples/database1.csv --pubchem-out results/out.csv

---

Pipelines

Pipeline	Config	Source	Input	API
PubChemIngest	PubChemConfig	PubChem	CSV with PubChem CID column	REST (public)
ChEMBLIngest	ChEMBLConfig	ChEMBL	CSV with ChEMBL ID column	REST (public)
SMILESPrep	SMILESConfig	Any	CSV/Excel with any SMILES column	Local file

All pipelines append a SMILES_RDKit column with the harmonized SMILES. Pipeline .run() methods return a pandas.DataFrame and do not write files. Use save_table(df, path) to persist results from Python, or use the CLI --*-out options.

---

Input Format

Pipeline	Required columns
PubChemIngest	id (optional), PubChem CID
ChEMBLIngest	id (optional), ChEMBL ID
SMILESPrep	id (optional), <smiles_col> (any name)

Supported file formats: CSV, TSV, XLSX, XLS.

---

Roadmap

• v0.3.0 - ML-ready features: ECFP fingerprints (with/without chirality), InChI/InChIKey for deduplication and robust cross-database matching.

---

Development

Project Structure

HARMONSMILE/
|-- harmonsmile/
|   |-- __init__.py        # Public API
|   |-- __main__.py        # python -m harmonsmile entry point
|   |-- _cli.py            # CLI implementation
|   |-- chembl.py          # ChEMBL REST client
|   |-- config.py          # PubChemConfig, ChEMBLConfig, SMILESConfig dataclasses
|   |-- io.py              # Table I/O utilities
|   |-- pipelines.py       # PubChemIngest, ChEMBLIngest, SMILESPrep
|   |-- pubchem.py         # PubChem REST client
|   |-- standardize.py     # RDKitStandardizer
|   `-- version.py         # Package version metadata
|-- tests/                 # Unit test suite (pytest) - 146 tests
|-- examples/              # Example scripts and datasets
|-- pyproject.toml
|-- environment.yml
|-- mkdocs.yml
|-- requirements-dev.txt
|-- CHANGELOG.md
|-- CITATION.cff
|-- CODE_OF_CONDUCT.md
|-- CONTRIBUTING.md
|-- COPYING
|-- COPYING.LESSER
|-- LICENSE
`-- README.md

Running Tests

python -m pytest tests -p no:cacheprovider --basetemp .pytest_tmp

Contributing

Contributions are welcome. Please open an issue before submitting a pull request. Follow the existing code style: NumPy-style docstrings, type hints, and SPDX license headers in all source files.

See CONTRIBUTING.md for full guidelines. Please also read our Code of Conduct.

---

Citation

If you use HARMONSMILE in your research, please cite it using the metadata in CITATION.cff or the format below:

Contreras-Torres, F. F. (2026). HARMONSMILE: Harmonize SMILES Strings for
Cheminformatics and Machine Learning. Zenodo. https://doi.org/10.5281/zenodo.20275498

---

Author

Developed by Flavio F. Contreras-Torres (Tecnologico de Monterrey) Monterrey, Mexico - May 2026

---

License

This project is licensed under the terms of the GNU Lesser General Public License v3.0 or later. SPDX identifier: LGPL-3.0-or-later.