submine 0.1.1__cp312-cp312-macosx_11_0_arm64.whl

submine/core/graph.py

@@ -0,0 +1,179 @@
+"""Core graph container used throughout *submine*.
+
+Design goals
+------------
+1) Keep a lightweight, dependency-free representation.
+2) Preserve the existing public surface used by wrappers:
+   - ``Graph.nodes`` : list of node ids
+   - ``Graph.edges`` : list of (u, v)
+   - ``Graph.node_labels`` : dict[node_id] -> label (optional)
+   - ``Graph.edge_labels`` : dict[(u, v)] -> label (optional)
+3) Add *optional* edge weights without breaking unweighted algorithms.
+
+Weights are stored as ``Graph.edge_weights`` (dict[(u, v)] -> float). If a
+weight is missing for an edge, it is treated as 1.0.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Hashable, Iterable, Iterator, List, Optional, Protocol, Tuple
+
+
+class GraphSource(Protocol):
+    """Anything that can yield Graph objects."""
+
+    def __iter__(self) -> Iterable["Graph"]:  # pragma: no cover
+        ...
+
+
+@dataclass(eq=True, frozen=True)
+class Node:
+    id: Any
+    label: Optional[Any] = None
+    data: Dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        if self.data is None:
+            object.__setattr__(self, "data", {})
+
+
+class Graph:
+    """Lightweight labeled (optionally weighted) undirected graph."""
+
+    def __init__(
+        self,
+        nodes: Optional[Iterable[Hashable]] = None,
+        edges: Optional[Iterable[Tuple[Hashable, Hashable]]] = None,
+        node_labels: Optional[Dict[Hashable, Any]] = None,
+        edge_labels: Optional[Dict[Tuple[Hashable, Hashable], Any]] = None,
+        edge_weights: Optional[Dict[Tuple[Hashable, Hashable], float]] = None,
+    ) -> None:
+        self.nodes: List[Hashable] = list(nodes) if nodes is not None else []
+        self.edges: List[Tuple[Hashable, Hashable]] = list(edges) if edges is not None else []
+        self.node_labels: Optional[Dict[Hashable, Any]] = node_labels
+        self.edge_labels: Optional[Dict[Tuple[Hashable, Hashable], Any]] = edge_labels
+        self.edge_weights: Optional[Dict[Tuple[Hashable, Hashable], float]] = edge_weights
+
+        # For incremental construction APIs.
+        self._nodes: Dict[Hashable, Node] = {}
+        self._adj: Dict[Hashable, List[Tuple[Hashable, Optional[Any], float]]] = {}
+
+        if self.nodes or self.edges:
+            # Seed internal indices for add_node/add_edge compatibility.
+            for nid in self.nodes:
+                lbl = self.node_labels.get(nid) if self.node_labels else None
+                self._nodes[nid] = Node(nid, lbl, {})
+                self._adj.setdefault(nid, [])
+            for (u, v) in self.edges:
+                lbl = None
+                if self.edge_labels is not None:
+                    lbl = self.edge_labels.get((u, v), self.edge_labels.get((v, u)))
+                w = 1.0
+                if self.edge_weights is not None:
+                    w = float(self.edge_weights.get((u, v), self.edge_weights.get((v, u), 1.0)))
+                self._adj.setdefault(u, []).append((v, lbl, w))
+                self._adj.setdefault(v, []).append((u, lbl, w))
+
+    @property
+    def is_weighted(self) -> bool:
+        if not self.edge_weights:
+            return False
+        return any(float(w) != 1.0 for w in self.edge_weights.values())
+
+    def add_node(self, node_id: Hashable, label: Optional[Any] = None, **data: Any) -> Node:
+        if node_id in self._nodes:
+            n = self._nodes[node_id]
+            lbl = n.label if label is None else label
+            merged = dict(n.data)
+            merged.update(data)
+            n2 = Node(node_id, lbl, merged)
+            self._nodes[node_id] = n2
+            if node_id not in self.nodes:
+                self.nodes.append(node_id)
+            if self.node_labels is not None:
+                self.node_labels[node_id] = lbl
+            self._adj.setdefault(node_id, [])
+            return n2
+
+        n = Node(node_id, label, data or None)
+        self._nodes[node_id] = n
+        self._adj.setdefault(node_id, [])
+        if node_id not in self.nodes:
+            self.nodes.append(node_id)
+        if label is not None:
+            if self.node_labels is None:
+                self.node_labels = {}
+            self.node_labels[node_id] = label
+        return n
+
+    def add_edge(
+        self,
+        u: Hashable,
+        v: Hashable,
+        label: Optional[Any] = None,
+        weight: float = 1.0,
+    ) -> None:
+        if u == v:
+            raise ValueError("Self loops are not supported.")
+        if u not in self._nodes:
+            self.add_node(u)
+        if v not in self._nodes:
+            self.add_node(v)
+
+        self.edges.append((u, v))
+        self._adj.setdefault(u, []).append((v, label, float(weight)))
+        self._adj.setdefault(v, []).append((u, label, float(weight)))
+
+        if label is not None:
+            if self.edge_labels is None:
+                self.edge_labels = {}
+            self.edge_labels[(u, v)] = label
+
+        if float(weight) != 1.0:
+            if self.edge_weights is None:
+                self.edge_weights = {}
+            self.edge_weights[(u, v)] = float(weight)
+
+    def iter_edges(self) -> Iterator[Tuple[Hashable, Hashable, Optional[Any]]]:
+        """Iterate edges once, yielding (u, v, label).
+
+        This preserves the legacy shape expected by existing writers.
+        """
+        seen: set[Tuple[Hashable, Hashable]] = set()
+        for (u, v) in self.edges:
+            a, b = (u, v) if u <= v else (v, u)
+            if (a, b) in seen:
+                continue
+            seen.add((a, b))
+            lbl = None
+            if self.edge_labels is not None:
+                lbl = self.edge_labels.get((u, v), self.edge_labels.get((v, u)))
+            yield (a, b, lbl)
+
+    def iter_edges_with_weights(
+        self,
+    ) -> Iterator[Tuple[Hashable, Hashable, Optional[Any], float]]:
+        """Iterate edges once, yielding (u, v, label, weight)."""
+        seen: set[Tuple[Hashable, Hashable]] = set()
+        for (u, v) in self.edges:
+            a, b = (u, v) if u <= v else (v, u)
+            if (a, b) in seen:
+                continue
+            seen.add((a, b))
+            lbl = None
+            if self.edge_labels is not None:
+                lbl = self.edge_labels.get((u, v), self.edge_labels.get((v, u)))
+            w = 1.0
+            if self.edge_weights is not None:
+                w = float(self.edge_weights.get((u, v), self.edge_weights.get((v, u), 1.0)))
+            yield (a, b, lbl, w)
+
+    def number_of_nodes(self) -> int:
+        return len(self.nodes)
+
+    def number_of_edges(self) -> int:
+        return len(self.edges)
+
+    def __repr__(self) -> str:
+        return f"Graph(num_nodes={self.number_of_nodes()}, num_edges={self.number_of_edges()}, weighted={self.is_weighted})"

submine/core/result.py

@@ -0,0 +1,121 @@
+# submine/core/result.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
+
+from .graph import Graph
+
+__all__ = [
+    "SubgraphOccurrence",
+    "SubgraphPattern",
+    "MiningResult",
+]
+
+
+@dataclass
+class SubgraphOccurrence:
+    """
+    One occurrence (embedding) of a pattern inside a particular input graph.
+
+    Attributes
+    ----------
+    graph_id : int
+        Index of the input graph in the dataset (0-based).
+    node_mapping : Mapping[int, int]
+        Mapping from pattern-local node ids -> node ids in the host graph.
+        Pattern-local ids should be 0..k-1 for a k-node pattern.
+    extra : dict
+        Optional algorithm-specific information
+        (e.g. edge mapping, score, position, etc.).
+    """
+    graph_id: int
+    node_mapping: Mapping[int, int]
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SubgraphPattern:
+    """
+    A mined subgraph pattern.
+
+    Attributes
+    ----------
+    pid : int
+        Pattern identifier (unique within a MiningResult).
+    graph : Graph
+        The pattern itself as a Graph object (pattern-local node ids 0..k-1).
+    support : int
+        Support count (e.g. number of graphs / embeddings where it appears).
+    frequency : Optional[float]
+        Relative frequency (e.g. support / num_graphs); optional.
+    occurrences : list[SubgraphOccurrence]
+        Concrete occurrences of this pattern in the input graphs (optional;
+        some algorithms may not provide embeddings).
+    attributes : dict
+        Algorithm-specific attributes (e.g. score, interestingness, DFScode).
+    """
+    pid: int
+    graph: Graph
+    support: int
+    frequency: Optional[float] = None
+    occurrences: List[SubgraphOccurrence] = field(default_factory=list)
+    attributes: Dict[str, Any] = field(default_factory=dict)
+
+    def add_occurrence(self, occ: SubgraphOccurrence) -> None:
+        self.occurrences.append(occ)
+
+
+@dataclass
+class MiningResult:
+    """
+    Container for the output of a subgraph mining run.
+
+    Attributes
+    ----------
+    patterns : list[SubgraphPattern]
+        List of mined patterns.
+    algorithm : str
+        Name of the algorithm that produced these patterns.
+    params : dict
+        Parameters used for the run (min_support, max_size, etc.).
+    runtime : Optional[float]
+        Wall-clock runtime in seconds, if measured.
+    metadata : dict
+        Additional metadata (dataset info, version, logs, etc.).
+    """
+    patterns: List[SubgraphPattern]
+    algorithm: str
+    params: Dict[str, Any] = field(default_factory=dict)
+    runtime: Optional[float] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __len__(self) -> int:
+        return len(self.patterns)
+
+    def top_k(self, k: int, key: str = "support") -> List[SubgraphPattern]:
+        """
+        Return the top-k patterns sorted by a given key.
+
+        Parameters
+        ----------
+        k : int
+            Number of patterns to return.
+        key : str
+            Sort key: 'support', 'frequency', or any numeric attribute name
+            stored in pattern.attributes[key].
+
+        Returns
+        -------
+        list[SubgraphPattern]
+        """
+        def key_fn(p: SubgraphPattern):
+            if key == "support":
+                return p.support
+            if key == "frequency":
+                return p.frequency if p.frequency is not None else 0.0
+            # fallback to attributes
+            val = p.attributes.get(key, 0.0)
+            return float(val)
+
+        return sorted(self.patterns, key=key_fn, reverse=True)[:k]

submine/datasets/__init__.py

@@ -0,0 +1,11 @@
+"""Built‑in datasets for submine.
+
+This package provides convenience loaders for commonly used benchmark
+datasets in frequent subgraph mining research. Datasets are returned
+as lists of :class:`~submine.core.graph.Graph` objects. The available
+datasets are documented in :mod:`submine.datasets.loaders`.
+"""
+
+from .loaders import get_dataset  # noqa: F401
+
+__all__ = ["get_dataset"]

submine/datasets/loaders.py

@@ -0,0 +1,145 @@
+"""Dataset loaders for submine.
+
+This module contains functions to load well‑known benchmark datasets
+such as MUTAG, ENZYMES and more. Where possible it attempts to use
+existing libraries to fetch the datasets (e.g. torch_geometric or
+networkx), but falls back to a simple synthetic dataset if these are
+unavailable. To add a new dataset, implement a function named
+``load_<datasetname>()`` that returns a list of
+:class:`~submine.core.graph.Graph` objects and register it in the
+``_DATASETS`` dictionary.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, List
+
+from ..core.graph import Graph
+
+
+def _load_toy() -> List[Graph]:
+    """Return a small synthetic dataset useful for testing.
+
+    The dataset contains two graphs: a triangle and a path of length 3.
+    Node labels are single characters.
+    """
+    # Graph 1: triangle A-B-C-A
+    g1 = Graph()
+    g1.add_node(0, label="A")
+    g1.add_node(1, label="B")
+    g1.add_node(2, label="C")
+    g1.add_edge(0, 1, label="ab")
+    g1.add_edge(1, 2, label="bc")
+    g1.add_edge(2, 0, label="ca")
+    # Graph 2: path D-E-F
+    g2 = Graph()
+    g2.add_node(0, label="D")
+    g2.add_node(1, label="E")
+    g2.add_node(2, label="F")
+    g2.add_edge(0, 1, label="de")
+    g2.add_edge(1, 2, label="ef")
+    return [g1, g2]
+
+
+def _load_mutag() -> List[Graph]:
+    """Load the MUTAG dataset if torch_geometric is available.
+
+    If the dataset cannot be downloaded or the library is missing a
+    NotImplementedError is raised.
+    """
+    try:
+        from torch_geometric.datasets import TUDataset  # type: ignore
+        import torch_geometric.utils  # noqa: F401  # type: ignore
+    except Exception as e:
+        raise NotImplementedError("Loading MUTAG requires torch_geometric and internet access") from e
+    # Fetch dataset
+    dataset = TUDataset(root="/tmp/MUTAG", name="MUTAG")
+    graphs: List[Graph] = []
+    for data in dataset:
+        # Convert to networkx graph then to our Graph
+        import networkx as nx  # type: ignore
+        g_nx = nx.Graph()
+        # Nodes with labels from x attribute (one-hot) if present
+        for i in range(data.num_nodes):
+            label = None
+            if hasattr(data, "node_label") and data.node_label is not None:
+                label = str(int(data.node_label[i]))
+            g_nx.add_node(i, label=label)
+        # Edges
+        edge_attr = data.edge_attr if data.edge_attr is not None else None
+        for j in range(data.edge_index.size(1)):
+            u = int(data.edge_index[0, j])
+            v = int(data.edge_index[1, j])
+            label = None
+            if edge_attr is not None:
+                label = str(int(edge_attr[j].item()))
+            g_nx.add_edge(u, v, label=label)
+        graphs.append(Graph.from_networkx(g_nx))
+    return graphs
+
+
+def _load_enzymes() -> List[Graph]:
+    """Load the ENZYMES dataset if torch_geometric is available."""
+    try:
+        from torch_geometric.datasets import TUDataset  # type: ignore
+        import torch_geometric.utils  # noqa: F401  # type: ignore
+    except Exception as e:
+        raise NotImplementedError("Loading ENZYMES requires torch_geometric and internet access") from e
+    dataset = TUDataset(root="/tmp/ENZYMES", name="ENZYMES")
+    graphs: List[Graph] = []
+    for data in dataset:
+        import networkx as nx  # type: ignore
+        g_nx = nx.Graph()
+        for i in range(data.num_nodes):
+            label = None
+            if hasattr(data, "node_label") and data.node_label is not None:
+                label = str(int(data.node_label[i]))
+            g_nx.add_node(i, label=label)
+        edge_attr = data.edge_attr if data.edge_attr is not None else None
+        for j in range(data.edge_index.size(1)):
+            u = int(data.edge_index[0, j])
+            v = int(data.edge_index[1, j])
+            label = None
+            if edge_attr is not None:
+                label = str(int(edge_attr[j].item()))
+            g_nx.add_edge(u, v, label=label)
+        graphs.append(Graph.from_networkx(g_nx))
+    return graphs
+
+
+DATASET_LOADERS: Dict[str, Callable[[], List[Graph]]] = {
+    "toy": _load_toy,
+    "mutag": _load_mutag,
+    "enzymes": _load_enzymes,
+}
+
+
+def get_dataset(name: str, **kwargs) -> List[Graph]:
+    """Load a dataset by name.
+
+    Supported names include ``"toy"``, ``"mutag"`` and ``"enzymes"``.
+    Names are case insensitive.
+
+    Parameters
+    ----------
+    name: str
+        Dataset identifier.
+    **kwargs: dict
+        Additional keyword arguments passed to the underlying loader. Not
+        currently used.
+
+    Returns
+    -------
+    List[Graph]
+        List of graphs comprising the dataset.
+
+    Raises
+    ------
+    KeyError
+        If the dataset name is unknown.
+    """
+    key = name.lower()
+    if key not in DATASET_LOADERS:
+        raise KeyError(f"Unknown dataset '{name}'. Available datasets: {list(DATASET_LOADERS.keys())}")
+    loader = DATASET_LOADERS[key]
+    return loader()

