synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Context/hier_context.py

@@ -0,0 +1,244 @@
+import copy
+from collections import defaultdict
+from typing import List, Any, Dict, Tuple, Callable
+
+from synkit.IO.debug import setup_logging
+from synkit.Graph.Feature.wl_hash import WLHash
+from synkit.Graph.Context.radius_expand import RadiusExpand
+from synkit.Graph.Matcher.batch_cluster import BatchCluster
+
+logger = setup_logging()
+
+
+class HierContext(RadiusExpand):
+    """Hierarchical clustering class for reaction context graphs.
+
+    Extends RadiusExpand to build multi-level graph representations and
+    clusters them based on structural features such as Weisfeiler-Lehman
+    hashing.
+    """
+
+    def __init__(
+        self,
+        node_label_names: List[str] = ["element", "charge"],
+        node_label_default: List[Any] = ["*", 0],
+        edge_attribute: str = "order",
+        max_radius: int = 3,
+    ) -> None:
+        """Initializes the HierContext class for hierarchical clustering of
+        reaction context graphs.
+
+        :param node_label_names: A list of node attribute names used for matching.
+        :type node_label_names: List[str]
+        :param node_label_default: A list of default values for node attributes.
+        :type node_label_default: List[Any]
+        :param edge_attribute: The edge attribute used in matching.
+        :type edge_attribute: str
+        :param max_radius: The maximum hierarchical level (radius) to be considered.
+        :type max_radius: int
+        """
+        super().__init__()
+        self.radius: List[int] = list(range(max_radius + 1))
+        self.node_label_names: List[str] = node_label_names
+        self.node_label_default: List[Any] = node_label_default
+        self.edge_attribute: str = edge_attribute
+        self.cluster: BatchCluster = BatchCluster(
+            self.node_label_names, self.node_label_default, self.edge_attribute
+        )
+
+    @staticmethod
+    def _group_class(
+        data: List[Dict[str, Any]], key: str
+    ) -> Dict[Any, List[Dict[str, Any]]]:
+        """Groups a list of dictionaries into subgroups based on the specified
+        key.
+
+        :param data: A list of dictionaries to be grouped.
+        :type data: List[Dict[str, Any]]
+        :param key: The key used for grouping items.
+        :type key: str
+
+        :return: Dictionary grouping entries by the selected key value.
+        :rtype: Dict[Any, List[Dict[str, Any]]]
+        """
+        grouped_data: Dict[Any, List[Dict[str, Any]]] = defaultdict(list)
+        for item in data:
+            grouped_data[item.get(key)].append(item)
+        return dict(grouped_data)
+
+    @staticmethod
+    def _update_child_idx(
+        data: List[List[Dict[str, Any]]], cls_id: str = "class"
+    ) -> List[List[Dict[str, Any]]]:
+        """Updates hierarchical templates by assigning child IDs based on
+        parent–cluster relationships.
+
+        :param data: A list of layers, where each layer is a list of dictionaries
+                     containing node data.
+        :type data: List[List[Dict[str, Any]]]
+        :param cls_id: The key used to identify the node's class or cluster ID (default is "class").
+        :type cls_id: str
+
+        :return: Hierarchical data whose nodes list their child class IDs.
+        :rtype: List[List[Dict[str, Any]]]
+        """
+        node_dict: Dict[str, Dict[str, Any]] = {}
+
+        # Initialize the "Child" list for each node and build a mapping based on layer index and class ID.
+        for layer_idx, layer in enumerate(data):
+            for node in layer:
+                node["Child"] = []
+                node_dict[f"{layer_idx}-{node[cls_id]}"] = node
+
+        # Update parent's "Child" list by linking child nodes to their respective parent(s).
+        for layer_idx, layer in enumerate(data[1:], 1):
+            for node in layer:
+                parents = node.get("Parent", [])
+                if isinstance(parents, (int, str)):
+                    parents = [parents]
+                for parent_id in parents:
+                    parent_key = f"{layer_idx - 1}-{parent_id}"
+                    if parent_key in node_dict:
+                        node_dict[parent_key]["Child"].append(node[cls_id])
+        return data
+
+    @staticmethod
+    def _process(
+        data: List[Dict[str, Any]],
+        k: int,
+        its_key: str,
+        context_key: str,
+        cls_func: Callable,
+    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+        """Processes a list of graph data entries by extracting context
+        subgraphs and computing their hashes, then classifies the data using
+        the provided clustering function.
+
+        :param data: A list of dictionaries, each representing a graph or data entry.
+        :type data: List[Dict[str, Any]]
+        :param k: The number of nearest neighbors to include during context extraction.
+        :type k: int
+        :param its_key: The key corresponding to the ITS graph in each data entry.
+        :type its_key: str
+        :param context_key: The key under which the extracted context subgraph will be stored.
+        :type context_key: str
+        :param cls_func: The clustering function instance to be used for clustering.
+        :type cls_func: Callable
+
+        :return: A tuple containing:
+                  The list of clustered data entries with updated cluster identifiers.
+                  The list of processed template dictionaries.
+        :rtype: Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]
+        """
+        for item in data:
+            context = RadiusExpand.extract_k(item[its_key], n_knn=k)
+            item[context_key] = context
+            item["WLHash"] = WLHash().weisfeiler_lehman_graph_hash(context)
+
+        cluster_results, templates = cls_func.cluster(data, [], context_key, "WLHash")
+
+        for result in cluster_results:
+            result[f"R_{k}"] = result.pop("class")
+
+        templates_processed = [
+            {"R-id": tpl["R-id"], context_key: tpl[context_key], "class": tpl["class"]}
+            for tpl in templates
+        ]
+
+        return cluster_results, templates_processed
+
+    def _process_level(
+        self,
+        data: List[Dict[str, Any]],
+        its_key: str,
+        context_key: str,
+        cls_func: Callable,
+        radius: int = 1,
+    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+        """Processes a specific hierarchical level by grouping data based on
+        parent cluster IDs, extracting context for child levels, and clustering
+        the data.
+
+        :param data: A list of dictionaries representing graph data entries.
+        :type data: List[Dict[str, Any]]
+        :param its_key: The key corresponding to the ITS graph in each entry.
+        :type its_key: str
+        :param context_key: The key under which the extracted context subgraph is stored.
+        :type context_key: str
+        :param cls_func: The clustering function instance to be used.
+        :type cls_func: Callable
+        :param radius: The current hierarchical level (radius) being processed (default is 1).
+        :type radius: int, optional
+
+        :return: A tuple containing:
+                  The updated list of data entries with new cluster indices for this level.
+                  The list of newly generated template dictionaries for this level.
+        :rtype: Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]
+        """
+        grouped_data: Dict[Any, List[Dict[str, Any]]] = self._group_class(
+            data, f"R_{radius - 1}"
+        )
+        templates: List[Dict[str, Any]] = []
+        cluster_indices_all: List[Dict[str, Any]] = []
+        template_offset: int = 0
+
+        for parent_class, group in grouped_data.items():
+            cluster_indices, new_templates = self._process(
+                group, radius, its_key, context_key, cls_func
+            )
+
+            for ci in cluster_indices:
+                ci[f"R_{radius}"] += template_offset
+
+            for tpl in new_templates:
+                tpl["class"] += template_offset
+                tpl["Parent"] = parent_class
+
+            cluster_indices_all.extend(cluster_indices)
+            templates.extend(new_templates)
+            template_offset = len(templates)
+
+        return cluster_indices_all, templates
+
+    def fit(
+        self,
+        original_data: List[Dict[str, Any]],
+        its_key: str = "ITS",
+        context_key: str = "K",
+    ) -> Tuple[List[Dict[str, Any]], List[List[Dict[str, Any]]]]:
+        """Processes a list of graph data entries, classifying each based on
+        hierarchical clustering. The method extracts context subgraphs,
+        computes graph hashes, and clusters the data at multiple hierarchical
+        levels. Finally, child node indices are updated based on parent–cluster
+        relationships.
+
+        :param original_data: A list of dictionaries, each representing a graph data entry
+                              with an ITS graph.
+        :type original_data: List[Dict[str, Any]]
+        :param its_key: The key in each dictionary corresponding to the ITS graph (default is "ITS").
+        :type its_key: str
+        :param context_key: The key under which the extracted context subgraph is stored (default is "K").
+        :type context_key: str
+
+        :return: A tuple containing:
+                  The updated list of graph data entries with hierarchical cluster indices.
+                  A list (per hierarchical level) of template dictionaries that have been updated with child indices.
+        :rtype: Tuple[List[Dict[str, Any]], List[List[Dict[str, Any]]]]
+        """
+        data: List[Dict[str, Any]] = copy.deepcopy(original_data)
+
+        logger.info("Processing parent level (radius 0)")
+        cluster_indices, templates = self._process(
+            data, 0, its_key, context_key, self.cluster
+        )
+        templates_all: List[List[Dict[str, Any]]] = [templates]
+
+        for radius in self.radius[1:]:
+            logger.info(f"Processing child level with radius {radius}")
+            cluster_indices, templates_radius = self._process_level(
+                data, its_key, context_key, self.cluster, radius
+            )
+            templates_all.append(templates_radius)
+
+        templates_all = self._update_child_idx(templates_all)
+        return cluster_indices, templates_all

synkit/Graph/Context/radius_expand.py

@@ -0,0 +1,252 @@
+import copy
+import networkx as nx
+from itertools import chain
+from joblib import Parallel, delayed
+from typing import List, Set, Dict, Any, Tuple
+
+from synkit.Graph.ITS.its_decompose import get_rc
+
+
+class RadiusExpand:
+    """A utility class for extracting and expanding reaction contexts from
+    chemical reaction graphs.
+
+    This class provides methods to:
+    - Identify reaction center nodes based on unequal edge orders.
+    - Expand reaction centers by including n-level nearest neighbors.
+    - Extract subgraphs from larger graphs.
+    - Construct a reaction context subgraph (K graph) from an ITS graph.
+    - Retrieve the longest unique extension path from reaction centers using DFS.
+    - Perform parallel extraction of reaction contexts from multiple reaction dictionaries.
+    - Remove edges based on specified edge attribute values.
+    """
+
+    def __init__(self) -> None:
+        """Initializes an instance of the RadiusExpand class.
+
+        This class does not maintain any instance-specific state and
+        uses only static and class methods.
+        """
+        pass
+
+    @staticmethod
+    def find_unequal_order_edges(G: nx.Graph) -> List[int]:
+        """Identifies reaction center nodes in a graph based on the presence of
+        unequal order edges.
+
+        :param G: Graph to analyze for reaction centers.
+        :type G: nx.Graph
+
+        :return: A list of node indices identified as reaction centers based on unequal order edges.
+        :rtype: List[int]
+        """
+        reaction_center_nodes: Set[int] = set()
+        for u, v, data in G.edges(data=True):
+            order = data.get("order", (1, 1))
+            if (
+                isinstance(order, tuple)
+                and order[0] != order[1]
+                and data.get("standard_order", 1) != 0
+            ):
+                reaction_center_nodes.update([u, v])
+        return list(reaction_center_nodes)
+
+    @staticmethod
+    def find_nearest_neighbors(
+        G: nx.Graph, center_nodes: List[int], n_knn: int = 1
+    ) -> Set[int]:
+        """Finds the n-level nearest neighbors around the specified center
+        nodes in a graph.
+
+        :param G: The graph in which to search for neighboring nodes.
+        :type G: nx.Graph
+        :param center_nodes: Initial center node indices.
+        :type center_nodes: List[int]
+        :param n_knn: The number of neighbor levels to include (default is 1).
+        :type n_knn: int, optional
+
+        :return: A set of node indices including the original center nodes and their nearest neighbors.
+        :rtype: Set[int]
+        """
+        extended_nodes: Set[int] = set(center_nodes)
+        for _ in range(n_knn):
+            neighbors = set(
+                chain.from_iterable(G.neighbors(node) for node in extended_nodes)
+            )
+            extended_nodes.update(neighbors)
+        return extended_nodes
+
+    @staticmethod
+    def extract_subgraph(G: nx.Graph, node_indices: List[int]) -> nx.Graph:
+        """Extracts a subgraph from the original graph containing the specified
+        node indices.
+
+        :param G: The original graph.
+        :type G: nx.Graph
+        :param node_indices: A list of node indices to include in the subgraph.
+        :type node_indices: List[int]
+
+        :return: A new graph that is a copy of the subgraph containing only the specified nodes.
+        :rtype: nx.Graph
+        """
+        return G.subgraph(node_indices).copy()
+
+    @staticmethod
+    def extract_k(its: nx.Graph, n_knn: int = 0) -> Tuple[nx.Graph, Any]:
+        """Constructs the context subgraph (K graph) from an ITS graph based on
+        reaction centers, and computes the longest extension path from these
+        centers constrained by 'standard_order' edges.
+
+        :param its: The ITS graph representing the reaction network.
+        :type its: nx.Graph
+        :param n_knn: The number of neighbor levels to include in the context subgraph.
+                      Default is 0.
+        :type n_knn: int, optional
+
+        :return: Extracted context graph. A zero radius returns the reaction
+                 center; ``-1`` uses the maximum radius.
+        :rtype: Tuple[nx.Graph, Any]
+        """
+        rc = get_rc(its)
+        rc_nodes = list(rc.nodes())
+        if n_knn == 0:
+            return rc
+        elif n_knn == -1:
+            paths = RadiusExpand.longest_radius_extension(its, rc_nodes)
+            n_knn = len(paths)
+
+        expanded_nodes = RadiusExpand.find_nearest_neighbors(its, rc_nodes, n_knn)
+        context = RadiusExpand.extract_subgraph(its, list(expanded_nodes))
+        return context
+
+    @staticmethod
+    def context_extraction(
+        data: Dict[str, Any],
+        its_key: str = "ITS",
+        context_key: str = "K",
+        n_knn: int = 0,
+    ) -> Dict[str, Any]:
+        """Extracts the reaction context for a single reaction dictionary by
+        computing both the context subgraph and the longest extension path.
+
+        :param data: Reaction data containing at least an ITS graph.
+        :type data: Dict[str, Any]
+        :param its_key: Key in the dictionary for retrieving the ITS graph.
+                        Default is ITS.
+        :type its_key: str, optional
+        :param context_key: Key under which to store the extracted context subgraph.
+                            Default is K.
+        :type context_key: str, optional
+        :param n_knn: Number of neighbor levels to include for context extraction.
+                      Default is 0.
+        :type n_knn: int, optional
+
+        :return: Reaction data containing the extracted context graph.
+        :rtype: Dict[str, Any]
+        """
+        context_data: Dict[str, Any] = copy.copy(data)
+        its = context_data[its_key]
+        context = RadiusExpand.extract_k(its, n_knn)
+        context_data[context_key] = context
+        return context_data
+
+    @classmethod
+    def paralle_context_extraction(
+        cls,
+        data: List[Dict[str, Any]],
+        its_key: str = "ITS",
+        context_key: str = "K",
+        n_jobs: int = 1,
+        verbose: int = 0,
+        n_knn: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """Performs parallel extraction of reaction contexts for multiple
+        reaction dictionaries.
+
+        :param data: A list of reaction data dictionaries, each containing an ITS graph.
+        :type data: List[Dict[str, Any]]
+        :param its_key: Key in the dictionary for retrieving the ITS graph.
+                        Default is ITS.
+        :type its_key: str, optional
+        :param context_key: Key under which to store the extracted context subgraph.
+                            Default is K.
+        :type context_key: str, optional
+        :param n_jobs: Number of parallel jobs to use. Default is 1.
+        :type n_jobs: int, optional
+        :param verbose: Verbosity level for the parallel processing. Default is 0.
+        :type verbose: int, optional
+        :param n_knn: Number of neighbor levels to include for context extraction.
+                      Default is 0.
+        :type n_knn: int, optional
+
+        :return: Reaction records augmented with their context graphs and
+                 longest extension paths.
+        :rtype: List[Dict[str, Any]]
+        """
+        return Parallel(n_jobs=n_jobs, verbose=verbose)(
+            delayed(cls.context_extraction)(reaction, its_key, context_key, n_knn)
+            for reaction in data
+        )
+
+    @staticmethod
+    def remove_normal_edges(graph: nx.Graph, property_key: str) -> nx.Graph:
+        """Removes edges from a graph where the specified edge attribute has a
+        value of 0.
+
+        :param graph: The input graph to modify.
+        :type graph: nx.Graph
+        :param property_key: The key of the edge attribute to check for removal;
+                             edges with a value of 0 will be removed.
+        :type property_key: str
+
+        :return: A copy of the input graph with the specified edges removed.
+        :rtype: nx.Graph
+        """
+        filtered_graph = graph.copy()
+        edges_to_remove = [
+            (u, v)
+            for u, v, attrs in filtered_graph.edges(data=True)
+            if attrs.get(property_key, 1) == 0
+        ]
+        filtered_graph.remove_edges_from(edges_to_remove)
+        return filtered_graph
+
+    @staticmethod
+    def longest_radius_extension(G: nx.Graph, rc_nodes: List[int]) -> List[int]:
+        """Computes the longest unique extension path in the graph starting
+        from the given reaction center nodes, constrained by traversing only
+        those edges where the 'standard_order' attribute equals 0.
+
+        This method uses a depth-first search (DFS) strategy to explore all possible
+        unique paths and returns the longest one.
+
+        :param G: The graph to search for extension paths.
+        :type G: nx.Graph
+        :param rc_nodes: A list of reaction center node indices to serve as starting points for the search.
+        :type rc_nodes: List[int]
+
+        :return: A list of node indices representing the longest unique extension path found.
+        :rtype: List[int]
+        """
+
+        def dfs(node: int, visited: Set[int], path: List[int]) -> List[int]:
+            visited.add(node)
+            longest_path = path.copy()
+            for neighbor in G.neighbors(node):
+                edge_data = G.get_edge_data(node, neighbor)
+                if edge_data.get("standard_order", 1) == 0 and neighbor not in visited:
+                    current_path = dfs(neighbor, visited.copy(), path + [neighbor])
+                    if len(current_path) > len(longest_path):
+                        longest_path = current_path
+            return longest_path
+
+        longest_extension: List[int] = []
+        visited_overall: Set[int] = set()
+
+        for rc_node in rc_nodes:
+            if rc_node not in visited_overall:
+                path = dfs(rc_node, visited_overall.copy(), [rc_node])
+                visited_overall.update(path)
+                if len(path) > len(longest_extension):
+                    longest_extension = path
+        return longest_extension

synkit/Graph/FG/__init__.py

@@ -0,0 +1,19 @@
+"""Functional-group detection on SynKit molecular graphs."""
+
+from .catalog import default_registry
+from .audit import FunctionalGroupAudit, audit_reaction_smiles
+from .api import FunctionalGroupLabels, smiles_to_graph_and_functional_groups
+from .detector import FunctionalGroupDetector
+from .model import FunctionalGroupMatch, FunctionalGroupPattern, FunctionalGroupRegistry
+
+__all__ = [
+    "FunctionalGroupDetector",
+    "FunctionalGroupLabels",
+    "FunctionalGroupAudit",
+    "FunctionalGroupMatch",
+    "FunctionalGroupPattern",
+    "FunctionalGroupRegistry",
+    "default_registry",
+    "audit_reaction_smiles",
+    "smiles_to_graph_and_functional_groups",
+]

synkit/Graph/FG/api.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import networkx as nx
+
+from synkit.IO.chem_converter import smiles_to_graph
+
+from .detector import FunctionalGroupDetector
+
+FunctionalGroupLabels = list[tuple[str, tuple[int, ...]]]
+
+
+def smiles_to_graph_and_functional_groups(
+    smiles: str,
+    *,
+    sanitize: bool = True,
+) -> tuple[nx.Graph, FunctionalGroupLabels]:
+    """Convert SMILES to a molecular graph and detect functional groups.
+
+    Atom-mapped SMILES keep their non-zero atom-map numbers as graph node IDs.
+    Unmapped atoms use their 1-based atom order as node IDs, so both mapped and
+    unmapped SMILES can be passed to the same API.
+
+    :param smiles: Input SMILES, with or without atom-map labels.
+    :type smiles: str
+    :param sanitize: If ``True``, sanitize the RDKit molecule during conversion.
+    :type sanitize: bool
+    :return: Molecular graph and detected ``(name, node_ids)`` FG labels.
+    :rtype: tuple[nx.Graph, list[tuple[str, tuple[int, ...]]]]
+    :raises ValueError: If the SMILES cannot be converted to a molecular graph.
+    """
+    graph = smiles_to_graph(
+        smiles,
+        drop_non_aam=False,
+        sanitize=sanitize,
+        use_index_as_atom_map=True,
+    )
+    if graph is None:
+        raise ValueError(f"Could not convert SMILES to molecular graph: {smiles!r}")
+    return graph, FunctionalGroupDetector().detect(graph)