graph-dependence 0.1.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.
@@ -0,0 +1,37 @@
1
+ name: Deploy research site
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+ pages: write
11
+ id-token: write
12
+
13
+ concurrency:
14
+ group: pages
15
+ cancel-in-progress: true
16
+
17
+ jobs:
18
+ deploy:
19
+ environment:
20
+ name: github-pages
21
+ url: ${{ steps.deployment.outputs.page_url }}
22
+ runs-on: ubuntu-latest
23
+ steps:
24
+ - name: Check out repository
25
+ uses: actions/checkout@v4
26
+
27
+ - name: Configure Pages
28
+ uses: actions/configure-pages@v5
29
+
30
+ - name: Upload site artifact
31
+ uses: actions/upload-pages-artifact@v3
32
+ with:
33
+ path: site
34
+
35
+ - name: Deploy to GitHub Pages
36
+ id: deployment
37
+ uses: actions/deploy-pages@v4
@@ -0,0 +1,26 @@
1
+ name: tests
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ jobs:
11
+ quality:
12
+ runs-on: ubuntu-latest
13
+ strategy:
14
+ matrix:
15
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ - uses: actions/setup-python@v5
19
+ with:
20
+ python-version: ${{ matrix.python-version }}
21
+ cache: pip
22
+ - run: python -m pip install --upgrade pip
23
+ - run: python -m pip install -e '.[dev]'
24
+ - run: ruff check .
25
+ - run: mypy
26
+ - run: pytest --cov --cov-report=term-missing
@@ -0,0 +1,12 @@
1
+ .DS_Store
2
+ .coverage
3
+ .mypy_cache/
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ .venv/
7
+ __pycache__/
8
+ build/
9
+ dist/
10
+ *.egg-info/
11
+ examples/data/
12
+
@@ -0,0 +1 @@
1
+ 3.14
@@ -0,0 +1,33 @@
1
+ cff-version: 1.2.0
2
+ message: >-
3
+ If you use this implementation, please cite the paper below and identify the
4
+ software version used.
5
+ type: software
6
+ title: "Graph Dependence: diagnostics for graph ablations"
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.
10
+ authors:
11
+ - family-names: Duggireddy
12
+ given-names: Prahas
13
+ affiliation: Third Wheel
14
+ orcid: "https://orcid.org/0009-0008-6106-0759"
15
+ version: 0.1.0
16
+ license: Apache-2.0
17
+ repository-code: "https://github.com/Third-Wheel/dependence-is-not-advantage"
18
+ url: "https://third-wheel.github.io/dependence-is-not-advantage/"
19
+ keywords:
20
+ - graph learning
21
+ - graph ablation
22
+ - link prediction
23
+ - graph null model
24
+ preferred-citation:
25
+ type: article
26
+ title: "Dependence Is Not Advantage: What Randomizing the Graph Does Not Measure"
27
+ authors:
28
+ - family-names: Duggireddy
29
+ given-names: Prahas
30
+ affiliation: Third Wheel
31
+ orcid: "https://orcid.org/0009-0008-6106-0759"
32
+ year: 2026
33
+ url: "https://www.alphaxiv.org/abs/2608.dependence-is-not-advantage"
@@ -0,0 +1,204 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work
42
+ and for which the editorial revisions, annotations, elaborations,
43
+ or other modifications represent, as a whole, an original work of
44
+ authorship. For the purposes of this License, Derivative Works
45
+ shall not include works that remain separable from, or merely link
46
+ (or bind by name) to the interfaces of, the Work and Derivative
47
+ Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright
53
+ owner or by an individual or Legal Entity authorized to submit on
54
+ behalf of the copyright owner. For the purposes of this definition,
55
+ "submitted" means any form of electronic, verbal, or written
56
+ communication sent to the Licensor or its representatives, including
57
+ but not limited to communication on electronic mailing lists, source
58
+ code control systems, and issue tracking systems that are managed by,
59
+ or on behalf of, the Licensor for the purpose of discussing and
60
+ improving the Work, but excluding communication that is conspicuously
61
+ marked or otherwise designated in writing by the copyright owner as
62
+ "Not a Contribution."
63
+
64
+ "Contributor" shall mean Licensor and any individual or Legal Entity
65
+ on behalf of whom a Contribution has been received by Licensor and
66
+ subsequently incorporated within the Work.
67
+
68
+ 2. Grant of Copyright License. Subject to the terms and conditions of
69
+ this License, each Contributor hereby grants to You a perpetual,
70
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
71
+ copyright license to reproduce, prepare Derivative Works of,
72
+ publicly display, publicly perform, sublicense, and distribute the
73
+ Work and such Derivative Works in Source or Object form.
74
+
75
+ 3. Grant of Patent License. Subject to the terms and conditions of
76
+ this License, each Contributor hereby grants to You a perpetual,
77
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
78
+ (except as stated in this section) patent license to make, have made,
79
+ use, offer to sell, sell, import, and otherwise transfer the Work,
80
+ where such license applies only to those patent claims licensable
81
+ by such Contributor that are necessarily infringed by their
82
+ Contribution(s) alone or by combination of their Contribution(s)
83
+ with the Work to which such Contribution(s) was submitted. If You
84
+ institute patent litigation against any entity (including a
85
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
86
+ or a Contribution incorporated within the Work constitutes direct
87
+ or contributory patent infringement, then any patent licenses
88
+ granted to You under this License for that Work shall terminate
89
+ as of the date such litigation is filed.
90
+
91
+ 4. Redistribution. You may reproduce and distribute copies of the
92
+ Work or Derivative Works thereof in any medium, with or without
93
+ modifications, and in Source or Object form, provided that You
94
+ meet the following conditions:
95
+
96
+ (a) You must give any other recipients of the Work or
97
+ Derivative Works a copy of this License; and
98
+
99
+ (b) You must cause any modified files to carry prominent notices
100
+ stating that You changed the files; and
101
+
102
+ (c) You must retain, in the Source form of any Derivative Works
103
+ that You distribute, all copyright, patent, trademark, and
104
+ attribution notices from the Source form of the Work,
105
+ excluding those notices that do not pertain to any part of
106
+ the Derivative Works; and
107
+
108
+ (d) If the Work includes a "NOTICE" text file as part of its
109
+ distribution, then any Derivative Works that You distribute
110
+ must include a readable copy of the attribution notices
111
+ contained within such NOTICE file, excluding those notices
112
+ that do not pertain to any part of the Derivative Works, in
113
+ at least one of the following places: within a NOTICE text
114
+ file distributed as part of the Derivative Works; within the
115
+ Source form or documentation, if provided along with the
116
+ Derivative Works; or, within a display generated by the
117
+ Derivative Works, if and wherever such third-party notices
118
+ normally appear. The contents of the NOTICE file are for
119
+ informational purposes only and do not modify the License.
120
+ You may add Your own attribution notices within Derivative
121
+ Works that You distribute, alongside or as an addendum to
122
+ the NOTICE text from the Work, provided that such additional
123
+ attribution notices cannot be construed as modifying the
124
+ License.
125
+
126
+ You may add Your own copyright statement to Your modifications and
127
+ may provide additional or different license terms and conditions
128
+ for use, reproduction, or distribution of Your modifications, or
129
+ for any such Derivative Works as a whole, provided Your use,
130
+ reproduction, and distribution of the Work otherwise complies with
131
+ the conditions stated in this License.
132
+
133
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
134
+ any Contribution intentionally submitted for inclusion in the Work
135
+ by You to the Licensor shall be under the terms and conditions of
136
+ this License, without any additional terms or conditions.
137
+ Notwithstanding the above, nothing herein shall supersede or modify
138
+ the terms of any separate license agreement you may have executed
139
+ with Licensor regarding such Contributions.
140
+
141
+ 6. Trademarks. This License does not grant permission to use the trade
142
+ names, trademarks, service marks, or product names of the Licensor,
143
+ except as required for reasonable and customary use in describing
144
+ the origin of the Work and reproducing the content of the NOTICE file.
145
+
146
+ 7. Disclaimer of Warranty. Unless required by applicable law or
147
+ agreed to in writing, Licensor provides the Work (and each
148
+ Contributor provides its Contributions) on an "AS IS" BASIS,
149
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
150
+ implied, including, without limitation, any warranties or conditions
151
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
152
+ PARTICULAR PURPOSE. You are solely responsible for determining the
153
+ appropriateness of using or redistributing the Work and assume any
154
+ risks associated with Your exercise of permissions under this License.
155
+
156
+ 8. Limitation of Liability. In no event and under no legal theory,
157
+ whether in tort (including negligence), contract, or otherwise,
158
+ unless required by applicable law (such as deliberate and grossly
159
+ negligent acts) or agreed to in writing, shall any Contributor be
160
+ liable to You for damages, including any direct, indirect, special,
161
+ incidental, or consequential damages of any character arising as
162
+ a result of this License or out of the use or inability to use the
163
+ Work (including but not limited to damages for loss of goodwill,
164
+ work stoppage, computer failure or malfunction, or any and all
165
+ other commercial damages or losses), even if such Contributor has
166
+ been advised of the possibility of such damages.
167
+
168
+ 9. Accepting Warranty or Additional Liability. While redistributing
169
+ the Work or Derivative Works thereof, You may choose to offer,
170
+ and charge a fee for, acceptance of support, warranty, indemnity,
171
+ or other liability obligations and/or rights consistent with this
172
+ License. However, in accepting such obligations, You may act only
173
+ on Your own behalf and on Your sole responsibility, not on behalf
174
+ of any other Contributor, and only if You agree to indemnify,
175
+ defend, and hold each Contributor harmless for any liability
176
+ incurred by, or claims asserted against, such Contributor by reason
177
+ of your accepting any such warranty or additional liability.
178
+
179
+ END OF TERMS AND CONDITIONS
180
+
181
+ APPENDIX: How to apply the Apache License to your work.
182
+
183
+ To apply the Apache License to your work, attach the following
184
+ boilerplate notice, with the fields enclosed by brackets "[]"
185
+ replaced with your own identifying information. (Don't include
186
+ the brackets!) The text should be enclosed in the appropriate
187
+ comment syntax for the file format. We also recommend that a
188
+ file or class name and description of purpose be included on the
189
+ same "printed page" as the copyright notice for easier
190
+ identification within third-party archives.
191
+
192
+ Copyright 2026 Third Wheel
193
+
194
+ Licensed under the Apache License, Version 2.0 (the "License");
195
+ you may not use this file except in compliance with the License.
196
+ You may obtain a copy of the License at
197
+
198
+ http://www.apache.org/licenses/LICENSE-2.0
199
+
200
+ Unless required by applicable law or agreed to in writing, software
201
+ distributed under the License is distributed on an "AS IS" BASIS,
202
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
203
+ See the License for the specific language governing permissions and
204
+ limitations under the License.
@@ -0,0 +1,211 @@
1
+ Metadata-Version: 2.4
2
+ Name: graph-dependence
3
+ Version: 0.1.0
4
+ Summary: Minimal diagnostics that separate graph dependence from graph advantage.
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: evaluation,graph ablation,graph learning,link prediction,null model
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 :: Information Analysis
24
+ Requires-Python: >=3.11
25
+ Requires-Dist: networkx<4,>=3.2
26
+ Provides-Extra: dev
27
+ Requires-Dist: mypy>=1.17; extra == 'dev'
28
+ Requires-Dist: pytest-cov>=6.2; extra == 'dev'
29
+ Requires-Dist: pytest>=8.4; extra == 'dev'
30
+ Requires-Dist: ruff>=0.12; extra == 'dev'
31
+ Requires-Dist: types-networkx>=3.2; extra == 'dev'
32
+ Provides-Extra: release
33
+ Requires-Dist: build>=1.2; extra == 'release'
34
+ Requires-Dist: twine>=6.1; extra == 'release'
35
+ Description-Content-Type: text/markdown
36
+
37
+ # Graph Dependence
38
+
39
+ This repository contains the reference implementation for [_Dependence Is Not
40
+ Advantage: What Randomizing the Graph Does Not
41
+ Measure_](https://www.alphaxiv.org/abs/2608.dependence-is-not-advantage). The
42
+ paper is by Prahas Duggireddy and the package is maintained by Third Wheel.
43
+
44
+ The package reports two comparisons that are easy to mix up in graph-ablation
45
+ studies:
46
+
47
+ - **Dependence:** how a graph procedure changes when the observed graph is
48
+ replaced by a stated graph null.
49
+ - **Advantage:** how that procedure compares with a named scorer that does not
50
+ receive the graph.
51
+
52
+ Randomization answers the first question. It does not answer the second one by
53
+ itself. The implementation is intentionally small, typed, and close to these
54
+ definitions. Version 0.1.0 is an early reference implementation, not a general
55
+ graph-learning framework or a full reproduction of the paper.
56
+
57
+ Paper and project links:
58
+
59
+ - [Preprint](https://www.alphaxiv.org/abs/2608.dependence-is-not-advantage)
60
+ - [Project page](https://third-wheel.github.io/dependence-is-not-advantage/)
61
+ - [Source on GitHub](https://github.com/Third-Wheel/dependence-is-not-advantage)
62
+ - [Citation metadata](CITATION.cff)
63
+
64
+ ## Quick start
65
+
66
+ The smallest complete example needs no network access. From a checkout:
67
+
68
+ ```bash
69
+ python -m pip install .
70
+ python examples/minimal.py
71
+ ```
72
+
73
+ It uses a fixed graph, fixed node-content features, a degree-preserving null,
74
+ and seed 7. The command prints a JSON-compatible report that is small enough
75
+ to read alongside the source.
76
+
77
+ For an evaluation of your own, the central call looks like this:
78
+
79
+ ```python
80
+ from graph_dependence import DegreePreservingNull, binary_auc, diagnose
81
+
82
+ # Provide these objects from your evaluation protocol.
83
+ report = diagnose(
84
+ graph=graph,
85
+ examples=examples,
86
+ targets=targets,
87
+ graph_scorer=score_with_graph,
88
+ graph_free_scorer=score_without_graph,
89
+ null_model=DegreePreservingNull(attempts_per_edge=10),
90
+ metric=binary_auc,
91
+ null_draws=10,
92
+ seed=7,
93
+ )
94
+ print(report.to_dict())
95
+ ```
96
+
97
+ The call keeps the intact, null, and graph-free comparator scores together.
98
+ The resulting report can be serialized with `to_dict()` without a custom
99
+ encoder.
100
+
101
+ ## What the report means
102
+
103
+ | Field | Comparison | Interpretation |
104
+ | --------------- | ----------------------------------- | ---------------------------------------------------------------- |
105
+ | `dependence` | `observed_score - null_score` | Change under the declared graph intervention. |
106
+ | `advantage` | `observed_score - comparator_score` | Difference from the named graph-free scorer. |
107
+ | `null_survival` | `null_score / observed_score` | Fraction of the observed score that remains after randomization. |
108
+
109
+ `advantage` is `None` when no graph-free scorer is supplied. `null_survival` is
110
+ `None` when the observed score is not positive, because the ratio is undefined
111
+ there. The report also records the three reference scores, the seed, the null
112
+ model name, and sampler diagnostics.
113
+
114
+ ## The public API
115
+
116
+ | Symbol | Use |
117
+ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
118
+ | `diagnose` | Evaluate the intact, null, and optional graph-free arms and return one report. |
119
+ | `DegreePreservingNull` | Generate fixed-budget double-edge-swap null graphs and record the checks performed. |
120
+ | `DependenceReport` | Store scores, contrasts, seed, and metadata; `to_dict()` returns JSON-compatible values. |
121
+ | `binary_auc` | Provide a small dependency-free binary ranking metric for examples and tests. |
122
+ | `GraphScorer`, `GraphFreeScorer`, `Metric`, `NullModel` | Define the typed callable boundaries supplied by the caller. |
123
+
124
+ The formal definitions, empirical results, and claim boundaries remain in the
125
+ paper. The package implements the diagnostic around them; it does not recreate
126
+ the paper's training runs or manuscript tables.
127
+
128
+ ## Supplying scorers and metrics
129
+
130
+ A graph scorer receives a NetworkX graph and the evaluation examples. A
131
+ graph-free scorer receives the same examples without the graph. Both return one
132
+ score per example. A metric receives those scores and the targets and returns a
133
+ scalar, with larger values meaning better performance.
134
+
135
+ ```python
136
+ def score_with_graph(graph, examples):
137
+ return [len(list(nx.common_neighbors(graph, u, v))) for u, v in examples]
138
+
139
+
140
+ def score_without_graph(examples):
141
+ return [content_similarity[u, v] for u, v in examples]
142
+ ```
143
+
144
+ Custom scorers and metrics are ordinary callables. If a scorer trains a model
145
+ or uses randomness, condition-specific fitting and seed control are the
146
+ caller's responsibility. The `seed` argument controls null generation only.
147
+
148
+ ## The degree-preserving null
149
+
150
+ `DegreePreservingNull` applies a fixed budget of double-edge-swap attempts to
151
+ an undirected, simple, unweighted graph. It rejects self-loops, duplicate
152
+ edges, and new edges listed in `forbidden_edges`. Each draw records accepted
153
+ swaps, edge retention, component counts, and explicit degree and edge-count
154
+ checks.
155
+
156
+ Degree preservation describes a constraint, not a unique probability
157
+ distribution. The implementation records its sampler and budget and does not
158
+ claim uniform sampling over all graphs with the same degree sequence. Edge
159
+ attributes are rejected because assigning them to newly formed edges would
160
+ silently define a different intervention.
161
+
162
+ ## Public-data example
163
+
164
+ [`examples/cora.py`](examples/cora.py) downloads the public Cora citation graph,
165
+ constructs a deterministic link-prediction split, and compares
166
+ common-neighbor scores with a graph-free bag-of-words Jaccard scorer:
167
+
168
+ ```bash
169
+ python examples/cora.py
170
+ ```
171
+
172
+ This is an API example, not a reproduction of the paper's Cora row. The paper
173
+ uses the published HeaRT split, its hard negatives, and Hits@20. The example
174
+ uses a small deterministic split and AUC so that it can remain independent of
175
+ a training framework.
176
+
177
+ ## Repository layout
178
+
179
+ ```text
180
+ src/graph_dependence/ package implementation and py.typed marker
181
+ examples/minimal.py deterministic, network-free example
182
+ examples/cora.py optional public-data example
183
+ tests/ package and scientific-boundary tests
184
+ site/ paper page, searchable PDF, figure, and citations
185
+ ```
186
+
187
+ The paper and visible landing page are authoritative for scholarly claims.
188
+ `pyproject.toml` is authoritative for package version and support metadata;
189
+ `CITATION.cff` is authoritative for software citation metadata.
190
+
191
+ ## Scope
192
+
193
+ This repository does not train GraphSAGE, recreate manuscript tables, prescribe
194
+ a universally valid null model, or turn predictive improvement into evidence of
195
+ downstream recommendation benefit. It is a reference implementation for
196
+ separating dependence from advantage in an evaluation protocol.
197
+
198
+ For the formal definitions and empirical study, see the [paper](https://www.alphaxiv.org/abs/2608.dependence-is-not-advantage). For software reuse,
199
+ cite the version used and see [`CITATION.cff`](CITATION.cff).
200
+
201
+ ## Development
202
+
203
+ The package supports Python 3.11 and newer. To run the local checks after an
204
+ editable install:
205
+
206
+ ```bash
207
+ python -m pip install -e '.[dev]'
208
+ ruff check .
209
+ mypy --strict .
210
+ pytest --cov=graph_dependence --cov-branch
211
+ ```