submine/errors.py

@@ -0,0 +1,41 @@
+"""Submine exception hierarchy.
+
+These exceptions provide stable, semantically meaningful error types that
+downstream applications can catch without parsing strings.
+"""
+
+from __future__ import annotations
+
+
+class SubmineError(Exception):
+    """Base class for all library-defined exceptions."""
+
+
+class SubmineInputError(SubmineError, ValueError):
+    """Raised when user-supplied inputs (files, graphs, parameters) are invalid."""
+
+
+class ParameterValidationError(SubmineInputError):
+    """Raised when algorithm parameters fail validation."""
+
+
+class BackendUnavailableError(SubmineError, RuntimeError):
+    """Raised when an optional external backend (binary, JVM, etc.) is unavailable."""
+
+
+class BackendExecutionError(SubmineError, RuntimeError):
+    """Raised when an external backend fails during execution."""
+
+
+class ResourceLimitError(SubmineInputError):
+    """Raised when an input exceeds configured resource limits."""
+
+__all__ = [
+    "SubmineError",
+    "SubmineInputError",
+    "ParameterValidationError",
+    "BackendUnavailableError",
+    "BackendExecutionError",
+    "ResourceLimitError",
+]
+

submine/io/__init__.py

@@ -0,0 +1,30 @@
+"""Input/Output utilities for submine.
+
+This package contains helper functions to serialise graphs to the input
+formats expected by different subgraph mining algorithms and to parse
+their outputs back into :class:`~submine.core.graph.Graph` objects.
+"""
+
+from .common import ensure_dir  # noqa: F401
+from .gspan import write_gspan_dataset  # noqa: F401
+from .transcode import (  # noqa: F401
+    detect_format,
+    load_graphs,
+    transcode_path,
+    FMT_EDGELIST,
+    FMT_GEXF,
+    FMT_GSPAN,
+    FMT_LG,
+)
+
+__all__ = [
+    "ensure_dir",
+    "write_gspan_dataset",
+    "detect_format",
+    "load_graphs",
+    "transcode_path",
+    "FMT_EDGELIST",
+    "FMT_GEXF",
+    "FMT_GSPAN",
+    "FMT_LG",
+]

