synkit 1.6.5__py3-none-win_amd64.whl

synkit/Graph/Matcher/multi_turbo_iso.py

@@ -0,0 +1,186 @@
+import networkx as nx
+from collections import defaultdict
+from typing import Any, Dict, List, Set, Tuple, Union
+from synkit.Graph.Matcher.turbo_iso import TurboISO
+
+######################################################################
+# MultiTurboISO – one global index for **N host graphs × M patterns**
+######################################################################
+
+
+class MultiTurboISO:
+    """Accelerated sub-graph search across a batch of host graphs.
+
+    Builds a single global signature bucket over all hosts and reuses a
+    lightweight TurboISO matcher per host. For each query graph, hosts
+    are first pruned by a signature + degree filter, and then TurboISO’s
+    backtracking is run only on the surviving hosts.
+
+    :param hosts: List of host graphs to index.
+    :type hosts: List[nx.Graph]
+    :param node_label: Node attribute(s) used for signature matching.
+    :type node_label: str or list[str]
+    :param edge_label: Edge attribute(s) to match; pass None to ignore
+        edges.
+    :type edge_label: str or list[str] or None
+    :param distance_threshold: Skip distance filtering if candidate pool
+        is smaller.
+    :type distance_threshold: int
+    :return: An instance of MultiTurboISO with global index built.
+    :rtype: MultiTurboISO
+    """
+
+    # --------------------------------------------------------------- init
+    def __init__(
+        self,
+        hosts: List[nx.Graph],
+        node_label: Union[str, List[str]] = "label",
+        edge_label: Union[str, List[str], None] = None,
+        distance_threshold: int = 5000,
+    ) -> None:
+        # normalise selectors ------------------------------------------------
+        self._node_attr = (
+            [node_label] if isinstance(node_label, str) else list(node_label)
+        )
+        self._edge_attr = (
+            []
+            if edge_label is None
+            else [edge_label] if isinstance(edge_label, str) else list(edge_label)
+        )
+        self._dthr = distance_threshold
+
+        # store hosts & create one TurboISO per host ------------------------
+
+        self._hosts: List[nx.Graph] = hosts
+        self._matchers: List[TurboISO] = [
+            TurboISO(
+                h,
+                node_label=self._node_attr,
+                edge_label=self._edge_attr,
+                distance_threshold=distance_threshold,
+            )
+            for h in hosts
+        ]
+
+        # global bucket: signature → {(host_idx, node)} ---------------------
+        self._bucket: Dict[Tuple[Any, ...], Set[Tuple[int, Any]]] = defaultdict(set)
+        for idx, m in enumerate(self._matchers):
+            for node, sig in m._sig.items():
+                self._bucket[sig].add((idx, node))
+
+        # degree maps for quick filtering -----------------------------------
+        self._deg: List[Dict[Any, int]] = [dict(H.degree()) for H in hosts]
+
+    # --------------------------------------------------------- repr / help
+    def __repr__(self) -> str:
+        return (
+            f"<MultiTurboISO hosts={len(self._hosts)} "
+            f"node_label={self._node_attr} edge_label={self._edge_attr} "
+            f"dthr={self._dthr}>"
+        )
+
+    def __help__(self) -> str:  # for interactive use
+        return self.__doc__
+
+    # ----------------------------------------------------------- properties
+    @property
+    def hosts(self) -> List[nx.Graph]:
+        """Return the list of host graphs."""
+        return self._hosts
+
+    @property
+    def num_hosts(self) -> int:
+        """Number of host graphs indexed."""
+        return len(self._hosts)
+
+    @property
+    def node_label(self) -> List[str]:
+        """Node‑attribute selector(s)."""
+        return list(self._node_attr)
+
+    @property
+    def edge_label(self) -> List[str]:
+        """Edge‑attribute selector(s).
+
+        Empty list means ‘ignore’.
+        """
+        return list(self._edge_attr)
+
+    # -------------------------------------------------------------- helpers
+    def _node_sig(self, v: Any, G: nx.Graph) -> Tuple[Any, ...]:
+        if self._matchers:
+            return self._matchers[0]._node_signature(v, G)
+        return TurboISO(G, node_label=self._node_attr)._node_signature(v, G)
+
+    def _init_candidates(self, Q: nx.Graph) -> Dict[int, Dict[Any, Set[Any]]]:
+        """Return per‑host candidate sets after signature + degree filter."""
+        cand: Dict[int, Dict[Any, Set[Any]]] = defaultdict(dict)
+        # (1) signature filter ------------------------------------------------
+        for q in Q.nodes:
+            sig = self._node_sig(q, Q)
+            for hidx, v in self._bucket.get(sig, ()):  # O(1) bucket lookup
+                cand[hidx].setdefault(q, set()).add(v)
+        # (2) degree filter + host pruning -----------------------------------
+        qdeg = {q: Q.degree(q) for q in Q.nodes}
+        for hidx in list(cand.keys()):
+            cmap = cand[hidx]
+            if len(cmap) < len(Q):  # missing some query nodes entirely
+                del cand[hidx]
+                continue
+            dmap = self._deg[hidx]
+            for q in Q.nodes:
+                vs = {v for v in cmap[q] if dmap[v] >= qdeg[q]}
+                if not vs:  # prune host if any q has no candidates
+                    del cand[hidx]
+                    break
+                cmap[q] = vs
+        return cand
+
+    # -------------------------------------------------------------- search
+    def search_one(
+        self,
+        Q: nx.Graph,
+        *,
+        prune: bool = False,
+    ) -> Dict[int, Union[bool, List[Dict[Any, Any]]]]:
+        """Match a single pattern graph *Q* against every host.
+
+        :param Q: Query / pattern graph.
+        :type Q: nx.Graph
+        :param prune: Forwarded to TurboISO.  If *True*, return just a boolean per
+                      host (‘found?’), otherwise return the full list of mappings.
+        :type prune: bool, default False
+
+        :return: ``{host_idx: result}`` where *result* is *bool* if *prune* is
+                  *True* else a list of node‑mapping dicts.
+        :rtype: dict
+        """
+
+        if not Q:
+            empty_result: Union[bool, List[Dict[Any, Any]]] = True if prune else [{}]
+            return {index: empty_result for index in range(len(self._hosts))}
+
+        host_cands = self._init_candidates(Q)
+        out: Dict[int, Union[bool, List[Dict[Any, Any]]]] = {}
+        for hidx, C in host_cands.items():
+            m: TurboISO = self._matchers[hidx]
+            original = m._init_candidates
+            m._init_candidates = lambda _Q: C  # type: ignore
+            try:
+                out[hidx] = m.search(Q, prune=prune)
+            finally:
+                m._init_candidates = original
+        return out
+
+    def search_many(
+        self,
+        patterns: List[nx.Graph],
+        *,
+        prune: bool = False,
+    ) -> List[Dict[int, Union[bool, List[Dict[Any, Any]]]]]:
+        """Match a list of pattern graphs.
+
+        Returns a list of per‑pattern dictionaries in the same order as
+        the input list.
+        """
+        return [self.search_one(p, prune=prune) for p in patterns]

