synkit 1.6.5__py3-none-win_amd64.whl

synkit/Chem/Fingerprint/fp_calculator.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+from typing import Any, Dict, List
+from joblib import Parallel, delayed
+
+from synkit.IO.debug import configure_warnings_and_logs
+from synkit.Chem.Fingerprint.transformation_fp import TransformationFP
+
+configure_warnings_and_logs(True, True)
+
+
+class FPCalculator:
+    """Calculate fingerprint vectors for chemical reactions represented by
+    SMILES strings.
+
+    :cvar fps: Shared fingerprint engine instance.
+    :vartype fps: TransformationFP
+    :cvar VALID_FP_TYPES: Supported fingerprint type identifiers.
+    :vartype VALID_FP_TYPES: List[str]
+    :param n_jobs: Number of parallel jobs to use for batch processing.
+    :type n_jobs: int
+    :param verbose: Verbosity level for parallel execution.
+    :type verbose: int
+    """
+
+    fps: TransformationFP = TransformationFP()
+    VALID_FP_TYPES: List[str] = [
+        "drfp",
+        "avalon",
+        "maccs",
+        "torsion",
+        "pharm2D",
+        "ecfp2",
+        "ecfp4",
+        "ecfp6",
+        "fcfp2",
+        "fcfp4",
+        "fcfp6",
+        "rdk5",
+        "rdk6",
+        "rdk7",
+        "ap",
+    ]
+
+    def __init__(self, n_jobs: int = 1, verbose: int = 0) -> None:
+        """Initialize the FPCalculator.
+
+        :param n_jobs: Number of parallel jobs to use for fingerprint
+            computation.
+        :type n_jobs: int
+        :param verbose: Verbosity level for the parallel processing.
+        :type verbose: int
+        """
+        self.n_jobs = n_jobs
+        self.verbose = verbose
+
+    def _validate_fp_type(self, fp_type: str) -> None:
+        """Ensure the requested fingerprint type is supported.
+
+        :param fp_type: Fingerprint type identifier to validate.
+        :type fp_type: str
+        :raises ValueError: If `fp_type` is not in VALID_FP_TYPES.
+        """
+        if fp_type not in self.VALID_FP_TYPES:
+            valid = ", ".join(self.VALID_FP_TYPES)
+            raise ValueError(
+                f"Unsupported fingerprint type '{fp_type}'. Supported types: {valid}."
+            )
+
+    @staticmethod
+    def dict_process(
+        data_dict: Dict[str, Any],
+        rsmi_key: str,
+        symbol: str = ">>",
+        fp_type: str = "ecfp4",
+        absolute: bool = True,
+    ) -> Dict[str, Any]:
+        """Compute a fingerprint for a single reaction SMILES entry and add it
+        to the dict.
+
+        :param data_dict: Dictionary containing reaction data.
+        :type data_dict: dict
+        :param rsmi_key: Key in `data_dict` for the reaction SMILES string.
+        :type rsmi_key: str
+        :param symbol: Delimiter between reactant and product in the SMILES.
+        :type symbol: str
+        :param fp_type: Fingerprint type to compute.
+        :type fp_type: str
+        :param absolute: Whether to take absolute values of the fingerprint difference.
+        :type absolute: bool
+        :return: The input dictionary with a new key named by `fp_type`, holding the fingerprint vector.
+        :rtype: dict
+        :raises ValueError: If `rsmi_key` is missing in `data_dict`.
+        """
+        if rsmi_key not in data_dict:
+            raise ValueError(f"Key '{rsmi_key}' not found in data dictionary.")
+        # compute and insert fingerprint
+        vec = FPCalculator.fps.fit(
+            data_dict[rsmi_key], symbols=symbol, fp_type=fp_type, abs=absolute
+        )
+        data_dict[f"{fp_type}"] = vec
+        return data_dict
+
+    def parallel_process(
+        self,
+        data_dicts: List[Dict[str, Any]],
+        rsmi_key: str,
+        symbol: str = ">>",
+        fp_type: str = "ecfp4",
+        absolute: bool = True,
+    ) -> List[Dict[str, Any]]:
+        """Compute fingerprints for a batch of reaction dictionaries in
+        parallel.
+
+        :param data_dicts: List of dictionaries, each containing a reaction SMILES.
+        :type data_dicts: list of dict
+        :param rsmi_key: Key in each dict for the reaction SMILES string.
+        :type rsmi_key: str
+        :param symbol: Delimiter between reactant and product in the SMILES.
+        :type symbol: str
+        :param fp_type: Fingerprint type to compute.
+        :type fp_type: str
+        :param absolute: Whether to take absolute values of the fingerprint difference.
+        :type absolute: bool
+        :return: A list of dictionaries augmented with `fp_{fp_type}` entries.
+        :rtype: list of dict
+        :raises ValueError: If `fp_type` is unsupported or any dict is missing `rsmi_key`.
+        """
+        # Validate fingerprint type once
+        self._validate_fp_type(fp_type)
+
+        # Process in parallel
+        results = Parallel(n_jobs=self.n_jobs, verbose=self.verbose)(
+            delayed(self.dict_process)(dd, rsmi_key, symbol, fp_type, absolute)
+            for dd in data_dicts
+        )
+        return results
+
+    def __str__(self) -> str:
+        """Short string summarizing the calculator configuration.
+
+        :return: A summary of n_jobs and verbosity.
+        :rtype: str
+        """
+        return f"<FPCalculator n_jobs={self.n_jobs} verbose={self.verbose}>"
+
+    def help(self) -> None:
+        """Print details about supported fingerprint types and usage.
+
+        :return: None
+        :rtype: NoneType
+        """
+        print("FPCalculator supports the following fingerprint types:")
+        for t in self.VALID_FP_TYPES:
+            print("  -", t)
+        print(f"Configured for {self.n_jobs} parallel jobs, verbose={self.verbose}")

