molprim 0.1.0__py3-none-any.whl

molprim/__init__.py

@@ -0,0 +1,24 @@
+"""scikit-learn interface for primitive structure extraction and graph kernels.
+
+Wongsriphisant et al., "A classification of biochemical compounds based on
+their primitive structures and graph kernels", 2020.
+"""
+from importlib.metadata import PackageNotFoundError, version
+
+from .datasets import fetch_tudataset, read_tudataset
+from .extractor import PrimitiveStructureExtractor
+from .features import LabelPairEdgeCounter
+from .kernels import GraphKernelTransformer
+
+try:
+    __version__ = version("molprim")
+except PackageNotFoundError:  # running from a source checkout without installing
+    __version__ = "unknown"
+
+__all__ = [
+    "GraphKernelTransformer",
+    "LabelPairEdgeCounter",
+    "PrimitiveStructureExtractor",
+    "fetch_tudataset",
+    "read_tudataset",
+]

molprim/_algorithms.py

@@ -0,0 +1,198 @@
+"""Primitive structure selection (Algorithm 1) and extraction (Algorithm 2).
+
+Candidates are labelled cycles, stars and single edges, so instead of generic
+subgraph isomorphism (VF2) each family is enumerated directly and identified
+by a canonical key built from its labels:
+
+- cycle: ``("C", labels)``, the smallest rotation or reflection of the labels
+  around the cycle
+- star: ``("S", centre_label, sorted_leaf_labels)``
+- edge: ``("P2", sorted_end_labels)``
+
+Two labelled cycles (stars, edges) are isomorphic exactly when their keys are
+equal, so this gives the same result as the VF2 code in the original
+notebooks.
+"""
+from collections import defaultdict
+from itertools import combinations
+from math import factorial
+
+import networkx as nx
+from joblib import Parallel, delayed
+
+EDGE_PREFIX = "P2"
+
+
+def _order(labels):
+    """Sort key that works for any hashable labels, including mixed types."""
+    return tuple(map(repr, labels))
+
+
+def _sorted(labels):
+    return tuple(sorted(labels, key=lambda label: repr(label)))
+
+
+def _cycle_key(labels):
+    labels = list(labels)
+    n = len(labels)
+    reflected = labels[::-1]
+    variants = [tuple(seq[i:] + seq[:i]) for seq in (labels, reflected) for i in range(n)]
+    return ("C", min(variants, key=_order))
+
+
+def check_sizes(cycle_sizes, star_sizes):
+    for kind, sizes in (("cycle", cycle_sizes), ("star", star_sizes)):
+        for n in sizes:
+            if n < 3:
+                raise ValueError(f"{kind} sizes must be >= 3, got {n}")
+
+
+def iter_structures(graph, cycle_sizes, star_sizes, include_edge, node_label, induced):
+    """Yield ``(prefix, key, nodes)`` for every cycle, star and edge of ``graph``.
+
+    With ``induced=True`` only induced structures are produced (chordless
+    cycles, stars whose leaves are pairwise non-adjacent), as in candidate
+    selection. With ``induced=False`` every occurrence is produced, as in
+    extraction.
+    """
+    label = {n: data[node_label] for n, data in graph.nodes(data=True)}
+    if cycle_sizes:
+        find_cycles = nx.chordless_cycles if induced else nx.simple_cycles
+        for cycle in find_cycles(graph, max(cycle_sizes)):
+            if len(cycle) in cycle_sizes:
+                yield f"C{len(cycle)}", _cycle_key(label[n] for n in cycle), cycle
+    for centre in graph:
+        neighbours = [n for n in graph[centre] if n != centre]
+        for size in star_sizes:
+            for leaves in combinations(neighbours, size - 1):
+                if induced and any(graph.has_edge(a, b) for a, b in combinations(leaves, 2)):
+                    continue
+                yield f"S{size}", ("S", label[centre], _sorted(label[n] for n in leaves)), (centre, *leaves)
+    if include_edge:
+        for u, v in graph.edges:
+            if u != v:
+                yield EDGE_PREFIX, (EDGE_PREFIX, _sorted((label[u], label[v]))), (u, v)
+
+
+def _graph_counts(graph, cycle_sizes, star_sizes, include_edge, node_label):
+    counts = defaultdict(int)
+    prefixes = {}
+    for prefix, key, _ in iter_structures(graph, cycle_sizes, star_sizes, include_edge, node_label, induced=True):
+        counts[key] += 1
+        prefixes[key] = prefix
+    return counts, prefixes
+
+
+def structure_graph(key, node_label):
+    """The labelled cycle, star or edge described by ``key``."""
+    if key[0] == "C":
+        graph = nx.cycle_graph(len(key[1]))
+        labels = key[1]
+    elif key[0] == "S":
+        graph = nx.star_graph(len(key[2]))
+        labels = (key[1], *key[2])
+    else:
+        graph = nx.path_graph(2)
+        labels = key[1]
+    nx.set_node_attributes(graph, dict(enumerate(labels)), node_label)
+    return graph
+
+
+def enumerate_candidates(graphs, cycle_sizes, star_sizes, include_edge, node_label, n_jobs=None):
+    """Collect every distinct labelled cycle, star and edge that occurs (induced) in ``graphs``.
+
+    Returns ``(keys, labels, counts)`` in extraction priority order: cycles
+    (largest first), stars (largest first), then edges; within a shape the most
+    frequent comes first and is labelled ``-1`` (e.g. ``"C6-1"``).
+
+    Counts follow the original notebooks, which counted VF2 mappings and
+    divided by the cycle length, the number of star leaves, or 2 for an edge:
+    2 per cycle occurrence, (leaves - 1)! per star occurrence, 1 per edge.
+    """
+    check_sizes(cycle_sizes, star_sizes)
+    cycle_sizes, star_sizes = set(cycle_sizes), set(star_sizes)
+    per_graph = Parallel(n_jobs=n_jobs)(
+        delayed(_graph_counts)(g, cycle_sizes, star_sizes, include_edge, node_label) for g in graphs
+    )
+    occurrences = defaultdict(int)
+    prefix_of = {}
+    for counts, prefixes in per_graph:
+        for key, n in counts.items():
+            occurrences[key] += n
+        prefix_of.update(prefixes)
+
+    def weight(key):
+        if key[0] == "C":
+            return 2
+        if key[0] == "S":
+            return factorial(len(key[2]) - 1)
+        return 1
+
+    def priority(prefix):
+        kind, size = prefix[0], int(prefix[1:])
+        return ("CSP".index(kind), -size)
+
+    by_prefix = defaultdict(list)
+    for key, prefix in prefix_of.items():
+        by_prefix[prefix].append(key)
+
+    keys, labels, counts = [], [], []
+    for prefix in sorted(by_prefix, key=priority):
+        ranked = sorted(by_prefix[prefix], key=lambda k: (-occurrences[k], _order(k)))
+        for i, key in enumerate(ranked, start=1):
+            keys.append(key)
+            labels.append(f"{prefix}-{i}")
+            counts.append(occurrences[key] * weight(key))
+    return keys, labels, counts
+
+
+def find_occurrences(graph, keys, node_label):
+    """Vertex sets (sorted tuples of node positions) where each primitive in ``keys`` occurs in ``graph``.
+
+    Occurrences are label-preserving, not necessarily induced, subgraphs, as
+    with ``graph_tool.subgraph_isomorphism`` in the original code.
+    """
+    index = {key: i for i, key in enumerate(keys)}
+    cycle_sizes = {len(k[1]) for k in keys if k[0] == "C"}
+    star_sizes = {len(k[2]) + 1 for k in keys if k[0] == "S"}
+    include_edge = any(k[0] == EDGE_PREFIX for k in keys)
+    position = {n: i for i, n in enumerate(graph)}
+
+    found = [set() for _ in keys]
+    for _, key, nodes in iter_structures(graph, cycle_sizes, star_sizes, include_edge, node_label, induced=False):
+        i = index.get(key)
+        if i is not None:
+            found[i].add(tuple(sorted(position[n] for n in nodes)))
+    return [sorted(occurrences) for occurrences in found]
+
+
+def match_graphs(graphs, keys, node_label, n_jobs=None):
+    """:func:`find_occurrences` for every graph."""
+    return Parallel(n_jobs=n_jobs)(delayed(find_occurrences)(g, keys, node_label) for g in graphs)
+
+
+def assemble_primitive_graph(occurrences, labels, node_label):
+    """Build the primitive graph from per-primitive occurrences (Algorithm 2).
+
+    Occurrences are taken greedily in priority order and dropped when they
+    share more than half of their vertices with an occurrence already taken.
+    Each kept occurrence becomes a vertex labelled with its primitive, and two
+    vertices are joined when their occurrences share an original vertex.
+    """
+    taken = []
+    owners = defaultdict(list)  # original vertex -> indices into taken
+    for occurrence_list, label in zip(occurrences, labels):
+        for occurrence in occurrence_list:
+            occurrence = frozenset(occurrence)
+            overlapping = {j for v in occurrence for j in owners[v]}
+            if any(len(occurrence & taken[j][0]) > len(occurrence) / 2 for j in overlapping):
+                continue
+            for v in occurrence:
+                owners[v].append(len(taken))
+            taken.append((occurrence, label))
+
+    primitive_graph = nx.Graph()
+    primitive_graph.add_nodes_from((i, {node_label: label}) for i, (_, label) in enumerate(taken))
+    for indices in owners.values():
+        primitive_graph.add_edges_from(combinations(indices, 2))
+    return primitive_graph

