harmonsmile 0.1.1__py3-none-any.whl

harmonsmile/__init__.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""
+harmonsmile — Harmonize SMILES strings to canonical + isomeric + Kekulized convention.
+
+Provides pipelines and utilities for standardizing SMILES strings using RDKit,
+following the COCONUT 2.0 convention: canonical, isomeric, and Kekulized form.
+
+Classes
+-------
+RDKitStandardizer
+    Standardize SMILES strings using RDKit.
+Config
+    Immutable configuration for harmonsmile pipelines.
+PubChemIngest
+    Pipeline for ingesting and harmonizing PubChem compound data.
+ChEMBLIngest
+    Pipeline for ingesting and harmonizing ChEMBL compound data.
+SMILESPrep
+    Pipeline for harmonizing SMILES from any tabular source.
+
+Functions
+---------
+load_table(path)
+    Load a tabular file into a DataFrame.
+save_table(df, path)
+    Save a DataFrame to a CSV file.
+
+Examples
+--------
+Standardize a single SMILES string:
+
+>>> from harmonsmile import RDKitStandardizer
+>>> std = RDKitStandardizer()
+>>> std.to_iso_kek("c1ccccc1")
+'C1=CC=CC=C1'
+>>> std.to_conn_kek("C[C@@H](O)F")
+'CC(O)F'
+
+Harmonize a COCONUT or independent database:
+
+>>> from harmonsmile import CoconutPrep
+>>> CoconutPrep(
+...     input_path="data/database.csv",
+...     smiles_col="SMILES",
+...     output_path="results/database_harmonized.csv",
+... ).run()
+
+Fetch and harmonize PubChem data:
+
+>>> from harmonsmile import PubChemIngest, Config
+>>> cfg = Config(
+...     input_path="data/database_pubchem.csv",
+...     output_path="results/pubchem_harmonized.csv",
+... )
+>>> PubChemIngest(cfg).run()
+"""
+
+from .standardize import RDKitStandardizer
+from .pipelines import PubChemIngest, ChEMBLIngest, SMILESPrep, CoconutPrep
+from .config import Config
+from .pubchem import PubChemClient
+from .io import load_table, save_table
+from .version import __version__, PROJECT_NAME, PROJECT_VERSION, PROJECT_STATUS
+
+__author__ = "Flavio F. Contreras-Torres"
+
+__all__ = [
+    "RDKitStandardizer",
+    "PubChemIngest",
+    "ChEMBLIngest",
+    "SMILESPrep",
+    "Config",
+    "load_table",
+    "save_table",
+    "__version__",
+    "PROJECT_NAME",
+    "PROJECT_VERSION",
+    "PROJECT_STATUS"
+]

harmonsmile/__main__.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""
+Entry point for running harmonsmile as a module.
+
+Allows the package to be invoked directly from the command line
+using ``python -m harmonsmile``. All arguments are forwarded to the
+CLI defined in :mod:`harmonsmile._cli`.
+
+See Also
+--------
+harmonsmile._cli.main : The CLI entry point function.
+
+Examples
+--------
+Fetch PubChem properties and standardize SMILES::
+
+    python -m harmonsmile --pubchem-in data/db.csv --pubchem-out results/out.csv
+
+Standardize an existing SMILES column::
+
+    python -m harmonsmile --coconut-in data/db.csv --coconut-smiles SMILES --coconut-out results/out.csv
+"""
+
+from harmonsmile._cli import main
+
+if __name__ == "__main__":
+    main()

