molfp 0.2.0__py3-none-any.whl

molfp/__init__.py

@@ -0,0 +1,103 @@
+"""
+molfp — Native Python/RDKit molecular fingerprint library.
+
+13 fingerprint types + 7 novel analysis modules:
+  - explain: bit-level explainability (which atoms set which bits)
+  - annotate: chemical names/descriptions for every bit
+  - collisions: hash collision detection for hashed FPs
+  - similarity: similarity distribution diagnostics
+  - cliffs: activity cliff detection
+  - fusion: consensus fingerprint construction
+  - isomers: structural isomer awareness
+
+Usage:
+    import molfp
+
+    # Compute fingerprints
+    fp = molfp.maccs("CCO")
+    fps = molfp.maccs_batch(["CCO", "c1ccccc1"])
+
+    # Explain which atoms set which bits
+    molfp.explain("CCO", "ecfp4")
+
+    # Get chemical annotation for a bit
+    molfp.annotate("substructure", 1)
+
+    # Detect hash collisions
+    molfp.detect_collisions("c1ccccc1", "ecfp4")
+
+    # Find activity cliffs
+    molfp.activity_cliffs(smiles, activities, "ecfp4")
+
+    # Build optimal fusion fingerprint
+    molfp.fuse(smiles, activities, ["ecfp4", "maccs", "pubchem"])
+
+    # Check discriminative power
+    molfp.discriminative_power(smiles)
+"""
+
+__version__ = "0.2.0"
+
+# ── Core fingerprint functions ────────────────────────────────────────────────
+from .fingerprints import (
+    maccs,
+    ecfp4,
+    pubchem,
+    substructure,
+    substructure_count,
+    klekota_roth,
+    klekota_roth_count,
+    estate,
+    atompairs2d,
+    atompairs2d_count,
+    rdk,
+    rdk_ext,
+    rdk_graphonly,
+    maccs_batch,
+    ecfp4_batch,
+    pubchem_batch,
+    substructure_batch,
+    substructure_count_batch,
+    klekota_roth_batch,
+    klekota_roth_count_batch,
+    estate_batch,
+    atompairs2d_batch,
+    atompairs2d_count_batch,
+    rdk_batch,
+    rdk_ext_batch,
+    rdk_graphonly_batch,
+    available,
+    get,
+    compute_batch,
+    FINGERPRINTS,
+)
+
+# ── Novel analysis modules ────────────────────────────────────────────────────
+from .explain import explain
+from .annotate import annotate, get_annotations
+from .collisions import detect_collisions, collision_rate, collision_pairs
+from .similarity import similarity_matrix, similarity_profile, compare_fps
+from .cliffs import activity_cliffs, cliff_summary
+from .fusion import fuse, complementarity
+from .isomers import find_identical_fps, discriminative_power, isomer_sensitivity
+from .bioactivity import (
+    classify, class_similarity, enriched_bits, depleted_bits, profile as bioactivity_profile,
+)
+from .standardize import (
+    standardize_mol, standardize_smiles, get_inchikey,
+    desalt, neutralize, canonicalize_tautomer,
+    standardize_batch, deduplicate, preprocess,
+)
+from .sklearn import (
+    MACCSTransformer, ECFPTransformer, PubChemTransformer,
+    SubstructureTransformer, SubstructureCountTransformer,
+    KlekotaRothTransformer, KlekotaRothCountTransformer,
+    EStateTransformer, AtomPairs2DTransformer, AtomPairs2DCountTransformer,
+    RDKTransformer, RDKExtTransformer, RDKGraphOnlyTransformer,
+    get_transformer, TRANSFORMERS,
+)
+from .interpret import interpret, interpret_molecule, compare_molecules
+from .distance import (
+    tanimoto, dice, cosine, sokal_michener, russel_rao,
+    distance, pairwise, pairwise_distance, available_metrics,
+)

molfp/_pubchem.py