molprim/_utils.py

@@ -0,0 +1,16 @@
+import networkx as nx
+
+
+def check_graphs(X, node_label):
+    """Validate ``X`` as a non-empty sequence of undirected graphs whose nodes all carry ``node_label``."""
+    graphs = list(X)
+    if not graphs:
+        raise ValueError("X must contain at least one graph")
+    for i, g in enumerate(graphs):
+        if not isinstance(g, nx.Graph) or g.is_directed():
+            raise TypeError(f"X[{i}] is {type(g).__name__}; expected an undirected networkx.Graph")
+        for n, data in g.nodes(data=True):
+            if node_label not in data:
+                raise ValueError(f"node {n!r} of X[{i}] has no {node_label!r} attribute")
+    return graphs
+

molprim/datasets.py

@@ -0,0 +1,59 @@
+"""Loader for the TU Dortmund graph benchmark datasets (MUTAG, NCI1, BZR, COX2, ...)."""
+import io
+import zipfile
+from pathlib import Path
+from urllib.request import urlopen
+
+import networkx as nx
+import numpy as np
+from sklearn.datasets import get_data_home
+
+TU_URL = "https://www.chrsmrrs.com/graphkerneldatasets/{name}.zip"
+
+
+def fetch_tudataset(name, data_home=None):
+    """Download (once) and load a TU dataset as ``(graphs, y)``.
+
+    Files are cached under ``<data_home>/tudataset/<name>``; ``data_home``
+    defaults to scikit-learn's data directory.
+    """
+    root = Path(get_data_home(data_home)) / "tudataset"
+    folder = root / name
+    if not folder.exists():
+        with urlopen(TU_URL.format(name=name)) as response:
+            zipfile.ZipFile(io.BytesIO(response.read())).extractall(root)
+    return read_tudataset(folder)
+
+
+def read_tudataset(folder):
+    """Load a TU dataset from an extracted folder as ``(graphs, y)``.
+
+    Each graph is an undirected ``networkx.Graph`` with nodes ``0..n-1``. Node
+    and edge labels, when the dataset has them, are stored in the ``"label"``
+    attribute.
+    """
+    folder = Path(folder)
+    name = folder.name
+
+    def read(suffix, optional=False):
+        path = folder / f"{name}_{suffix}.txt"
+        if optional and not path.exists():
+            return None
+        return np.loadtxt(path, delimiter=",", dtype=int, ndmin=2)
+
+    graph_of_node = read("graph_indicator")[:, 0] - 1
+    edges = read("A") - 1
+    y = read("graph_labels")[:, 0]
+    node_labels = read("node_labels", optional=True)
+    edge_labels = read("edge_labels", optional=True)
+
+    graphs = [nx.Graph() for _ in range(len(y))]
+    first_node = np.searchsorted(graph_of_node, np.arange(len(y)))
+    for node, g in enumerate(graph_of_node):
+        attrs = {} if node_labels is None else {"label": int(node_labels[node, 0])}
+        graphs[g].add_node(node - first_node[g], **attrs)
+    for k, (u, v) in enumerate(edges):
+        g = graph_of_node[u]
+        attrs = {} if edge_labels is None else {"label": int(edge_labels[k, 0])}
+        graphs[g].add_edge(u - first_node[g], v - first_node[g], **attrs)
+    return graphs, y