synkit/Chem/Fingerprint/smiles_featurizer.py

@@ -0,0 +1,258 @@
+"""smiles_featurizer.py
+=======================
+Utility for converting SMILES strings into various cheminformatics fingerprints,
+with optional NumPy‐array conversion.
+
+Key features
+------------
+* **Multi‐fingerprint support** – MACCS, Avalon, ECFP/FCFP, RDKit, AtomPair, Torsion, Pharm2D
+* **SMILES validation** – raises on invalid input
+* **Array conversion** – output as NumPy arrays for ML pipelines
+* **Extensible** – add new methods or override via subclassing
+
+Quick start
+-----------
+>>> from synkit.Chem.Fingerprint.smiles_featurizer import SmilesFeaturizer
+>>> arr = SmilesFeaturizer.featurize_smiles("CCO", "ecfp4", convert_to_array=True)
+"""
+
+from __future__ import annotations
+from typing import Any
+
+import numpy as np
+from rdkit import Chem, DataStructs
+from rdkit.Chem import AllChem, MACCSkeys
+from rdkit.Chem.AtomPairs import Pairs, Torsions
+from rdkit.Avalon import pyAvalonTools as fpAvalon
+from rdkit.Chem.Pharm2D import Gobbi_Pharm2D, Generate
+
+
+class SmilesFeaturizer:
+    """Convert SMILES strings into chemical fingerprint vectors.
+
+    :cvar None: This class only provides static/​class methods and holds no state.
+
+    Supported fingerprint methods:
+      - MACCS keys
+      - Avalon
+      - ECFP/FCFP (Morgan)
+      - RDKit topological
+      - AtomPair
+      - Torsion
+      - 2D Pharmacophore
+
+    Use `featurize_smiles` for one‑line access.
+    """
+
+    def __init__(self) -> None:
+        """Initialize SmilesFeaturizer.
+
+        This class has no instance state; all methods are static or
+        class‑level.
+        """
+        pass
+
+    @staticmethod
+    def smiles_to_mol(smiles: str) -> Chem.Mol:
+        """Convert a SMILES string to an RDKit Mol object.
+
+        :param smiles: The SMILES string to convert.
+        :type smiles: str
+        :return: RDKit Mol object corresponding to the SMILES.
+        :rtype: Chem.Mol
+        :raises ValueError: If the SMILES string is invalid.
+        """
+        mol = Chem.MolFromSmiles(smiles)
+        if mol is None:
+            raise ValueError(f"Invalid SMILES string: {smiles!r}")
+        return mol
+
+    @staticmethod
+    def get_maccs_keys(mol: Chem.Mol) -> Any:
+        """Generate the MACCS keys fingerprint for a molecule.
+
+        :param mol: RDKit Mol object.
+        :type mol: Chem.Mol
+        :return: MACCS keys fingerprint bit vector.
+        :rtype: ExplicitBitVect
+        """
+        return MACCSkeys.GenMACCSKeys(mol)
+
+    @staticmethod
+    def get_avalon_fp(mol: Chem.Mol, nBits: int = 1024) -> Any:
+        """Generate the Avalon fingerprint for a molecule.
+
+        :param mol: RDKit Mol object.
+        :type mol: Chem.Mol
+        :param nBits: Length of the fingerprint vector.
+        :type nBits: int
+        :return: Avalon fingerprint bit vector.
+        :rtype: ExplicitBitVect
+        """
+        return fpAvalon.GetAvalonFP(mol, nBits)
+
+    @staticmethod
+    def get_ecfp(
+        mol: Chem.Mol, radius: int, nBits: int = 2048, useFeatures: bool = False
+    ) -> Any:
+        """Generate a Morgan fingerprint (ECFP or FCFP) for a molecule.
+
+        :param mol: RDKit Mol object.
+        :type mol: Chem.Mol
+        :param radius: Radius for the Morgan algorithm.
+        :type radius: int
+        :param nBits: Length of the fingerprint vector.
+        :type nBits: int
+        :param useFeatures: If True, generate a Feature‑Class
+            fingerprint (FCFP).
+        :type useFeatures: bool
+        :return: Morgan fingerprint bit vector.
+        :rtype: ExplicitBitVect
+        """
+        return AllChem.GetMorganFingerprintAsBitVect(
+            mol, radius, nBits=nBits, useFeatures=useFeatures
+        )
+
+    @staticmethod
+    def get_rdk_fp(
+        mol: Chem.Mol, maxPath: int, fpSize: int = 2048, nBitsPerHash: int = 2
+    ) -> Any:
+        """Generate an RDKit topological fingerprint for a molecule.
+
+        :param mol: RDKit Mol object.
+        :type mol: Chem.Mol
+        :param maxPath: Maximum path length (bonds) to include.
+        :type maxPath: int
+        :param fpSize: Length of the fingerprint vector.
+        :type fpSize: int
+        :param nBitsPerHash: Bits per hash for path hashing.
+        :type nBitsPerHash: int
+        :return: RDKit topological fingerprint bit vector.
+        :rtype: ExplicitBitVect
+        """
+        return Chem.RDKFingerprint(
+            mol, maxPath=maxPath, fpSize=fpSize, nBitsPerHash=nBitsPerHash
+        )
+
+    @staticmethod
+    def mol_to_ap(mol: Chem.Mol) -> Any:
+        """Generate an Atom Pair fingerprint for a molecule.
+
+        :param mol: RDKit Mol object.
+        :type mol: Chem.Mol
+        :return: Atom Pair fingerprint as an integer vector.
+        :rtype: ExplicitBitVect
+        """
+        return Pairs.GetAtomPairFingerprint(mol)
+
+    @staticmethod
+    def mol_to_torsion(mol: Chem.Mol) -> Any:
+        """Generate a Topological Torsion fingerprint for a molecule.
+
+        :param mol: RDKit Mol object.
+        :type mol: Chem.Mol
+        :return: Torsion fingerprint as an integer vector.
+        :rtype: ExplicitBitVect
+        """
+        return Torsions.GetTopologicalTorsionFingerprintAsIntVect(mol)
+
+    @staticmethod
+    def mol_to_pharm2d(mol: Chem.Mol) -> Any:
+        """Generate a 2D Pharmacophore fingerprint for a molecule.
+
+        :param mol: RDKit Mol object.
+        :type mol: Chem.Mol
+        :return: 2D pharmacophore fingerprint bit vector.
+        :rtype: ExplicitBitVect
+        """
+        return Generate.Gen2DFingerprint(mol, Gobbi_Pharm2D.factory)
+
+    @classmethod
+    def featurize_smiles(
+        cls,
+        smiles: str,
+        fingerprint_type: str,
+        convert_to_array: bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """Featurize a SMILES string into a chosen fingerprint, optionally
+        converting to a NumPy array.
+
+        :param smiles: The SMILES string to featurize.
+        :type smiles: str
+        :param fingerprint_type: One of 'maccs', 'avalon', 'ecfp#', 'fcfp#',
+                                 'rdk#', 'ap', 'torsion', 'pharm2d'.
+        :type fingerprint_type: str
+        :param convert_to_array: If True, convert the result to a NumPy array.
+        :type convert_to_array: bool
+        :param kwargs: Additional parameters passed to the chosen method:
+                       - `nBits` for Avalon/ECFP/FCFP
+                       - `radius` for ECFP/FCFP
+                       - `maxPath`, `fpSize`, `nBitsPerHash` for RDKit FP
+        :type kwargs: dict
+        :return: Fingerprint as a NumPy array (if `convert_to_array`) or RDKit bit vector.
+        :rtype: np.ndarray or ExplicitBitVect
+        :raises ValueError: If `fingerprint_type` is unsupported.
+        """
+        mol = cls.smiles_to_mol(smiles)
+
+        ft = fingerprint_type.lower()
+        if ft == "maccs":
+            fp = cls.get_maccs_keys(mol)
+        elif ft == "avalon":
+            fp = cls.get_avalon_fp(mol, nBits=kwargs.get("nBits", 1024))
+        elif ft.startswith("ecfp") or ft.startswith("fcfp"):
+            radius = int(ft[4])
+            use_features = ft.startswith("fcfp")
+            fp = cls.get_ecfp(
+                mol,
+                radius,
+                nBits=kwargs.get("nBits", 2048),
+                useFeatures=use_features,
+            )
+        elif ft.startswith("rdk"):
+            max_path = int(ft[3])
+            fp = cls.get_rdk_fp(
+                mol,
+                maxPath=max_path,
+                fpSize=kwargs.get("fpSize", 2048),
+                nBitsPerHash=kwargs.get("nBitsPerHash", 2),
+            )
+        elif ft == "ap":
+            fp = cls.mol_to_ap(mol)
+        elif ft == "torsion":
+            fp = cls.mol_to_torsion(mol)
+        elif ft == "pharm2d":
+            fp = cls.mol_to_pharm2d(mol)
+        else:
+            raise ValueError(f"Unsupported fingerprint type: {fingerprint_type!r}")
+
+        if convert_to_array:
+            if ft == "pharm2d":
+                bitstr = fp.ToBitString()
+                return np.array([int(b) for b in bitstr], dtype=np.int8)
+            arr = np.zeros((fp.GetNumBits(),), dtype=np.int8)
+            DataStructs.ConvertToNumpyArray(fp, arr)
+            return arr
+
+        return fp
+
+    def __str__(self) -> str:
+        """Short description of the featurizer.
+
+        :return: Class name.
+        :rtype: str
+        """
+        return "<SmilesFeaturizer>"
+
+    def help(self) -> None:
+        """Print supported fingerprint types and usage summary.
+
+        :return: None
+        :rtype: NoneType
+        """
+        print("SmilesFeaturizer supports the following fingerprint types:")
+        print("  - maccs, avalon, ecfp#, fcfp#, rdk#, ap, torsion, pharm2d")
+        print(
+            "Usage: SmilesFeaturizer.featurize_smiles(smiles, fingerprint_type, **kwargs)"
+        )

synkit/Chem/Fingerprint/transformation_fp.py

@@ -0,0 +1,139 @@
+"""transformation_fp.py
+=======================
+Compute reaction‐level fingerprints by combining molecular fingerprints
+of reactants and products, with optional absolute mode and bit‐vector conversion.
+
+Quick start
+-----------
+>>> from synkit.Chem.Fingerprint.transformation_fp import TransformationFP
+>>> arr = TransformationFP().fit('CCO>>CC=O', symbols='>>', fp_type='ecfp4', abs=True)
+>>> bv = TransformationFP().fit('CCO>>CC=O', symbols='>>', fp_type='ecfp4', abs=True, return_array=False)
+"""
+
+from __future__ import annotations
+from typing import Any, Union
+
+import numpy as np
+from rdkit.DataStructs import cDataStructs
+
+from synkit.Chem.Fingerprint.smiles_featurizer import SmilesFeaturizer
+
+
+class TransformationFP:
+    """Calculate reaction fingerprints by featurizing individual molecules and
+    combining them via vector subtraction.
+
+    :cvar None: Stateless utility class.
+    """
+
+    def __init__(self) -> None:
+        """Initialize TransformationFP.
+
+        This class has no instance state; all methods are static or
+        class‐level.
+        """
+        pass
+
+    @staticmethod
+    def convert_arr2vec(arr: np.ndarray) -> cDataStructs.ExplicitBitVect:
+        """Convert a non-negative NumPy array into an RDKit bit vector.
+
+        :param arr: Array of non-negative fingerprint values.
+        :type arr: np.ndarray
+        :return: RDKit bit vector with positive values encoded as 1.
+        :rtype: cDataStructs.ExplicitBitVect
+        :raises ValueError: If the array contains negative or non-finite values.
+        """
+        flat = np.asarray(arr).flatten()
+        if not np.isfinite(flat).all() or (flat < 0).any():
+            raise ValueError("Bit-vector output requires non-negative finite values.")
+        bitstr = "".join("1" if x else "0" for x in flat)
+        return cDataStructs.CreateFromBitString(bitstr)
+
+    def fit(
+        self,
+        reaction_smiles: str,
+        symbols: str,
+        fp_type: str,
+        abs: bool,
+        return_array: bool = True,
+        **kwargs: Any,
+    ) -> Union[np.ndarray, cDataStructs.ExplicitBitVect]:
+        """Generate a reaction fingerprint by subtracting reactant from product
+        fingerprints.
+
+        :param reaction_smiles: Reaction SMILES, reactant and product separated by `symbols`.
+        :type reaction_smiles: str
+        :param symbols: Delimiter between reactants and products in the SMILES string.
+        :type symbols: str
+        :param fp_type: Fingerprint type to use for individual molecules (e.g., 'ecfp4').
+        :type fp_type: str
+        :param abs: If True, take absolute value of the difference vector.
+        :type abs: bool
+        :param return_array: If True, return a NumPy array; otherwise convert to an RDKit bit vector.
+        :type return_array: bool
+        :param kwargs: Additional keyword arguments passed to `SmilesFeaturizer.featurize_smiles`.
+        :type kwargs: Any
+        :return: Reaction fingerprint as a NumPy array or RDKit bit vector.
+        :rtype: Union[np.ndarray, cDataStructs.ExplicitBitVect]
+        :raises ValueError: If `reaction_smiles` is not correctly formatted.
+        """
+        if symbols not in reaction_smiles:
+            raise ValueError(f"Reaction SMILES must contain separator '{symbols}'")
+        react_part, prod_part = reaction_smiles.split(symbols)
+
+        def sum_fps(parts: list[str]) -> np.ndarray:
+            total = None
+            for smi in parts:
+                vec = SmilesFeaturizer.featurize_smiles(smi, fp_type, **kwargs)
+                if total is None:
+                    total = vec.copy() if isinstance(vec, np.ndarray) else vec
+                else:
+                    total = total + vec  # type: ignore
+            return total  # type: ignore
+
+        react_vec = sum_fps(react_part.split("."))
+        prod_vec = sum_fps(prod_part.split("."))
+
+        diff = prod_vec - react_vec  # type: ignore
+        if abs:
+            diff = np.abs(diff)
+
+        if return_array:
+            return diff  # type: ignore
+        return TransformationFP.convert_arr2vec(diff)  # type: ignore
+
+    def help(self) -> None:
+        """Print usage summary for the TransformationFP class.
+
+        :return: None
+        :rtype: NoneType
+        """
+        print("TransformationFP: compute reaction fingerprints via vector subtraction.")
+        print(
+            "  fit(reaction_smiles, symbols, fp_type, abs, return_array=True, **kwargs)"
+        )
+        print("    reaction_smiles: 'R1.R2>>P1.P2' SMILES string")
+        print("    symbols: separator between reactants and products (e.g. '>>')")
+        print(
+            "    fp_type: one of 'maccs', 'avalon', 'ecfp#', 'fcfp#', 'rdk#', 'ap', 'torsion', 'pharm2d'"
+        )
+        print("    abs: take absolute difference (True/False)")
+        print("    return_array: return NumPy array (True) or RDKit bit vector (False)")
+        print("  convert_arr2vec(arr: np.ndarray) -> ExplicitBitVect")
+        print("Example:")
+        print("  tfp = TransformationFP()")
+        print("  arr = tfp.fit('CCO>>CC=O', '>>', 'ecfp4', abs=True)")
+        print(
+            "  bv = tfp.fit('CCO>>CC=O', '>>', 'ecfp4', abs=True, return_array=False)"
+        )
+
+    def __str__(self) -> str:
+        """Short description of the transformer.
+
+        :return: Class name.
+        :rtype: str
+        """
+        return "<TransformationFP>"
+
+    __repr__ = __str__

synkit/Chem/Mapper/README.rst

@@ -0,0 +1,43 @@
+Mapper source layout
+====================
+
+Public entry points are exported from ``synkit.Chem.Mapper``. The selected
+native mapper uses PABS with SLAP starting mappings. Use the main documentation for the
+`user guide <../../../doc/mapper.rst>`_ and
+`implementation notes <../../../doc/mapper/implementation.rst>`_.
+
+::
+
+   Mapper/
+     __init__.py          Public exports
+     mapper.py            Method selection and common results
+     reaction_search.py   Reaction preparation and output
+     _compat.py           Historical import and command aliases
+     chem/                Chemistry conversion
+     graph/               Graph models and symmetry helpers
+     io/                  Mapping serialization
+     solvers/
+       slap/              Python heuristic
+       exact/             Python exact methods and C++ graph bindings
+       native/            Shared C++ bindings and builds
+         cpp/             C++ sources, headers, CMake and examples
+     reporting/           Enumeration analysis and spectra
+     validation/          Reference and mapping checks
+     adapters/            Prediction seeds and executable templates
+
+All solver implementations live under ``solvers/``. Native source and bindings
+stay together in ``solvers/native/``. The user guide and implementation notes live in ``doc/mapper/``.
+
+Platform wheels bundle the shared C++ library. Source checkouts use an explicit
+build::
+
+   from synkit.Chem.Mapper import Mapper, map_reaction_implicit
+   from synkit.Chem.Mapper.solvers.native.build import build_mapper_native
+
+   library = build_mapper_native("build/mapper-core")
+   result = map_reaction_implicit("CCO>>COC", library_path=library)
+   mapper = Mapper("native", solver="pabs", library_path=library)
+
+The old ``exact``, ``slap`` and ``_native`` import paths remain aliases to the
+same implementations. New code uses the ``solvers`` paths. The historical
+``synkit.Chem.Reaction.Mapper`` namespace is also supported.