@@ -0,0 +1,157 @@
+"""
+PubChem/CACTVS fingerprint (881 bits) — internal implementation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rdkit import Chem
+
+from . import _smarts
+
+
+_ELEMENT_TO_ANUM = {}
+for _z in range(1, 119):
+    _sym = Chem.GetPeriodicTable().GetElementSymbol(_z)
+    _ELEMENT_TO_ANUM[_sym] = _z
+
+
+def _classify_rings(mol):
+    """Classify SSSR rings by size and type. Returns {(type, size): count}."""
+    ri = mol.GetRingInfo()
+    counts = {}
+
+    for ring in ri.AtomRings():
+        size = len(ring)
+        atomic_nums = [mol.GetAtomWithIdx(i).GetAtomicNum() for i in ring]
+
+        all_carbon = all(z == 6 for z in atomic_nums)
+        has_nitrogen = any(z == 7 for z in atomic_nums)
+        has_hetero = any(z not in (1, 6) for z in atomic_nums)
+
+        bonds = []
+        for i in range(size):
+            b = mol.GetBondBetweenAtoms(ring[i], ring[(i + 1) % size])
+            if b:
+                bonds.append(b)
+
+        is_aromatic = all(b.GetIsAromatic() for b in bonds)
+        is_saturated = all(b.GetBondType() == Chem.BondType.SINGLE for b in bonds)
+        is_sat_or_arom = is_saturated or is_aromatic
+        is_unsaturated = not is_saturated and not is_aromatic
+
+        counts[("countAnyRing", size)] = counts.get(("countAnyRing", size), 0) + 1
+
+        if is_sat_or_arom:
+            if all_carbon:
+                k = ("countSaturatedOrAromaticCarbonOnlyRing", size)
+                counts[k] = counts.get(k, 0) + 1
+            if has_nitrogen:
+                k = ("countSaturatedOrAromaticNitrogenContainingRing", size)
+                counts[k] = counts.get(k, 0) + 1
+            if has_hetero:
+                k = ("countSaturatedOrAromaticHeteroContainingRing", size)
+                counts[k] = counts.get(k, 0) + 1
+
+        if is_unsaturated:
+            if all_carbon:
+                k = ("countUnsaturatedCarbonOnlyRing", size)
+                counts[k] = counts.get(k, 0) + 1
+            if has_nitrogen:
+                k = ("countUnsaturatedNitrogenContainingRing", size)
+                counts[k] = counts.get(k, 0) + 1
+            if has_hetero:
+                k = ("countUnsaturatedHeteroContainingRing", size)
+                counts[k] = counts.get(k, 0) + 1
+
+        if is_aromatic:
+            counts[("countAromaticRing", "any")] = counts.get(("countAromaticRing", "any"), 0) + 1
+            if has_hetero:
+                counts[("countHeteroAromaticRing", "any")] = counts.get(("countHeteroAromaticRing", "any"), 0) + 1
+
+    return counts
+
+
+def load_definitions() -> tuple[list[tuple[int, int, int]], list[tuple[int, str, int | str, int]], list[tuple[int, Chem.rdchem.Mol]]]:
+    """Parse pubchem_fingerprint_definitions.txt.
+
+    Returns (section1, section2, smarts_bits).
+    """
+    path = _smarts._data_path("pubchem_fingerprint_definitions.txt")
+    section1, section2, smarts_bits = [], [], []
+    current_section = None
+
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.rstrip()
+            if not line or line.startswith("#") or line.startswith("====="):
+                continue
+            if "SECTION 1" in line:
+                current_section = 1; continue
+            elif "SECTION 2" in line:
+                current_section = 2; continue
+            elif any(f"SECTION {i}" in line for i in range(3, 8)):
+                current_section = "smarts"; continue
+            if line.startswith("Format:") or line.startswith("Ring type") or line.startswith("  "):
+                continue
+
+            parts = line.split()
+            if not parts or not parts[0].isdigit():
+                continue
+            bit = int(parts[0])
+
+            if current_section == 1:
+                anum = _ELEMENT_TO_ANUM.get(parts[1], 0)
+                section1.append((bit, anum, int(parts[3])))
+            elif current_section == 2:
+                ring_size = parts[2] if parts[2] == "any" else int(parts[2])
+                section2.append((bit, parts[1], ring_size, int(parts[4])))
+            elif current_section == "smarts" and len(parts) > 1:
+                pat = Chem.MolFromSmarts(parts[1])
+                if pat is not None:
+                    smarts_bits.append((bit, pat))
+
+    return section1, section2, smarts_bits
+
+
+class PubChemComputer:
+    """Lazy-loaded PubChem FP computer."""
+
+    def __init__(self):
+        self._loaded = False
+        self._s1 = self._s2 = self._smarts = None
+
+    def _ensure_loaded(self):
+        if not self._loaded:
+            self._s1, self._s2, self._smarts = load_definitions()
+            self._loaded = True
+
+    def compute(self, mol: Chem.rdchem.Mol) -> list[int]:
+        """Compute 881-bit PubChem FP for an RDKit Mol. Returns list of ints."""
+        self._ensure_loaded()
+        bits = [0] * 881
+
+        # Section 1: element counts
+        elem_counts = {}
+        for atom in mol.GetAtoms():
+            anum = atom.GetAtomicNum()
+            elem_counts[anum] = elem_counts.get(anum, 0) + 1
+        elem_counts[1] = sum(a.GetTotalNumHs() for a in mol.GetAtoms())
+
+        for bit, anum, threshold in self._s1:
+            if elem_counts.get(anum, 0) >= threshold:
+                bits[bit] = 1
+
+        # Section 2: ring counts
+        ring_counts = _classify_rings(mol)
+        for bit, ring_type, ring_size, threshold in self._s2:
+            if ring_counts.get((ring_type, ring_size), 0) >= threshold:
+                bits[bit] = 1
+
+        # Sections 3-7: SMARTS
+        for bit, pat in self._smarts:
+            if mol.HasSubstructMatch(pat):
+                bits[bit] = 1
+
+        return bits

molfp/_smarts.py

@@ -0,0 +1,105 @@
+"""
+SMARTS pattern loading, compilation, and matching utilities.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import os
+
+from rdkit import Chem
+
+
+def _data_path(filename):
+    """Resolve path to a data file in molfp/data/."""
+    return os.path.join(os.path.dirname(__file__), "data", filename)
+
+
+def load_smarts_file(filename: str) -> list[tuple[str, str]]:
+    """Load SMARTS patterns from a data file. Returns list of (name, smarts) tuples."""
+    path = _data_path(filename)
+    patterns = []
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if ":" in line and not line.startswith("["):
+                name, smarts = line.split(":", 1)
+                patterns.append((name.strip(), smarts.strip()))
+            else:
+                patterns.append((f"bit_{len(patterns)}", line))
+    return patterns
+
+
+def load_plain_smarts(filename: str) -> list[tuple[str, str]]:
+    """Load a file where each non-empty, non-comment line is a SMARTS string."""
+    path = _data_path(filename)
+    patterns = []
+    with open(path, encoding="utf-8") as f:
+        for i, line in enumerate(f):
+            line = line.strip()
+            if line and not line.startswith("#"):
+                patterns.append((f"bit_{i}", line))
+    return patterns
+
+
+def compile_smarts(patterns: list[tuple[str, str]]) -> tuple[list[tuple[str, Chem.rdchem.Mol | _SaltMatcher]], list[tuple[str, str]]]:
+    """Compile (name, smarts) list. Returns (compiled, failed).
+
+    Handles special patterns like the Salt disconnected-charge pattern.
+    """
+    compiled = []
+    failed = []
+    for name, smarts in patterns:
+        pat = Chem.MolFromSmarts(smarts)
+        if pat is not None:
+            compiled.append((name, pat))
+        elif _is_salt_pattern(smarts):
+            compiled.append((name, _SaltMatcher()))
+        else:
+            failed.append((name, smarts))
+    return compiled, failed
+
+
+def _is_salt_pattern(smarts):
+    return "[-1,-2,-3,-4,-5,-6,-7" in smarts and "+1,+2,+3,+4,+5,+6,+7" in smarts
+
+
+class _SaltMatcher:
+    pass
+
+
+def _check_salt(mol):
+    has_neg = has_pos = False
+    for atom in mol.GetAtoms():
+        fc = atom.GetFormalCharge()
+        if fc < 0:
+            has_neg = True
+        if fc > 0:
+            has_pos = True
+        if has_neg and has_pos:
+            return True
+    return False
+
+
+def match_binary(mol: Chem.rdchem.Mol, compiled_patterns: list[tuple[str, Chem.rdchem.Mol | _SaltMatcher]]) -> list[int]:
+    """Match patterns, return list of 0/1 ints."""
+    result = []
+    for _, pat in compiled_patterns:
+        if isinstance(pat, _SaltMatcher):
+            result.append(1 if _check_salt(mol) else 0)
+        else:
+            result.append(1 if mol.HasSubstructMatch(pat) else 0)
+    return result
+
+
+def match_count(mol: Chem.rdchem.Mol, compiled_patterns: list[tuple[str, Chem.rdchem.Mol | _SaltMatcher]]) -> list[int]:
+    """Count pattern matches, return list of ints."""
+    result = []
+    for _, pat in compiled_patterns:
+        if isinstance(pat, _SaltMatcher):
+            result.append(1 if _check_salt(mol) else 0)
+        else:
+            result.append(len(mol.GetSubstructMatches(pat)))
+    return result