harmonsmile/_cli.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""
+Command-line interface for harmonsmile.
+
+Implements the ``harmonsmile`` entry point and ``python -m harmonsmile``
+invocation. Arguments are parsed and forwarded to
+:class:`~harmonsmile.pipelines.PubChemIngest`,
+:class:`~harmonsmile.pipelines.ChEMBLIngest`, and
+:class:`~harmonsmile.pipelines.SMILESPrep`.
+
+Examples
+--------
+::
+
+    harmonsmile --pubchem-in data/db.csv --pubchem-out results/out.csv
+    harmonsmile --chembl-in data/db.csv --chembl-out results/out.csv
+    harmonsmile --coconut-in data/db.csv --coconut-smiles SMILES --coconut-out results/out.csv
+    python -m harmonsmile --pubchem-in data/db.csv --pubchem-out results/out.csv
+"""
+
+from __future__ import annotations
+from .version import __version__
+import argparse
+import os
+
+from .config import Config
+from .pipelines import PubChemIngest, ChEMBLIngest, SMILESPrep
+
+
+def _ensure_dirs() -> None:
+    for d in ("logs", "results"):
+        os.makedirs(d, exist_ok=True)
+
+
+def _parse(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="harmonsmile",
+        description="Harmonize SMILES strings to canonical + isomeric + Kekulized convention.",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}",)
+    pub = p.add_argument_group("PubChem")
+    pub.add_argument("--pubchem-in",     dest="pub_in",         metavar="FILE")
+    pub.add_argument("--pubchem-out",    dest="pub_out",         metavar="FILE")
+    pub.add_argument("--pubchem-cidcol", dest="pubchem_cidcol",  default="PubChem CID", metavar="COL")
+
+    chembl = p.add_argument_group("ChEMBL")
+    chembl.add_argument("--chembl-in",    dest="chembl_in",    metavar="FILE")
+    chembl.add_argument("--chembl-out",   dest="chembl_out",   metavar="FILE")
+    chembl.add_argument("--chembl-idcol", dest="chembl_idcol", default="ChEMBL ID", metavar="COL")
+
+    coco = p.add_argument_group("COCONUT / independent")
+    coco.add_argument("--coconut-in",     dest="coco_in",     metavar="FILE")
+    coco.add_argument("--coconut-out",    dest="coco_out",    metavar="FILE")
+    coco.add_argument("--coconut-smiles", dest="coco_smiles", metavar="COL")
+
+    args = p.parse_args(argv)
+
+    # Validate paired arguments
+    if bool(args.pub_in) != bool(args.pub_out):
+        p.error("--pubchem-in and --pubchem-out must be provided together.")
+    if bool(args.chembl_in) != bool(args.chembl_out):
+        p.error("--chembl-in and --chembl-out must be provided together.")
+    if bool(args.coco_in) != bool(args.coco_out):
+        p.error("--coconut-in and --coconut-out must be provided together.")
+    if args.coco_in and not args.coco_smiles:
+        p.error("--coconut-smiles is required when --coconut-in is provided.")
+
+    return args
+
+
+def main(argv: list[str] | None = None) -> None:
+    """
+    Entry point for the harmonsmile command-line interface.
+
+    Parameters
+    ----------
+    argv : list of str, optional
+        Argument list. Defaults to sys.argv if None.
+
+    Examples
+    --------
+    Programmatic invocation with PubChem pipeline:
+
+    >>> from harmonsmile._cli import main
+    >>> main(["--pubchem-in", "data/db.csv", "--pubchem-out", "results/out.csv"])
+
+    Programmatic invocation with ChEMBL pipeline:
+
+    >>> main(["--chembl-in", "data/db.csv", "--chembl-out", "results/out.csv"])
+
+    Programmatic invocation with COCONUT pipeline:
+
+    >>> main(["--coconut-in", "data/db.csv", "--coconut-smiles", "SMILES",
+    ...       "--coconut-out", "results/out.csv"])
+    """
+    args = _parse(argv)
+    ran_any = False
+
+    if args.pub_in and args.pub_out:
+        _ensure_dirs()
+        cfg = Config(
+            input_path=args.pub_in,
+            output_path=args.pub_out,
+            cid_col=args.pubchem_cidcol,
+        )
+        PubChemIngest(cfg).run()
+        ran_any = True
+
+    if args.chembl_in and args.chembl_out:
+        _ensure_dirs()
+        ChEMBLIngest(
+            input_path=args.chembl_in,
+            output_path=args.chembl_out,
+            chembl_id_col=args.chembl_idcol,
+        ).run()
+        ran_any = True
+
+    if args.coco_in and args.coco_out and args.coco_smiles:
+        _ensure_dirs()
+        SMILESPrep(args.coco_in, args.coco_smiles, args.coco_out).run()
+        ran_any = True
+
+    if not ran_any:
+        raise SystemExit(
+            "Nothing to run. Provide --pubchem-*, --chembl-*, and/or --coconut-* arguments.\n"
+            "Run 'harmonsmile --help' for usage."
+        )

harmonsmile/chembl.py

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""
+ChEMBL REST API client for harmonsmile.
+
+Provides :class:`_ChEMBLClient` for fetching compound properties from the
+ChEMBL REST API, with exponential backoff and persistent connection reuse.
+"""
+
+from __future__ import annotations
+import logging
+import re
+import time
+from typing import Any, Callable
+
+import requests
+
+_CHEMBL_ID_RE = re.compile(r"^CHEMBL\d+$")
+
+_ROOT_FIELDS: tuple[str, ...] = ("molecule_chembl_id", "pref_name")
+_STRUCT_FIELDS: tuple[str, ...] = ("canonical_smiles", "standard_inchi", "standard_inchi_key")
+_PROP_FIELDS: tuple[str, ...] = (
+    "alogp", "full_mwt", "full_molformula",
+    "hba", "hbd", "heavy_atoms",
+    "psa", "qed_weighted", "num_ro5_violations", "rtb",
+)
+_ALL_FIELDS: tuple[str, ...] = _ROOT_FIELDS + _STRUCT_FIELDS + _PROP_FIELDS
+
+
+class _ChEMBLClient:
+    """
+    Client for fetching compound properties from the ChEMBL REST API.
+
+    Uses exponential backoff on failure and a persistent requests.Session
+    for efficient connection reuse across multiple compounds.
+
+    Parameters
+    ----------
+    logger : Callable[[str], None] or None, optional
+        Callable for error reporting. Defaults to the module logger warning.
+    sleep : float, optional
+        Base sleep time in seconds between requests. Defaults to 0.2.
+    retries : int, optional
+        Number of retry attempts on failure. Defaults to 3.
+
+    Examples
+    --------
+    >>> client = _ChEMBLClient()
+    >>> props = client.fetch_props("CHEMBL25")  # doctest: +SKIP
+    >>> client.close()
+    """
+
+    _BASE_URL = "https://www.ebi.ac.uk/chembl/api/data/molecule"
+
+    def __init__(
+        self,
+        logger: Callable[[str], None] | None = None,
+        sleep: float = 0.2,
+        retries: int = 3,
+    ) -> None:
+        if not 0.1 <= sleep <= 10.0:
+            raise ValueError("sleep must be between 0.1 and 10.0 seconds.")
+        if not 1 <= retries <= 10:
+            raise ValueError("retries must be between 1 and 10.")
+        self.log = logger or (lambda m: logging.getLogger(__name__).warning(m))
+        self.sleep = sleep
+        self.retries = retries
+        self._session = requests.Session()
+        self._session.headers.update({"User-Agent": "harmonsmile (python-requests)"})
+
+    def fetch_props(self, chembl_id: str | None) -> dict[str, Any]:
+        """
+        Fetch compound properties from ChEMBL by ChEMBL ID.
+
+        Parameters
+        ----------
+        chembl_id : str or None
+            ChEMBL compound identifier (e.g. 'CHEMBL25'). Whitespace is
+            stripped; IDs not matching ``CHEMBL\\d+`` return all-None values.
+
+        Returns
+        -------
+        dict[str, Any]
+            Dictionary of 15 extracted properties. Values are None if the
+            fetch failed or the identifier is missing or invalid.
+
+        Examples
+        --------
+        >>> client = _ChEMBLClient()
+        >>> client.fetch_props("CHEMBL25")  # doctest: +SKIP
+        {'molecule_chembl_id': 'CHEMBL25', 'pref_name': 'ASPIRIN', ...}
+        >>> client.fetch_props("")
+        {'molecule_chembl_id': None, 'pref_name': None, ...}
+        >>> client.close()
+        """
+        null = {f: None for f in _ALL_FIELDS}
+        if not chembl_id:
+            return null
+        chembl_id = str(chembl_id).strip()
+        if not _CHEMBL_ID_RE.match(chembl_id):
+            return null
+        url = f"{self._BASE_URL}/{chembl_id}.json"
+        for k in range(self.retries):
+            try:
+                r = self._session.get(url, timeout=12)
+                r.raise_for_status()
+                data = r.json()
+                structs = data.get("molecule_structures") or {}
+                props = data.get("molecule_properties") or {}
+                result: dict[str, Any] = {
+                    "molecule_chembl_id": data.get("molecule_chembl_id"),
+                    "pref_name":          data.get("pref_name"),
+                    "canonical_smiles":   structs.get("canonical_smiles"),
+                    "standard_inchi":     structs.get("standard_inchi"),
+                    "standard_inchi_key": structs.get("standard_inchi_key"),
+                    "alogp":              props.get("alogp"),
+                    "full_mwt":           props.get("full_mwt"),
+                    "full_molformula":    props.get("full_molformula"),
+                    "hba":                props.get("hba"),
+                    "hbd":                props.get("hbd"),
+                    "heavy_atoms":        props.get("heavy_atoms"),
+                    "psa":                props.get("psa"),
+                    "qed_weighted":       props.get("qed_weighted"),
+                    "num_ro5_violations": props.get("num_ro5_violations"),
+                    "rtb":                props.get("rtb"),
+                }
+                time.sleep(self.sleep)
+                return result
+            except Exception as e:
+                if k + 1 == self.retries:
+                    self.log(f"[ChEMBL] {chembl_id}: {e}")
+                    return null
+                time.sleep(self.sleep * (2 ** k))
+        return null
+
+    def __enter__(self) -> _ChEMBLClient:
+        """
+        Enter the context manager.
+
+        Returns
+        -------
+        _ChEMBLClient
+            The client instance itself.
+        """
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        """
+        Exit the context manager and release resources.
+
+        Parameters
+        ----------
+        exc_type : type or None
+            Exception type, if any.
+        exc_val : BaseException or None
+            Exception value, if any.
+        exc_tb : traceback or None
+            Exception traceback, if any.
+
+        Returns
+        -------
+        bool
+            Always False; exceptions are not suppressed.
+        """
+        self.close()
+        return False
+
+    def close(self) -> None:
+        """
+        Close the underlying HTTP session.
+
+        Should be called when the client is no longer needed to release
+        connection resources.
+
+        Examples
+        --------
+        >>> client = _ChEMBLClient()
+        >>> client.close()
+        """
+        self._session.close()