synkit/Graph/Matcher/orbit.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+from typing import Dict, FrozenSet, Hashable, Iterable, List, Set
+
+
+class OrbitAccuracy:
+    """Compare two orbit partitions (approximate vs exact) and compute accuracy metrics.
+
+    The class is intentionally small and OOP-styled: most methods are chainable
+    (return ``self``) and computed results are exposed via properties.
+
+    :param approx_orbits: Iterable of frozenset-like objects (each containing node identifiers).
+                          Each element represents one orbit (set of node ids) from the *approximate*
+                          partition. The iterable is consumed and a *copy* (list of frozensets) is
+                          stored internally.
+    :param exact_orbits: Iterable of frozenset-like objects (each containing node identifiers).
+                         Each element represents one orbit from the *exact* partition.
+
+    :raises ValueError: If the union of nodes covered by the two partitions differs (i.e. they do
+        not refer to the same node set), a :class:`ValueError` is raised with a
+        short diagnostic listing nodes missing in either partition.
+
+    :ivar nodes: The set of all node identifiers (union of both partitions). Available
+                 after initialization.
+    :vartype nodes: set
+    :ivar metrics: Computed metrics (see :meth:`compute`) exposed as a dictionary via the
+                   :attr:`metrics` property.
+    :vartype metrics: dict
+    :ivar confusion_map: A mapping ``approx_orbit_index -> { exact_orbit_index: overlap_count }``
+                         exposed via the :attr:`confusion_map` property.
+
+    :vartype confusion_map: dict
+
+    .. rubric:: Notes
+
+    - Node identifiers must be hashable (ints, str, ...).
+    - The input iterables are not modified; the class stores its own frozenset
+      copies.
+    - :meth:`compute` is chainable and returns ``self``; read metrics via the
+      :attr:`metrics` property.
+
+    .. rubric:: Examples
+
+    .. code-block:: python
+
+        approx = [frozenset({1}), frozenset({2, 3})]
+        exact  = [frozenset({1}), frozenset({2, 3})]
+
+        oa = OrbitAccuracy(approx, exact).compute()
+        print(oa)                       # -> <OrbitAccuracy nodes=3 approx_orbits=2 exact_orbits=2>
+        print(oa.metrics)               # -> {'node_exact_match_fraction': 1.0, ...}
+        print(oa.confusion_map)         # -> {0: {0: 1}, 1: {1: 2}}
+    """
+
+    def __init__(
+        self,
+        approx_orbits: Iterable[FrozenSet[Hashable]],
+        exact_orbits: Iterable[FrozenSet[Hashable]],
+    ) -> None:
+        # store copies as frozensets to guarantee immutability semantics
+        self._approx_raw: List[FrozenSet[Hashable]] = [
+            frozenset(s) for s in approx_orbits
+        ]
+        self._exact_raw: List[FrozenSet[Hashable]] = [
+            frozenset(s) for s in exact_orbits
+        ]
+        self._validate()
+        self._build_mappings()
+        self._metrics: Dict[str, float] = {}
+        self._confusion: Dict[int, Dict[int, int]] = {}
+
+    def __repr__(self) -> str:
+        return (
+            f"<OrbitAccuracy nodes={len(self.nodes)} "
+            f"approx_orbits={len(self._approx_raw)} exact_orbits={len(self._exact_raw)}>"
+        )
+
+    # ---- Convenience / help ----
+    def help(self) -> str:
+        """Return a short usage/help string.
+
+        :return: Brief one-line instructions on how to use the class.
+        :rtype: str
+        """
+        return (
+            "Instantiate with approx and exact orbit iterables of frozensets. "
+            "Call .compute() then read .metrics or .confusion_map."
+        )
+
+    # ---- Internal validation / mapping builders ----
+    def _validate(self) -> None:
+        """Ensure both partitions cover the same node set.
+
+        :raises ValueError: If the union of nodes in ``approx_orbits`` differs from that in
+            ``exact_orbits``. The raised message includes nodes missing in
+            either partition for quick diagnostics.
+        """
+        approx_nodes: Set[Hashable] = (
+            set().union(*self._approx_raw) if self._approx_raw else set()
+        )
+        exact_nodes: Set[Hashable] = (
+            set().union(*self._exact_raw) if self._exact_raw else set()
+        )
+        if approx_nodes != exact_nodes:
+            missing_in_approx = exact_nodes - approx_nodes
+            missing_in_exact = approx_nodes - exact_nodes
+            msg_parts = []
+            if missing_in_approx:
+                msg_parts.append(
+                    "nodes missing in approx: " f"{sorted(missing_in_approx, key=repr)}"
+                )
+            if missing_in_exact:
+                msg_parts.append(
+                    f"nodes missing in exact: {sorted(missing_in_exact, key=repr)}"
+                )
+            raise ValueError(
+                "Orbit partitions do not cover the same node set. "
+                + " ".join(msg_parts)
+            )
+        self.nodes: Set[Hashable] = approx_nodes
+
+    def _build_mappings(self) -> None:
+        """Build node -> orbit index mappings for both partitions (internal use)."""
+        self._node_to_approx: Dict[Hashable, int] = {}
+        self._node_to_exact: Dict[Hashable, int] = {}
+        for i, orb in enumerate(self._approx_raw):
+            for n in orb:
+                self._node_to_approx[n] = i
+        for j, orb in enumerate(self._exact_raw):
+            for n in orb:
+                self._node_to_exact[n] = j
+
+    # ---- Core API ----
+    def compute(self, brute_force_pairs: bool = True) -> "OrbitAccuracy":
+        """Compute all metrics and build the confusion map.
+
+        This method is chainable and returns ``self``; call :attr:`metrics` or
+        :attr:`confusion_map` afterwards to access results.
+
+        :param brute_force_pairs: If True (default) compute pairwise accuracy by checking all unordered
+                                  node pairs (O(N^2)). For very large node sets a combinatorial
+                                  method (based on orbit sizes) may be preferred; this implementation
+                                  defaults to brute-force because typical orbit counts are moderate.
+        :type brute_force_pairs: bool, optional
+
+        :return: Returns ``self`` to enable chaining.
+        :rtype: OrbitAccuracy
+        """
+        self._compute_node_exact_match_fraction()
+        self._compute_confusion()
+        self._compute_purity()
+        if brute_force_pairs:
+            self._compute_pairwise_accuracy_bruteforce()
+        else:
+            self._compute_pairwise_accuracy_combinatorial_fallback()
+        return self
+
+    def _compute_node_exact_match_fraction(self) -> None:
+        """Compute fraction of nodes whose approx orbit exactly equals the exact orbit."""
+        correct = 0
+        for n in self.nodes:
+            approx_idx = self._node_to_approx[n]
+            exact_idx = self._node_to_exact[n]
+            if self._approx_raw[approx_idx] == self._exact_raw[exact_idx]:
+                correct += 1
+        total = len(self.nodes) or 1
+        self._metrics["node_exact_match_fraction"] = correct / total
+
+    def _compute_confusion(self) -> None:
+        """Build confusion matrix as a dict: approx_idx -> { exact_idx: overlap_count }."""
+        conf: Dict[int, Dict[int, int]] = {}
+        for ai, aorb in enumerate(self._approx_raw):
+            row: Dict[int, int] = {}
+            for ej, eorb in enumerate(self._exact_raw):
+                inter = len(aorb & eorb)
+                if inter:
+                    row[ej] = inter
+            conf[ai] = row
+        self._confusion = conf
+
+    def _compute_purity(self) -> None:
+        """
+        Compute purity: weighted average (by approx-orbit size) of the largest
+        overlap between each approx-orbit and any exact-orbit.
+        """
+        total_nodes = len(self.nodes) or 1
+        weight_sum = 0
+        for ai, aorb in enumerate(self._approx_raw):
+            if not aorb:
+                continue
+            overlaps = self._confusion.get(ai, {})
+            best_overlap = max(overlaps.values()) if overlaps else 0
+            weight_sum += best_overlap
+        self._metrics["purity"] = weight_sum / total_nodes
+
+    def _compute_pairwise_accuracy_bruteforce(self) -> None:
+        """Brute-force O(N^2) pairwise agreement calculation (same-orbit vs different-orbit)."""
+        nodes = list(self.nodes)
+        n = len(nodes)
+        if n < 2:
+            self._metrics["pairwise_accuracy"] = 1.0
+            return
+        matches = 0
+        total = 0
+        for i in range(n):
+            ni = nodes[i]
+            for j in range(i + 1, n):
+                nj = nodes[j]
+                approx_same = self._node_to_approx[ni] == self._node_to_approx[nj]
+                exact_same = self._node_to_exact[ni] == self._node_to_exact[nj]
+                if approx_same == exact_same:
+                    matches += 1
+                total += 1
+        self._metrics["pairwise_accuracy"] = matches / total if total else 1.0
+
+    def _compute_pairwise_accuracy_combinatorial_fallback(self) -> None:
+        """
+        Placeholder for a combinatorial pairwise method (not implemented).
+        Currently delegates to the brute-force implementation.
+        """
+        self._compute_pairwise_accuracy_bruteforce()
+
+    # ---- Properties / accessors ----
+    @property
+    def metrics(self) -> Dict[str, float]:
+        """Return computed metrics.
+
+        :return: Copy of the metrics dictionary. Call :meth:`compute` first to populate.
+        :rtype: dict
+        """
+        return dict(self._metrics)
+
+    @property
+    def confusion_map(self) -> Dict[int, Dict[int, int]]:
+        """Return the confusion map: approx_orbit_index -> { exact_orbit_index: count }.
+
+        :return: Copy of the internal confusion mapping. Call :meth:`compute` first.
+        :rtype: dict
+        """
+        # return a shallow copy to avoid accidental external mutation
+        return {k: dict(v) for k, v in self._confusion.items()}
+
+    @property
+    def approx_orbits(self) -> List[FrozenSet[Hashable]]:
+        """Return the stored approx-orbits as a list of frozensets.
+
+        :return: Internal copy of the approximate orbit list.
+        :rtype: list
+        """
+        return list(self._approx_raw)
+
+    @property
+    def exact_orbits(self) -> List[FrozenSet[Hashable]]:
+        """Return the stored exact-orbits as a list of frozensets.
+
+        :return: Internal copy of the exact orbit list.
+        :rtype: list
+        """
+        return list(self._exact_raw)
+
+    # ---- Human-readable report ----
+    def report(self, max_rows: int = 10) -> str:
+        """Produce a short human-readable report summarising computed metrics and the
+        top confusion rows.
+
+        :param max_rows: Maximum number of confusion rows to include in the textual report.
+                         Default is 10.
+        :type max_rows: int, optional
+
+        :return: A multi-line string summarising the results. Call :meth:`compute`
+                  before calling this method.
+        :rtype: str
+        """
+        lines: List[str] = []
+        m = self.metrics
+        lines.append(repr(self))
+        lines.append("Metrics:")
+        for k in ("node_exact_match_fraction", "pairwise_accuracy", "purity"):
+            if k in m:
+                lines.append(f"  {k}: {m[k]:.6f}")
+        lines.append("Top confusion rows (approx_orbit_idx -> {exact_idx:count}):")
+        for ai in sorted(self._confusion)[:max_rows]:
+            lines.append(f"  {ai} -> {self._confusion[ai]}")
+        return "\n".join(lines)