molfp/annotate.py

@@ -0,0 +1,198 @@
+"""
+Chemical annotation: human-readable names and descriptions for fingerprint bits.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rdkit import Chem
+from rdkit.Chem import MACCSkeys
+
+from . import _smarts
+from .fingerprints import _get_substructure_patterns, _get_kr_patterns, _get_pubchem_computer
+
+_annotation_cache = {}
+
+
+def annotate(fp_type: str, bit_idx: int) -> dict[str, Any]:
+    """Get human-readable annotation for a specific fingerprint bit.
+
+    Args:
+        fp_type: fingerprint name (e.g. "substructure", "pubchem", "maccs")
+        bit_idx: bit index (0-based)
+
+    Returns:
+        dict with keys: name, smarts (if applicable), description, category
+    """
+    annotations = get_annotations(fp_type)
+    if bit_idx not in annotations:
+        return {"name": f"bit_{bit_idx}", "description": "Unknown bit", "category": "unknown"}
+    return annotations[bit_idx]
+
+
+def get_annotations(fp_type: str) -> dict[int, dict[str, Any]]:
+    """Get all annotations for a fingerprint type. Returns {bit_idx: annotation_dict}."""
+    if fp_type in _annotation_cache:
+        return _annotation_cache[fp_type]
+
+    dispatch = {
+        "maccs": _annotate_maccs,
+        "substructure": _annotate_substructure,
+        "substructure_count": _annotate_substructure,
+        "klekota_roth": _annotate_kr,
+        "klekota_roth_count": _annotate_kr,
+        "pubchem": _annotate_pubchem,
+        "estate": _annotate_estate,
+        "ecfp4": _annotate_hashed,
+        "atompairs2d": _annotate_hashed,
+        "atompairs2d_count": _annotate_hashed,
+        "rdk": _annotate_hashed,
+        "rdk_ext": _annotate_hashed,
+        "rdk_graphonly": _annotate_hashed,
+    }
+    if fp_type not in dispatch:
+        raise KeyError(f"Unknown fp_type: {fp_type}")
+
+    result = dispatch[fp_type](fp_type)
+    _annotation_cache[fp_type] = result
+    return result
+
+
+def _annotate_maccs(fp_type):
+    annotations = {}
+    patts = MACCSkeys.smartsPatts
+    for bit_idx in range(166):
+        rdkit_bit = bit_idx + 1
+        if rdkit_bit in patts:
+            entry = patts[rdkit_bit]
+            sma = entry[0] if len(entry) > 0 else ""
+            desc = entry[1] if len(entry) > 1 else ""
+            if not isinstance(desc, str):
+                desc = f"MACCS key {rdkit_bit}"
+            annotations[bit_idx] = {
+                "name": f"MACCS_{rdkit_bit}",
+                "smarts": sma,
+                "description": desc if desc else f"MACCS key {rdkit_bit}",
+                "category": "substructure",
+            }
+        else:
+            annotations[bit_idx] = {
+                "name": f"MACCS_{rdkit_bit}",
+                "description": f"MACCS key {rdkit_bit} (no public definition)",
+                "category": "substructure",
+            }
+    return annotations
+
+
+def _annotate_substructure(fp_type):
+    patterns = _get_substructure_patterns()
+    annotations = {}
+    for i, (name, pat) in enumerate(patterns):
+        smarts = ""
+        if isinstance(pat, _smarts._SaltMatcher):
+            smarts = "([-charge]).([+charge])"
+        else:
+            smarts = Chem.MolToSmarts(pat) if pat else ""
+        annotations[i] = {
+            "name": name,
+            "smarts": smarts,
+            "description": f"Inte:Ligand functional group: {name}",
+            "category": "functional_group",
+        }
+    return annotations
+
+
+def _annotate_kr(fp_type):
+    raw = _smarts.load_plain_smarts("klekota_roth_smarts.txt")
+    annotations = {}
+    for i, (name, smarts_str) in enumerate(raw):
+        annotations[i] = {
+            "name": f"KRFP{i + 1}",
+            "smarts": smarts_str,
+            "description": f"Klekota-Roth substructure {i + 1}",
+            "category": "bioactivity_substructure",
+        }
+    return annotations
+
+
+def _annotate_pubchem(fp_type):
+    computer = _get_pubchem_computer()
+    computer._ensure_loaded()
+    annotations = {}
+
+    for bit, anum, threshold in computer._s1:
+        sym = Chem.GetPeriodicTable().GetElementSymbol(anum) if anum > 0 else "?"
+        annotations[bit] = {
+            "name": f"PubchemFP{bit}",
+            "description": f"Element count: {sym} >= {threshold}",
+            "category": "element_count",
+        }
+
+    for bit, ring_type, ring_size, threshold in computer._s2:
+        annotations[bit] = {
+            "name": f"PubchemFP{bit}",
+            "description": f"Ring: {ring_type} size={ring_size} >= {threshold}",
+            "category": "ring_count",
+        }
+
+    for bit, pat in computer._smarts:
+        smarts = Chem.MolToSmarts(pat) if pat else ""
+        section = "3-7"
+        if 263 <= bit <= 326:
+            section = "3 (atom pairs)"
+        elif 327 <= bit <= 415:
+            section = "4 (nearest neighbors)"
+        elif 416 <= bit <= 459:
+            section = "5 (detailed neighbors)"
+        elif 460 <= bit <= 712:
+            section = "6 (bond-specific)"
+        elif 713 <= bit <= 880:
+            section = "7 (ring substitution)"
+        annotations[bit] = {
+            "name": f"PubchemFP{bit}",
+            "smarts": smarts,
+            "description": f"Section {section} substructure",
+            "category": "smarts",
+        }
+
+    return annotations
+
+
+def _annotate_estate(fp_type):
+    from rdkit.Chem.EState import AtomTypes as AT
+    AT.BuildPatts()
+    patterns = AT.esPatterns
+
+    atom_type_names = [
+        "sLi","ssBe","ssssBe","ssBH","sssB","ssssB",
+        "sCH3","dCH2","ssCH2","tCH","dsCH","aaCH","sssCH","ddC","tsC",
+        "dssC","aasC","aaaC","ssssC","sNH3","sNH2","ssNH2","dNH","ssNH",
+        "aaNH","tN","sssNH","dsN","aaN","sssN","ddsN","aasN","ssssN",
+        "sOH","dO","ssO","aaO","sF","sSiH3","ssSiH2","sssSiH","ssssSi",
+        "sPH2","ssPH","sssP","dsssP","sssssP","sSH","dS","ssS","aaS",
+        "dssS","ddssS","ssssssS","sCl","sGeH3","ssGeH2","sssGeH","ssssGe",
+        "sAsH2","ssAsH","sssAs","sssdAs","sssssAs","sSeH","dSe","ssSe",
+        "aaSe","dssSe","ddssSe","sBr","sSnH3","ssSnH2","sssSnH","ssssSn",
+        "sI","sPbH3","ssPbH2","sssPbH","ssssPb",
+    ]
+    annotations = {}
+    for i in range(79):
+        name = atom_type_names[i] if i < len(atom_type_names) else f"EState_{i}"
+        smarts = ""
+        if patterns and i < len(patterns):
+            _, pat = patterns[i]
+            if pat is not None:
+                smarts = Chem.MolToSmarts(pat)
+        annotations[i] = {
+            "name": name,
+            "smarts": smarts,
+            "description": f"E-State atom type: {name}",
+            "category": "atom_type",
+        }
+    return annotations
+
+
+def _annotate_hashed(fp_type):
+    """For hashed fingerprints, bits don't have fixed meanings."""
+    return {}  # empty — use explain() with a specific molecule instead