harmonsmile/config.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""
+Configuration dataclass for harmonsmile pipelines.
+
+Defines the immutable :class:`Config` object used by
+:class:`~harmonsmile.pipelines.PubChemIngest` to parameterize
+input/output paths, PubChem column names, and properties to fetch.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+
+VALID_PUBCHEM_PROPS: frozenset[str] = frozenset({
+    "SMILES", "ConnectivitySMILES", "MolecularWeight",
+    "MolecularFormula", "InChI", "InChIKey", "XLogP", "TPSA",
+    "HBondDonorCount", "HBondAcceptorCount", "RotatableBondCount",
+    "HeavyAtomCount", "Charge",
+})
+
+
+@dataclass(frozen=True)
+class Config:
+    """
+    Immutable configuration for harmonsmile pipelines.
+
+    Parameters
+    ----------
+    input_path : str
+        Path to the input file (CSV, TSV, XLSX).
+    output_path : str
+        Path to the output CSV file.
+    error_log : str, optional
+        Path to the error log file. Defaults to 'logs/errors.txt'.
+    cid_col : str, optional
+        Name of the PubChem CID column. Defaults to 'PubChem CID'.
+    props : tuple of str, optional
+        PubChem properties to fetch. Defaults to all available properties.
+    """
+
+    input_path: str
+    output_path: str
+    error_log: str = "logs/errors.txt"
+    cid_col: str = "PubChem CID"
+    props: tuple[str, ...] = ("SMILES", "ConnectivitySMILES", "MolecularFormula",
+    "MolecularWeight", "InChI", "InChIKey", "XLogP", "TPSA",
+    "Charge", "HBondDonorCount", "HBondAcceptorCount",
+    "RotatableBondCount", "HeavyAtomCount",)
+
+    def __post_init__(self) -> None:
+        if not self.input_path:
+            raise ValueError("input_path must not be empty.")
+        if not self.output_path:
+            raise ValueError("output_path must not be empty.")
+        if ".." in self.output_path:
+            raise ValueError("output_path must not contain path traversal patterns ('..').")
+        if not self.props:
+            raise ValueError("props must contain at least one PubChem property.")
+        invalid = {p for p in self.props if p not in VALID_PUBCHEM_PROPS}
+        if invalid:
+            raise ValueError(f"Invalid PubChem properties: {sorted(invalid)}")

