synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Feature/Fingerprint/wl_rxn_fps.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+import networkx as nx
+from collections import Counter
+from hashlib import blake2b
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any, Union
+import numpy as np
+from synkit.IO import rsmi_to_graph
+
+
+@dataclass
+class WLRnxFps:
+    """
+    Weisfeiler-Lehman Reaction Fingerprint Sketch (NetworkX).
+
+    :param radius: number of WL refinement iterations
+    :type  radius: int
+    :param size: bit budget for the parity sketch
+    :type  size: int
+    :param to_array: whether to return fingerprint as NumPy array
+    :type  to_array: bool
+
+    Usage example:
+    >>> rsmi = ('COc1cc(NC(N)=S)ccc1-n1cnc(C)c1.O=C1C(Br)CCCC1c1ccc(Cl)cc1Cl'
+    >>> +'>>Br.COc1cc(Nc2nc3c(s2)CCCC3c2ccc(Cl)cc2Cl)ccc1-n1cnc(C)c1.O')
+    >>> react, prod = rsmi_to_graph(rsmi, drop_non_aam=False, use_index_as_atom_map=False)
+    >>> fps = WLRnxFps(radius=2, size=1024, to_array=False).fit(react, prod)
+    >>> bits = fps.fingerprint
+    """
+
+    radius: int = 2
+    size: int = 1024
+    to_array: bool = False
+
+    _tokens_R: Optional[Counter] = field(init=False, default=None)
+    _tokens_P: Optional[Counter] = field(init=False, default=None)
+    _delta: Optional[Counter] = field(init=False, default=None)
+    _support: Optional[List[int]] = field(init=False, default=None)
+    _fingerprint: Optional[Union[List[int], np.ndarray]] = field(
+        init=False, default=None
+    )
+
+    def fit(self, react: nx.Graph, prod: nx.Graph) -> WLRnxFps:
+        """Compute WL tokens for reactant and product graphs, then build parity sketch on Δ-support.
+
+        :param react: reactant graph with node attrs 'element','aromatic','hcount','charge'
+        :type react: nx.Graph
+        :param prod: product graph with same node/edge attrs
+        :type prod: nx.Graph
+        :return: self
+        :rtype: WLRnxFps
+        :raises ValueError: if size is not positive
+        """
+        if self.size <= 0:
+            raise ValueError("size must be a positive integer")
+
+        def wl_tokens(G: nx.Graph) -> Counter:
+            labels: Dict[int, int] = {}
+            for n, attrs in G.nodes(data=True):
+                atom_tuple = (
+                    attrs.get("element"),
+                    bool(attrs.get("aromatic", False)),
+                    int(attrs.get("charge", 0)),
+                    int(attrs.get("hcount", 0)),
+                    G.degree(n),
+                )
+                labels[n] = _h64(("init", atom_tuple))
+            cnt = Counter(labels.values())
+            for k in range(1, self.radius + 1):
+                new_labels: Dict[int, int] = {}
+                for n in G.nodes():
+                    neigh = []
+                    for m in G.neighbors(n):
+                        bond_order = float(G.edges[n, m].get("order", 1.0))
+                        neigh.append((_h64(("bond", bond_order)), labels[m]))
+                    neigh.sort()
+                    new_labels[n] = _h64(("wl", k, labels[n], tuple(neigh)))
+                labels = new_labels
+                cnt.update(labels.values())
+            return cnt
+
+        TR = wl_tokens(react)
+        TP = wl_tokens(prod)
+
+        Delta = Counter(TP)
+        for h, v in TR.items():
+            Delta[h] -= v
+            if Delta[h] == 0:
+                del Delta[h]
+
+        support = list(Delta.keys())
+        self._tokens_R = TR
+        self._tokens_P = TP
+        self._delta = Delta
+        self._support = support
+
+        bits = np.zeros(self.size, dtype=int) if self.to_array else [0] * self.size
+        for h in support:
+            idx = h % self.size
+            if self.to_array:
+                bits[idx] ^= 1
+            else:
+                bits[idx] = bits[idx] ^ 1
+        self._fingerprint = bits
+
+        return self
+
+    @classmethod
+    def from_rsmi(
+        cls,
+        rsmi: str,
+        radius: int = 2,
+        size: int = 1024,
+        to_array: bool = False,
+        drop_non_aam: bool = False,
+        use_index_as_atom_map: bool = False,
+    ) -> WLRnxFps:
+        """Build WLRnxFps directly from a reaction SMILES string.
+
+        :param rsmi: reaction SMILES string
+        :type rsmi: str
+        :param radius: number of WL refinement iterations
+        :type radius: int
+        :param size: bit budget for the parity sketch
+        :type size: int
+        :param to_array: return fingerprint as NumPy array if True
+        :type to_array: bool
+        :param drop_non_aam: drop atoms without atom-atom mapping
+        :type drop_non_aam: bool
+        :param use_index_as_atom_map: interpret node indices as atom map numbers
+        :type use_index_as_atom_map: bool
+        :return: fitted WLRnxFps instance
+        :rtype: WLRnxFps
+        :raises ValueError: on invalid SMILES parsing
+        """
+        try:
+            react, prod = rsmi_to_graph(
+                rsmi,
+                drop_non_aam=drop_non_aam,
+                use_index_as_atom_map=use_index_as_atom_map,
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to parse rsmi: {e}")
+
+        return cls(radius=radius, size=size, to_array=to_array).fit(react, prod)
+
+    @property
+    def tokens_R(self) -> Counter:
+        """:return: WL token counts for reactant
+        :rtype: Counter
+        :raises AttributeError: if fit() has not been called
+        """
+        if self._tokens_R is None:
+            raise AttributeError("Call fit() before accessing tokens_R")
+        return self._tokens_R
+
+    @property
+    def tokens_P(self) -> Counter:
+        """:return: WL token counts for product
+        :rtype: Counter
+        :raises AttributeError: if fit() has not been called
+        """
+        if self._tokens_P is None:
+            raise AttributeError("Call fit() before accessing tokens_P")
+        return self._tokens_P
+
+    @property
+    def delta(self) -> Counter:
+        """:return: Signed token difference (product - reactant)
+        :rtype: Counter
+        :raises AttributeError: if fit() has not been called
+        """
+        if self._delta is None:
+            raise AttributeError("Call fit() before accessing delta")
+        return self._delta
+
+    @property
+    def support(self) -> List[int]:
+        """:return: Tokens with non-zero delta
+        :rtype: List[int]
+        :raises AttributeError: if fit() has not been called
+        """
+        if self._support is None:
+            raise AttributeError("Call fit() before accessing support")
+        return self._support
+
+    @property
+    def fingerprint(self) -> Union[List[int], np.ndarray]:
+        """:return: Parity sketch bit vector (0/1)
+        :rtype: Union[List[int], numpy.ndarray]
+        :raises AttributeError: if fit() has not been called
+        """
+        if self._fingerprint is None:
+            raise AttributeError("Call fit() before accessing fingerprint")
+        return self._fingerprint
+
+    def __repr__(self) -> str:
+        support_len = len(self._support) if self._support is not None else 0
+        return (
+            f"<WLRnxFps radius={self.radius} size={self.size} "
+            f"support={support_len} to_array={self.to_array}>"
+        )
+
+    def help(self) -> None:
+        """Print usage examples and class docstring.
+
+        :return: None
+        """
+        print(self.__doc__)
+
+
+def _h64(obj: Any) -> int:
+    """Compute a stable 64-bit hash of an object.
+
+    :param obj: any hashable representation
+    :type obj: Any
+    :return: 64-bit integer hash
+    :rtype: int
+    """
+    h = blake2b(digest_size=8)
+    h.update(repr(obj).encode("utf-8"))
+    return int.from_bytes(h.digest(), "little")

synkit/Graph/Feature/__init__.py

@@ -0,0 +1,5 @@
+from .wl_hash import WLHash
+from .morgan_fps import MorganFPs
+from .path_fps import PathFPs
+
+__all__ = ["WLHash", "MorganFPs", "PathFPs"]

synkit/Graph/Feature/graph_descriptors.py

@@ -0,0 +1,323 @@
+import networkx as nx
+from joblib import Parallel, delayed
+from typing import List, Dict, Any, Union
+from collections import Counter, OrderedDict
+from synkit.IO.debug import setup_logging
+from synkit.Graph.Feature.graph_signature import GraphSignature
+
+logger = setup_logging()
+
+
+class GraphDescriptor:
+    def __init__(self) -> None:
+        pass
+
+    @staticmethod
+    def is_graph_empty(graph: Union[nx.Graph, dict, list, Any]) -> bool:
+        """Determine if a graph representation is empty.
+
+        :param graph: A graph representation which can be
+                      a NetworkX graph, a dictionary, a list, or an object with an 'is_empty' method.
+        :type graph: Union[nx.Graph, dict, list, Any]
+
+        :return: True if the graph is empty, False otherwise.
+        :rtype: bool
+
+        :raises TypeError: If the graph representation is not supported.
+        """
+        if isinstance(graph, nx.Graph):
+            return graph.number_of_nodes() == 0
+        elif isinstance(graph, dict):
+            return len(graph) == 0
+        elif isinstance(graph, list):
+            return all(len(row) == 0 for row in graph)
+        elif hasattr(graph, "is_empty"):
+            return graph.is_empty()
+        else:
+            raise TypeError("Unsupported graph representation")
+
+    @staticmethod
+    def is_acyclic_graph(G: nx.Graph) -> bool:
+        """Determines if the given graph is acyclic.
+
+        :param G: The graph to be checked.
+        :type G: nx.Graph
+
+        :return: True if the graph is acyclic, False otherwise.
+        :rtype: bool
+        """
+        GraphDescriptor._validate_graph_input(G)
+        return nx.is_tree(G) if not GraphDescriptor.is_graph_empty(G) else False
+
+    @staticmethod
+    def is_single_cyclic_graph(G: nx.Graph) -> bool:
+        """Determines if the given graph has exactly one cycle.
+
+        :param G: The graph to be checked.
+        :type G: nx.Graph
+
+        :return: True if the graph is single cyclic, False otherwise.
+        :rtype: bool
+        """
+        GraphDescriptor._validate_graph_input(G)
+        if GraphDescriptor.is_graph_empty(G) or not nx.is_connected(G):
+            return False
+
+        cycles = nx.cycle_basis(G)
+        if cycles and set(G.nodes()) == {node for cycle in cycles for node in cycle}:
+            return G.number_of_edges() == G.number_of_nodes()
+        return False
+
+    @staticmethod
+    def is_complex_cyclic_graph(G: nx.Graph) -> bool:
+        """Determines if the graph is complex cyclic with multiple cycles.
+
+        :param G: The graph to be checked.
+        :type G: nx.Graph
+
+        :return: True if the graph is complex cyclic, False otherwise.
+        :rtype: bool
+        """
+        GraphDescriptor._validate_graph_input(G)
+        if GraphDescriptor.is_graph_empty(G) or not nx.is_connected(G):
+            return False
+
+        cycles = nx.minimum_cycle_basis(G)
+        nodes_in_cycles = {node for cycle in cycles for node in cycle}
+        return len(cycles) > 1 and nodes_in_cycles == set(G.nodes())
+
+    @staticmethod
+    def check_graph_type(G: nx.Graph) -> str:
+        """Classifies the graph as acyclic, single cyclic, or complex cyclic.
+
+        :param G: The graph to be checked.
+        :type G: nx.Graph
+
+        :return: The classification result.
+        :rtype: str
+        """
+        GraphDescriptor._validate_graph_input(G)
+        if GraphDescriptor.is_graph_empty(G):
+            return "Empty Graph"
+        elif GraphDescriptor.is_acyclic_graph(G):
+            return "Acyclic"
+        elif GraphDescriptor.is_single_cyclic_graph(G):
+            return "Single Cyclic"
+        elif GraphDescriptor.is_complex_cyclic_graph(G):
+            return "Combinatorial Cyclic"
+        else:
+            return "Complex Cyclic"
+
+    @staticmethod
+    def get_cycle_member_rings(G: nx.Graph, type="minimal") -> List[int]:
+        """Identifies all cycles in the given graph using cycle bases to ensure
+        no overlap and returns a list of the sizes of these cycles (member
+        rings), sorted in ascending order.
+
+        :param G: The NetworkX graph to be analyzed.
+        :type G: nx.Graph
+
+        :return: A sorted list of cycle sizes (member rings) found in the graph.
+        :rtype: List[int]
+        """
+        if not isinstance(G, nx.Graph):
+            raise TypeError("Input must be a networkx Graph object.")
+
+        if type == "minimal":
+            cycles = nx.minimum_cycle_basis(G)
+        else:
+            cycles = nx.cycle_basis(G)
+        member_rings = [len(cycle) for cycle in cycles]
+
+        member_rings.sort()
+
+        return member_rings
+
+    @staticmethod
+    def get_element_count(graph: nx.Graph) -> Dict[str, int]:
+        """Counts occurrences of each element in the graph nodes.
+
+        :param graph: A NetworkX graph with 'element' attribute in nodes.
+        :type graph: nx.Graph
+
+        :return: An ordered dictionary with element counts.
+        :rtype: Dict[str, int]
+        """
+        element_counts = Counter(data["element"] for _, data in graph.nodes(data=True))
+        return OrderedDict(sorted(element_counts.items()))
+
+    @staticmethod
+    def get_descriptors(
+        entry: Dict,
+        reaction_centers: str = "RC",
+        its: str = "ITS",
+        condensed: bool = True,
+    ) -> Dict:
+        """Enhance an entry dictionary with topology type and reaction type
+        descriptors.
+
+        :param entry: A dictionary with reaction data.
+        :type entry: Dict
+        :param reaction_centers: Key for accessing reaction center data.
+        :type reaction_centers: str
+        :param its: Key for accessing ITS (Intermediate Transition State) data.
+        :type its: str
+
+        :return: The enhanced entry with additional descriptors.
+        :rtype: Dict
+        """
+        graph = GraphDescriptor._extract_graph(entry, reaction_centers)
+        its_graph = GraphDescriptor._extract_graph(entry, its)
+
+        if not graph or not its_graph:
+            return entry  # Early exit if graphs are missing
+
+        # Set initial topology descriptor for the reaction center graph
+        entry["topo"] = GraphDescriptor.check_graph_type(graph)
+        entry["cycle"] = GraphDescriptor.get_cycle_member_rings(graph)
+        entry["atom_count"] = GraphDescriptor.get_element_count(graph)
+        entry["its_count"] = GraphDescriptor.get_element_count(its_graph)
+
+        # Determine the reaction type based on the topology type
+        entry["rtype"] = (
+            "Elementary"
+            if entry["topo"] in ["Single Cyclic", "Acyclic"]
+            else "Complicated"
+        )
+
+        GraphDescriptor._adjust_cycle_and_step(entry, "cycle", entry["topo"])
+        entry["signature_rc"] = GraphSignature(graph).create_graph_signature()
+
+        # Initialize ITS descriptors and call adjust
+        topo_its = GraphDescriptor.check_graph_type(its_graph)
+        cycle_its = GraphDescriptor.get_cycle_member_rings(its_graph)
+        entry["cycle_its"] = cycle_its  # Ensure key is initialized
+        GraphDescriptor._adjust_cycle_and_step(
+            entry, "cycle_its", topo_its, its_prefix="its"
+        )
+
+        entry["signature_its"] = GraphSignature(its_graph).create_graph_signature()
+
+        return entry
+
+    @staticmethod
+    def _extract_graph(entry: Dict, key: str) -> Union[nx.Graph, None]:
+        """Extracts a graph from an entry dictionary based on the specified
+        key.
+
+        :param entry: The dictionary containing graph data.
+        :type entry: Dict
+        :param key: The key for accessing graph data.
+        :type key: str
+
+        :return: The extracted graph or None if unavailable.
+        :rtype: Union[nx.Graph, None]
+        """
+        data = entry.get(key)
+        if isinstance(data, tuple):
+            try:
+                return data[2]
+            except IndexError:
+                logger.error(f"No graph data available at index 2 for entry {entry}")
+        elif isinstance(data, nx.Graph):
+            return data
+        else:
+            logger.error(f"Unsupported data type for {key} in entry {entry}")
+        return None
+
+    @staticmethod
+    def _adjust_cycle_and_step(
+        entry: Dict, cycle_key: str, topo_type: str, its_prefix: str = ""
+    ) -> None:
+        """Adjusts cycle and step descriptors based on the graph topology type.
+
+        :param entry: The entry dictionary to update.
+        :type entry: Dict
+        :param cycle_key: The key for the cycle descriptor.
+        :type cycle_key: str
+        :param topo_type: The topology type.
+        :type topo_type: str
+        :param its_prefix: Prefix for ITS-specific descriptors.
+        :type its_prefix: str
+        """
+        step_key = f"rstep_{its_prefix}" if its_prefix else "rstep"
+
+        # Initialize the step key in the dictionary to avoid KeyError
+        if cycle_key not in entry:
+            entry[cycle_key] = []
+
+        if topo_type == "Acyclic":
+            entry[cycle_key] = [0]
+        elif topo_type == "Complex Cyclic":
+            entry[cycle_key] = [0] + entry[cycle_key]
+
+        entry[step_key] = len(entry[cycle_key])
+
+    @staticmethod
+    def _validate_graph_input(G: nx.Graph) -> None:
+        """Validates that the input is a NetworkX graph.
+
+        :param G: The graph to validate.
+        :type G: nx.Graph
+
+        :raises TypeError: If G is not a NetworkX Graph.
+        """
+        if not isinstance(G, nx.Graph):
+            raise TypeError("Input must be a NetworkX Graph object.")
+
+    @staticmethod
+    def process_entries_in_parallel(
+        entries: List[Dict],
+        reaction_centers: str = "RC",
+        its: str = "ITS",
+        condensed: bool = True,
+        n_jobs: int = 4,
+        verbose: int = 0,
+    ) -> List[Dict]:
+        """Processes a list of entries in parallel to enhance each entry with
+        descriptors.
+
+        :param entries: List of dictionaries containing reaction data to enhance.
+        :type entries: List[Dict]
+        :param reaction_centers: Key to retrieve reaction center graph data from each
+                                 entry dictionary.
+        :type reaction_centers: str
+        :param its: Key to retrieve ITS (Intermediate Transition State) graph data from
+                    each entry dictionary.
+        :type its: str
+        :param condensed: If True, condenses node signatures with counts.
+        :type condensed: bool
+        :param n_jobs: Number of jobs to run in parallel. -1 uses all processors.
+        :type n_jobs: int
+        :param verbose: The verbosity level for joblib's Parallel.
+        :type verbose: int
+
+        :return: A list of enhanced dictionaries with added descriptors.
+        :rtype: List[Dict]
+        """
+        return Parallel(n_jobs=n_jobs, verbose=verbose)(
+            delayed(GraphDescriptor.get_descriptors)(
+                entry, reaction_centers, its, condensed
+            )
+            for entry in entries
+        )
+
+
+def check_graph_connectivity(graph: nx.Graph) -> str:
+    """Check the connectivity of a NetworkX graph.
+
+    This function assesses whether all nodes in the graph are connected by some path,
+    applicable to undirected graphs.
+
+    :param graph: A NetworkX graph object.
+    :type graph: nx.Graph
+
+    :return: Returns 'Connected' if the graph is connected, otherwise 'Disconnected'.
+    :rtype: str
+
+    :raises NetworkXNotImplemented: If graph is directed and does not support is_connected.
+    """
+    if nx.is_connected(graph):
+        return "Connected"
+    else:
+        return "Disconnected."

synkit/Graph/Feature/graph_fps.py

@@ -0,0 +1,96 @@
+import networkx as nx
+import hashlib
+import numpy as np
+
+
+class GraphFP:
+    def __init__(
+        self, graph: nx.Graph, nBits: int = 1024, hash_alg: str = "sha256"
+    ) -> None:
+        """Initialize the GraphFP class to create binary fingerprints based on
+        various graph characteristics.
+
+        :param graph: Graph on which to perform analysis.
+        :type graph: nx.Graph
+        :param nBits: Size of the binary fingerprint in bits.
+        :type nBits: int
+        :param hash_alg: Cryptographic hash function used for hashing.
+        :type hash_alg: str
+        """
+        self.graph = graph
+        self.nBits = nBits
+        self.hash_alg = hash_alg
+        self.hash_function = getattr(hashlib, self.hash_alg)
+
+    def fingerprint(self, method: str) -> str:
+        """Generate a binary string fingerprint of the graph using the
+        specified method.
+
+        :param method: The method to use for fingerprinting
+                       ('spectrum', 'adjacency', 'degree', 'motif')
+        :type method: str
+
+        :return: A binary string of length `nBits` that represents the fingerprint of the graph.
+        :rtype: str
+        """
+        if method == "spectrum":
+            fp = self._spectrum_fp()
+        elif method == "adjacency":
+            fp = self._adjacency_fp()
+        elif method == "degree":
+            fp = self._degree_sequence_fp()
+        elif method == "motif":
+            fp = self._motif_count_fp()
+        else:
+            raise ValueError("Unsupported fingerprinting method.")
+
+        # If the fingerprint is shorter than nBits, use iterative deepening
+        if len(fp) < self.nBits:
+            fp += self.iterative_deepening(self.nBits - len(fp))
+
+        return fp[: self.nBits]
+
+    def _spectrum_fp(self) -> str:
+        # Graph spectrum (eigenvalues of the adjacency matrix)
+        eigenvalues = np.linalg.eigvals(nx.adjacency_matrix(self.graph).todense())
+        sorted_eigenvalues = np.sort(eigenvalues)[: self.nBits]
+        eigen_str = "".join(
+            bin(int(abs(eig)))[2:].zfill(8) for eig in sorted_eigenvalues
+        )
+        return eigen_str[: self.nBits]
+
+    def _adjacency_fp(self) -> str:
+        # Adjacency matrix flattened
+        adj_matrix = nx.adjacency_matrix(self.graph).todense().flatten()
+        adj_str = "".join(str(int(x)) for x in adj_matrix)
+        return adj_str[: self.nBits]
+
+    def _degree_sequence_fp(self) -> str:
+        # Degree sequence
+        degrees = sorted([d for n, d in self.graph.degree()], reverse=True)
+        degree_str = "".join(bin(d)[2:].zfill(8) for d in degrees)
+        return degree_str[: self.nBits]
+
+    def _motif_count_fp(self) -> str:
+        # Motif counts (e.g., number of triangles)
+        triangles = sum(nx.triangles(self.graph).values()) // 3
+        triangle_str = bin(triangles)[2:].zfill(self.nBits)
+        return triangle_str[: self.nBits]
+
+    def iterative_deepening(self, remaining_bits: int) -> str:
+        """Extend the hash length using iterative hashing until the desired bit
+        length is achieved.
+
+        :param remaining_bits: Number of bits needed to complete the fingerprint
+                               to `nBits`.
+        :type remaining_bits: int
+
+        :return: Additional binary data to achieve the desired hash length.
+        :rtype: str
+        """
+        additional_data = ""
+        hash_obj = self.hash_function()
+        while len(additional_data) * 4 < remaining_bits:
+            hash_obj.update(additional_data.encode())
+            additional_data += hash_obj.hexdigest()
+        return bin(int(additional_data, 16))[2:][:remaining_bits]