molprim/extractor.py

@@ -0,0 +1,104 @@
+import numpy as np
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.utils.validation import check_is_fitted
+
+from ._algorithms import EDGE_PREFIX, assemble_primitive_graph, enumerate_candidates, match_graphs, structure_graph
+from ._utils import check_graphs
+
+
+class PrimitiveStructureExtractor(TransformerMixin, BaseEstimator):
+    """Rewrite molecular graphs as graphs of their primitive structures.
+
+    ``fit`` collects the labelled cycles, stars and edges that occur in the
+    training graphs and keeps the frequent ones (Algorithm 1 of the paper).
+    ``transform`` turns each graph into a primitive graph: one vertex per
+    occurrence of a primitive, labelled with that primitive (e.g. ``"C6-1"``),
+    and an edge wherever two occurrences share an atom (Algorithm 2).
+
+    The output is a list of ``networkx.Graph``, meant to be followed by a graph
+    kernel (:class:`GraphKernelTransformer`) or :class:`LabelPairEdgeCounter`.
+
+    Parameters
+    ----------
+    threshold : float, default=0
+        Percentile (0-100) of candidate counts below which a cycle or star is
+        discarded. Edges (P2) are always kept. 0 keeps every candidate.
+    cycle_sizes : tuple of int, default=(3, ..., 10)
+        Numbers of vertices of the candidate cycles.
+    star_sizes : tuple of int, default=(3, ..., 7)
+        Numbers of vertices (centre included) of the candidate stars.
+    include_edge : bool, default=True
+        Whether the single edge P2 is a candidate.
+    node_label : str, default="label"
+        Node attribute holding the atom type. The primitive graphs use the
+        same attribute name for their labels.
+    n_jobs : int, default=None
+        Number of parallel jobs over graphs (joblib semantics).
+
+    Attributes
+    ----------
+    candidates_ : list of networkx.Graph
+        Every labelled candidate found in the training graphs, in extraction
+        priority order: cycles, then stars (largest first), then edges.
+    candidate_labels_ : list of str
+        Names such as ``"C6-1"``: shape, then rank by count within the shape.
+    candidate_counts_ : ndarray of int
+        Frequency of each candidate in the training graphs, normalised as in
+        the original notebooks.
+    candidate_keys_ : list of tuple
+        Canonical form of each candidate (see ``_algorithms``).
+    selected_ : ndarray of int
+        Indices into the candidate lists of the primitives kept by ``threshold``.
+    primitive_labels_ : list of str
+        Labels of the selected primitives.
+    """
+
+    def __init__(
+        self,
+        threshold=0,
+        cycle_sizes=(3, 4, 5, 6, 7, 8, 9, 10),
+        star_sizes=(3, 4, 5, 6, 7),
+        include_edge=True,
+        node_label="label",
+        n_jobs=None,
+    ):
+        self.threshold = threshold
+        self.cycle_sizes = cycle_sizes
+        self.star_sizes = star_sizes
+        self.include_edge = include_edge
+        self.node_label = node_label
+        self.n_jobs = n_jobs
+
+    def fit(self, X, y=None):
+        if not 0 <= self.threshold <= 100:
+            raise ValueError(f"threshold must be in [0, 100], got {self.threshold}")
+        graphs = check_graphs(X, self.node_label)
+        keys, labels, counts = enumerate_candidates(
+            graphs, self.cycle_sizes, self.star_sizes, self.include_edge, self.node_label, self.n_jobs
+        )
+        if not keys:
+            raise ValueError("no candidate primitive structure occurs in the training graphs")
+
+        counts = np.asarray(counts)
+        cut = np.percentile(counts, self.threshold)
+        is_edge = np.array([label.startswith(EDGE_PREFIX) for label in labels])
+
+        self.candidate_keys_ = keys
+        self.candidate_labels_ = labels
+        self.candidate_counts_ = counts
+        self.candidates_ = [structure_graph(key, self.node_label) for key in keys]
+        self.selected_ = np.flatnonzero(is_edge | (counts >= cut))
+        self.primitive_labels_ = [labels[i] for i in self.selected_]
+        return self
+
+    @property
+    def primitives_(self):
+        """The selected primitives as labelled graphs."""
+        return [self.candidates_[i] for i in self.selected_]
+
+    def transform(self, X):
+        check_is_fitted(self)
+        graphs = check_graphs(X, self.node_label)
+        keys = [self.candidate_keys_[i] for i in self.selected_]
+        occurrences = match_graphs(graphs, keys, self.node_label, self.n_jobs)
+        return [assemble_primitive_graph(occ, self.primitive_labels_, self.node_label) for occ in occurrences]

