submine 0.1.1__cp312-cp312-macosx_11_0_arm64.whl

submine/io/gexf.py

@@ -0,0 +1,88 @@
+"""GEXF reader.
+
+We use NetworkX's GEXF parser to support common graph exports.
+
+Mapping rules
+-------------
+- Node labels: if a node attribute named ``label`` exists, it is used; otherwise
+  we use the node id as its label.
+- Edge labels: if an edge attribute named ``label`` exists, it is used.
+- Edge weights: if an edge attribute named ``weight`` exists and is not 1.0, it
+  is stored in :attr:`submine.core.graph.Graph.edge_weights`.
+
+Notes
+-----
+GEXF can represent directed graphs, multi-edges, and parallel edges. The internal
+``Graph`` container in *submine* is currently undirected and does not preserve
+parallel edges. We therefore:
+  - coerce to an undirected simple graph
+  - keep the first-seen label/weight for each undirected edge
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Hashable, Tuple
+
+import networkx as nx
+
+from ..core.graph import Graph
+
+
+def read_gexf(path: str | Path) -> Graph:
+    p = Path(path)
+    g_nx = nx.read_gexf(p)
+
+    # Coerce to undirected simple graph to match our internal container.
+    if isinstance(g_nx, (nx.MultiGraph, nx.MultiDiGraph)):
+        g_simple = nx.Graph()
+        for u, v, data in g_nx.edges(data=True):
+            if u == v:
+                continue
+            if g_simple.has_edge(u, v):
+                continue
+            g_simple.add_edge(u, v, **(data or {}))
+        for n, data in g_nx.nodes(data=True):
+            g_simple.add_node(n, **(data or {}))
+        g_nx = g_simple
+    else:
+        g_nx = nx.Graph(g_nx)
+
+    nodes = list(g_nx.nodes())
+
+    node_labels: Dict[Hashable, Any] = {}
+    for n, data in g_nx.nodes(data=True):
+        if data is None:
+            node_labels[n] = str(n)
+        else:
+            node_labels[n] = data.get("label", str(n))
+
+    edges = []
+    edge_labels: Dict[Tuple[Hashable, Hashable], Any] = {}
+    edge_weights: Dict[Tuple[Hashable, Hashable], float] = {}
+
+    for u, v, data in g_nx.edges(data=True):
+        if u == v:
+            continue
+        a, b = (u, v) if str(u) <= str(v) else (v, u)
+        key = (a, b)
+        edges.append(key)
+
+        if data:
+            if "label" in data and data["label"] is not None:
+                edge_labels[key] = data["label"]
+            if "weight" in data and data["weight"] is not None:
+                try:
+                    w = float(data["weight"])
+                except Exception:
+                    w = 1.0
+                if w != 1.0:
+                    edge_weights[key] = w
+
+    return Graph(
+        nodes=nodes,
+        edges=edges,
+        node_labels=node_labels or None,
+        edge_labels=edge_labels or None,
+        edge_weights=edge_weights or None,
+    )

submine/io/gspan.py

@@ -0,0 +1,268 @@
+# submine/io/gspan.py
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Hashable, Iterable, List, Tuple
+
+from ..core.graph import Graph
+from ..errors import SubmineInputError
+from ..utils.checks import iter_text_lines
+
+
+
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+
+
+def read_gspan_dataset(path: Path | str) -> List[Graph]:
+    """
+    Read a gSpan-formatted dataset file and return a list of Graph objects.
+
+    Expected format:
+
+        t # N         # start of N-th graph
+        v M L         # vertex M has label L
+        e P Q L       # edge (P, Q) has label L
+        ...
+        t # -1        # end of file sentinel (required by some gSpan impls)
+
+    Notes
+    -----
+    - Vertex ids within each graph are assumed to be integers (0..n-1).
+    - Labels are read as integers (you can remap them later if desired).
+    - Edges are treated as undirected; we store them as (min(u, v), max(u, v))
+      and avoid duplicates.
+    """
+    path = Path(path)
+
+    graphs: List[Graph] = []
+
+    current_nodes: Optional[list[int]] = None
+    current_node_labels: Optional[dict[int, int]] = None
+    current_edges: Optional[list[tuple[int, int]]] = None
+    current_edge_labels: Optional[dict[tuple[int, int], int]] = None
+
+    def flush_current_graph():
+        nonlocal current_nodes, current_node_labels, current_edges, current_edge_labels
+        if current_nodes is None:
+            return
+        graphs.append(
+            Graph(
+                nodes=current_nodes,
+                edges=current_edges,
+                node_labels=current_node_labels,
+                edge_labels=current_edge_labels,
+            )
+        )
+        current_nodes = None
+        current_node_labels = None
+        current_edges = None
+        current_edge_labels = None
+
+    for raw_line in iter_text_lines(path):
+        line = raw_line.strip()
+        if not line:
+            continue
+        parts = line.split()
+
+        rec_type = parts[0]
+
+        # Graph header: t # gid
+        if rec_type == "t":
+            # flush previous graph if any
+            if len(parts) >= 3:
+                gid = int(parts[2])
+            else:
+                raise ValueError(f"Malformed 't' line: {line!r}")
+
+            if gid == -1:
+                # End-of-dataset sentinel: flush the last graph and stop
+                flush_current_graph()
+                break
+
+            # start a new graph
+            flush_current_graph()
+            current_nodes = []
+            current_node_labels = {}
+            current_edges = []
+            current_edge_labels = {}
+
+        elif rec_type == "v":
+            if current_nodes is None:
+                raise ValueError(f"Vertex line outside of any graph: {line!r}")
+            if len(parts) < 3:
+                raise ValueError(f"Malformed 'v' line: {line!r}")
+            vid = int(parts[1])
+            lbl = int(parts[2])
+            current_nodes.append(vid)
+            current_node_labels[vid] = lbl  # type: ignore[arg-type]
+
+        elif rec_type == "e":
+            if current_edges is None:
+                raise ValueError(f"Edge line outside of any graph: {line!r}")
+            if len(parts) < 4:
+                raise ValueError(f"Malformed 'e' line: {line!r}")
+            u = int(parts[1])
+            v = int(parts[2])
+            lbl = int(parts[3])
+
+            # treat as undirected, avoid duplicates
+            if u <= v:
+                key = (u, v)
+            else:
+                key = (v, u)
+
+            if key not in current_edge_labels:  # type: ignore[operator]
+                current_edges.append(key)       # type: ignore[arg-type]
+                current_edge_labels[key] = lbl  # type: ignore[index]
+
+        else:
+            # Unknown record; you can choose to ignore or raise
+            raise SubmineInputError(f"Unknown record type '{rec_type}' in line: {line!r}")
+
+    # If file ended without the required terminator, still return what we have.
+    flush_current_graph()
+    return graphs
+
+def convert_gspan_graph(gspan_g) -> Graph:
+    """
+    Convert a vendored gSpan graph.Graph object into submine.core.graph.Graph.
+
+    Assumes:
+      - gspan_g.vertices is a dict {vid: Vertex}
+      - Vertex has: vid, vlb, edges (dict[to_vid, Edge])
+      - Edge has: eid, frm, to, elb
+    """
+    nodes = []
+    node_labels = {}
+    edges = []
+    edge_labels = {}
+
+    # 1. Nodes + labels
+    for vid, v in gspan_g.vertices.items():
+        nodes.append(vid)
+        node_labels[vid] = v.vlb
+
+    # 2. Edges (avoid duplicates in undirected graphs)
+    seen = set()
+    for vid, v in gspan_g.vertices.items():
+        # v.edges is a dict: {to_vid: Edge}
+        for to, e in v.edges.items():
+            u, w = e.frm, e.to
+            # canonicalize for undirected graph
+            key = (u, w) if u <= w else (w, u)
+            if key in seen:
+                continue
+            seen.add(key)
+            edges.append(key)
+            edge_labels[key] = e.elb
+
+    return Graph(
+        nodes=nodes,
+        edges=edges,
+        node_labels=node_labels,
+        edge_labels=edge_labels,
+    )
+
+
+def _build_label_maps(graphs: List[Graph]):
+    """
+    Map arbitrary node/edge labels to consecutive ints >= 2,
+    because gSpan forbids 0 and 1.
+    """
+    node_label_map: Dict[Hashable, int] = {}
+    edge_label_map: Dict[Hashable, int] = {}
+
+    next_node_label = 2
+    next_edge_label = 2
+
+    for G in graphs:
+        # Node labels
+        if G.node_labels is not None:
+            for nid in G.nodes:
+                lbl = G.node_labels.get(nid, None)
+                if lbl is None:
+                    continue
+                if lbl not in node_label_map:
+                    node_label_map[lbl] = next_node_label
+                    next_node_label += 1
+
+        # Edge labels
+        if G.edge_labels is not None:
+            for e, lbl in G.edge_labels.items():
+                if lbl not in edge_label_map:
+                    edge_label_map[lbl] = next_edge_label
+                    next_edge_label += 1
+
+    # Fallback: if there are unlabeled nodes/edges, give them a default label
+    if not node_label_map:
+        node_label_map["__default_node__"] = 2
+    if not edge_label_map:
+        edge_label_map["__default_edge__"] = 2
+
+    return node_label_map, edge_label_map
+
+
+def write_gspan_dataset(graphs: Iterable[Graph], path: Path) -> None:
+    """
+    Write a list of Graph objects to a gSpan-compatible file.
+
+    Format:
+        t # N           -> N-th graph
+        v M L           -> vertex M has label L
+        e P Q L         -> edge (P, Q) has label L
+        ...
+        t # -1          -> end of file
+
+    NOTE:
+      - Vertex ids must be 0..n-1 *within each graph*.
+      - All labels must be integers >= 2 (we map them if needed).
+    """
+    
+    graphs = list(graphs)
+    node_label_map, edge_label_map = _build_label_maps(graphs)
+
+    with path.open("w") as f:
+        for gid, G in enumerate(graphs):
+            f.write(f"t # {gid}\n")
+
+            # Remap node ids to 0..n-1 locally
+            id_map = {orig_id: new_id for new_id, orig_id in enumerate(G.nodes)}
+
+            # Write vertices
+            for orig_id in G.nodes:
+                new_id = id_map[orig_id]
+                if G.node_labels is None:
+                    # use default label
+                    label_key = "__default_node__"
+                else:
+                    raw_lbl = G.node_labels.get(orig_id, "__default_node__")
+                    label_key = raw_lbl if raw_lbl in node_label_map else "__default_node__"
+
+                lbl_int = node_label_map[label_key]
+                f.write(f"v {new_id} {lbl_int}\n")
+
+            # Write edges
+            for e in G.edges:
+                if len(e) == 2:
+                    u, v = e
+                    raw_elbl = "__default_edge__"
+                elif len(e) == 3:
+                    u, v, raw_elbl = e
+                else:
+                    raise ValueError(f"Edge tuple must be (u,v) or (u,v,label), got {e!r}")
+
+                u_new = id_map[u]
+                v_new = id_map[v]
+
+                if G.edge_labels is not None:
+                    raw_elbl = G.edge_labels.get((u, v), raw_elbl)
+
+                label_key = raw_elbl if raw_elbl in edge_label_map else "__default_edge__"
+                elbl_int = edge_label_map[label_key]
+
+                f.write(f"e {u_new} {v_new} {elbl_int}\n")
+
+        # Required terminator for this implementation
+        f.write("t # -1\n")

submine/io/sopagrami.py

@@ -0,0 +1,143 @@
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Hashable, Optional, Tuple
+
+from ..core.graph import Graph
+from ..errors import SubmineInputError
+from ..utils.checks import iter_text_lines
+
+
+def read_lg(path: str | Path) -> Graph:
+    """Read a single SoPaGraMi/gSpan-style ``.lg`` file into :class:`~submine.core.graph.Graph`.
+
+    Supports edge lines of the form:
+
+    - ``e u v``
+    - ``e u v label``
+    - ``e u v label weight``
+    - ``e u v weight`` (rare; treated as unlabeled edge with weight)
+
+    The reader is streaming and suitable for large graphs.
+    """
+    path = Path(path)
+
+    nodes: list[int] = []
+    node_labels: dict[int, str] = {}
+    edges: list[Tuple[int, int]] = []
+    edge_labels: dict[Tuple[int, int], str] = {}
+    edge_weights: dict[Tuple[int, int], float] = {}
+
+    with path.open("r", encoding="utf-8", errors="replace") as f:
+        for raw_line in f:
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+
+            parts = line.split()
+            rec = parts[0]
+
+            if rec == "t":
+                # dataset marker (ignored); SoPaGraMi uses a single graph in practice
+                continue
+
+            if rec == "v":
+                if len(parts) < 3:
+                    raise SubmineInputError(f"Malformed vertex line: {line!r}")
+                vid = int(parts[1])
+                lbl = parts[2]
+                if vid not in node_labels:
+                    nodes.append(vid)
+                node_labels[vid] = lbl
+                continue
+
+            if rec == "e":
+                if len(parts) < 3:
+                    raise SubmineInputError(f"Malformed edge line: {line!r}")
+                u = int(parts[1])
+                v = int(parts[2])
+                edges.append((u, v))
+
+                # Parse optional label / weight. We accept a few variants.
+                lbl: Optional[str] = None
+                w: Optional[float] = None
+                if len(parts) == 4:
+                    # Could be label or weight. Prefer weight if it parses cleanly.
+                    try:
+                        w = float(parts[3])
+                    except ValueError:
+                        lbl = parts[3]
+                elif len(parts) >= 5:
+                    lbl = parts[3]
+                    try:
+                        w = float(parts[4])
+                    except ValueError:
+                        w = None
+
+                a, b = (u, v) if u <= v else (v, u)
+                if lbl is not None:
+                    edge_labels[(a, b)] = lbl
+                if w is not None and float(w) != 1.0:
+                    edge_weights[(a, b)] = float(w)
+                continue
+
+            # Unknown line type: ignore for robustness.
+            continue
+
+    # In case vertices were not explicitly listed, infer nodes from edges.
+    if not nodes:
+        s = set()
+        for (u, v) in edges:
+            s.add(u)
+            s.add(v)
+        nodes = sorted(s)
+
+    return Graph(nodes=nodes, edges=edges, node_labels=node_labels or None, edge_labels=edge_labels or None, edge_weights=edge_weights or None)
+
+
+def write_lg(graph: Graph, path: str | Path, directed: bool = False, include_weight: bool = False) -> None:
+    """
+    Write a single Graph to SoPaGraMi's .lg format.
+
+    - Nodes are reindexed to 0..n-1 internally.
+    - Node labels come from graph.node_labels (fallback to string of node id).
+    - Edge labels come from graph.edge_labels (fallback to empty string).
+    """
+    path = Path(path)
+
+    # Map original node ids -> contiguous [0..n-1]
+    node_ids = list(graph.nodes)
+    id_map: Dict[Hashable, int] = {nid: i for i, nid in enumerate(node_ids)}
+
+    node_labels = graph.node_labels or {}
+    edge_labels = graph.edge_labels or {}
+    edge_weights = graph.edge_weights or {}
+
+    with path.open("w") as f:
+        # vertices
+        for nid in node_ids:
+            idx = id_map[nid]
+            lbl = node_labels.get(nid, str(nid))
+            f.write(f"v {idx} {lbl}\n")
+
+        # edges
+        for (u_orig, v_orig) in graph.edges:
+            u = id_map[u_orig]
+            v = id_map[v_orig]
+
+            # SoPaGraMi supports directed; if undirected we still write one edge
+            lbl = edge_labels.get((u_orig, v_orig)) or edge_labels.get((v_orig, u_orig)) or ""
+            w = edge_weights.get((u_orig, v_orig), edge_weights.get((v_orig, u_orig), 1.0))
+
+            if include_weight and float(w) != 1.0:
+                # If there is no label, we still emit a placeholder label to keep parsing unambiguous.
+                if lbl == "":
+                    f.write(f"e {u} {v} _ {float(w)}\n")
+                else:
+                    f.write(f"e {u} {v} {lbl} {float(w)}\n")
+            else:
+                if lbl == "":
+                    f.write(f"e {u} {v}\n")
+                else:
+                    f.write(f"e {u} {v} {lbl}\n")

submine/io/transcode.py

@@ -0,0 +1,147 @@
+"""Format detection and transcoding utilities.
+
+Many third-party miners operate on a *native on-disk* format (e.g., gSpan datasets
+or SoPaGraMi ``.lg``). For these miners, the most efficient pipeline is:
+
+    user input file  ->  transcode to miner native file  ->  miner runs
+
+This module implements the 'transcode to native' step so the API does not need to
+round-trip through an intermediate :class:`~submine.core.graph.Graph` unless the
+input itself is not in the miner's native format.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Optional
+import re
+from ..core.graph import Graph
+
+
+class UnknownFormatError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class FormatSpec:
+    """A lightweight format descriptor."""
+
+    key: str
+    suffixes: tuple[str, ...]
+
+
+# Canonical format keys used across the library.
+FMT_LG = "lg"  # SoPaGraMi single-graph format
+FMT_GSPAN = "gspan"  # gSpan dataset format (t/v/e ... t#-1)
+FMT_GEXF = "gexf"  # NetworkX-readable GEXF
+FMT_EDGELIST = "edgelist"  # whitespace-separated u v [label]
+
+_GSPAN_DATA_RE = re.compile(r".*\.data(\.[A-Za-z0-9_-]+)?$")  # matches .data, .data.x, .data.2 etc
+_KNOWN_FORMATS: List[FormatSpec] = [
+    FormatSpec(FMT_LG, (".lg",)),
+    # treat both classic .gspan and Gatech-like *.data / *.data.x as gSpan datasets
+    FormatSpec(FMT_GSPAN, (".gspan", ".data", ".data.x")),
+    FormatSpec(FMT_GEXF, (".gexf",)),
+    FormatSpec(FMT_EDGELIST, (".edgelist", ".txt", ".tsv", ".csv")),
+]
+
+
+def detect_format(path: str | Path) -> str:
+    """Detect the most likely input format from a file path.
+
+    Detection is filename-based (not content-based) by design for speed.
+
+    Notes
+    -----
+    - Gatech-style gSpan datasets frequently use ``*.data`` and ``*.data.<tag>`` where
+      ``<tag>`` may be an integer shard index (e.g., ``.data.2``) or an arbitrary token
+      (e.g., ``.data.x``). We treat all of these as :data:`FMT_GSPAN`.
+    - For ``.txt/.csv/.tsv`` we assume edge-list unless otherwise specified.
+    """
+    p = Path(path)
+    name = p.name.lower()
+    suf = p.suffix.lower()
+
+    # Handle multi-suffix gSpan dataset conventions first.
+    if _GSPAN_DATA_RE.match(name):
+        return FMT_GSPAN
+
+    # Exact suffix matches (single suffix) for known formats.
+    for spec in _KNOWN_FORMATS:
+        if suf in spec.suffixes:
+            return spec.key
+
+    # Fallback for compound suffixes like ".data.x" where Path.suffix == ".x".
+    for spec in _KNOWN_FORMATS:
+        for ss in spec.suffixes:
+            if name.endswith(ss):
+                return spec.key
+
+    raise UnknownFormatError(f"Cannot detect graph format from file: {p}")
+
+
+def load_graphs(path: str | Path, *, fmt: Optional[str] = None) -> List[Graph]:
+    """Load graphs from a supported file format."""
+    p = Path(path)
+    fmt = fmt or detect_format(p)
+
+    if fmt == FMT_GSPAN:
+        from .gspan import read_gspan_dataset
+
+        return list(read_gspan_dataset(p))
+
+    if fmt == FMT_LG:
+        from .sopagrami import read_lg
+
+        return [read_lg(p)]
+
+    if fmt == FMT_EDGELIST:
+        from .common import read_edgelist_dataset
+
+        return list(read_edgelist_dataset(p))
+
+    if fmt == FMT_GEXF:
+        from .gexf import read_gexf
+
+        return [read_gexf(p)]
+
+    raise UnknownFormatError(f"Unsupported input format: {fmt}")
+
+
+def write_graphs(graphs: Iterable[Graph], path: str | Path, *, fmt: str) -> Path:
+    """Write graphs to a given native format."""
+    p = Path(path)
+
+    if fmt == FMT_GSPAN:
+        from .gspan import write_gspan_dataset
+
+        write_gspan_dataset(list(graphs), p)
+        return p
+
+    if fmt == FMT_LG:
+        from .sopagrami import write_lg
+
+        gs = list(graphs)
+        if len(gs) != 1:
+            raise ValueError(f".lg expects exactly one graph; got {len(gs)}")
+        write_lg(gs[0], p)
+        return p
+
+    raise UnknownFormatError(f"Unsupported output format: {fmt}")
+
+
+def transcode_path(
+    src_path: str | Path,
+    dst_path: str | Path,
+    *,
+    dst_fmt: str,
+    src_fmt: Optional[str] = None,
+) -> Path:
+    """Transcode an on-disk graph dataset to another format.
+
+    This function parses the input *once* into in-memory graphs (only when needed)
+    and then writes the target native file.
+    """
+    graphs = load_graphs(src_path, fmt=src_fmt)
+    return write_graphs(graphs, dst_path, fmt=dst_fmt)

submine/registry.py

@@ -0,0 +1,8 @@
+# submine/registry.py
+from __future__ import annotations
+
+from typing import Dict, Type
+
+# We intentionally don't import SubgraphMiner here to avoid cycles.
+# We just store "type" and let base.py handle typing.
+available_algorithms: Dict[str, Type] = {}

submine/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Miscellaneous utilities used across submine."""
+
+from .logging import get_logger  # noqa: F401
+from .checks import is_tool_available  # noqa: F401
+
+__all__ = ["get_logger", "is_tool_available"]