gahib 2.0.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.
- gahib-2.0.0/LICENSE +21 -0
- gahib-2.0.0/PKG-INFO +171 -0
- gahib-2.0.0/README.md +124 -0
- gahib-2.0.0/gahib/__init__.py +25 -0
- gahib-2.0.0/gahib/core/__init__.py +20 -0
- gahib-2.0.0/gahib/core/agent.py +568 -0
- gahib-2.0.0/gahib/core/environment.py +557 -0
- gahib-2.0.0/gahib/core/graph_modules.py +281 -0
- gahib-2.0.0/gahib/core/graph_utils.py +206 -0
- gahib-2.0.0/gahib/core/mixin.py +258 -0
- gahib-2.0.0/gahib/core/model.py +307 -0
- gahib-2.0.0/gahib/core/module.py +387 -0
- gahib-2.0.0/gahib/core/utils.py +281 -0
- gahib-2.0.0/gahib/interpretation.py +1121 -0
- gahib-2.0.0/gahib/metrics/__init__.py +443 -0
- gahib-2.0.0/gahib/metrics/dre.py +138 -0
- gahib-2.0.0/gahib/metrics/lse.py +221 -0
- gahib-2.0.0/gahib.egg-info/PKG-INFO +171 -0
- gahib-2.0.0/gahib.egg-info/SOURCES.txt +23 -0
- gahib-2.0.0/gahib.egg-info/dependency_links.txt +1 -0
- gahib-2.0.0/gahib.egg-info/requires.txt +33 -0
- gahib-2.0.0/gahib.egg-info/top_level.txt +1 -0
- gahib-2.0.0/pyproject.toml +61 -0
- gahib-2.0.0/setup.cfg +4 -0
- gahib-2.0.0/tests/test_models.py +462 -0
gahib-2.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025-2026
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
gahib-2.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: gahib
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Graph Attention Hyperbolic Information Bottleneck VAE for single-cell omics analysis
|
|
5
|
+
Author: Zeyu Fu
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/PeterPonyu/GAHIB
|
|
8
|
+
Project-URL: Repository, https://github.com/PeterPonyu/GAHIB
|
|
9
|
+
Project-URL: Paper, https://doi.org/10.3389/fgene.2026.1863100
|
|
10
|
+
Keywords: single-cell,VAE,hyperbolic,graph-neural-network,scRNA-seq
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Requires-Dist: torch>=1.12
|
|
20
|
+
Requires-Dist: numpy
|
|
21
|
+
Requires-Dist: scipy
|
|
22
|
+
Requires-Dist: scikit-learn
|
|
23
|
+
Requires-Dist: anndata
|
|
24
|
+
Requires-Dist: tqdm
|
|
25
|
+
Requires-Dist: pandas
|
|
26
|
+
Provides-Extra: graph
|
|
27
|
+
Requires-Dist: torch-geometric; extra == "graph"
|
|
28
|
+
Provides-Extra: scanpy
|
|
29
|
+
Requires-Dist: scanpy; extra == "scanpy"
|
|
30
|
+
Provides-Extra: scvi
|
|
31
|
+
Requires-Dist: scvi-tools; extra == "scvi"
|
|
32
|
+
Provides-Extra: viz
|
|
33
|
+
Requires-Dist: matplotlib; extra == "viz"
|
|
34
|
+
Requires-Dist: seaborn; extra == "viz"
|
|
35
|
+
Provides-Extra: all
|
|
36
|
+
Requires-Dist: torch-geometric; extra == "all"
|
|
37
|
+
Requires-Dist: scanpy; extra == "all"
|
|
38
|
+
Requires-Dist: scvi-tools; extra == "all"
|
|
39
|
+
Requires-Dist: matplotlib; extra == "all"
|
|
40
|
+
Requires-Dist: seaborn; extra == "all"
|
|
41
|
+
Provides-Extra: dev
|
|
42
|
+
Requires-Dist: pytest; extra == "dev"
|
|
43
|
+
Requires-Dist: scanpy; extra == "dev"
|
|
44
|
+
Requires-Dist: matplotlib; extra == "dev"
|
|
45
|
+
Requires-Dist: seaborn; extra == "dev"
|
|
46
|
+
Dynamic: license-file
|
|
47
|
+
|
|
48
|
+
<div align="center">
|
|
49
|
+
<a href="https://peterponyu.github.io/">
|
|
50
|
+
<img src="https://peterponyu.github.io/assets/badges/GAHIB.svg" width="64" alt="ZF Lab · GAHIB">
|
|
51
|
+
</a>
|
|
52
|
+
</div>
|
|
53
|
+
|
|
54
|
+
# GAHIB
|
|
55
|
+
|
|
56
|
+
A PyTorch implementation of a graph-attention variational autoencoder with
|
|
57
|
+
an information bottleneck and a Lorentz hyperbolic geometry loss, applied
|
|
58
|
+
to single-cell RNA-seq latent representation learning.
|
|
59
|
+
|
|
60
|
+
## What it does
|
|
61
|
+
|
|
62
|
+
Given a `scanpy` `AnnData` with raw counts, GAHIB fits a VAE whose encoder
|
|
63
|
+
can be an MLP, a Transformer, or a graph neural network (GAT, GCN,
|
|
64
|
+
GraphSAGE, ChebConv, TAG, GraphTransformer, ARMA). The latent code is
|
|
65
|
+
shaped by three losses:
|
|
66
|
+
|
|
67
|
+
- a reconstruction term (NB, ZINB, Poisson, or ZIP),
|
|
68
|
+
- an information-bottleneck term that compresses the latent into a 2D
|
|
69
|
+
manifold coordinate, and
|
|
70
|
+
- a Lorentz-hyperbolic term that anchors the manifold coordinate on the
|
|
71
|
+
hyperboloid so radial distance encodes hierarchy.
|
|
72
|
+
|
|
73
|
+
Optional SDE and PDE modules are provided for trajectory experiments.
|
|
74
|
+
|
|
75
|
+
## Install
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
pip install gahib
|
|
79
|
+
# graph encoders, scanpy and scVI helpers
|
|
80
|
+
pip install "gahib[all]"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
For development, clone the repository and run `pip install -e ".[all]"`.
|
|
84
|
+
|
|
85
|
+
Python 3.9 or later. Full dependency list in `pyproject.toml`.
|
|
86
|
+
|
|
87
|
+
## Usage
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
import scanpy as sc
|
|
91
|
+
from gahib import GAHIB
|
|
92
|
+
|
|
93
|
+
adata = sc.read_h5ad("data/human_cd34_bone_marrow.h5ad")
|
|
94
|
+
|
|
95
|
+
model = GAHIB(
|
|
96
|
+
adata,
|
|
97
|
+
layer="counts",
|
|
98
|
+
encoder_type="graph",
|
|
99
|
+
graph_type="GAT",
|
|
100
|
+
latent_dim=10,
|
|
101
|
+
i_dim=2,
|
|
102
|
+
irecon=1.0,
|
|
103
|
+
lorentz=5.0,
|
|
104
|
+
)
|
|
105
|
+
|
|
106
|
+
model.fit(epochs=200, patience=30)
|
|
107
|
+
Z = model.get_latent()
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Set `encoder_type="mlp"` (default) for a plain VAE without the graph
|
|
111
|
+
encoder.
|
|
112
|
+
|
|
113
|
+
## Important constraint
|
|
114
|
+
|
|
115
|
+
The hyperbolic loss depends on the information-bottleneck target. With
|
|
116
|
+
`irecon=0`, the bottleneck coordinate is untrained and the Lorentz
|
|
117
|
+
distance becomes degenerate. The model enforces this dependency
|
|
118
|
+
internally.
|
|
119
|
+
|
|
120
|
+
## Main outputs
|
|
121
|
+
|
|
122
|
+
| Call | Returns |
|
|
123
|
+
| --------------------- | ------------------------------------- |
|
|
124
|
+
| `model.get_latent()` | the learned embedding |
|
|
125
|
+
| `model.get_time()` | the trajectory time estimate (if SDE) |
|
|
126
|
+
| `model.get_centroid()`| per-cluster latent centroids |
|
|
127
|
+
|
|
128
|
+
## Experiment runners
|
|
129
|
+
|
|
130
|
+
The `experiments/` directory contains reproducible runners for the
|
|
131
|
+
benchmark and robustness studies. Each runner takes its dataset paths
|
|
132
|
+
from `GAHIB_DATASET_DIRS` and writes results to
|
|
133
|
+
`GAHIB_results/{study}/`.
|
|
134
|
+
|
|
135
|
+
## Repository layout
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
gahib/ package source (core model, metrics, interpretation)
|
|
139
|
+
experiments/ benchmark and robustness runners
|
|
140
|
+
tests/ pytest suite
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## Tests
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
pytest
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## Citation
|
|
150
|
+
|
|
151
|
+
If you use GAHIB, please cite the article:
|
|
152
|
+
|
|
153
|
+
> Fu Z, Fu J, Wang X, Liu Y, Ran T. GAHIB: graph attention VAE with a hyperbolic information bottleneck for biologically structured single-cell representations. *Frontiers in Genetics*. 2026;17:1863100. https://doi.org/10.3389/fgene.2026.1863100
|
|
154
|
+
|
|
155
|
+
```bibtex
|
|
156
|
+
@article{fu2026gahib,
|
|
157
|
+
author = {Fu, Zeyu and Fu, Jiawei and Wang, Xiaoxia and Liu, Yiyao and Ran, Tianfei},
|
|
158
|
+
title = {GAHIB: graph attention VAE with a hyperbolic information bottleneck for biologically structured single-cell representations},
|
|
159
|
+
journal = {Frontiers in Genetics},
|
|
160
|
+
volume = {17},
|
|
161
|
+
pages = {1863100},
|
|
162
|
+
year = {2026},
|
|
163
|
+
doi = {10.3389/fgene.2026.1863100}
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
GitHub's "Cite this repository" button reads the same record from `CITATION.cff`.
|
|
168
|
+
|
|
169
|
+
## License
|
|
170
|
+
|
|
171
|
+
MIT. See `LICENSE`.
|
gahib-2.0.0/README.md
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<a href="https://peterponyu.github.io/">
|
|
3
|
+
<img src="https://peterponyu.github.io/assets/badges/GAHIB.svg" width="64" alt="ZF Lab · GAHIB">
|
|
4
|
+
</a>
|
|
5
|
+
</div>
|
|
6
|
+
|
|
7
|
+
# GAHIB
|
|
8
|
+
|
|
9
|
+
A PyTorch implementation of a graph-attention variational autoencoder with
|
|
10
|
+
an information bottleneck and a Lorentz hyperbolic geometry loss, applied
|
|
11
|
+
to single-cell RNA-seq latent representation learning.
|
|
12
|
+
|
|
13
|
+
## What it does
|
|
14
|
+
|
|
15
|
+
Given a `scanpy` `AnnData` with raw counts, GAHIB fits a VAE whose encoder
|
|
16
|
+
can be an MLP, a Transformer, or a graph neural network (GAT, GCN,
|
|
17
|
+
GraphSAGE, ChebConv, TAG, GraphTransformer, ARMA). The latent code is
|
|
18
|
+
shaped by three losses:
|
|
19
|
+
|
|
20
|
+
- a reconstruction term (NB, ZINB, Poisson, or ZIP),
|
|
21
|
+
- an information-bottleneck term that compresses the latent into a 2D
|
|
22
|
+
manifold coordinate, and
|
|
23
|
+
- a Lorentz-hyperbolic term that anchors the manifold coordinate on the
|
|
24
|
+
hyperboloid so radial distance encodes hierarchy.
|
|
25
|
+
|
|
26
|
+
Optional SDE and PDE modules are provided for trajectory experiments.
|
|
27
|
+
|
|
28
|
+
## Install
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pip install gahib
|
|
32
|
+
# graph encoders, scanpy and scVI helpers
|
|
33
|
+
pip install "gahib[all]"
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
For development, clone the repository and run `pip install -e ".[all]"`.
|
|
37
|
+
|
|
38
|
+
Python 3.9 or later. Full dependency list in `pyproject.toml`.
|
|
39
|
+
|
|
40
|
+
## Usage
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
import scanpy as sc
|
|
44
|
+
from gahib import GAHIB
|
|
45
|
+
|
|
46
|
+
adata = sc.read_h5ad("data/human_cd34_bone_marrow.h5ad")
|
|
47
|
+
|
|
48
|
+
model = GAHIB(
|
|
49
|
+
adata,
|
|
50
|
+
layer="counts",
|
|
51
|
+
encoder_type="graph",
|
|
52
|
+
graph_type="GAT",
|
|
53
|
+
latent_dim=10,
|
|
54
|
+
i_dim=2,
|
|
55
|
+
irecon=1.0,
|
|
56
|
+
lorentz=5.0,
|
|
57
|
+
)
|
|
58
|
+
|
|
59
|
+
model.fit(epochs=200, patience=30)
|
|
60
|
+
Z = model.get_latent()
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Set `encoder_type="mlp"` (default) for a plain VAE without the graph
|
|
64
|
+
encoder.
|
|
65
|
+
|
|
66
|
+
## Important constraint
|
|
67
|
+
|
|
68
|
+
The hyperbolic loss depends on the information-bottleneck target. With
|
|
69
|
+
`irecon=0`, the bottleneck coordinate is untrained and the Lorentz
|
|
70
|
+
distance becomes degenerate. The model enforces this dependency
|
|
71
|
+
internally.
|
|
72
|
+
|
|
73
|
+
## Main outputs
|
|
74
|
+
|
|
75
|
+
| Call | Returns |
|
|
76
|
+
| --------------------- | ------------------------------------- |
|
|
77
|
+
| `model.get_latent()` | the learned embedding |
|
|
78
|
+
| `model.get_time()` | the trajectory time estimate (if SDE) |
|
|
79
|
+
| `model.get_centroid()`| per-cluster latent centroids |
|
|
80
|
+
|
|
81
|
+
## Experiment runners
|
|
82
|
+
|
|
83
|
+
The `experiments/` directory contains reproducible runners for the
|
|
84
|
+
benchmark and robustness studies. Each runner takes its dataset paths
|
|
85
|
+
from `GAHIB_DATASET_DIRS` and writes results to
|
|
86
|
+
`GAHIB_results/{study}/`.
|
|
87
|
+
|
|
88
|
+
## Repository layout
|
|
89
|
+
|
|
90
|
+
```text
|
|
91
|
+
gahib/ package source (core model, metrics, interpretation)
|
|
92
|
+
experiments/ benchmark and robustness runners
|
|
93
|
+
tests/ pytest suite
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Tests
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
pytest
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Citation
|
|
103
|
+
|
|
104
|
+
If you use GAHIB, please cite the article:
|
|
105
|
+
|
|
106
|
+
> Fu Z, Fu J, Wang X, Liu Y, Ran T. GAHIB: graph attention VAE with a hyperbolic information bottleneck for biologically structured single-cell representations. *Frontiers in Genetics*. 2026;17:1863100. https://doi.org/10.3389/fgene.2026.1863100
|
|
107
|
+
|
|
108
|
+
```bibtex
|
|
109
|
+
@article{fu2026gahib,
|
|
110
|
+
author = {Fu, Zeyu and Fu, Jiawei and Wang, Xiaoxia and Liu, Yiyao and Ran, Tianfei},
|
|
111
|
+
title = {GAHIB: graph attention VAE with a hyperbolic information bottleneck for biologically structured single-cell representations},
|
|
112
|
+
journal = {Frontiers in Genetics},
|
|
113
|
+
volume = {17},
|
|
114
|
+
pages = {1863100},
|
|
115
|
+
year = {2026},
|
|
116
|
+
doi = {10.3389/fgene.2026.1863100}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
GitHub's "Cite this repository" button reads the same record from `CITATION.cff`.
|
|
121
|
+
|
|
122
|
+
## License
|
|
123
|
+
|
|
124
|
+
MIT. See `LICENSE`.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""
|
|
2
|
+
GAHIB: Graph Attention Hyperbolic Information Bottleneck
|
|
3
|
+
========================================================
|
|
4
|
+
|
|
5
|
+
A unified deep learning framework for single-cell omics analysis combining:
|
|
6
|
+
- Variational Autoencoder (VAE) with count-based likelihoods (NB, ZINB, Poisson, ZIP)
|
|
7
|
+
- Lorentz (hyperbolic) geometric regularization for hierarchical structure
|
|
8
|
+
- Dual-path information bottleneck for coordinated biological programs
|
|
9
|
+
- Graph neural network encoders (GAT, GCN, ChebConv, SAGE, etc.)
|
|
10
|
+
- Multi-encoder: MLP, Transformer, and Graph backbones
|
|
11
|
+
- Disentanglement: beta-VAE, DIP-VAE, TC-VAE, InfoVAE regularizers
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
import logging
|
|
15
|
+
|
|
16
|
+
logging.getLogger("gahib").addHandler(logging.NullHandler())
|
|
17
|
+
|
|
18
|
+
from .core.agent import GAHIB
|
|
19
|
+
|
|
20
|
+
__all__ = ["GAHIB"]
|
|
21
|
+
|
|
22
|
+
__version__ = "2.0.0"
|
|
23
|
+
__author__ = "Zeyu Fu"
|
|
24
|
+
__project__ = "GAHIB"
|
|
25
|
+
__full_name__ = "Graph Attention Hyperbolic Information Bottleneck"
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""
|
|
2
|
+
GAHIB Core: Graph Attention Hyperbolic Information Bottleneck
|
|
3
|
+
=============================================================
|
|
4
|
+
|
|
5
|
+
Integrates:
|
|
6
|
+
- GAHIB: Hyperbolic VAE with Lorentz geometry, information bottleneck,
|
|
7
|
+
and count-based likelihoods.
|
|
8
|
+
- CCVGAE: Graph Attention Network encoders/decoders, graph structure learning,
|
|
9
|
+
subgraph sampling, and centroid inference.
|
|
10
|
+
|
|
11
|
+
Encoder options: 'mlp', 'transformer', 'graph' (GAT, GCN, ChebConv, SAGE, etc.)
|
|
12
|
+
Decoder options: 'mlp' (with NB/ZINB/Poisson/ZIP likelihoods), 'graph'
|
|
13
|
+
Regularization: beta-VAE, DIP-VAE, beta-TC-VAE, InfoVAE, Lorentz/Euclidean manifold
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from .agent import GAHIB
|
|
17
|
+
|
|
18
|
+
__all__ = ["GAHIB"]
|
|
19
|
+
|
|
20
|
+
__version__ = "2.0.0"
|