graph-dependence 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. {graph_dependence-0.1.0 → graph_dependence-0.2.0}/.gitignore +4 -1
  2. {graph_dependence-0.1.0 → graph_dependence-0.2.0}/CITATION.cff +10 -8
  3. graph_dependence-0.2.0/PKG-INFO +209 -0
  4. graph_dependence-0.2.0/README.md +175 -0
  5. {graph_dependence-0.1.0 → graph_dependence-0.2.0}/pyproject.toml +13 -25
  6. graph_dependence-0.2.0/src/graph_dependence/__init__.py +25 -0
  7. graph_dependence-0.2.0/src/graph_dependence/randomize.py +94 -0
  8. graph_dependence-0.2.0/src/graph_dependence/report.py +220 -0
  9. graph_dependence-0.2.0/src/graph_dependence/train.py +464 -0
  10. graph_dependence-0.2.0/tests/test_randomize.py +87 -0
  11. graph_dependence-0.2.0/tests/test_report.py +64 -0
  12. graph_dependence-0.2.0/tests/test_train.py +280 -0
  13. graph_dependence-0.1.0/.github/workflows/pages.yml +0 -37
  14. graph_dependence-0.1.0/.github/workflows/tests.yml +0 -26
  15. graph_dependence-0.1.0/.python-version +0 -1
  16. graph_dependence-0.1.0/PKG-INFO +0 -211
  17. graph_dependence-0.1.0/README.md +0 -175
  18. graph_dependence-0.1.0/examples/cora.py +0 -124
  19. graph_dependence-0.1.0/examples/minimal.py +0 -86
  20. graph_dependence-0.1.0/site/citation.bib +0 -7
  21. graph_dependence-0.1.0/site/dependence-is-not-advantage.pdf +0 -0
  22. graph_dependence-0.1.0/site/favicon.svg +0 -21
  23. graph_dependence-0.1.0/site/figure-1.png +0 -0
  24. graph_dependence-0.1.0/site/index.html +0 -424
  25. graph_dependence-0.1.0/site/robots.txt +0 -4
  26. graph_dependence-0.1.0/site/site.js +0 -135
  27. graph_dependence-0.1.0/site/sitemap.xml +0 -6
  28. graph_dependence-0.1.0/site/styles.css +0 -650
  29. graph_dependence-0.1.0/src/graph_dependence/__init__.py +0 -26
  30. graph_dependence-0.1.0/src/graph_dependence/api.py +0 -143
  31. graph_dependence-0.1.0/src/graph_dependence/metrics.py +0 -49
  32. graph_dependence-0.1.0/src/graph_dependence/nulls.py +0 -150
  33. graph_dependence-0.1.0/src/graph_dependence/types.py +0 -107
  34. graph_dependence-0.1.0/tests/test_api.py +0 -162
  35. graph_dependence-0.1.0/tests/test_metrics.py +0 -32
  36. graph_dependence-0.1.0/tests/test_nulls.py +0 -79
  37. {graph_dependence-0.1.0 → graph_dependence-0.2.0}/LICENSE +0 -0
  38. {graph_dependence-0.1.0 → graph_dependence-0.2.0}/src/graph_dependence/py.typed +0 -0
@@ -8,5 +8,8 @@ __pycache__/
8
8
  build/
9
9
  dist/
10
10
  *.egg-info/
