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 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"