submine/io/common.py

@@ -0,0 +1,173 @@
+"""Common I/O helpers used by algorithm wrappers.
+
+Functions defined here are not tied to a specific algorithm. They
+perform tasks such as ensuring that directories exist or creating
+temporary working directories.
+"""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Iterator
+
+from pathlib import Path
+from typing import List, Optional, Tuple, Any
+
+from ..core.graph import Graph
+from ..errors import SubmineInputError
+from ..utils.checks import iter_text_lines
+
+
+def ensure_dir(path: str | Path) -> Path:
+    """Ensure that the directory at ``path`` exists.
+
+    Parameters
+    ----------
+    path: str or pathlib.Path
+        Directory path to create if it does not exist.
+
+    Returns
+    -------
+    pathlib.Path
+        The Path instance corresponding to ``path``.
+    """
+    p = Path(path)
+    if not p.exists():
+        p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+@contextmanager
+def temporary_directory() -> Iterator[Path]:
+    """Context manager yielding a temporary directory as a Path.
+
+    The directory and its contents are removed on exit. Useful when
+    writing temporary files for external algorithms.
+    """
+    with TemporaryDirectory() as tmp:
+        yield Path(tmp)
+
+
+def _maybe_int(x: str) -> Any:
+    """Try to parse as int, fallback to string."""
+    try:
+        return int(x)
+    except ValueError:
+        return x
+
+
+def read_edgelist_dataset(path: str | Path) -> List[Graph]:
+    """
+    Read an edge-list dataset file and return a list of Graph objects.
+
+    Supported formats
+    -----------------
+    1) Single graph (no 't # gid' headers):
+
+        u v
+        u v label
+
+       - Nodes are inferred from all endpoints.
+       - Edge labels are used if a third column is present on ANY line.
+
+    2) Multiple graphs (with gSpan-like headers):
+
+        t # 0
+        u v
+        u v label
+        t # 1
+        u v
+        ...
+
+       - Each 't # gid' starts a new graph.
+       - Nodes are inferred per graph.
+
+    Returns
+    -------
+    List[Graph]
+        A list of Graph objects constructed from the file.
+    """
+    path = Path(path)
+
+    graphs: List[Graph] = []
+
+    current_edges: Optional[List[Tuple[Any, Any]]] = None
+    current_edge_labels: Optional[dict[Tuple[Any, Any], Any]] = None
+    any_labels_in_current = False
+
+    def flush_current_graph():
+        nonlocal current_edges, current_edge_labels, any_labels_in_current
+        if current_edges is None:
+            return
+
+        # Build node set from edges
+        nodes_set = set()
+        for u, v in current_edges:
+            nodes_set.add(u)
+            nodes_set.add(v)
+        # Deterministic node ordering for reproducible transcoding/writing.
+        # Edge lists may mix ints/strings; sort by type name then by string value.
+        nodes = sorted(nodes_set, key=lambda x: (type(x).__name__, str(x)))
+
+        edge_labels = current_edge_labels if any_labels_in_current else None
+
+        graphs.append(
+            Graph(
+                nodes=nodes,
+                edges=current_edges,
+                node_labels=None,        # edge-list doesn't carry node labels
+                edge_labels=edge_labels,
+            )
+        )
+        current_edges = None
+        current_edge_labels = None
+        any_labels_in_current = False
+
+    for raw_line in iter_text_lines(path):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+
+        # Accept both whitespace-separated and comma-separated edge lists.
+        if "," in line:
+            line = line.replace(",", " ")
+        parts = line.split()
+        rec_type = parts[0]
+
+        # Multi-graph header: t # gid
+        if rec_type == "t" and len(parts) >= 3 and parts[1] == "#":
+            # flush previous graph, start new
+            flush_current_graph()
+            current_edges = []
+            current_edge_labels = {}
+            any_labels_in_current = False
+            # we ignore gid value; it's just a marker
+            continue
+
+        # Otherwise, treat as an edge line: u v [label]
+        if current_edges is None:
+            # No graph header seen yet: assume single-graph file
+            current_edges = []
+            current_edge_labels = {}
+            any_labels_in_current = False
+
+        if len(parts) < 2:
+            raise ValueError(f"Malformed edge line: {line!r}")
+
+        u = _maybe_int(parts[0])
+        v = _maybe_int(parts[1])
+
+        if len(parts) >= 3:
+            lbl = _maybe_int(parts[2])
+            any_labels_in_current = True
+            current_edges.append((u, v))
+            current_edge_labels[(u, v)] = lbl  # type: ignore[index]
+        else:
+            current_edges.append((u, v))
+
+    # Flush final graph (single-graph files without a trailing header)
+    flush_current_graph()
+    return graphs