synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Molecule/descriptors.py

@@ -0,0 +1,452 @@
+# synkit/Chem/Molecule/descriptors.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    List,
+    Tuple,
+    Optional,
+    Protocol,
+    runtime_checkable,
+    Dict,
+    Any,
+    Sequence,
+)
+
+from rdkit import Chem
+from rdkit.Chem import AllChem, rdMolDescriptors
+from rdkit import RDLogger
+
+# Keep RDKit quiet in helper scope (best effort)
+try:
+    RDLogger.DisableLog("rdApp.*")
+except Exception:
+    pass
+
+
+@runtime_checkable
+class _MolLike(Protocol):
+    """
+    Minimal protocol for RDKit-like molecules used by this module.
+    """
+
+    def GetNumAtoms(self) -> int: ...
+    def GetAtoms(self): ...
+    def GetAtomWithIdx(self, idx: int): ...
+
+
+# -----------------------------
+# Internal small helpers
+# -----------------------------
+def compute_gasteiger_inplace(mol: Chem.Mol | Any) -> None:
+    """Compatibility helper: compute Gasteiger charges in-place (best-effort).
+    Reintroduced for backward compatibility with code that imports this from
+    synkit.Chem.Molecule.descriptors.
+
+    :param mol: RDKit Mol (or mol-like object) to annotate. Mutates in place.
+    :return: None
+    """
+    try:
+        AllChem.ComputeGasteigerCharges(mol)
+    except Exception:
+        # best-effort: swallow RDKit quirks and continue
+        return
+
+
+def _make_copy_and_sanitize(mol: Chem.Mol | _MolLike, sanitize: bool) -> Chem.Mol:
+    """Make a defensive copy of ``mol`` and optionally sanitize it.
+
+    :param mol: input molecule-like object
+    :param sanitize: whether to call ``Chem.SanitizeMol`` on the copy
+    :return: copied (and possibly sanitized) RDKit Mol
+    """
+    m = Chem.Mol(mol)
+    if sanitize:
+        try:
+            Chem.SanitizeMol(m)
+        except Exception:
+            # best-effort: keep working with the copy even if sanitization fails
+            pass
+    return m
+
+
+def _safe_get_gasteiger_value(atom: Any) -> float:
+    """Extract a Gasteiger charge value from an RDKit atom, tolerant to API variants.
+
+    :param atom: RDKit atom-like object.
+    :return: float value (0.0 on failure).
+    """
+    try:
+        if atom.HasProp("_GasteigerCharge"):
+            try:
+                return float(atom.GetProp("_GasteigerCharge"))
+            except Exception:
+                try:
+                    return float(atom.GetDoubleProp("_GasteigerCharge"))
+                except Exception:
+                    return 0.0
+    except Exception:
+        return 0.0
+    return 0.0
+
+
+def _compute_gasteiger_list(m: Chem.Mol, n_atoms: int) -> List[float]:
+    """
+    Compute per-atom Gasteiger charges for molecule ``m``.
+
+    Best-effort: returns a list of length ``n_atoms`` filled with floats.
+    """
+    gasteiger: List[float] = [0.0] * n_atoms
+    try:
+        AllChem.ComputeGasteigerCharges(m)
+        for a in m.GetAtoms():
+            try:
+                idx = a.GetIdx()
+            except Exception:
+                continue
+            gasteiger[idx] = _safe_get_gasteiger_value(a)
+    except Exception:
+        # On any failure leave zeros
+        pass
+    return gasteiger
+
+
+def _compute_estate_list(m: Chem.Mol, n_atoms: int) -> List[float]:
+    """
+    Compute per-atom EState indices (best-effort). Returns zeros if unavailable.
+    """
+    try:
+        estate_vals = list(
+            __import__("rdkit.Chem.EState", fromlist=["EState"]).EState.EStateIndices(m)
+        )
+        if len(estate_vals) != n_atoms:
+            estate_vals = [0.0] * n_atoms
+    except Exception:
+        estate_vals = [0.0] * n_atoms
+    return estate_vals
+
+
+def _calc_crippen_contribs(m: Chem.Mol) -> Optional[List[Tuple[float, float]]]:
+    """
+    Version-tolerant wrapper for RDKit's Crippen contribution routine.
+
+    Kept small and used by _compute_crippen_lists.
+    """
+    fn = getattr(rdMolDescriptors, "CalcCrippenContribs", None)
+    if fn is None:
+        fn = getattr(rdMolDescriptors, "_CalcCrippenContribs", None)
+    if fn is None:
+        return None
+    try:
+        return list(fn(m))
+    except Exception:
+        return None
+
+
+def _compute_crippen_lists(
+    m: Chem.Mol, n_atoms: int
+) -> Tuple[List[float], List[float]]:
+    """
+    Compute per-atom Crippen (logP, MR) lists. Returns two lists of length n_atoms.
+    """
+    cr_logp: List[float] = [0.0] * n_atoms
+    cr_mr: List[float] = [0.0] * n_atoms
+    cr = _calc_crippen_contribs(m)
+    if cr is not None and len(cr) == n_atoms:
+        try:
+            cr_logp = [float(x[0]) for x in cr]
+            cr_mr = [float(x[1]) for x in cr]
+        except Exception:
+            cr_logp = [0.0] * n_atoms
+            cr_mr = [0.0] * n_atoms
+    return cr_logp, cr_mr
+
+
+def _normalize_vector(vec: Sequence[float], method: Optional[str]) -> List[float]:
+    """
+    Normalize a numeric vector in-place style (returns a new list).
+
+    Supported methods: None, "zscore", "minmax".
+    If method is None or vector length <= 1, returns a float copy of vec.
+    """
+    n = len(vec)
+    if n == 0 or method is None:
+        return [float(x) for x in vec]
+
+    vals = [float(x) for x in vec]
+    if method == "zscore":
+        mean = sum(vals) / n
+        var = sum((x - mean) ** 2 for x in vals) / n
+        std = var**0.5
+        if std == 0.0:
+            return [0.0 for _ in vals]
+        return [(x - mean) / std for x in vals]
+    elif method == "minmax":
+        lo = min(vals)
+        hi = max(vals)
+        if hi == lo:
+            return [0.0 for _ in vals]
+        return [(x - lo) / (hi - lo) for x in vals]
+    else:
+        raise ValueError(f"Unsupported normalization method: {method!r}")
+
+
+def _apply_normalization_to_all(
+    vectors: Dict[str, List[float]], method: Optional[str]
+) -> Dict[str, List[float]]:
+    """
+    Apply normalization ``method`` to all vectors in the dict and return a new dict.
+    """
+    if method is None:
+        # ensure float conversion
+        return {k: [float(x) for x in v] for k, v in vectors.items()}
+    normalized: Dict[str, List[float]] = {}
+    for k, v in vectors.items():
+        normalized[k] = _normalize_vector(v, method)
+    return normalized
+
+
+# -----------------------------
+# Public dataclass + builder
+# -----------------------------
+
+
+@dataclass(frozen=True)
+class PerMolDescriptors:
+    """
+    Immutable container for per-atom descriptor lists.
+
+    :param gasteiger: per-atom Gasteiger charges
+    :param estate: per-atom EState indices
+    :param crippen_logp: per-atom Crippen logP contributions
+    :param crippen_mr: per-atom Crippen MR contributions
+    """
+
+    gasteiger: List[float]
+    estate: List[float]
+    crippen_logp: List[float]
+    crippen_mr: List[float]
+
+    # ----------------- Convenience constructors ---------------------------
+    @classmethod
+    def compute(
+        cls,
+        mol: Chem.Mol | _MolLike,
+        sanitize: bool = True,
+        normalize: Optional[str] = None,
+    ) -> "PerMolDescriptors":
+        """Best-effort compute per-atom descriptors for the given molecule.
+
+        This function delegates work to small helpers for clarity and easier
+        testing. Behavior is identical to the previous implementation.
+
+        :param mol: RDKit molecule (or duck-typed equivalent).
+        :param sanitize: try to sanitize the copied molecule (default True).
+        :param normalize: normalization method: None (default), "zscore", or "minmax".
+        :return: PerMolDescriptors instance.
+        """
+        # Defensive copy and optional sanitization
+        m = _make_copy_and_sanitize(mol, sanitize)
+        n_atoms = m.GetNumAtoms() if hasattr(m, "GetNumAtoms") else 0
+
+        # Compute components (small focused helpers)
+        gasteiger = _compute_gasteiger_list(m, n_atoms)
+        estate_vals = _compute_estate_list(m, n_atoms)
+        cr_logp, cr_mr = _compute_crippen_lists(m, n_atoms)
+
+        # Apply normalization if requested
+        vectors = {
+            "gasteiger": gasteiger,
+            "estate": estate_vals,
+            "crippen_logp": cr_logp,
+            "crippen_mr": cr_mr,
+        }
+        vectors = _apply_normalization_to_all(vectors, normalize)
+
+        return cls(
+            gasteiger=vectors["gasteiger"],
+            estate=vectors["estate"],
+            crippen_logp=vectors["crippen_logp"],
+            crippen_mr=vectors["crippen_mr"],
+        )
+
+    @classmethod
+    def from_smiles(
+        cls, smiles: str, sanitize: bool = True, normalize: Optional[str] = None
+    ) -> "PerMolDescriptors":
+        """Parse SMILES and compute descriptors.
+
+        :param smiles: SMILES string to parse.
+        :param sanitize: try to sanitize the parsed molecule (default True).
+        :param normalize: optional normalization ("zscore" | "minmax" | None).
+        :return: PerMolDescriptors instance.
+        :raises ValueError: if SMILES fails to parse.
+        """
+        m = Chem.MolFromSmiles(smiles)
+        if m is None:
+            raise ValueError(f"Failed to parse SMILES: {smiles!r}")
+        return cls.compute(m, sanitize=sanitize, normalize=normalize)
+
+    # ----------------- Small helpers / serialization ---------------------
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(num_atoms={self.num_atoms}, "
+            f"has_gasteiger={any(v != 0.0 for v in self.gasteiger)})"
+        )
+
+    @property
+    def num_atoms(self) -> int:
+        """Infer atom count from stored lists (prefers gasteiger length).
+
+        :return: inferred atom count.
+        """
+        return len(self.gasteiger)
+
+    def to_dict(self) -> Dict[str, List[float]]:
+        """Convert to a plain dictionary.
+
+        :return: dict with the per-atom lists.
+        """
+        return {
+            "gasteiger": list(self.gasteiger),
+            "estate": list(self.estate),
+            "crippen_logp": list(self.crippen_logp),
+            "crippen_mr": list(self.crippen_mr),
+        }
+
+
+class PerMolDescriptorsBuilder:
+    """Fluent builder for :class:`PerMolDescriptors`.
+
+    .. rubric:: Example
+
+    .. code-block:: python
+
+        desc = (
+            PerMolDescriptorsBuilder(mol)
+            .compute_gasteiger()
+            .compute_estate()
+            .compute_crippen()
+            .normalize("zscore")
+            .build()
+            .descriptor
+        )
+
+    The builder's chainable methods return ``self``; call ``.build()`` then
+    access the final PerMolDescriptors via the ``.descriptor`` property.
+    """
+
+    def __init__(self, mol: Chem.Mol | _MolLike, sanitize: bool = True):
+        """Create a builder for the given molecule.
+
+        :param mol: RDKit Mol or equivalent.
+        :param sanitize: try to sanitize the internal copy (default True).
+        """
+        self._mol = Chem.Mol(mol)
+        self._sanitize = sanitize
+        if sanitize:
+            try:
+                Chem.SanitizeMol(self._mol)
+            except Exception:
+                pass
+
+        n_atoms = self._mol.GetNumAtoms() if hasattr(self._mol, "GetNumAtoms") else 0
+        self._n_atoms = n_atoms
+
+        # Internal working vectors (None until computed)
+        self._gasteiger: Optional[List[float]] = None
+        self._estate: Optional[List[float]] = None
+        self._crippen_logp: Optional[List[float]] = None
+        self._crippen_mr: Optional[List[float]] = None
+        self._normalized_method: Optional[str] = None
+        self._built: Optional[PerMolDescriptors] = None
+
+    # ---------- Chainable compute methods --------------------------------
+    def compute_gasteiger(self) -> "PerMolDescriptorsBuilder":
+        """Compute Gasteiger charges (best-effort) and store internally.
+
+        :return: self (chainable).
+        """
+        self._gasteiger = _compute_gasteiger_list(self._mol, self._n_atoms)
+        self._built = None
+        return self
+
+    def compute_estate(self) -> "PerMolDescriptorsBuilder":
+        """Compute EState indices (best-effort).
+
+        :return: self (chainable).
+        """
+        self._estate = _compute_estate_list(self._mol, self._n_atoms)
+        self._built = None
+        return self
+
+    def compute_crippen(self) -> "PerMolDescriptorsBuilder":
+        """Compute Crippen per-atom contributions (best-effort).
+
+        :return: self (chainable).
+        """
+        cr_logp, cr_mr = _compute_crippen_lists(self._mol, self._n_atoms)
+        self._crippen_logp = cr_logp
+        self._crippen_mr = cr_mr
+        self._built = None
+        return self
+
+    # ---------- Normalization --------------------------------------------
+    def normalize(self, method: Optional[str]) -> "PerMolDescriptorsBuilder":
+        """Normalize any computed vectors using ``method`` ("zscore" | "minmax" | None).
+
+        :param method: normalization method or None to skip.
+        :return: self (chainable).
+        """
+        if method is None:
+            self._normalized_method = None
+            return self
+
+        if method not in ("zscore", "minmax"):
+            raise ValueError(f"Unsupported normalization method: {method!r}")
+
+        if self._gasteiger is not None:
+            self._gasteiger = _normalize_vector(self._gasteiger, method)
+        if self._estate is not None:
+            self._estate = _normalize_vector(self._estate, method)
+        if self._crippen_logp is not None:
+            self._crippen_logp = _normalize_vector(self._crippen_logp, method)
+        if self._crippen_mr is not None:
+            self._crippen_mr = _normalize_vector(self._crippen_mr, method)
+
+        self._normalized_method = method
+        self._built = None
+        return self
+
+    # ---------- Finalize / retrieve -------------------------------------
+    def build(self) -> "PerMolDescriptorsBuilder":
+        """Finalize internal state and prepare the immutable PerMolDescriptors.
+
+        The method stores the result internally and returns ``self``. Use the
+        ``.descriptor`` property to access the final object.
+
+        :return: self
+        """
+        # If a vector wasn't computed, fill with zeros of appropriate length
+        n = self._n_atoms
+        g = self._gasteiger if self._gasteiger is not None else [0.0] * n
+        e = self._estate if self._estate is not None else [0.0] * n
+        crp = self._crippen_logp if self._crippen_logp is not None else [0.0] * n
+        crm = self._crippen_mr if self._crippen_mr is not None else [0.0] * n
+
+        self._built = PerMolDescriptors(
+            gasteiger=g, estate=e, crippen_logp=crp, crippen_mr=crm
+        )
+        return self
+
+    @property
+    def descriptor(self) -> PerMolDescriptors:
+        """Retrieve the built PerMolDescriptors. If not built yet, ``build()`` is
+        called implicitly.
+
+        :return: PerMolDescriptors
+        """
+        if self._built is None:
+            self.build()
+        assert self._built is not None
+        return self._built

