strictnull 0.1.0__py3-none-any.whl

strictnull/__init__.py

@@ -0,0 +1,26 @@
+"""strictnull: build the control before you compare.
+
+A graph only looks special against the right control.  Two controls are
+provided, deliberately ordered from weak to strict:
+
+    weak_null    same node count and edge count, nothing else preserved
+    strict_null  every node keeps its exact degree (in and out, if directed)
+
+If an apparent property of a graph survives only against the weak control,
+the property belongs to the degree sequence, not to the wiring.
+
+    >>> import strictnull as sn
+    >>> g = sn.Graph.from_edges(edges, directed=True)
+    >>> print(sn.compare(g, n_null=20))
+"""
+
+from .graph import Graph
+from .nulls import weak_null, strict_null, ensemble, verify
+from .stats import STATS, register
+from .compare import compare, Report
+
+__version__ = "0.1.0"
+__all__ = [
+    "Graph", "weak_null", "strict_null", "ensemble", "verify",
+    "STATS", "register", "compare", "Report",
+]

strictnull/cli.py

@@ -0,0 +1,43 @@
+"""strictnull EDGES.csv [--undirected] [--n-null 20] [--stats a,b,c] [--json out.json]"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .graph import Graph
+from .stats import STATS, DEFAULT
+from .compare import compare
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="strictnull",
+        description="Compare a graph against a weak (edge-count) and a strict (degree-preserving) null model.")
+    ap.add_argument("edges", help="CSV edge list with header: source,target[,weight]")
+    ap.add_argument("--undirected", action="store_true", help="treat edges as undirected")
+    ap.add_argument("--n-null", type=int, default=20, help="draws per control (default 20)")
+    ap.add_argument("--stats", default=",".join(DEFAULT),
+                    help="comma-separated statistics; known: " + ", ".join(sorted(STATS)))
+    ap.add_argument("--swaps-per-edge", type=int, default=20)
+    ap.add_argument("--shuffle-weights", action="store_true",
+                    help="also shuffle weights across edges in the strict null")
+    ap.add_argument("--seed", type=int, default=0)
+    ap.add_argument("--json", help="write the report as JSON to this path")
+    ap.add_argument("--delimiter", default=",")
+    ap.add_argument("-v", "--verbose", action="store_true")
+    a = ap.parse_args(argv)
+
+    g = Graph.from_csv(a.edges, directed=not a.undirected, delimiter=a.delimiter)
+    stats = [s.strip() for s in a.stats.split(",") if s.strip()]
+    rep = compare(g, stats=stats, n_null=a.n_null, seed=a.seed, swaps_per_edge=a.swaps_per_edge,
+                  keep_weights=not a.shuffle_weights, verbose=a.verbose)
+    print(rep)
+    if a.json:
+        rep.to_json(a.json)
+        print(f"\nwrote {a.json}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

strictnull/compare.py

@@ -0,0 +1,169 @@
+"""Compare a graph against the weak and the strict control, and say what survived."""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Sequence, Union
+
+import numpy as np
+
+from .graph import Graph
+from .nulls import ensemble, verify
+from .stats import STATS, DEFAULT
+
+StatSpec = Union[str, Callable[[Graph], float]]
+
+
+@dataclass
+class Row:
+    stat: str
+    real: float
+    weak_mean: float
+    weak_sd: float
+    strict_mean: float
+    strict_sd: float
+    z_weak: float
+    z_strict: float
+    fraction_explained_by_degree: float
+    invariant_under_strict: bool
+    invariant_under_weak: bool
+
+
+@dataclass
+class Report:
+    graph: str
+    n_null: int
+    swaps_per_edge: int
+    fraction_rewired: float
+    rows: List[Row] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "graph": self.graph, "n_null": self.n_null, "swaps_per_edge": self.swaps_per_edge,
+            "fraction_rewired": self.fraction_rewired,
+            "rows": [r.__dict__ for r in self.rows], "warnings": list(self.warnings),
+        }
+
+    def to_json(self, path: Optional[str] = None, indent: int = 1) -> str:
+        s = json.dumps(self.to_dict(), indent=indent)
+        if path:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(s)
+        return s
+
+    def __str__(self) -> str:
+        lines = [f"{self.graph}", f"controls: {self.n_null} draws each, strict null rewired {self.fraction_rewired:.1%} of edges", ""]
+        head = f"{'statistic':16s} {'real':>10s} {'weak null':>18s} {'strict null':>18s} {'z(weak)':>9s} {'z(strict)':>10s} {'by degree':>10s}"
+        lines.append(head)
+        lines.append("-" * len(head))
+        for r in self.rows:
+            fe = "-" if math.isnan(r.fraction_explained_by_degree) else f"{r.fraction_explained_by_degree:9.0%}"
+            flag = "  INVARIANT" if r.invariant_under_strict else ""
+            lines.append(
+                f"{r.stat:16s} {r.real:10.4f} {r.weak_mean:9.4f}+-{r.weak_sd:<7.4f} "
+                f"{r.strict_mean:9.4f}+-{r.strict_sd:<7.4f} {_fz(r.z_weak):>9s} {_fz(r.z_strict):>10s} {fe:>10s}{flag}")
+        if self.warnings:
+            lines.append("")
+            for w in self.warnings:
+                lines.append(f"warning: {w}")
+        return "\n".join(lines)
+
+
+def _fz(z: float) -> str:
+    if math.isnan(z):
+        return "nan"
+    if math.isinf(z):
+        return "inf" if z > 0 else "-inf"
+    return f"{z:+.1f}"
+
+
+def _z(real: float, mean: float, sd: float) -> float:
+    if sd == 0:
+        return 0.0 if real == mean else math.copysign(math.inf, real - mean)
+    return (real - mean) / sd
+
+
+def _resolve(stats: Sequence[StatSpec]) -> Dict[str, Callable[[Graph], float]]:
+    out = {}
+    for s in stats:
+        if callable(s):
+            out[getattr(s, "__name__", f"stat{len(out)}")] = s
+        elif s in STATS:
+            out[s] = STATS[s]
+        else:
+            raise KeyError(f"unknown statistic {s!r}; known: {sorted(STATS)}")
+    return out
+
+
+def compare(graph: Graph, stats: Sequence[StatSpec] = DEFAULT, n_null: int = 20, seed: int = 0,
+            swaps_per_edge: int = 20, keep_weights: bool = True, verbose: bool = False) -> Report:
+    """Measure ``stats`` on the graph and on ``n_null`` weak and strict nulls.
+
+    ``fraction_explained_by_degree`` is (strict_mean - weak_mean) / (real - weak_mean):
+    the share of the gap between the graph and the weak control that the
+    degree sequence alone reproduces.  Near 1 means the "structure" is the
+    degree distribution.  ``invariant_under_strict`` flags a statistic that is
+    identical, to the last digit, on the graph and on every strict null: that
+    control did not touch what the statistic measures, so the comparison is
+    vacuous for it.
+    """
+    if n_null < 2:
+        raise ValueError("n_null must be at least 2; one draw is not a control")
+    fns = _resolve(stats)
+    real = {k: float(f(graph)) for k, f in fns.items()}
+
+    weak_vals = {k: [] for k in fns}
+    strict_vals = {k: [] for k in fns}
+    rewired = []
+    for i, h in enumerate(ensemble(graph, n=n_null, seed=seed, kind="weak")):
+        rep = verify(graph, h, strict=False)
+        if not rep["n_edges_match"]:
+            raise AssertionError("weak null has the wrong edge count")
+        for k, f in fns.items():
+            weak_vals[k].append(float(f(h)))
+        if verbose:
+            print(f"  weak null {i + 1}/{n_null}")
+    for i, h in enumerate(ensemble(graph, n=n_null, seed=seed + 7, kind="strict",
+                                   swaps_per_edge=swaps_per_edge, keep_weights=keep_weights)):
+        rep = verify(graph, h, strict=True)
+        rewired.append(rep["fraction_rewired"])
+        for k, f in fns.items():
+            strict_vals[k].append(float(f(h)))
+        if verbose:
+            print(f"  strict null {i + 1}/{n_null}  rewired {rep['fraction_rewired']:.1%}")
+
+    report = Report(graph=repr(graph), n_null=n_null, swaps_per_edge=swaps_per_edge,
+                    fraction_rewired=float(np.mean(rewired)))
+    if report.fraction_rewired < 0.8:
+        report.warnings.append(
+            f"strict null rewired only {report.fraction_rewired:.0%} of edges; raise swaps_per_edge "
+            f"or accept that this graph has little room to rewire (very dense or very constrained degrees)")
+    if graph.dropped_self_loops or graph.merged_duplicates:
+        report.warnings.append(
+            f"graph construction dropped {graph.dropped_self_loops} self-loops and merged "
+            f"{graph.merged_duplicates} duplicate edges; nulls are defined on the simple graph")
+
+    for k in fns:
+        w = np.asarray(weak_vals[k]); s = np.asarray(strict_vals[k])
+        wm, wsd, sm, ssd = float(w.mean()), float(w.std()), float(s.mean()), float(s.std())
+        gap = real[k] - wm
+        frac = (sm - wm) / gap if gap != 0 else float("nan")
+        inv_s = bool(np.all(s == real[k]))
+        inv_w = bool(np.all(w == real[k]))
+        row = Row(stat=k, real=real[k], weak_mean=wm, weak_sd=wsd, strict_mean=sm, strict_sd=ssd,
+                  z_weak=_z(real[k], wm, wsd), z_strict=_z(real[k], sm, ssd),
+                  fraction_explained_by_degree=float(frac),
+                  invariant_under_strict=inv_s, invariant_under_weak=inv_w)
+        report.rows.append(row)
+        if inv_s and inv_w:
+            report.warnings.append(
+                f"{k!r} is identical on the graph and on every null: this statistic is invariant under both "
+                f"controls, so the comparison measures nothing for it")
+        elif inv_s:
+            report.warnings.append(
+                f"{k!r} is identical on the graph and on every strict null: the degree-preserving control "
+                f"does not touch what it measures (it is a function of the degree sequence)")
+    return report

strictnull/graph.py

@@ -0,0 +1,151 @@
+"""A thin wrapper around igraph.Graph that remembers what it was built from."""
+
+from __future__ import annotations
+
+import csv
+from typing import Iterable, Optional
+
+import numpy as np
+
+try:
+    import igraph as ig
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("strictnull needs python-igraph: pip install igraph") from exc
+
+
+class Graph:
+    """Directed or undirected simple graph with optional edge weights.
+
+    Self-loops are dropped on construction and duplicate edges are merged
+    (weights summed), because the null models are defined on simple graphs.
+    """
+
+    def __init__(self, g: "ig.Graph", dropped_self_loops: int = 0, merged_duplicates: int = 0):
+        self.g = g
+        self.directed = g.is_directed()
+        self.dropped_self_loops = dropped_self_loops
+        self.merged_duplicates = merged_duplicates
+
+    # ------------------------------------------------------------ builders
+    @classmethod
+    def from_edges(cls, edges, weights=None, directed: bool = True, n_nodes: Optional[int] = None) -> "Graph":
+        edges = np.asarray(edges, dtype=np.int64)
+        if edges.size == 0:
+            edges = edges.reshape(0, 2)
+        if edges.ndim != 2 or edges.shape[1] != 2:
+            raise ValueError(f"edges must have shape (E, 2), got {edges.shape}")
+        if weights is not None:
+            weights = np.asarray(weights, dtype=np.float64)
+            if len(weights) != len(edges):
+                raise ValueError("weights length must match edges length")
+        if n_nodes is None:
+            n_nodes = int(edges.max()) + 1 if len(edges) else 0
+
+        keep = edges[:, 0] != edges[:, 1]
+        dropped = int((~keep).sum())
+        edges = edges[keep]
+        if weights is not None:
+            weights = weights[keep]
+
+        if not directed:
+            edges = np.sort(edges, axis=1)
+        merged = {}
+        for i, (u, v) in enumerate(map(tuple, edges.tolist())):
+            if (u, v) in merged:
+                if weights is not None:
+                    merged[(u, v)] += float(weights[i])
+            else:
+                merged[(u, v)] = float(weights[i]) if weights is not None else None
+        n_dup = len(edges) - len(merged)
+
+        g = ig.Graph(n=n_nodes, edges=list(merged.keys()), directed=directed)
+        if weights is not None:
+            g.es["weight"] = list(merged.values())
+        return cls(g, dropped_self_loops=dropped, merged_duplicates=n_dup)
+
+    @classmethod
+    def from_adjacency(cls, A, directed: bool = True) -> "Graph":
+        A = np.asarray(A)
+        if A.ndim != 2 or A.shape[0] != A.shape[1]:
+            raise ValueError("adjacency must be square")
+        src, dst = np.nonzero(A)
+        if not directed:
+            keep = src <= dst
+            src, dst = src[keep], dst[keep]
+        w = A[src, dst].astype(np.float64)
+        return cls.from_edges(np.stack([src, dst], axis=1), w, directed=directed, n_nodes=A.shape[0])
+
+    @classmethod
+    def from_networkx(cls, G) -> "Graph":
+        nodes = list(G.nodes())
+        index = {n: i for i, n in enumerate(nodes)}
+        edges, weights, has_w = [], [], False
+        for u, v, d in G.edges(data=True):
+            edges.append((index[u], index[v]))
+            if "weight" in d:
+                has_w = True
+            weights.append(float(d.get("weight", 1.0)))
+        out = cls.from_edges(edges, weights if has_w else None, directed=G.is_directed(), n_nodes=len(nodes))
+        out.labels = nodes
+        return out
+
+    @classmethod
+    def from_csv(cls, path, directed: bool = True, delimiter: str = ",") -> "Graph":
+        """Edge list with a header. Columns: source, target[, weight]. Node ids may be any strings."""
+        rows = []
+        with open(path, newline="", encoding="utf-8") as f:
+            reader = csv.reader(f, delimiter=delimiter)
+            header = next(reader)
+            if len(header) < 2:
+                raise ValueError("need at least two columns: source, target")
+            has_w = len(header) >= 3
+            for r in reader:
+                if not r or not r[0].strip():
+                    continue
+                rows.append((r[0].strip(), r[1].strip(), float(r[2]) if has_w and len(r) > 2 and r[2].strip() else 1.0))
+        labels = sorted({r[0] for r in rows} | {r[1] for r in rows})
+        index = {n: i for i, n in enumerate(labels)}
+        edges = [(index[a], index[b]) for a, b, _ in rows]
+        weights = [w for _, _, w in rows] if has_w else None
+        out = cls.from_edges(edges, weights, directed=directed, n_nodes=len(labels))
+        out.labels = labels
+        return out
+
+    # ------------------------------------------------------------ accessors
+    @property
+    def n_nodes(self) -> int:
+        return self.g.vcount()
+
+    @property
+    def n_edges(self) -> int:
+        return self.g.ecount()
+
+    @property
+    def weighted(self) -> bool:
+        return "weight" in self.g.edge_attributes()
+
+    def edges(self) -> np.ndarray:
+        e = np.array(self.g.get_edgelist(), dtype=np.int64)
+        return e.reshape(-1, 2)
+
+    def weights(self) -> Optional[np.ndarray]:
+        return np.asarray(self.g.es["weight"], dtype=np.float64) if self.weighted else None
+
+    def degrees(self):
+        """(in, out) for directed graphs; (deg, deg) for undirected."""
+        if self.directed:
+            return (np.asarray(self.g.degree(mode="in"), dtype=np.int64),
+                    np.asarray(self.g.degree(mode="out"), dtype=np.int64))
+        d = np.asarray(self.g.degree(), dtype=np.int64)
+        return d, d
+
+    def copy(self) -> "Graph":
+        out = Graph(self.g.copy(), self.dropped_self_loops, self.merged_duplicates)
+        if hasattr(self, "labels"):
+            out.labels = self.labels
+        return out
+
+    def __repr__(self) -> str:
+        kind = "directed" if self.directed else "undirected"
+        w = ", weighted" if self.weighted else ""
+        return f"Graph({kind}{w}, {self.n_nodes} nodes, {self.n_edges} edges)"

strictnull/nulls.py

@@ -0,0 +1,116 @@
+"""The two controls, and the check that makes them controls."""
+
+from __future__ import annotations
+
+import random
+from typing import Iterator
+
+import numpy as np
+import igraph as ig
+
+from .graph import Graph
+
+
+def weak_null(graph: Graph, seed: int = 0) -> Graph:
+    """Erdős–Rényi control: same node count and edge count, nothing else.
+
+    Weights, if present, are shuffled onto the new edges, so the weight
+    distribution is preserved but its placement is random.  This is the
+    control most papers use.  On its own it cannot tell wiring from degree.
+    """
+    rng = np.random.default_rng(seed)
+    n, m = graph.n_nodes, graph.n_edges
+    directed = graph.directed
+    max_edges = n * (n - 1) if directed else n * (n - 1) // 2
+    if m > max_edges:
+        raise ValueError("more edges than a simple graph can hold")
+
+    seen, out = set(), []
+    while len(out) < m:
+        need = m - len(out)
+        a = rng.integers(0, n, size=need * 2 + 8)
+        b = rng.integers(0, n, size=need * 2 + 8)
+        for u, v in zip(a.tolist(), b.tolist()):
+            if u == v:
+                continue
+            key = (u, v) if directed else (min(u, v), max(u, v))
+            if key in seen:
+                continue
+            seen.add(key)
+            out.append(key)
+            if len(out) == m:
+                break
+
+    g = ig.Graph(n=n, edges=out, directed=directed)
+    if graph.weighted:
+        g.es["weight"] = rng.permutation(graph.weights()).tolist()
+    return Graph(g)
+
+
+def strict_null(graph: Graph, seed: int = 0, swaps_per_edge: int = 20, keep_weights: bool = True) -> Graph:
+    """Degree-preserving control: every node keeps its exact degree.
+
+    Directed graphs keep each node's in-degree and out-degree separately.
+    Implemented with repeated double-edge swaps restricted to simple graphs
+    (the configuration model conditioned on no self-loops or multi-edges).
+    ``swaps_per_edge`` of 10-20 is enough to forget the original wiring; the
+    report from ``verify`` says how much was actually rewired.
+
+    ``keep_weights`` carries each weight with the edge slot it sat in, so the
+    weight multiset is preserved.  ``keep_weights=False`` additionally
+    shuffles weights across edges.
+    """
+    if swaps_per_edge <= 0:
+        raise ValueError("swaps_per_edge must be positive")
+    g = graph.g.copy()
+    ig.set_random_number_generator(random.Random(seed))
+    n_swaps = swaps_per_edge * max(graph.n_edges, 1)
+    try:
+        try:
+            g.rewire(n=n_swaps, allowed_edge_types="simple")      # igraph >= 1.0
+        except TypeError:
+            g.rewire(n=n_swaps, mode="simple")                    # igraph 0.10 / 0.11
+    finally:
+        ig.set_random_number_generator(random)
+    if graph.weighted:
+        w = graph.weights()
+        g.es["weight"] = w.tolist() if keep_weights else np.random.default_rng(seed + 1).permutation(w).tolist()
+    return Graph(g)
+
+
+def ensemble(graph: Graph, n: int = 20, seed: int = 0, kind: str = "strict", **kwargs) -> Iterator[Graph]:
+    """Yield ``n`` independent nulls.  One draw is not a control; it is one draw."""
+    fn = {"strict": strict_null, "weak": weak_null}[kind]
+    for i in range(n):
+        yield fn(graph, seed=seed + 1000 * i, **kwargs)
+
+
+def verify(original: Graph, null: Graph, strict: bool = True) -> dict:
+    """Check that a null is what it claims to be.  Raises if ``strict`` and degrees moved."""
+    oi, oo = original.degrees()
+    ni, no = null.degrees()
+    el = null.g.get_edgelist()
+    report = {
+        "n_nodes_match": original.n_nodes == null.n_nodes,
+        "n_edges_match": original.n_edges == null.n_edges,
+        "in_degree_exact": bool(np.array_equal(oi, ni)),
+        "out_degree_exact": bool(np.array_equal(oo, no)),
+        "self_loops": int(sum(1 for u, v in el if u == v)),
+        "multi_edges": null.n_edges - len(set(el)),
+    }
+    if not original.directed:
+        report["degree_exact"] = report.pop("in_degree_exact")
+        report.pop("out_degree_exact")
+    orig_set = set(original.g.get_edgelist())
+    shared = len(orig_set & set(el))
+    report["edges_retained"] = shared
+    report["fraction_rewired"] = 1.0 - shared / max(len(orig_set), 1)
+    if original.weighted and null.weighted:
+        report["weight_multiset_preserved"] = bool(np.allclose(np.sort(original.weights()), np.sort(null.weights())))
+    if strict:
+        deg_ok = report.get("degree_exact", report.get("in_degree_exact", False) and report.get("out_degree_exact", False))
+        if not deg_ok:
+            raise AssertionError("degree sequence was not preserved")
+        if report["self_loops"] or report["multi_edges"]:
+            raise AssertionError("null contains self-loops or multi-edges")
+    return report

strictnull/stats.py

@@ -0,0 +1,83 @@
+"""Graph statistics.  Each takes a Graph and returns a float.
+
+Register your own with ``@register("name")`` or pass callables to ``compare``.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict
+
+from .graph import Graph
+
+STATS: Dict[str, Callable[[Graph], float]] = {}
+
+
+def register(name: str):
+    def deco(fn):
+        STATS[name] = fn
+        return fn
+    return deco
+
+
+def _undirected(graph: Graph):
+    if not graph.directed:
+        return graph.g
+    u = graph.g.copy()
+    u.to_undirected(combine_edges="first")
+    return u
+
+
+@register("reciprocity")
+def reciprocity(graph: Graph) -> float:
+    """Fraction of edges whose reverse edge also exists.  Undirected graphs: 1.0."""
+    return float(graph.g.reciprocity()) if graph.directed else 1.0
+
+
+@register("clustering")
+def clustering(graph: Graph) -> float:
+    """Global transitivity of the underlying undirected graph."""
+    return float(_undirected(graph).transitivity_undirected(mode="zero"))
+
+
+@register("avg_clustering")
+def avg_clustering(graph: Graph) -> float:
+    return float(_undirected(graph).transitivity_avglocal_undirected(mode="zero"))
+
+
+@register("avg_path")
+def avg_path(graph: Graph) -> float:
+    """Mean shortest path over connected pairs, ignoring direction."""
+    return float(_undirected(graph).average_path_length(directed=False))
+
+
+@register("assortativity")
+def assortativity(graph: Graph) -> float:
+    return float(_undirected(graph).assortativity_degree(directed=False))
+
+
+@register("n_triangles")
+def n_triangles(graph: Graph) -> float:
+    return float(len(_undirected(graph).cliques(min=3, max=3)))
+
+
+@register("max_core")
+def max_core(graph: Graph) -> float:
+    return float(max(_undirected(graph).coreness()) if graph.n_nodes else 0.0)
+
+
+@register("modularity_leiden")
+def modularity_leiden(graph: Graph) -> float:
+    """Modularity of the best Leiden partition (undirected).  Seeded for reproducibility."""
+    u = _undirected(graph)
+    part = u.community_leiden(objective_function="modularity", n_iterations=-1)
+    return float(part.modularity)
+
+
+@register("mean_weight")
+def mean_weight(graph: Graph) -> float:
+    """Present so an invariant statistic is on hand: weights are carried by every null."""
+    w = graph.weights()
+    return float(w.mean()) if w is not None and len(w) else float("nan")
+
+
+DEFAULT = ["reciprocity", "clustering", "avg_path", "assortativity"]