molprim/features.py

@@ -0,0 +1,52 @@
+from itertools import combinations_with_replacement
+
+import numpy as np
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.utils.validation import check_is_fitted
+
+from ._utils import check_graphs
+
+
+class LabelPairEdgeCounter(TransformerMixin, BaseEstimator):
+    """Count each graph's edges by the unordered pair of labels at their ends.
+
+    This is the "Edges" similarity measure of the paper: one feature per pair
+    of labels seen in ``fit`` (``a|b`` with ``a <= b``). Edges touching a label
+    unseen in ``fit`` are ignored. The paper follows it with
+    ``VarianceThreshold()`` and ``SVC(kernel="rbf", gamma="auto")``.
+
+    Parameters
+    ----------
+    node_label : str, default="label"
+        Node attribute holding the label.
+
+    Attributes
+    ----------
+    labels_ : list
+        Labels seen in ``fit``, sorted by their string form.
+    """
+
+    def __init__(self, node_label="label"):
+        self.node_label = node_label
+
+    def fit(self, X, y=None):
+        graphs = check_graphs(X, self.node_label)
+        self.labels_ = sorted({label for g in graphs for _, label in g.nodes(data=self.node_label)}, key=str)
+        self._pairs = {pair: k for k, pair in enumerate(combinations_with_replacement(range(len(self.labels_)), 2))}
+        return self
+
+    def transform(self, X):
+        check_is_fitted(self, "labels_")
+        graphs = check_graphs(X, self.node_label)
+        index = {label: i for i, label in enumerate(self.labels_)}
+        out = np.zeros((len(graphs), len(self._pairs)))
+        for row, g in enumerate(graphs):
+            for u, v in g.edges:
+                a, b = index.get(g.nodes[u][self.node_label]), index.get(g.nodes[v][self.node_label])
+                if a is not None and b is not None:
+                    out[row, self._pairs[min(a, b), max(a, b)]] += 1
+        return out
+
+    def get_feature_names_out(self, input_features=None):
+        check_is_fitted(self, "labels_")
+        return np.array([f"{self.labels_[a]}|{self.labels_[b]}" for a, b in self._pairs], dtype=object)