synkit/Chem/Molecule/formula.py

@@ -0,0 +1,249 @@
+from typing import Dict, List, Optional, Union, Any
+import re
+from copy import deepcopy
+
+import pandas as pd
+from joblib import Parallel, delayed
+from rdkit import Chem
+from rdkit.Chem import Descriptors, rdMolDescriptors
+
+
+class Formula:
+    """
+    Decompose SMILES into element counts and generate Hill-order formulas / molecular weights using RDKit.
+
+    Main APIs:
+      - :meth:`decompose`: element counts as a dict (e.g., {'C': 6, 'H': 6})
+      - :meth:`hill_formula`: Hill-order formula string
+      - :meth:`mol_weight`: RDKit molecular weight (sums '.' fragments)
+      - :meth:`process_list`: batch over a list of SMILES
+      - :meth:`process_list_dict`: batch over a list of dicts or a pandas DataFrame
+
+    Hill notation rules implemented:
+      - If carbon ('C') present: list 'C', then 'H', then other elements alphabetically.
+      - If no carbon: list all elements alphabetically.
+      - Counts of 1 are omitted (CH3, not C1H3).
+
+    :param n_jobs: Number of parallel jobs for batch processing via joblib. Use 1 to disable parallelism.
+    :param verbose: Verbosity level passed to joblib.Parallel.
+    """
+
+    _element_pattern = re.compile(r"([A-Z][a-z]*)(\d*)")
+
+    def __init__(self, n_jobs: int = 1, verbose: int = 0) -> None:
+        self.n_jobs = int(n_jobs)
+        self.verbose = int(verbose)
+
+    def __repr__(self) -> str:
+        return f"Formula(n_jobs={self.n_jobs}, verbose={self.verbose})"
+
+    # ---------------------------- Core utilities ---------------------------- #
+
+    @staticmethod
+    def _parse_formula_string(formula: str) -> Dict[str, int]:
+        """
+        Parse a molecular formula string into a dict of element counts.
+
+        :param formula: Molecular formula string (e.g., "C6H12O6", "CH4", "H2O").
+        :return: Dict mapping element symbol to integer count.
+        """
+        parts = Formula._element_pattern.findall(formula)
+        return {elem: (int(n) if n else 1) for elem, n in parts}
+
+    @staticmethod
+    def _sum_counts(counts_list: List[Dict[str, int]]) -> Dict[str, int]:
+        """
+        Sum a list of element-count dictionaries.
+
+        :param counts_list: List of dicts of element counts.
+        :return: Single dict with summed counts.
+        """
+        out: Dict[str, int] = {}
+        for d in counts_list:
+            for k, v in d.items():
+                out[k] = out.get(k, 0) + int(v)
+        return out
+
+    # ----------------------------- Single item ------------------------------ #
+
+    def decompose(self, smiles: str) -> Dict[str, int]:
+        """
+        Decompose a SMILES string into element counts using RDKit's CalcMolFormula.
+        Disconnected fragments separated by '.' are handled by summing counts.
+
+        :param smiles: SMILES string (may contain '.' for multiple fragments).
+        :return: Dict of element counts (empty dict if invalid/empty).
+        """
+        if not isinstance(smiles, str) or not smiles.strip():
+            return {}
+
+        per_frag_counts: List[Dict[str, int]] = []
+        for frag in smiles.split("."):
+            mol = Chem.MolFromSmiles(frag)
+            if mol is None:
+                # Ignore invalid fragments
+                continue
+            fstr = rdMolDescriptors.CalcMolFormula(mol)
+            per_frag_counts.append(self._parse_formula_string(fstr))
+
+        return self._sum_counts(per_frag_counts)
+
+    def hill_formula(self, smiles: str) -> str:
+        """
+        Convert a SMILES to a Hill-order formula string.
+
+        Rules:
+          - If 'C' present: C then H then other elements alphabetical.
+          - If no 'C': all elements alphabetical.
+          - Counts of 1 are omitted.
+
+        :param smiles: SMILES string.
+        :return: Hill-order formula string; empty string for invalid/empty SMILES.
+        """
+        counts = self.decompose(smiles)
+        if not counts:
+            return ""
+
+        def fmt(elem: str, n: int) -> str:
+            return f"{elem}{n if n != 1 else ''}"
+
+        if "C" in counts:
+            parts: List[str] = []
+            parts.append(fmt("C", counts.get("C", 0)))
+            if counts.get("H", 0) > 0:
+                parts.append(fmt("H", counts["H"]))
+            others = sorted(k for k in counts.keys() if k not in ("C", "H"))
+            parts.extend(fmt(k, counts[k]) for k in others if counts[k] > 0)
+            # Defensive: drop any accidental zeros
+            parts = [p for p in parts if not p.endswith("0")]
+            return "".join(parts)
+
+        # No carbon present
+        parts = [fmt(k, counts[k]) for k in sorted(counts.keys()) if counts[k] > 0]
+        return "".join(parts)
+
+    def mol_weight(self, smiles: str) -> Optional[float]:
+        """
+        Compute molecular weight using RDKit (sum over '.' fragments).
+
+        :param smiles: SMILES string (may contain '.' fragments).
+        :return: Molecular weight as float, or None if invalid/empty.
+        """
+        if not isinstance(smiles, str) or not smiles.strip():
+            return None
+
+        total = 0.0
+        valid = False
+        for frag in smiles.split("."):
+            mol = Chem.MolFromSmiles(frag)
+            if mol is None:
+                continue
+            total += Descriptors.MolWt(mol)
+            valid = True
+
+        return total if valid else None
+
+    # ----------------------------- Batch APIs -------------------------------- #
+
+    def process_list(
+        self,
+        smiles_list: List[str],
+        what: str = "hill",
+    ) -> List[Union[str, Dict[str, int], float, None]]:
+        """
+        Batch process a list of SMILES.
+
+        :param smiles_list: List of SMILES strings.
+        :param what: One of {'hill', 'decompose', 'molwt'}.
+        :return: List of results corresponding to 'what'.
+                 - 'hill' -> List[str]
+                 - 'decompose' -> List[Dict[str,int]]
+                 - 'molwt' -> List[Optional[float]]
+        :raises ValueError: If 'what' is unsupported.
+        """
+        dispatch = {
+            "hill": self.hill_formula,
+            "decompose": self.decompose,
+            "molwt": self.mol_weight,
+        }
+        if what not in dispatch:
+            raise ValueError(
+                "Unsupported 'what'. Choose from {'hill', 'decompose', 'molwt'}."
+            )
+
+        fn = dispatch[what]
+        if self.n_jobs == 1:
+            return [fn(s) for s in smiles_list]
+        return Parallel(n_jobs=self.n_jobs, verbose=self.verbose)(
+            delayed(fn)(s) for s in smiles_list
+        )
+
+    def process_list_dict(
+        self,
+        records: Union[List[Dict[str, Any]], pd.DataFrame],
+        smiles_key: str = "smiles",
+        out_key: str = "hill",
+        what: str = "hill",
+        copy: bool = True,
+    ) -> List[Dict[str, Any]]:
+        """
+        Batch process a list of dictionaries (or a pandas DataFrame) containing SMILES,
+        and return a list of dictionaries with the computed output appended.
+
+        - If a pandas DataFrame is provided, it is converted to a list of dicts (records).
+        - Input dicts are deep-copied by default to avoid in-place mutation.
+
+        :param records: List[dict] or pandas DataFrame. Each record must contain `smiles_key`.
+        :param smiles_key: Key in each record holding the SMILES string.
+        :param out_key: Output key to store the computed value, e.g. 'hill', 'decompose', 'molwt'.
+        :param what: One of {'hill', 'decompose', 'molwt'} specifying the computation.
+        :param copy: If True, deep-copy each record before adding output.
+        :return: List of dicts with an added `out_key`.
+        :raises KeyError: If a record is missing `smiles_key`.
+        :raises ValueError: If 'what' is unsupported.
+        """
+        if isinstance(records, pd.DataFrame):
+            records = records.to_dict(orient="records")
+
+        if not isinstance(records, list):
+            raise ValueError("`records` must be a list of dicts or a pandas DataFrame.")
+
+        dispatch = {
+            "hill": self.hill_formula,
+            "decompose": self.decompose,
+            "molwt": self.mol_weight,
+        }
+        if what not in dispatch:
+            raise ValueError(
+                "Unsupported 'what'. Choose from {'hill', 'decompose', 'molwt'}."
+            )
+
+        fn = dispatch[what]
+
+        # Extract SMILES list with index mapping
+        smiles_seq: List[str] = []
+        for i, rec in enumerate(records):
+            if not isinstance(rec, dict):
+                raise ValueError(f"Record at index {i} is not a dict.")
+            if smiles_key not in rec:
+                raise KeyError(
+                    f"Record at index {i} missing required key '{smiles_key}'."
+                )
+            smiles_seq.append(rec[smiles_key])
+
+        # Compute results
+        if self.n_jobs == 1:
+            outputs = [fn(s) for s in smiles_seq]
+        else:
+            outputs = Parallel(n_jobs=self.n_jobs, verbose=self.verbose)(
+                delayed(fn)(s) for s in smiles_seq
+            )
+
+        # Attach outputs
+        out_records: List[Dict[str, Any]] = []
+        for rec, val in zip(records, outputs):
+            r = deepcopy(rec) if copy else rec
+            r[out_key] = val
+            out_records.append(r)
+
+        return out_records