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, standardization, and harmonization of molecular structure tables for cheminformatics workflows and machine learning applications within the computational drug discovery pipeline.

The platform enables:

• Source-aware molecular table preparation: Ingests molecular identifiers or SMILES from PubChem, ChEMBL, and independent tabular datasets while preserving source traceability.
• Deterministic identifier handling: Uses robust, alias-aware input detection for PubChem CIDs and emits a canonical PubChem_CID output column for downstream interoperability.
• RDKit canonicalization: Generates SMILES_RDKit as a canonical/isomeric/Kekulé RDKit representation, preserving compatibility with workflows that use Kekulized SMILES for deduplication or comparison.
• SMILES harmonization: Generates SMILES_Harmonized as a canonical/isomeric/aromatic representation after controlled RDKit-native standardization and harmonization.
• Auditable status reporting: Reports harmonization outcomes through SMILES_Harmonization_Status and SMILES_Harmonization_Message, distinguishing successful harmonization, controlled transformations, unsupported ambiguous structures, and failures.
• Cross-source comparison: Preserves structural bridge fields such as InChI and InChIKey to support comparison across PubChem, ChEMBL, and independent molecular databases.

SMILES Column Contract

HARMONSMILE exposes three universal SMILES representations in pipeline outputs:

• SMILES: source/input SMILES. This is the value used as input for RDKit canonicalization and lab harmonization.
• SMILES_RDKit: RDKit canonical + isomeric + Kekulized representation, produced by RDKitStandardizer.to_iso_kek(SMILES). This column is preserved for compatibility with v0.2.5. It is not a full chemical harmonization layer and does not intentionally desalt, neutralize, reionize, or canonicalize tautomers.
• SMILES_Harmonized: lab-harmonized representation, produced by RDKitStandardizer.to_lab_harmonized(SMILES). It uses an RDKit-native MolStandardize policy with validation before automatic modification, controlled parent generation for simple salts/counterions, normalization, uncharging, reionization, optional tautomer canonicalization, and final canonical/isomeric/aromatic serialization.

SMILES_Harmonized is intended for database harmonization, deduplication, and cross-source matching. It is not guaranteed to represent the most stable, most abundant, pH-specific, or biologically active tautomer. HARMONSMILE does not export tautomer ensembles; it stores one canonical harmonized representation per input row. Source traceability is preserved through SMILES and SMILES_RDKit.

Rows are not dropped when harmonization fails. Instead, the result is carried in:

• SMILES_Harmonization_Status: short filterable status returned by the harmonization engine: ok, ok_with_warnings, unsupported, or failed.
• SMILES_Harmonization_Message: short auditable message for warnings, unsupported structures, or failures; empty/None for successful ok rows.

Some sources may also provide source-specific SMILES columns. For example, ConnectivitySMILES is a PubChem-provided connectivity SMILES column preserved when available; it is not generated by HARMONSMILE and is not present for all sources.

Installation

For package users:

Create and activate a Python environment:

conda create -n harmonsmile_env python=3.11
conda activate harmonsmile_env

Install HARMONSMILE from PyPI:

pip install harmonsmile

For contributors/developers:

Clone the repository:

git clone https://github.com/NanoBiostructuresRG/harmonsmile.git
cd harmonsmile

Create and activate the development environment:

conda env create -f environment.yml
conda activate harmonsmile_env

Install HARMONSMILE in editable mode with development dependencies:

python -m pip install -e .[dev]

RDKit is a required runtime dependency (rdkit>=2022.09). For package users, it is declared in pyproject.toml and installed through the package dependency resolver. For contributors, environment.yml preinstalls RDKit from conda-forge for a stable local scientific stack.

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

All pipelines preserve the source SMILES, append SMILES_RDKit, and append the lab harmonization columns SMILES_Harmonized, SMILES_Harmonization_Status, and SMILES_Harmonization_Message. 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

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

Roadmap

• v0.3.0 - Lab-harmonized SMILES contract/layer for database harmonization, deduplication, and cross-source 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.