11
- examples/data/
11
+ data/
12
+ figures/*.aux
13
+ figures/*.log
14
+ figures/*.pdf
12
15
 
@@ -3,27 +3,29 @@ message: >-
3
3
  If you use this implementation, please cite the paper below and identify the
4
4
  software version used.
5
5
  type: software
6
- title: "Graph Dependence: diagnostics for graph ablations"
6
+ title: "graph-dependence: split a graph-randomization drop into gain and penalty"
7
7
  abstract: >-
8
- A small Python implementation of diagnostics that separate dependence on an
9
- observed graph arrangement from advantage over a named graph-free comparator.
8
+ Trains a PyTorch Geometric model on the real graph, on degree-preserving
9
+ randomized graphs and with no edges, and reports the gain (what the graph
10
+ adds to the model), the penalty (what wrong edges cost it) and the drop,
11
+ with 95% intervals paired by seed.
10
12
  authors:
11
13
  - family-names: Duggireddy
12
14
  given-names: Prahas
13
15
  affiliation: Third Wheel
14
16
  orcid: "https://orcid.org/0009-0008-6106-0759"
15
- version: 0.1.0
17
+ version: 0.2.0
16
18
  license: Apache-2.0
17
19
  repository-code: "https://github.com/Third-Wheel/dependence-is-not-advantage"
18
20
  url: "https://third-wheel.github.io/dependence-is-not-advantage/"
19
21
  keywords:
20
- - graph learning
22
+ - graph neural networks
21
23
  - graph ablation
22
- - link prediction
23
- - graph null model
24
+ - degree-preserving randomization
25
+ - PyTorch Geometric
24
26
  preferred-citation:
25
27
  type: article
26
- title: "Dependence Is Not Advantage: What Randomizing the Graph Does Not Measure"
28
+ title: "Dependence Is Not Advantage: What a Graph-Randomization Drop Measures"
27
29
  authors:
28
30
  - family-names: Duggireddy
29
31
  given-names: Prahas
@@ -0,0 +1,209 @@
1
+ Metadata-Version: 2.5
2
+ Name: graph-dependence
3
+ Version: 0.2.0
4
+ Summary: Split a graph-randomization drop into what the graph adds and what wrong edges cost.
5
+ Project-URL: Homepage, https://third-wheel.github.io/dependence-is-not-advantage/
6
+ Project-URL: Documentation, https://github.com/Third-Wheel/dependence-is-not-advantage#readme
7
+ Project-URL: Paper, https://www.alphaxiv.org/abs/2608.dependence-is-not-advantage
8
+ Project-URL: Repository, https://github.com/Third-Wheel/dependence-is-not-advantage
9
+ Project-URL: Issues, https://github.com/Third-Wheel/dependence-is-not-advantage/issues
10
+ Author-email: Prahas Duggireddy <prahasduggireddy@thirdwheel.ai>
11
+ License-Expression: Apache-2.0
12
+ License-File: LICENSE
13
+ Keywords: PyTorch Geometric,degree-preserving randomization,edge shuffling,graph ablation,graph neural networks
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: License :: OSI Approved :: Apache Software License
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
24
+ Requires-Python: >=3.11
25
+ Requires-Dist: torch-geometric>=2.5
26
+ Requires-Dist: torch>=2.2
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=8.4; extra == 'dev'
29
+ Requires-Dist: ruff>=0.12; extra == 'dev'
30
+ Provides-Extra: release
31
+ Requires-Dist: build>=1.2; extra == 'release'
32
+ Requires-Dist: twine>=6.1; extra == 'release'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # graph-dependence
36
+
37
+ Applied papers often test whether a graph neural network needs its graph by randomizing the
38
+ edges, keeping every node's degree, and reporting how far the score drops. The drop is the sum
39
+ of two things:
40
+
41
+ ```
42
+ drop = score(real graph) - score(randomized graph) = gain + penalty
43
+ gain = score(real graph) - score(no edges) what the real graph adds to the model
44
+ penalty = score(no edges) - score(randomized graph) what wrong edges cost it
45
+ ```
46
+
47
+ Only the gain says whether the graph helps, and measuring it takes one more run: the same model,
48
+ layers unchanged, trained with no edges. This package runs all three and reports each part with a
49
+ 95% interval.
50
+
51
+ The two parts can be very different sizes. Here are GAT and GraphSAGE on CiteSeer link
52
+ prediction (Hits@20, 400 epochs, mean of five seeds):
53
+
54
+ | model | real graph | no edges | randomized | drop | gain |
55
+ |-----------|-----------:|---------:|-----------:|-----:|-----:|
56
+ | GAT | 51.6 | 55.9 | 4.4 | 91% | −4.3 |
57
+ | GraphSAGE | 55.3 | 56.5 | 43.5 | 21% | −1.2 |
58
+
59
+ Judged by the drop, GAT depends on the graph four times as much as GraphSAGE does. Judged by
60
+ the gain, neither model does better with the real graph than with no edges at all. All of GAT's
61
+ drop is penalty. Its layers have no separate weight for a node's own features, so every layer mixes
62
+ in whatever neighbours the graph supplies, and random ones wreck it.
63
+
64
+ The paper, [*Dependence Is Not Advantage: What a Graph-Randomization Drop
65
+ Measures*](https://third-wheel.github.io/dependence-is-not-advantage/), has more cases, among them a
66
+ human–virus protein-interaction model, and explains why the drop varies so much from one layer
67
+ type to another.
68
+
69
+ ## Which comparison answers your question
70
+
71
+ | If you want to know | compare |
72
+ |---|---|
73
+ | whether the graph is worth building | the model with the graph against the best model without it |
74
+ | whether this model uses the graph | the same model trained with the real graph and with no edges (the **gain**) |
75
+ | whether the wiring matters beyond the degrees | the real graph against a degree-preserving randomized graph (the **drop**) |
76
+ | whether a trained model survives errors in its graph | the trained model, tested on a perturbed graph without retraining (the **test-time drop**) |
77
+
78
+ The package measures the last three. For the first, tune a strong graph-free model yourself.
79
+
80
+ ## Install
81
+
82
+ ```bash
83
+ pip install graph-dependence
84
+ ```
85
+
86
+ This installs PyTorch and PyTorch Geometric if they are missing. For a GPU build of PyTorch,
87
+ install it first by following [pytorch.org](https://pytorch.org/get-started/locally/). The
88
+ Planetoid datasets in the example below also need `pip install scipy`.
89
+
90
+ ## Train your model three ways: `gain_penalty`
91
+
92
+ Give `gain_penalty` a function that builds your model, a PyTorch Geometric graph and the task,
93
+ `"node"` (node classification) or `"link"` (link prediction):
94
+
95
+ ```python
96
+ from torch_geometric.datasets import Planetoid
97
+ from torch_geometric.nn import GCN
98
+
99
+ from graph_dependence import gain_penalty
100
+
101
+
102
+ def make_model(in_channels, out_channels):
103
+ return GCN(in_channels, 64, num_layers=2, out_channels=out_channels, dropout=0.5)
104
+
105
+
106
+ data = Planetoid("data", "Cora")[0]
107
+ report = gain_penalty(make_model, data, "node", seeds=5)
108
+ print(report)
109
+ ```
110
+
111
+ This takes about six minutes on a laptop CPU (an M1 Pro). After a line for each run, it prints:
112
+
113
+ ```
114
+ node classification, accuracy on a 0-100 scale, 5 seeds
115
+ learning rate chosen for each run on validation from (0.01, 0.001)
116
+
117
+ real graph no edges randomized
118
+ score 79.7 55.0 27.7
119
+ best epoch 12 319 45
120
+ epochs trained 1012 1319 1045
121
+
122
+ mean 95% interval
123
+ gain real - no edges +24.7 [+22.9, +26.4]
124
+ penalty no edges - randomized +27.3 [+24.5, +30.2]
125
+ drop real - randomized +52.0 [+48.5, +55.4]
126
+
127
+ The drop is 65% of the real-graph score. Across seeds the randomized-graph
128
+ scores range from 25.7 to 31.0.
129
+
130
+ Reading: the gain interval is above zero, so the graph helps this model. Gain is
131
+ 47% of the drop and penalty is the rest.
132
+ ```
133
+
134
+ The graph is worth about 25 points to GCN on Cora, and even so more than half of the 52-point
135
+ drop is penalty.
136
+
137
+ For each seed, `gain_penalty` draws a degree-preserving randomized graph and trains the model on
138
+ the real graph, the randomized graph and no edges, all from the same initialization. Every run
139
+ tries the same learning rates (`lrs=(0.01, 0.001)` by default), keeps the one with the best
140
+ validation score and stops early on validation. Pass `test_time_drop=True` to also score each
141
+ real-graph model on the randomized graph without retraining.
142
+
143
+ For link prediction the model reads only the training links. The randomized graph is drawn from
144
+ those links, never creates a held-out pair, and the training targets stay the real links. A model
145
+ trained on shuffled targets falls to chance whatever graph it reads, which says nothing about the
146
+ graph. Pass a benchmark's own `splits=` to use its negatives; otherwise the package makes a
147
+ fixed random split and says so in the report.
148
+
149
+ The report's fields (`report.gain`, `report.penalty`, `report.drop`, `report.scores`,
150
+ `report.best_epoch`, ...) are there for your own tables. `help(gain_penalty)` lists every option.
151
+
152
+ ## Use your own training code: `split_drop`
153
+
154
+ If you already train your model yourself, make the randomized graph with `randomize_edges`, train
155
+ the three versions over several seeds, and pass the test scores in the same seed order:
156
+
157
+ ```python
158
+ from graph_dependence import randomize_edges, split_drop
159
+
160
+ randomized = randomize_edges(data.edge_index, data.num_nodes, seed=seed) # one draw per seed
161
+
162
+ report = split_drop(
163
+ real=[...], # one test score per seed, higher is better
164
+ no_edges=[...], # the same model and layers, trained with an empty edge_index
165
+ randomized=[...], # trained on that seed's randomized graph
166
+ metric="AUPRC",
167
+ )
168
+ print(report)
169
+ ```
170
+
171
+ `randomize_edges` takes an undirected `edge_index` holding both directions of every edge, as
172
+ PyTorch Geometric stores it, and returns one in the same form. It applies double-edge swaps one at a
173
+ time and counts rejected swaps, which makes every graph it can reach with the same degrees equally
174
+ likely in the long run. Its `forbidden` argument keeps given node pairs, such as held-out links, from
175
+ becoming edges.
176
+
177
+ ## Reading the report
178
+
179
+ - **A positive drop does not show that the graph helps.** If the gain's interval includes zero or
180
+ lies below it, the drop shows only that real edges beat random ones.
181
+ - **The penalty depends on the layer.** A layer with a separate weight for the node's own features,
182
+ such as GraphSAGE or GraphConv, can learn to rely less on its neighbours and pays a much smaller
183
+ penalty than GCN or GAT. In the paper, adding that weight to GCN and GAT cut the penalty by 17 to
184
+ 42 points and raised the gain by only 2 to 8. Compare drops across architectures with this in mind.
185
+ - **The penalty depends on how long the models train.** On CiteSeer, training ten times longer cut
186
+ GCN's penalty from 45 to 33 points. The report flags runs that hit `max_epochs`, but a run that
187
+ stopped early may still be on a plateau. If the randomized-graph runs stop very early, double
188
+ `patience` and see whether the penalty moves.
189
+ - **A test-time drop answers a different question.** It measures how a trained model copes with a
190
+ graph unlike its training graph, and it can be far larger than the retrained drop. For DeepGNHV on
191
+ viruses seen in training, the paper measures 44.3 AUPRC points against 1.3. Report it separately.
192
+
193
+ ## Citation
194
+
195
+ ```bibtex
196
+ @misc{duggireddy2026dependence,
197
+ title = {Dependence Is Not Advantage: What a Graph-Randomization Drop Measures},
198
+ author = {Duggireddy, Prahas},
199
+ year = {2026},
200
+ note = {Preprint},
201
+ url = {https://www.alphaxiv.org/abs/2608.dependence-is-not-advantage}
202
+ }
203
+ ```
204
+
205
+ Version 0.2.0 replaces the 0.1 API (`diagnose` and its graph-free comparator) with the
206
+ gain-and-penalty split described here.
207
+
208
+ Apache-2.0 licensed. Written by [Prahas Duggireddy](https://orcid.org/0009-0008-6106-0759) at
209
+ [Third Wheel](https://thirdwheel.ai).
@@ -0,0 +1,175 @@
1
+ # graph-dependence
2
+
3
+ Applied papers often test whether a graph neural network needs its graph by randomizing the
4
+ edges, keeping every node's degree, and reporting how far the score drops. The drop is the sum
5
+ of two things:
6
+
7
+ ```
8
+ drop = score(real graph) - score(randomized graph) = gain + penalty
9
+ gain = score(real graph) - score(no edges) what the real graph adds to the model
10
+ penalty = score(no edges) - score(randomized graph) what wrong edges cost it
11
+ ```
12
+
13
+ Only the gain says whether the graph helps, and measuring it takes one more run: the same model,
14
+ layers unchanged, trained with no edges. This package runs all three and reports each part with a
15
+ 95% interval.
16
+
17
+ The two parts can be very different sizes. Here are GAT and GraphSAGE on CiteSeer link
18
+ prediction (Hits@20, 400 epochs, mean of five seeds):
19
+
20
+ | model | real graph | no edges | randomized | drop | gain |
21
+ |-----------|-----------:|---------:|-----------:|-----:|-----:|
22
+ | GAT | 51.6 | 55.9 | 4.4 | 91% | −4.3 |
23
+ | GraphSAGE | 55.3 | 56.5 | 43.5 | 21% | −1.2 |
24
+
25
+ Judged by the drop, GAT depends on the graph four times as much as GraphSAGE does. Judged by
26
+ the gain, neither model does better with the real graph than with no edges at all. All of GAT's
27
+ drop is penalty. Its layers have no separate weight for a node's own features, so every layer mixes
28
+ in whatever neighbours the graph supplies, and random ones wreck it.
29
+
30
+ The paper, [*Dependence Is Not Advantage: What a Graph-Randomization Drop
31
+ Measures*](https://third-wheel.github.io/dependence-is-not-advantage/), has more cases, among them a
32
+ human–virus protein-interaction model, and explains why the drop varies so much from one layer
33
+ type to another.
34
+
35
+ ## Which comparison answers your question
36
+
37
+ | If you want to know | compare |
38
+ |---|---|
39
+ | whether the graph is worth building | the model with the graph against the best model without it |
40
+ | whether this model uses the graph | the same model trained with the real graph and with no edges (the **gain**) |
41
+ | whether the wiring matters beyond the degrees | the real graph against a degree-preserving randomized graph (the **drop**) |
42
+ | whether a trained model survives errors in its graph | the trained model, tested on a perturbed graph without retraining (the **test-time drop**) |
43
+
44
+ The package measures the last three. For the first, tune a strong graph-free model yourself.
45
+
46
+ ## Install
47
+
48
+ ```bash
49
+ pip install graph-dependence
50
+ ```
51
+
52
+ This installs PyTorch and PyTorch Geometric if they are missing. For a GPU build of PyTorch,
53
+ install it first by following [pytorch.org](https://pytorch.org/get-started/locally/). The
54
+ Planetoid datasets in the example below also need `pip install scipy`.
55
+
56
+ ## Train your model three ways: `gain_penalty`
57
+
58
+ Give `gain_penalty` a function that builds your model, a PyTorch Geometric graph and the task,
59
+ `"node"` (node classification) or `"link"` (link prediction):
60
+
61
+ ```python
62
+ from torch_geometric.datasets import Planetoid
63
+ from torch_geometric.nn import GCN
64
+
65
+ from graph_dependence import gain_penalty
66
+
67
+
68
+ def make_model(in_channels, out_channels):
69
+ return GCN(in_channels, 64, num_layers=2, out_channels=out_channels, dropout=0.5)
70
+
71
+
72
+ data = Planetoid("data", "Cora")[0]
73
+ report = gain_penalty(make_model, data, "node", seeds=5)
74
+ print(report)
75
+ ```
76
+
77
+ This takes about six minutes on a laptop CPU (an M1 Pro). After a line for each run, it prints:
78
+
79
+ ```
80
+ node classification, accuracy on a 0-100 scale, 5 seeds
81
+ learning rate chosen for each run on validation from (0.01, 0.001)
82
+
83
+ real graph no edges randomized
84
+ score 79.7 55.0 27.7
85
+ best epoch 12 319 45
86
+ epochs trained 1012 1319 1045
87
+
88
+ mean 95% interval
89
+ gain real - no edges +24.7 [+22.9, +26.4]
90
+ penalty no edges - randomized +27.3 [+24.5, +30.2]
91
+ drop real - randomized +52.0 [+48.5, +55.4]
92
+
93
+ The drop is 65% of the real-graph score. Across seeds the randomized-graph
94
+ scores range from 25.7 to 31.0.
95
+
96
+ Reading: the gain interval is above zero, so the graph helps this model. Gain is
97
+ 47% of the drop and penalty is the rest.
98
+ ```
99
+
100
+ The graph is worth about 25 points to GCN on Cora, and even so more than half of the 52-point
101
+ drop is penalty.
102
+
103
+ For each seed, `gain_penalty` draws a degree-preserving randomized graph and trains the model on
104
+ the real graph, the randomized graph and no edges, all from the same initialization. Every run
105
+ tries the same learning rates (`lrs=(0.01, 0.001)` by default), keeps the one with the best
106
+ validation score and stops early on validation. Pass `test_time_drop=True` to also score each
107
+ real-graph model on the randomized graph without retraining.
108
+
109
+ For link prediction the model reads only the training links. The randomized graph is drawn from
110
+ those links, never creates a held-out pair, and the training targets stay the real links. A model
111
+ trained on shuffled targets falls to chance whatever graph it reads, which says nothing about the
112
+ graph. Pass a benchmark's own `splits=` to use its negatives; otherwise the package makes a
113
+ fixed random split and says so in the report.
114
+
115
+ The report's fields (`report.gain`, `report.penalty`, `report.drop`, `report.scores`,
116
+ `report.best_epoch`, ...) are there for your own tables. `help(gain_penalty)` lists every option.
117
+
118
+ ## Use your own training code: `split_drop`
119
+
120
+ If you already train your model yourself, make the randomized graph with `randomize_edges`, train
121
+ the three versions over several seeds, and pass the test scores in the same seed order:
122
+
123
+ ```python
124
+ from graph_dependence import randomize_edges, split_drop
125
+
126
+ randomized = randomize_edges(data.edge_index, data.num_nodes, seed=seed) # one draw per seed
127
+
128
+ report = split_drop(
129
+ real=[...], # one test score per seed, higher is better
130
+ no_edges=[...], # the same model and layers, trained with an empty edge_index
131
+ randomized=[...], # trained on that seed's randomized graph
132
+ metric="AUPRC",
133
+ )
134
+ print(report)
135
+ ```
136
+
137
+ `randomize_edges` takes an undirected `edge_index` holding both directions of every edge, as
138
+ PyTorch Geometric stores it, and returns one in the same form. It applies double-edge swaps one at a
139
+ time and counts rejected swaps, which makes every graph it can reach with the same degrees equally
140
+ likely in the long run. Its `forbidden` argument keeps given node pairs, such as held-out links, from
141
+ becoming edges.
142
+
143
+ ## Reading the report
144
+
145
+ - **A positive drop does not show that the graph helps.** If the gain's interval includes zero or
146
+ lies below it, the drop shows only that real edges beat random ones.
147
+ - **The penalty depends on the layer.** A layer with a separate weight for the node's own features,
148
+ such as GraphSAGE or GraphConv, can learn to rely less on its neighbours and pays a much smaller
149
+ penalty than GCN or GAT. In the paper, adding that weight to GCN and GAT cut the penalty by 17 to
150
+ 42 points and raised the gain by only 2 to 8. Compare drops across architectures with this in mind.
151
+ - **The penalty depends on how long the models train.** On CiteSeer, training ten times longer cut
152
+ GCN's penalty from 45 to 33 points. The report flags runs that hit `max_epochs`, but a run that
153
+ stopped early may still be on a plateau. If the randomized-graph runs stop very early, double
154
+ `patience` and see whether the penalty moves.
155
+ - **A test-time drop answers a different question.** It measures how a trained model copes with a
156
+ graph unlike its training graph, and it can be far larger than the retrained drop. For DeepGNHV on
157
+ viruses seen in training, the paper measures 44.3 AUPRC points against 1.3. Report it separately.
158
+
159
+ ## Citation
160
+
161
+ ```bibtex
162
+ @misc{duggireddy2026dependence,
163
+ title = {Dependence Is Not Advantage: What a Graph-Randomization Drop Measures},
164
+ author = {Duggireddy, Prahas},
165
+ year = {2026},
166
+ note = {Preprint},
167
+ url = {https://www.alphaxiv.org/abs/2608.dependence-is-not-advantage}
168
+ }
169
+ ```
170
+
171
+ Version 0.2.0 replaces the 0.1 API (`diagnose` and its graph-free comparator) with the
172
+ gain-and-penalty split described here.
173
+
174
+ Apache-2.0 licensed. Written by [Prahas Duggireddy](https://orcid.org/0009-0008-6106-0759) at
175
+ [Third Wheel](https://thirdwheel.ai).
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "graph-dependence"
7
- version = "0.1.0"
8
- description = "Minimal diagnostics that separate graph dependence from graph advantage."
7
+ version = "0.2.0"
8
+ description = "Split a graph-randomization drop into what the graph adds and what wrong edges cost."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
11
11
  license = "Apache-2.0"
@@ -13,11 +13,11 @@ authors = [
13
13
  { name = "Prahas Duggireddy", email = "prahasduggireddy@thirdwheel.ai" },
14
14
  ]
15
15
  keywords = [
16
- "graph learning",
16
+ "graph neural networks",
17
17
  "graph ablation",
18
- "link prediction",
19
- "null model",
20
- "evaluation",
18
+ "degree-preserving randomization",
19
+ "edge shuffling",
20
+ "PyTorch Geometric",
21
21
  ]
22
22
  classifiers = [
23
23
  "Development Status :: 3 - Alpha",
@@ -29,17 +29,14 @@ classifiers = [
29
29
  "Programming Language :: Python :: 3.12",
30
30
  "Programming Language :: Python :: 3.13",
31
31
  "Programming Language :: Python :: 3.14",
32
- "Topic :: Scientific/Engineering :: Information Analysis",
32
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
33
33
  ]
34
- dependencies = ["networkx>=3.2,<4"]
34
+ dependencies = ["torch>=2.2", "torch_geometric>=2.5"]
35
35
 
36
36
  [project.optional-dependencies]
37
37
  dev = [
38
- "mypy>=1.17",
39
38
  "pytest>=8.4",
40
- "pytest-cov>=6.2",
41
39
  "ruff>=0.12",
42
- "types-networkx>=3.2",
43
40
  ]
44
41
  release = [
45
42
  "build>=1.2",
@@ -53,6 +50,9 @@ Paper = "https://www.alphaxiv.org/abs/2608.dependence-is-not-advantage"
53
50
  Repository = "https://github.com/Third-Wheel/dependence-is-not-advantage"
54
51
  Issues = "https://github.com/Third-Wheel/dependence-is-not-advantage/issues"
55
52
 
53
+ [tool.hatch.build.targets.sdist]
54
+ include = ["src", "tests", "README.md", "LICENSE", "CITATION.cff", "pyproject.toml"]
55
+
56
56
  [tool.hatch.build.targets.wheel]
57
57
  packages = ["src/graph_dependence"]
58
58
 
@@ -60,22 +60,10 @@ packages = ["src/graph_dependence"]
60
60
  addopts = "-ra --strict-config --strict-markers"
61
61
  testpaths = ["tests"]
62
62
 
63
- [tool.coverage.run]
64
- branch = true
65
- source = ["graph_dependence"]
66
-
67
- [tool.coverage.report]
68
- show_missing = true
69
- skip_covered = true
70
-
71
- [tool.mypy]
72
- python_version = "3.12"
73
- strict = true
74
- files = ["src", "tests", "examples"]
75
-
76
63
  [tool.ruff]
77
64
  target-version = "py311"
78
- line-length = 88
65
+ line-length = 100
79
66
 
80
67
  [tool.ruff.lint]
81
68
  select = ["B", "E", "F", "I", "N", "RUF", "UP"]
69
+ ignore = ["N812"] # import torch.nn.functional as F is the PyTorch convention
@@ -0,0 +1,25 @@
1
+ """Split a graph-randomization drop into what the graph adds and what wrong edges cost.
2
+
3
+ A randomization ablation trains a graph neural network on the real graph and on a
4
+ degree-preserving randomized graph, and reports the fall in score, the drop. The
5
+ drop is a sum of two parts::
6
+
7
+ drop = score(real graph) - score(randomized graph) = gain + penalty
8
+ gain = score(real graph) - score(no edges) what the graph adds to this model
9
+ penalty = score(no edges) - score(randomized graph) what wrong edges cost it
10
+
11
+ Only the gain measures whether the graph helps the model, and it takes a third
12
+ run, the same model with no edges.
13
+
14
+ ``gain_penalty`` trains a PyTorch Geometric model on all three graphs for node
15
+ classification or link prediction. ``split_drop`` takes scores you measured with
16
+ your own training code. Both return a ``Report``; ``print(report)`` shows the
17
+ gain, the penalty and the drop with 95% intervals paired by seed.
18
+ """
19
+
20
+ from .randomize import randomize_edges
21
+ from .report import Estimate, Report, split_drop
22
+ from .train import gain_penalty
23
+
24
+ __all__ = ["Estimate", "Report", "gain_penalty", "randomize_edges", "split_drop"]
25
+ __version__ = "0.2.0"
@@ -0,0 +1,94 @@
1
+ """Degree-preserving randomization of an undirected graph given as an ``edge_index``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import random
6
+
7
+ import torch
8
+ from torch import Tensor
9
+
10
+
11
+ def randomize_edges(
12
+ edge_index: Tensor,
13
+ num_nodes: int,
14
+ *,
15
+ forbidden: Tensor | None = None,
16
+ swaps_per_edge: int = 10,
17
+ seed: int = 0,
18
+ ) -> Tensor:
19
+ """Randomize an undirected simple graph so that every node keeps its degree.
20
+
21
+ One double-edge swap is attempted at a time: two edges (a, b) and (c, d)
22
+ are drawn uniformly, and (a, d), (c, b) or (a, c), (b, d) is proposed with
23
+ equal probability. A proposal that would create a self-loop, a repeated
24
+ edge or a ``forbidden`` pair is rejected, and the graph stays as it is for
25
+ that step. Rejected steps count, which is what makes the chain's
26
+ stationary distribution uniform over the simple graphs it can reach with
27
+ these degrees (Fosdick et al., SIAM Review 2018). Applying many swaps at
28
+ once from one pairing of the edges does not have this property.
29
+
30
+ ``edge_index`` holds both directions of every edge, as PyTorch Geometric
31
+ stores undirected graphs, and so does the result. ``forbidden`` is a
32
+ [2, F] tensor of node pairs that must not become edges, for example the
33
+ held-out pairs of a link-prediction split.
34
+
35
+ To train your own model on a randomized graph::
36
+
37
+ data.edge_index = randomize_edges(data.edge_index, data.num_nodes, seed=seed)
38
+ """
39
+ pairs, _ = undirected_pairs(edge_index, num_nodes)
40
+ edges = pairs.t().tolist()
41
+ m = len(edges)
42
+ if m < 2:
43
+ raise ValueError("the graph needs at least two edges to randomize")
44
+
45
+ def key(a: int, b: int) -> int:
46
+ return a * num_nodes + b if a < b else b * num_nodes + a
47
+
48
+ present = {key(a, b) for a, b in edges}
49
+ banned = set() if forbidden is None else {key(a, b) for a, b in forbidden.t().tolist()}
50
+ rng = random.Random(seed)
51
+ for _ in range(swaps_per_edge * m):
52
+ i, j = rng.randrange(m), rng.randrange(m)
53
+ if i == j:
54
+ continue
55
+ (a, b), (c, d) = edges[i], edges[j]
56
+ if rng.random() < 0.5:
57
+ c, d = d, c
58
+ if a == d or c == b:
59
+ continue
60
+ new1, new2 = key(a, d), key(c, b)
61
+ if new1 in present or new2 in present or new1 in banned or new2 in banned:
62
+ continue
63
+ present.difference_update((key(a, b), key(c, d)))
64
+ present.update((new1, new2))
65
+ edges[i], edges[j] = [a, d], [c, b]
66
+ return both_directions(torch.tensor(edges, dtype=torch.long).t())
67
+
68
+
69
+ def undirected_pairs(edge_index: Tensor, num_nodes: int) -> tuple[Tensor, int]:
70
+ """One column (u < v) per edge of an undirected graph, and how many self-loops were dropped."""
71
+ u, v = edge_index.cpu()
72
+ loops = int((u == v).sum())
73
+ keys = torch.unique((u * num_nodes + v)[u != v])
74
+ reverse = (keys % num_nodes) * num_nodes + keys // num_nodes
75
+ if not torch.isin(reverse, keys).all():
76
+ raise ValueError(
77
+ "the graph is directed: some edge (u, v) has no (v, u). Degree-preserving "
78
+ "double-edge swaps are defined here for undirected graphs; pass "
79
+ "torch_geometric.utils.to_undirected(edge_index) if direction can be ignored."
80
+ )
81
+ keys = keys[keys // num_nodes < keys % num_nodes]
82
+ return torch.stack([keys // num_nodes, keys % num_nodes]), loops
83
+
84
+
85
+ def both_directions(pairs: Tensor) -> Tensor:
86
+ """An ``edge_index`` holding each pair in both directions."""
87
+ return torch.cat([pairs, pairs.flip(0)], dim=1)
88
+
89
+
90
+ def drop_pairs(edge_index: Tensor, pairs: Tensor, num_nodes: int) -> Tensor:
91
+ """``edge_index`` without the given node pairs, in either direction."""
92
+ keys = edge_index[0] * num_nodes + edge_index[1]
93
+ gone = torch.cat([pairs[0] * num_nodes + pairs[1], pairs[1] * num_nodes + pairs[0]])
94
+ return edge_index[:, ~torch.isin(keys, gone)]