strictnull 0.1.0__tar.gz

strictnull-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,152 @@
+# 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/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "strictnull"
+version = "0.1.0"
+description = "Build the control before you compare: degree-preserving null models for graphs, with the checks that make them a control."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Tsuruta Lab" }]
+keywords = ["null model", "configuration model", "degree-preserving", "network", "connectome", "control group", "igraph"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = ["numpy>=1.22", "igraph>=0.10"]
+
+[project.optional-dependencies]
+networkx = ["networkx>=2.6"]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/tsurutanmen/strictnull"
+Issues = "https://github.com/tsurutanmen/strictnull/issues"
+
+[project.scripts]
+strictnull = "strictnull.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["strictnull*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

strictnull-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

strictnull-0.1.0/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-0.1.0/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-0.1.0/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