molprim/kernels.py

@@ -0,0 +1,135 @@
+from collections import Counter
+
+import networkx as nx
+import numpy as np
+from scipy import sparse
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.utils.validation import check_is_fitted
+
+from ._utils import check_graphs
+
+KERNELS = ("wl_subtree", "wl_sp", "sp")
+
+
+class GraphKernelTransformer(TransformerMixin, BaseEstimator):
+    """Graph kernel as a transformer, for ``SVC(kernel="precomputed")``.
+
+    ``fit_transform`` returns the kernel matrix of the training graphs and
+    ``transform`` returns the kernel between new graphs and the training
+    graphs, so ``make_pipeline(GraphKernelTransformer(), SVC(kernel="precomputed"))``
+    trains and predicts directly on lists of graphs.
+
+    Kernel values match grakel's ``GraphKernel`` with the same settings:
+
+    - ``"wl_subtree"``: Weisfeiler-Lehman subtree kernel,
+      ``[{"name": "weisfeiler_lehman", "n_iter": n_iter}, {"name": "subtree_wl"}]``
+    - ``"wl_sp"``: Weisfeiler-Lehman shortest-path kernel,
+      ``[{"name": "weisfeiler_lehman", "n_iter": n_iter}, {"name": "SP"}]``
+    - ``"sp"``: shortest-path kernel, ``[{"name": "SP"}]`` (ignores ``n_iter``)
+
+    Parameters
+    ----------
+    kernel : {"wl_subtree", "wl_sp", "sp"}, default="wl_subtree"
+    n_iter : int, default=3
+        Number of WL relabelling iterations h; base kernels are summed over
+        iterations 0..h.
+    normalize : bool, default=True
+        Cosine-normalise the kernel: K(x, y) / sqrt(K(x, x) K(y, y)).
+    node_label : str, default="label"
+        Node attribute holding the label.
+    """
+
+    def __init__(self, kernel="wl_subtree", n_iter=3, normalize=True, node_label="label"):
+        self.kernel = kernel
+        self.n_iter = n_iter
+        self.normalize = normalize
+        self.node_label = node_label
+
+    def fit(self, X, y=None):
+        self._fit(X)
+        return self
+
+    def fit_transform(self, X, y=None):
+        features = self._fit(X)
+        return self._kernel(features, self._fit_diag)
+
+    def transform(self, X):
+        check_is_fitted(self, "features_")
+        graphs = check_graphs(X, self.node_label)
+        counts = self._count_features(graphs, self._relabel_tables, learn=False)
+        diag = np.array([sum(c * c for c in counter.values()) for counter in counts], dtype=float)
+        return self._kernel(self._to_matrix(counts), diag)
+
+    def _fit(self, X):
+        if self.kernel not in KERNELS:
+            raise ValueError(f"kernel must be one of {KERNELS}, got {self.kernel!r}")
+        if self.n_iter < 0:
+            raise ValueError(f"n_iter must be >= 0, got {self.n_iter}")
+        graphs = check_graphs(X, self.node_label)
+        self._relabel_tables = [{} for _ in range(self._n_levels())]
+        counts = self._count_features(graphs, self._relabel_tables, learn=True)
+        self.vocabulary_ = {}
+        for counter in counts:
+            for key in counter:
+                self.vocabulary_.setdefault(key, len(self.vocabulary_))
+        self.features_ = self._to_matrix(counts)
+        self._fit_diag = np.asarray(self.features_.multiply(self.features_).sum(axis=1)).ravel()
+        return self.features_
+
+    def _n_levels(self):
+        return 1 if self.kernel == "sp" else self.n_iter + 1
+
+    def _kernel(self, features, diag):
+        K = (features @ self.features_.T).toarray()
+        if self.normalize:
+            scale = np.sqrt(np.outer(diag, self._fit_diag))
+            K = np.divide(K, scale, out=np.zeros_like(K), where=scale > 0)
+        return K
+
+    def _to_matrix(self, counts):
+        rows, cols, values = [], [], []
+        for i, counter in enumerate(counts):
+            for key, value in counter.items():
+                j = self.vocabulary_.get(key)
+                if j is not None:  # features unseen in fit only affect the normalisation
+                    rows.append(i)
+                    cols.append(j)
+                    values.append(value)
+        return sparse.csr_matrix((values, (rows, cols)), shape=(len(counts), len(self.vocabulary_)), dtype=float)
+
+    def _count_features(self, graphs, tables, learn):
+        if not learn:
+            # Unseen WL signatures get fresh ids in a scratch copy so the fitted tables stay unchanged.
+            tables = [dict(t) for t in tables]
+        return [self._graph_features(g, tables) for g in graphs]
+
+    def _graph_features(self, graph, tables):
+        position = {n: i for i, n in enumerate(graph)}
+        labels = [_compress(tables[0], data[self.node_label]) for _, data in graph.nodes(data=True)]
+        neighbours = [[position[m] for m in graph[n]] for n in graph]
+        if self.kernel != "wl_subtree":
+            # Ordered pairs of distinct, connected vertices, as grakel's shortest-path kernel counts them.
+            distances = [
+                (position[u], position[v], d)
+                for u, lengths in nx.all_pairs_shortest_path_length(graph)
+                for v, d in lengths.items()
+                if u != v
+            ]
+
+        counter = Counter()
+        for level in range(len(tables)):
+            if level > 0:
+                labels = [
+                    _compress(tables[level], (label, tuple(sorted(labels[j] for j in neighbours[i]))))
+                    for i, label in enumerate(labels)
+                ]
+            if self.kernel == "wl_subtree":
+                counter.update((level, label) for label in labels)
+            else:
+                counter.update((level, labels[i], labels[j], d) for i, j, d in distances)
+        return counter
+
+
+def _compress(table, signature):
+    """Integer id of ``signature`` in ``table``, adding it when new."""
+    return table.setdefault(signature, len(table))