strictnull-0.1.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: strictnull
+Version: 0.1.0
+Summary: Build the control before you compare: degree-preserving null models for graphs, with the checks that make them a control.
+Author: Tsuruta Lab
+License: MIT
+Project-URL: Homepage, https://github.com/tsurutanmen/strictnull
+Project-URL: Issues, https://github.com/tsurutanmen/strictnull/issues
+Keywords: null model,configuration model,degree-preserving,network,connectome,control group,igraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: igraph>=0.10
+Provides-Extra: networkx
+Requires-Dist: networkx>=2.6; extra == "networkx"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# strictnull
+
+Build the control before you compare.
+
+A graph only looks special against the right control. Most papers compare a network against an
+Erdős–Rényi graph with the same number of nodes and edges. That control cannot tell wiring from
+degree: a heavy-tailed degree distribution on its own produces clustering, short paths, reciprocity,
+and communities. `strictnull` puts the second control next to the first, verifies both, and tells you
+how much of the "structure" was the degree sequence.
+
+```
+pip install git+https://github.com/tsurutanmen/strictnull
+```
+
+A PyPI release is planned; until then install from GitHub as above. Requires numpy and [igraph](https://python.igraph.org). `networkx` is optional (for `Graph.from_networkx`).
+
+## Thirty seconds
+
+```
+$ strictnull tests/data/toy.csv --n-null 20
+
+Graph(directed, weighted, 60 nodes, 400 edges)
+controls: 20 draws each, strict null rewired 73.4% of edges
+
+statistic              real          weak null        strict null   z(weak)  z(strict)  by degree
+-------------------------------------------------------------------------------------------------
+reciprocity          0.1250    0.1150+-0.0251      0.1153+-0.0171        +0.4       +0.6         2%
+clustering           0.2835    0.2154+-0.0075      0.2817+-0.0091        +9.0       +0.2        97%
+avg_path             1.8113    1.8391+-0.0098      1.8178+-0.0075        -2.8       -0.9        77%
+assortativity       -0.1818   -0.0292+-0.0311     -0.1695+-0.0172        -4.9       -0.7        92%
+
+warning: strict null rewired only 73% of edges; raise swaps_per_edge or accept that this graph has little room to rewire
+```
+
+Against the weak control this toy graph is nine standard deviations more clustered than chance.
+Against the strict control it is 0.2. The degree sequence explains 97% of the gap. Nothing about the
+wiring is special here; the paper that reported `z = 9` would have been reporting its degree
+distribution.
+
+## The three numbers
+
+For each statistic the report gives:
+
+| column | meaning |
+|---|---|
+| `weak null` | mean and sd over draws of an Erdős–Rényi graph with the same node and edge count (weights shuffled). The control most papers use. |
+| `strict null` | mean and sd over draws of a degree-preserving rewiring: every node keeps its exact in-degree and out-degree, everything else is randomised. |
+| `z(weak)`, `z(strict)` | distance of the real value from each control, in control standard deviations. |
+| `by degree` | `(strict − weak) / (real − weak)`: the share of the weak-control gap that the degree sequence alone reproduces. Near 100% means the structure is the degree distribution. |
+
+## Python
+
+```python
+import strictnull as sn
+
+g = sn.Graph.from_csv("edges.csv", directed=True)      # header: source,target[,weight]
+g = sn.Graph.from_edges(edges, weights, directed=True)  # (E, 2) int array
+g = sn.Graph.from_adjacency(A, directed=True)
+g = sn.Graph.from_networkx(G)
+
+rep = sn.compare(g, stats=["clustering", "reciprocity", "avg_path", "assortativity"], n_null=20, seed=0)
+print(rep)
+rep.to_json("report.json")
+
+for row in rep.rows:
+    print(row.stat, row.z_strict, row.fraction_explained_by_degree)
+```
+
+Built-in statistics: `reciprocity`, `clustering`, `avg_clustering`, `avg_path`, `assortativity`,
+`n_triangles`, `max_core`, `modularity_leiden`, `mean_weight`. Add your own:
+
+```python
+@sn.register("rich_club_100")
+def rich_club_100(graph):
+    ...
+    return value
+
+rep = sn.compare(g, stats=["rich_club_100", "clustering"])
+# or pass the callable directly: sn.compare(g, stats=[rich_club_100])
+```
+
+### Swapping the graph inside a model
+
+When the claim is not about a statistic but about a model that uses the graph (a connectome as a
+fixed layer, a knowledge graph as a prior), draw nulls and retrain:
+
+```python
+for i, h in enumerate(sn.ensemble(g, n=5, seed=0)):        # independent degree-preserving draws
+    sn.verify(g, h, strict=True)                            # raises if a degree moved
+    A_null = h.g.get_adjacency(attribute="weight")          # or h.edges(), h.weights()
+    acc = train_and_evaluate(A_null)
+```
+
+Compare the real graph's outcome against the mean and spread over draws, not against one draw.
+
+## What the tool refuses or flags, and why
+
+- **One draw is not a control.** `compare` raises on `n_null < 2`.
+- **Every null is verified before use.** Exact degree match, no self-loops, no multi-edges, weight
+  multiset preserved, and the fraction of edges actually rewired. Below 80% rewired, the report warns.
+- **Invariant statistics are flagged.** If a statistic is identical, to the last digit, on the graph
+  and on every null, the control never touched what it measures. That is not "no effect"; it is
+  "nothing was tested". The row is marked `INVARIANT` and a warning explains which control it is
+  invariant under. Functions of the degree sequence (max degree, degree variance) are invariant under
+  the strict null. Functions of the edge count or weight multiset are invariant under both.
+
+## Worked example: a connectome
+
+The larval *Drosophila* connectome released by Winding et al. (2023): 2,952 neurons, 110,140
+directed edges. Ten draws per control, 25 seconds.
+
+```
+statistic              real          weak null        strict null   z(weak)  z(strict)  by degree
+reciprocity          0.2569    0.0126+-0.0004      0.0250+-0.0006      +677.1     +380.7         5%
+clustering           0.2350    0.0252+-0.0000      0.0537+-0.0001     +5103.3    +1469.6        14%
+avg_path             2.7466    2.1262+-0.0002      2.2596+-0.0008     +2840.9     +631.7        22%
+assortativity        0.2365   -0.0012+-0.0020     -0.0138+-0.0021      +116.1     +119.7        -5%
+```
+
+Here the wiring is real: the degree sequence explains only 5–22% of each gap and the strict-control
+z stays in the hundreds. That is the case where the strict control changes nothing about the
+conclusion, and it still had to be run to know that.
+
+The same connectome, used as a fixed recurrent layer in an MNIST classifier, gave the opposite
+result: swapping the layer for a strict null moved accuracy by +0.002, within seed noise. Structure
+exists, and the task does not use it. The two findings, and the code that produced them, are in the
+[Tsuruta Lab research notes](https://tsurutalab.org/notes/).
+
+## Claude Code skill
+
+`skill/strictnull/SKILL.md` teaches Claude Code when to reach for this tool and how to write up the
+result. Install it by copying the folder:
+
+```
+cp -r skill/strictnull ~/.claude/skills/strictnull
+```
+
+After that, a sentence like "this network is more clustered than random" in a session triggers the
+comparison against both controls and a write-up that names the control.
+
+## Method
+
+The strict null is the directed configuration model conditioned on simple graphs, sampled by
+double-edge swaps (Maslov & Sneppen 2002), `swaps_per_edge` swaps per edge (default 20). For
+undirected graphs the same procedure preserves each node's degree. The weak null samples uniformly
+among simple graphs with the given edge count. See Fosdick, Larremore, Nishimura & Ugander (2018),
+*Configuring random graph models with fixed degree sequences*, SIAM Review 60(2), for the space of
+choices this tool does not cover (multigraphs, self-loops, stub matching).
+
+## License
+
+MIT.

strictnull-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+strictnull/__init__.py,sha256=mE2RnCFOO5-5sBrmRgfUU-_Zad5QcT_V4H6LfVJGyVQ,903
+strictnull/cli.py,sha256=542jlksQzPAcpLQmGcnOVA_dnswMhzeMT1kSuoTDc-M,1808
+strictnull/compare.py,sha256=Nzu7rzmQe3VCXL2vIhbCIPjlCicTEdpqZ9KOVk4P2wc,6967
+strictnull/graph.py,sha256=_NYXa37HuWqb4O1BtgBwO4HZUYNtJgNx03At2vMUDRI,5988
+strictnull/nulls.py,sha256=W28vwFr4_DJRmmTVnVqRu9NPePclUSUyqGx5Y8eJfr4,4737
+strictnull/stats.py,sha256=8oEj8k6_gCSppYbMsBt-eHA6_gFc9ZapyBPZcGDAz2Y,2398
+strictnull-0.1.0.dist-info/licenses/LICENSE,sha256=LsE50bq1amk_QUYNjCk785wcz3x-j6KitwyCim2U1ko,1068
+strictnull-0.1.0.dist-info/METADATA,sha256=ZnrsZ7XwT7Tc36v_fB0yRDWPcg1nZZE83Aqri8JUlXE,8272
+strictnull-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+strictnull-0.1.0.dist-info/entry_points.txt,sha256=eHAfcX8iZg05wwYTkmtgdvQB1a4Z2r2qxCV2NoygMB0,51
+strictnull-0.1.0.dist-info/top_level.txt,sha256=MIWwYfOZtkEmyVWwEyiw9dP2h1nFh8XZPNZroDTTq74,11
+strictnull-0.1.0.dist-info/RECORD,,

strictnull-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
+

strictnull-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+strictnull = strictnull.cli:main

strictnull-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tsuruta Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

strictnull-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+strictnull