harmonsmile/io.py

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""
+Table I/O utilities for harmonsmile.
+
+Provides :func:`load_table` and :func:`save_table` for reading and writing
+tabular chemical data.
+"""
+
+from __future__ import annotations
+import os
+from typing import Any
+import pandas as pd
+
+
+def _sanitize_cid(x: Any) -> str | None:
+    """
+    Sanitize a PubChem CID value to a clean numeric string.
+
+    Parameters
+    ----------
+    x : Any
+        Raw CID value (int, float, str, or NaN).
+
+    Returns
+    -------
+    str or None
+        Numeric string CID, or None if the value is missing or invalid.
+
+    Examples
+    --------
+    >>> _sanitize_cid(2723949.0)
+    '2723949'
+    >>> _sanitize_cid("  12345  ")
+    '12345'
+    >>> _sanitize_cid(None)
+    """
+    if pd.isna(x):
+        return None
+    try:
+        if isinstance(x, float):
+            x = int(x)
+        s = str(x).strip()
+        s = "".join(ch for ch in s if ch.isdigit())
+        return s or None
+    except Exception:
+        return None
+
+
+def load_table(path: str | os.PathLike) -> pd.DataFrame:
+    """
+    Load a tabular file into a DataFrame.
+
+    Supports CSV, TSV, TXT, XLSX, XLSM, and XLS formats.
+    Automatically detects delimiter for text files; falls back to
+    semicolon separator with latin-1 encoding if auto-detection fails.
+
+    Parameters
+    ----------
+    path : str or os.PathLike
+        Path to the input file.
+
+    Returns
+    -------
+    pd.DataFrame
+        Loaded DataFrame with cleaned 'id' and 'PubChem CID' columns
+        if present.
+
+    Raises
+    ------
+    ValueError
+        If the file format is not supported.
+
+    Examples
+    --------
+    >>> df = load_table("data/database_pubchem.csv")
+    >>> df = load_table("data/database_coconut.xlsx")
+    """
+    ext = os.path.splitext(path)[1].lower()
+    if ext in (".csv", ".tsv", ".txt"):
+        try:
+            df = pd.read_csv(path, engine="python", sep=None, encoding="utf-8-sig")
+        except Exception:
+            df = pd.read_csv(path, sep=";", encoding="latin-1")
+    elif ext in (".xlsx", ".xlsm", ".xls"):
+        df = pd.read_excel(path)
+    else:
+        raise ValueError(f"Unsupported format: {path}")
+
+    if "id" in df.columns:
+        df["id"] = pd.to_numeric(df["id"], errors="coerce").astype("Int64")
+    if "PubChem CID" in df.columns:
+        df["PubChem CID"] = df["PubChem CID"].apply(_sanitize_cid)
+    return df
+
+
+def save_table(df: pd.DataFrame, path: str | os.PathLike) -> None:
+    """
+    Save a DataFrame to a CSV file.
+
+    Parent directories are created automatically if they do not exist.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame to save.
+    path : str or os.PathLike
+        Output file path.
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> df = pd.DataFrame({"SMILES": ["C1=CC=CC=C1"], "SMILES_RDKit": ["C1=CC=CC=C1"]})
+    >>> save_table(df, "results/output.csv")
+    """
+    os.makedirs(os.path.dirname(os.fspath(path)) or ".", exist_ok=True)
+    df.to_csv(path, index=False, encoding="utf-8")