molprim-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: molprim
+Version: 0.1.0
+Summary: Primitive structure extraction and graph kernels for molecular graph classification, with a scikit-learn API
+Author: Peemapat Wongsriphisant
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/PeemapatW/primitive-structure-extraction
+Project-URL: Repository, https://github.com/PeemapatW/primitive-structure-extraction
+Project-URL: Issues, https://github.com/PeemapatW/primitive-structure-extraction/issues
+Keywords: graph classification,graph kernels,cheminformatics,molecular graphs,scikit-learn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: joblib
+Requires-Dist: networkx>=3.1
+Requires-Dist: numpy
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: scipy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# molprim
+
+**Mol**ecular **prim**itives: classify molecular graphs by their **primitive
+structures**, that is, rings, branching points and bonds. The package rewrites
+each molecule as a small graph whose vertices are these structures, then
+compares molecules with graph kernels.
+Everything is a scikit-learn transformer, so it plugs into `Pipeline`,
+`GridSearchCV` and `cross_val_score`.
+
+This is the implementation of:
+
+> P. Wongsriphisant, C. Lursinsap, A. Suratanee and K. Plaimas,
+> "A classification of biochemical compounds based on their primitive structures and graph kernels", IEEE, 2020, pp. 104–109.
+
+## Install
+
+```bash
+pip install molprim
+```
+
+Requires Python ≥ 3.9 with networkx, numpy, scipy and scikit-learn. It needs neither graph-tool nor grakel.
+
+## Quickstart
+
+```python
+from sklearn.model_selection import cross_val_score
+from sklearn.pipeline import make_pipeline
+from sklearn.svm import SVC
+
+from molprim import GraphKernelTransformer, PrimitiveStructureExtractor, fetch_tudataset
+
+graphs, y = fetch_tudataset("MUTAG")  # list of networkx.Graph with a "label" node attribute
+
+model = make_pipeline(
+    PrimitiveStructureExtractor(),
+    GraphKernelTransformer(kernel="wl_sp", n_iter=2),
+    SVC(kernel="precomputed"),
+)
+print(cross_val_score(model, graphs, y, cv=5).mean())
+```
+
+Inputs are lists of undirected `networkx.Graph` whose nodes carry the atom type
+in a node attribute (`"label"` by default; change it with `node_label=`).
+For a fuller example, see [`examples/quickstart.py`](examples/quickstart.py).
+
+## How it works
+
+1. **Selection** (`PrimitiveStructureExtractor.fit`): collects every labelled
+   cycle (3–10 atoms), star (3–7 atoms) and bond that occurs in the training
+   molecules, and keeps those whose frequency is at least the `threshold`
+   percentile. Bonds are always kept.
+2. **Extraction** (`PrimitiveStructureExtractor.transform`): finds the
+   primitives in each molecule, largest cycles first, then stars, then bonds.
+   An occurrence that shares more than half of its atoms with one already taken
+   is skipped. Each kept occurrence becomes a vertex labelled by its primitive
+   (e.g. `"C6-1"`, the most frequent 6-ring). Two vertices are joined when
+   their occurrences share an atom.
+3. **Similarity**: either a graph kernel on the primitive graphs, or a count of
+   adjacent primitive pairs fed to an RBF SVM.
+
+| Component | Purpose |
+|---|---|
+| `PrimitiveStructureExtractor` | molecules → primitive graphs |
+| `GraphKernelTransformer` | Weisfeiler-Lehman subtree (`"wl_subtree"`), WL shortest-path (`"wl_sp"`) or shortest-path (`"sp"`) kernel. `fit_transform` returns the training kernel matrix and `transform` the kernel against the training graphs, for `SVC(kernel="precomputed")`. Values match grakel's `GraphKernel`. |
+| `LabelPairEdgeCounter` | counts edges per pair of end labels (the paper's "Edges" measure) |
+| `fetch_tudataset`, `read_tudataset` | load TU Dortmund benchmark datasets (MUTAG, NCI1, BZR, COX2, …) as networkx graphs |
+
+Tune the extraction like any other hyper-parameter, for example
+`GridSearchCV(model, {"primitivestructureextractor__threshold": [0, 50], "graphkerneltransformer__n_iter": [1, 2, 3]})`.
+
+## Implementation notes
+
+- Primitives are learned in `fit`, from the training graphs only.
+- Candidate cycles, stars and bonds are enumerated directly and identified by
+  a canonical form of their labels, rather than with general subgraph
+  isomorphism. Extracting the primitive graphs of all 3,865 NCI1 molecules
+  takes a few seconds.
+- When occurrences overlap, the one kept is chosen deterministically: larger
+  shapes first, then more frequent primitives, then vertex order.
+
+## Benchmarks
+
+Scripts that evaluate the package on TU datasets (MUTAG, BZR, COX2, NCI1),
+with their per-split results and runtimes, are in [`benchmarks/`](benchmarks/).
+
+## Repository layout
+
+```
+src/molprim/               the package
+tests/                     pytest suite
+examples/                  usage examples
+benchmarks/                benchmark scripts and results of this implementation
+legacy/                    original notebooks and results from the 2020 paper (see legacy/README.md)
+```
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## License
+
+BSD-3-Clause, the same as scikit-learn. See [LICENSE](LICENSE).

molprim-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+molprim/__init__.py,sha256=Xty7eqhnDTOpr0uL-YtQKB0Jr4Suqk5wSIejeQ30Tzk,773
+molprim/_algorithms.py,sha256=Buc-R8y4nvkCLnnqS2zgrYNVMlJjUjGxkWyebnPfLn4,7909
+molprim/_utils.py,sha256=O_jDlaMWY6nDsXHDcxEhDrbwp7JDS9XZJ0QNUjq4Xlo,652
+molprim/datasets.py,sha256=77FCxDniiLDP0ErAc2kwrunJwYSImdwn_1WGwr8R2qY,2165
+molprim/extractor.py,sha256=QMyDl-CW14uHqbAzZgudGXaBkWAFaPiBsJsszRxCSZc,4504
+molprim/features.py,sha256=K3iRY0rNEynf2qLluUSzFYPRl1MaplY9EmzGIm0Jjcg,2050
+molprim/kernels.py,sha256=4fo64sJVspy3fjJ0zScY1edPWZErN7klC52by4Ovj-I,5659
+molprim-0.1.0.dist-info/licenses/LICENSE,sha256=Bpqz6JvJdb2Rx0IPH4XolloXbVZkOwkRzfgdncF5b5Y,1532
+molprim-0.1.0.dist-info/METADATA,sha256=PUgyKftakyXbTgCP7kMKSAHT6H74GgU9f-QyMDsE_Co,5506
+molprim-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+molprim-0.1.0.dist-info/top_level.txt,sha256=xnod4x6Ekh-o0oXCTpphW27Dfd-f05BXvsxXqHpqE6A,8
+molprim-0.1.0.dist-info/RECORD,,

molprim-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

molprim-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2020-2026, Peemapat Wongsriphisant and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

molprim-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+molprim