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.
- {graph_dependence-0.1.0 → graph_dependence-0.2.0}/.gitignore +4 -1
- {graph_dependence-0.1.0 → graph_dependence-0.2.0}/CITATION.cff +10 -8
- graph_dependence-0.2.0/PKG-INFO +209 -0
- graph_dependence-0.2.0/README.md +175 -0
- {graph_dependence-0.1.0 → graph_dependence-0.2.0}/pyproject.toml +13 -25
- graph_dependence-0.2.0/src/graph_dependence/__init__.py +25 -0
- graph_dependence-0.2.0/src/graph_dependence/randomize.py +94 -0
- graph_dependence-0.2.0/src/graph_dependence/report.py +220 -0
- graph_dependence-0.2.0/src/graph_dependence/train.py +464 -0
- graph_dependence-0.2.0/tests/test_randomize.py +87 -0
- graph_dependence-0.2.0/tests/test_report.py +64 -0
- graph_dependence-0.2.0/tests/test_train.py +280 -0
- graph_dependence-0.1.0/.github/workflows/pages.yml +0 -37
- graph_dependence-0.1.0/.github/workflows/tests.yml +0 -26
- graph_dependence-0.1.0/.python-version +0 -1
- graph_dependence-0.1.0/PKG-INFO +0 -211
- graph_dependence-0.1.0/README.md +0 -175
- graph_dependence-0.1.0/examples/cora.py +0 -124
- graph_dependence-0.1.0/examples/minimal.py +0 -86
- graph_dependence-0.1.0/site/citation.bib +0 -7
- graph_dependence-0.1.0/site/dependence-is-not-advantage.pdf +0 -0
- graph_dependence-0.1.0/site/favicon.svg +0 -21
- graph_dependence-0.1.0/site/figure-1.png +0 -0
- graph_dependence-0.1.0/site/index.html +0 -424
- graph_dependence-0.1.0/site/robots.txt +0 -4
- graph_dependence-0.1.0/site/site.js +0 -135
- graph_dependence-0.1.0/site/sitemap.xml +0 -6
- graph_dependence-0.1.0/site/styles.css +0 -650
- graph_dependence-0.1.0/src/graph_dependence/__init__.py +0 -26
- graph_dependence-0.1.0/src/graph_dependence/api.py +0 -143
- graph_dependence-0.1.0/src/graph_dependence/metrics.py +0 -49
- graph_dependence-0.1.0/src/graph_dependence/nulls.py +0 -150
- graph_dependence-0.1.0/src/graph_dependence/types.py +0 -107
- graph_dependence-0.1.0/tests/test_api.py +0 -162
- graph_dependence-0.1.0/tests/test_metrics.py +0 -32
- graph_dependence-0.1.0/tests/test_nulls.py +0 -79
- {graph_dependence-0.1.0 → graph_dependence-0.2.0}/LICENSE +0 -0
- {graph_dependence-0.1.0 → graph_dependence-0.2.0}/src/graph_dependence/py.typed +0 -0
|
@@ -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: "
|
|
6
|
+
title: "graph-dependence: split a graph-randomization drop into gain and penalty"
|
|
7
7
|
abstract: >-
|
|
8
|
-
|
|
9
|
-
|
|
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.
|
|
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
|
|
22
|
+
- graph neural networks
|
|
21
23
|
- graph ablation
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
+
- degree-preserving randomization
|
|
25
|
+
- PyTorch Geometric
|
|
24
26
|
preferred-citation:
|
|
25
27
|
type: article
|
|
26
|
-
title: "Dependence Is Not Advantage: What
|
|
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.
|
|
8
|
-
description = "
|
|
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
|
|
16
|
+
"graph neural networks",
|
|
17
17
|
"graph ablation",
|
|
18
|
-
"
|
|
19
|
-
"
|
|
20
|
-
"
|
|
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 ::
|
|
32
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
33
33
|
]
|
|
34
|
-
dependencies = ["
|
|
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 =
|
|
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)]
|