Usage

Installation

pip install harmonsmile

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

Quick Start

PubChemChEMBLSMILESSingle SMILES

from harmonsmile import PubChemIngest, PubChemConfig, save_table

cfg = PubChemConfig(
    input_path="examples/example_pubchem.csv",
)
df = PubChemIngest(cfg).run()
save_table(df, "results/example_pubchem_harmonized.csv")

from harmonsmile import ChEMBLIngest, ChEMBLConfig, save_table

cfg = ChEMBLConfig(
    input_path="examples/example_chembl.csv",
)
df = ChEMBLIngest(cfg).run()
save_table(df, "results/example_chembl_harmonized.csv")

from harmonsmile import SMILESPrep, SMILESConfig, save_table

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

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

Command-Line Interface

# PubChem batch
harmonsmile --pubchem-in examples/db.csv --pubchem-out results/out.csv

# ChEMBL batch
harmonsmile --chembl-in examples/db.csv --chembl-out results/out.csv

# SMILES batch
harmonsmile --smiles-in examples/db.csv --smiles-col SMILES --smiles-out results/out.csv

# Single Entry
harmonsmile --pubchem-cid 2723949
harmonsmile --chembl-id CHEMBL294199

Pipelines

PubChem

PubChemIngest reads CSV data with a PubChem CID column and resolves molecules through the public REST API.

ChEMBL

ChEMBLIngest reads CSV data with a ChEMBL ID column and resolves structures through the public REST API.

Local SMILES

SMILESPrep accepts CSV or Excel files with any SMILES column name and processes them locally.

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) from Python, or CLI --*-out options, to persist results.

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.