gahib 2.0.0__py3-none-any.whl
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/__init__.py +25 -0
- gahib/core/__init__.py +20 -0
- gahib/core/agent.py +568 -0
- gahib/core/environment.py +557 -0
- gahib/core/graph_modules.py +281 -0
- gahib/core/graph_utils.py +206 -0
- gahib/core/mixin.py +258 -0
- gahib/core/model.py +307 -0
- gahib/core/module.py +387 -0
- gahib/core/utils.py +281 -0
- gahib/interpretation.py +1121 -0
- gahib/metrics/__init__.py +443 -0
- gahib/metrics/dre.py +138 -0
- gahib/metrics/lse.py +221 -0
- gahib-2.0.0.dist-info/METADATA +171 -0
- gahib-2.0.0.dist-info/RECORD +19 -0
- gahib-2.0.0.dist-info/WHEEL +5 -0
- gahib-2.0.0.dist-info/licenses/LICENSE +21 -0
- gahib-2.0.0.dist-info/top_level.txt +1 -0
gahib/__init__.py
ADDED
|
@@ -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"
|
gahib/core/__init__.py
ADDED
|
@@ -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"
|
gahib/core/agent.py
ADDED
|
@@ -0,0 +1,568 @@
|
|
|
1
|
+
"""
|
|
2
|
+
GAHIB: Graph Attention Hyperbolic Information Bottleneck VAE
|
|
3
|
+
=======================================================================
|
|
4
|
+
|
|
5
|
+
A unified deep learning framework for single-cell omics analysis combining:
|
|
6
|
+
- Variational Autoencoder (VAE) for dimensionality reduction
|
|
7
|
+
- Lorentz geometric regularization for hierarchical structure
|
|
8
|
+
- Dual-path information bottleneck for coordinated biological programs
|
|
9
|
+
- Transformer-based attention mechanisms for long-range dependencies
|
|
10
|
+
- Multiple count-based likelihood functions (NB, ZINB, Poisson, ZIP)
|
|
11
|
+
- Graph neural network encoders (GAT, GCN, ChebConv, SAGE, etc.)
|
|
12
|
+
- Graph structure decoders for adjacency learning
|
|
13
|
+
- Subgraph-aware training for scalability
|
|
14
|
+
|
|
15
|
+
Supports scRNA-seq and scATAC-seq modalities without architectural modification.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
# ============================================================================
|
|
19
|
+
# agent.py - Main User Interface
|
|
20
|
+
# ============================================================================
|
|
21
|
+
from .environment import Env
|
|
22
|
+
from anndata import AnnData
|
|
23
|
+
from typing import Optional
|
|
24
|
+
import logging
|
|
25
|
+
import torch
|
|
26
|
+
import tqdm
|
|
27
|
+
import time
|
|
28
|
+
import numpy as np
|
|
29
|
+
|
|
30
|
+
logger = logging.getLogger(__name__)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class GAHIB(Env):
|
|
34
|
+
"""
|
|
35
|
+
GAHIB: Graph Attention Hyperbolic Information Bottleneck VAE
|
|
36
|
+
|
|
37
|
+
A unified framework for single-cell omics analysis (scRNA-seq and scATAC-seq)
|
|
38
|
+
that learns low-dimensional representations while preserving both local
|
|
39
|
+
cell-state structure and global hierarchical organization through Lorentz
|
|
40
|
+
geometric regularization, information bottleneck architecture, and optional
|
|
41
|
+
graph neural network encoders.
|
|
42
|
+
|
|
43
|
+
Architecture Overview
|
|
44
|
+
---------------------
|
|
45
|
+
1. **Encoder**: MLP, Transformer, or Graph (GAT/GCN/etc.) backbone
|
|
46
|
+
2. **Information Bottleneck**: Optional compression layer for hierarchical features
|
|
47
|
+
3. **Manifold Regularization**: Lorentz or Euclidean distance constraints
|
|
48
|
+
4. **Feature Decoder**: MLP or Graph decoder for expression reconstruction
|
|
49
|
+
5. **Structure Decoder** (optional): Adjacency reconstruction (CCVGAE-style)
|
|
50
|
+
|
|
51
|
+
Parameters
|
|
52
|
+
----------
|
|
53
|
+
adata : AnnData
|
|
54
|
+
Annotated data matrix with raw count data in ``adata.layers[layer]``
|
|
55
|
+
layer : str, default='counts'
|
|
56
|
+
Layer name containing raw unnormalized count data
|
|
57
|
+
recon : float, default=1.0
|
|
58
|
+
Weight for reconstruction loss (primary objective)
|
|
59
|
+
irecon : float, default=0.0
|
|
60
|
+
Weight for information bottleneck reconstruction loss
|
|
61
|
+
lorentz : float, default=0.0
|
|
62
|
+
Weight for geometric manifold regularization
|
|
63
|
+
beta : float, default=1.0
|
|
64
|
+
Weight for KL divergence (beta-VAE); >1 encourages disentanglement
|
|
65
|
+
dip : float, default=0.0
|
|
66
|
+
Weight for Disentangled Inferred Prior (DIP-VAE) loss
|
|
67
|
+
tc : float, default=0.0
|
|
68
|
+
Weight for Total Correlation (beta-TC-VAE) loss
|
|
69
|
+
info : float, default=0.0
|
|
70
|
+
Weight for Maximum Mean Discrepancy (InfoVAE) loss
|
|
71
|
+
hidden_dim : int, default=128
|
|
72
|
+
Hidden layer dimension in encoder/decoder
|
|
73
|
+
latent_dim : int, default=10
|
|
74
|
+
Primary latent space dimensionality
|
|
75
|
+
i_dim : int, default=2
|
|
76
|
+
Information bottleneck dimension (should be < latent_dim)
|
|
77
|
+
lr : float, default=1e-4
|
|
78
|
+
Learning rate for Adam optimizer
|
|
79
|
+
use_bottleneck_lorentz : bool, default=True
|
|
80
|
+
If True, compute manifold distance on bottleneck; else on resampled latents
|
|
81
|
+
loss_type : str, default='nb'
|
|
82
|
+
Count likelihood model: 'nb', 'zinb', 'poisson', or 'zip'
|
|
83
|
+
grad_clip : float, default=1.0
|
|
84
|
+
Gradient clipping threshold for training stability
|
|
85
|
+
adaptive_norm : bool, default=True
|
|
86
|
+
Use dataset-specific normalization heuristics
|
|
87
|
+
use_layer_norm : bool, default=True
|
|
88
|
+
Apply layer normalization in encoder/decoder
|
|
89
|
+
use_euclidean_manifold : bool, default=False
|
|
90
|
+
Use Euclidean distance instead of Lorentz (hyperbolic) distance
|
|
91
|
+
train_size : float, default=0.7
|
|
92
|
+
Proportion of cells for training set
|
|
93
|
+
val_size : float, default=0.15
|
|
94
|
+
Proportion of cells for validation set
|
|
95
|
+
test_size : float, default=0.15
|
|
96
|
+
Proportion of cells for test set
|
|
97
|
+
batch_size : int, default=128
|
|
98
|
+
Mini-batch size for stochastic gradient descent
|
|
99
|
+
random_seed : int, default=42
|
|
100
|
+
Random seed for reproducibility
|
|
101
|
+
device : torch.device, optional
|
|
102
|
+
Computation device (auto-detects CUDA if available)
|
|
103
|
+
|
|
104
|
+
Encoder Selection
|
|
105
|
+
-----------------
|
|
106
|
+
encoder_type : str, default='mlp'
|
|
107
|
+
Encoder backbone:
|
|
108
|
+
- 'mlp': Standard MLP with LayerNorm (default)
|
|
109
|
+
- 'transformer': Multi-head attention encoder
|
|
110
|
+
- 'graph': Graph neural network encoder (requires torch_geometric)
|
|
111
|
+
|
|
112
|
+
Transformer Parameters (encoder_type='transformer')
|
|
113
|
+
---------------------------------------------------
|
|
114
|
+
attn_embed_dim : int, default=64
|
|
115
|
+
attn_num_heads : int, default=4
|
|
116
|
+
attn_num_layers : int, default=2
|
|
117
|
+
attn_seq_len : int, default=32
|
|
118
|
+
|
|
119
|
+
Graph Parameters (encoder_type='graph')
|
|
120
|
+
----------------------------------------
|
|
121
|
+
graph_type : str, default='GAT'
|
|
122
|
+
Graph convolution type: 'GAT', 'GCN', 'Cheb', 'SAGE', 'SSG',
|
|
123
|
+
'Transformer', 'GIN', 'Linear', 'GeneralConv', 'FILM'
|
|
124
|
+
graph_hidden_layers : int, default=2
|
|
125
|
+
graph_dropout : float, default=0.05
|
|
126
|
+
graph_Cheb_k : int, default=1
|
|
127
|
+
graph_alpha : float, default=0.5
|
|
128
|
+
use_residual : bool, default=True
|
|
129
|
+
use_graph_decoder : bool, default=False
|
|
130
|
+
Enable adjacency reconstruction (structure decoder)
|
|
131
|
+
structure_decoder_type : str, default='mlp'
|
|
132
|
+
Structure decoder type: 'bilinear', 'inner_product', 'mlp'
|
|
133
|
+
decoder_hidden_dim : int, default=128
|
|
134
|
+
graph_threshold : float, default=0
|
|
135
|
+
graph_sparse_threshold : float, optional
|
|
136
|
+
w_adj : float, default=0.0
|
|
137
|
+
Weight for adjacency BCE loss
|
|
138
|
+
graph_loss_weight : float, default=1.0
|
|
139
|
+
n_neighbors : int, default=15
|
|
140
|
+
KNN neighbors for constructing cell-cell graph
|
|
141
|
+
n_var : int, optional
|
|
142
|
+
Number of highly variable genes to select
|
|
143
|
+
tech : str, default='PCA'
|
|
144
|
+
Decomposition method: 'PCA', 'NMF', 'ICA', 'FA'
|
|
145
|
+
batch_tech : str, optional
|
|
146
|
+
Batch correction method: 'harmony', 'scvi', or None
|
|
147
|
+
all_feat : bool, default=False
|
|
148
|
+
Whether to use all features or only HVGs
|
|
149
|
+
subgraph_size : int, default=512
|
|
150
|
+
Subgraph size for scalable graph training
|
|
151
|
+
num_subgraphs_per_epoch : int, default=10
|
|
152
|
+
Subgraphs sampled per epoch
|
|
153
|
+
|
|
154
|
+
Examples
|
|
155
|
+
--------
|
|
156
|
+
>>> import scanpy as sc
|
|
157
|
+
>>> from gahib import GAHIB
|
|
158
|
+
>>>
|
|
159
|
+
>>> # Load data
|
|
160
|
+
>>> adata = sc.read_h5ad('data.h5ad')
|
|
161
|
+
>>>
|
|
162
|
+
>>> # Standard MLP encoder
|
|
163
|
+
>>> model = GAHIB(adata, layer='counts')
|
|
164
|
+
>>> model.fit(epochs=100)
|
|
165
|
+
>>> latent = model.get_latent()
|
|
166
|
+
>>>
|
|
167
|
+
>>> # With Lorentz regularization and information bottleneck
|
|
168
|
+
>>> model = GAHIB(adata, lorentz=5.0, latent_dim=10, i_dim=2)
|
|
169
|
+
>>> model.fit(epochs=400, patience=25)
|
|
170
|
+
>>>
|
|
171
|
+
>>> # Graph encoder (requires torch_geometric)
|
|
172
|
+
>>> model = GAHIB(
|
|
173
|
+
... adata, encoder_type='graph', graph_type='GAT',
|
|
174
|
+
... use_graph_decoder=True, w_adj=0.1
|
|
175
|
+
... )
|
|
176
|
+
>>> model.fit(epochs=200)
|
|
177
|
+
>>> centroids = model.get_centroid() # CCVGAE-style centroid inference
|
|
178
|
+
"""
|
|
179
|
+
|
|
180
|
+
def __init__(
|
|
181
|
+
self,
|
|
182
|
+
adata: AnnData,
|
|
183
|
+
layer: str = "counts",
|
|
184
|
+
recon: float = 1.0,
|
|
185
|
+
irecon: float = 0.0,
|
|
186
|
+
lorentz: float = 0.0,
|
|
187
|
+
beta: float = 1.0,
|
|
188
|
+
dip: float = 0.0,
|
|
189
|
+
tc: float = 0.0,
|
|
190
|
+
info: float = 0.0,
|
|
191
|
+
hidden_dim: int = 128,
|
|
192
|
+
latent_dim: int = 10,
|
|
193
|
+
i_dim: int = 2,
|
|
194
|
+
lr: float = 1e-4,
|
|
195
|
+
use_bottleneck_lorentz: bool = True,
|
|
196
|
+
loss_type: str = "nb",
|
|
197
|
+
grad_clip: float = 1.0,
|
|
198
|
+
adaptive_norm: bool = True,
|
|
199
|
+
use_layer_norm: bool = True,
|
|
200
|
+
use_euclidean_manifold: bool = False,
|
|
201
|
+
train_size: float = 0.7,
|
|
202
|
+
val_size: float = 0.15,
|
|
203
|
+
test_size: float = 0.15,
|
|
204
|
+
batch_size: int = 128,
|
|
205
|
+
random_seed: int = 42,
|
|
206
|
+
device: torch.device = None,
|
|
207
|
+
# Encoder/Decoder selection
|
|
208
|
+
encoder_type: str = "mlp",
|
|
209
|
+
feature_decoder_type: str = "mlp",
|
|
210
|
+
# Transformer
|
|
211
|
+
attn_embed_dim: int = 64,
|
|
212
|
+
attn_num_heads: int = 4,
|
|
213
|
+
attn_num_layers: int = 2,
|
|
214
|
+
attn_seq_len: int = 32,
|
|
215
|
+
attn_dropout: float = 0.1,
|
|
216
|
+
# Graph (CCVGAE)
|
|
217
|
+
graph_type: str = "GAT",
|
|
218
|
+
graph_hidden_layers: int = 2,
|
|
219
|
+
graph_dropout: float = 0.05,
|
|
220
|
+
graph_Cheb_k: int = 1,
|
|
221
|
+
graph_alpha: float = 0.5,
|
|
222
|
+
use_residual: bool = True,
|
|
223
|
+
use_graph_decoder: bool = False,
|
|
224
|
+
structure_decoder_type: str = "mlp",
|
|
225
|
+
decoder_hidden_dim: int = 128,
|
|
226
|
+
graph_threshold: float = 0,
|
|
227
|
+
graph_sparse_threshold: Optional[float] = None,
|
|
228
|
+
w_adj: float = 0.0,
|
|
229
|
+
graph_loss_weight: float = 1.0,
|
|
230
|
+
# Graph data construction
|
|
231
|
+
n_neighbors: int = 15,
|
|
232
|
+
n_var: Optional[int] = None,
|
|
233
|
+
tech: str = "PCA",
|
|
234
|
+
batch_tech: Optional[str] = None,
|
|
235
|
+
all_feat: bool = False,
|
|
236
|
+
subgraph_size: int = 512,
|
|
237
|
+
num_subgraphs_per_epoch: int = 10,
|
|
238
|
+
):
|
|
239
|
+
# Auto-detect device
|
|
240
|
+
if device is None:
|
|
241
|
+
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
|
|
242
|
+
|
|
243
|
+
# Validate parameters
|
|
244
|
+
if not (0.99 <= train_size + val_size + test_size <= 1.01):
|
|
245
|
+
raise ValueError(
|
|
246
|
+
f"Split sizes must sum to 1.0, got {train_size + val_size + test_size}"
|
|
247
|
+
)
|
|
248
|
+
|
|
249
|
+
if train_size < 0 or val_size < 0 or test_size < 0:
|
|
250
|
+
raise ValueError("Split sizes must be non-negative")
|
|
251
|
+
|
|
252
|
+
if i_dim >= latent_dim:
|
|
253
|
+
raise ValueError(
|
|
254
|
+
f"Information bottleneck dimension ({i_dim}) must be < latent dimension ({latent_dim})"
|
|
255
|
+
)
|
|
256
|
+
|
|
257
|
+
# Validate enum-like parameters
|
|
258
|
+
_VALID_LOSS = {"nb", "zinb", "poisson", "zip"}
|
|
259
|
+
_VALID_ENCODER = {"mlp", "transformer", "graph"}
|
|
260
|
+
if loss_type not in _VALID_LOSS:
|
|
261
|
+
raise ValueError(f"loss_type={loss_type!r} not in {_VALID_LOSS}")
|
|
262
|
+
if encoder_type not in _VALID_ENCODER:
|
|
263
|
+
raise ValueError(f"encoder_type={encoder_type!r} not in {_VALID_ENCODER}")
|
|
264
|
+
|
|
265
|
+
# Validate positive numeric parameters
|
|
266
|
+
for name, val in [("hidden_dim", hidden_dim), ("latent_dim", latent_dim),
|
|
267
|
+
("batch_size", batch_size), ("lr", lr)]:
|
|
268
|
+
if val <= 0:
|
|
269
|
+
raise ValueError(f"{name} must be positive, got {val}")
|
|
270
|
+
|
|
271
|
+
# Initialize parent environment
|
|
272
|
+
super().__init__(
|
|
273
|
+
adata=adata,
|
|
274
|
+
layer=layer,
|
|
275
|
+
recon=recon,
|
|
276
|
+
irecon=irecon,
|
|
277
|
+
lorentz=lorentz,
|
|
278
|
+
beta=beta,
|
|
279
|
+
dip=dip,
|
|
280
|
+
tc=tc,
|
|
281
|
+
info=info,
|
|
282
|
+
hidden_dim=hidden_dim,
|
|
283
|
+
latent_dim=latent_dim,
|
|
284
|
+
i_dim=i_dim,
|
|
285
|
+
lr=lr,
|
|
286
|
+
use_bottleneck_lorentz=use_bottleneck_lorentz,
|
|
287
|
+
loss_type=loss_type,
|
|
288
|
+
grad_clip=grad_clip,
|
|
289
|
+
adaptive_norm=adaptive_norm,
|
|
290
|
+
use_layer_norm=use_layer_norm,
|
|
291
|
+
use_euclidean_manifold=use_euclidean_manifold,
|
|
292
|
+
train_size=train_size,
|
|
293
|
+
val_size=val_size,
|
|
294
|
+
test_size=test_size,
|
|
295
|
+
batch_size=batch_size,
|
|
296
|
+
random_seed=random_seed,
|
|
297
|
+
device=device,
|
|
298
|
+
encoder_type=encoder_type,
|
|
299
|
+
feature_decoder_type=feature_decoder_type,
|
|
300
|
+
attn_embed_dim=attn_embed_dim,
|
|
301
|
+
attn_num_heads=attn_num_heads,
|
|
302
|
+
attn_num_layers=attn_num_layers,
|
|
303
|
+
attn_seq_len=attn_seq_len,
|
|
304
|
+
attn_dropout=attn_dropout,
|
|
305
|
+
graph_type=graph_type,
|
|
306
|
+
graph_hidden_layers=graph_hidden_layers,
|
|
307
|
+
graph_dropout=graph_dropout,
|
|
308
|
+
graph_Cheb_k=graph_Cheb_k,
|
|
309
|
+
graph_alpha=graph_alpha,
|
|
310
|
+
use_residual=use_residual,
|
|
311
|
+
use_graph_decoder=use_graph_decoder,
|
|
312
|
+
structure_decoder_type=structure_decoder_type,
|
|
313
|
+
decoder_hidden_dim=decoder_hidden_dim,
|
|
314
|
+
graph_threshold=graph_threshold,
|
|
315
|
+
graph_sparse_threshold=graph_sparse_threshold,
|
|
316
|
+
w_adj=w_adj,
|
|
317
|
+
graph_loss_weight=graph_loss_weight,
|
|
318
|
+
n_neighbors=n_neighbors,
|
|
319
|
+
n_var=n_var,
|
|
320
|
+
tech=tech,
|
|
321
|
+
batch_tech=batch_tech,
|
|
322
|
+
all_feat=all_feat,
|
|
323
|
+
subgraph_size=subgraph_size,
|
|
324
|
+
num_subgraphs_per_epoch=num_subgraphs_per_epoch,
|
|
325
|
+
)
|
|
326
|
+
|
|
327
|
+
# Resource tracking
|
|
328
|
+
self.train_time = 0.0
|
|
329
|
+
self.peak_memory_gb = 0.0
|
|
330
|
+
self.actual_epochs = 0
|
|
331
|
+
|
|
332
|
+
# ====================================================================
|
|
333
|
+
# Training
|
|
334
|
+
# ====================================================================
|
|
335
|
+
|
|
336
|
+
def fit(
|
|
337
|
+
self,
|
|
338
|
+
epochs: int = 400,
|
|
339
|
+
patience: int = 25,
|
|
340
|
+
val_every: int = 5,
|
|
341
|
+
early_stop: bool = True,
|
|
342
|
+
compute_metrics: bool = True,
|
|
343
|
+
):
|
|
344
|
+
"""
|
|
345
|
+
Train the GAHIB model.
|
|
346
|
+
|
|
347
|
+
Parameters
|
|
348
|
+
----------
|
|
349
|
+
epochs : int, default=400
|
|
350
|
+
Maximum number of training epochs
|
|
351
|
+
patience : int, default=25
|
|
352
|
+
Early stopping patience
|
|
353
|
+
val_every : int, default=5
|
|
354
|
+
Validation frequency (every N epochs)
|
|
355
|
+
early_stop : bool, default=True
|
|
356
|
+
Enable early stopping mechanism
|
|
357
|
+
compute_metrics : bool, default=True
|
|
358
|
+
If True, compute clustering metrics (ARI, NMI, etc.) during
|
|
359
|
+
validation. Set to False for faster training when intermediate
|
|
360
|
+
metrics are not needed — early stopping will use reconstruction
|
|
361
|
+
loss on the validation set instead.
|
|
362
|
+
|
|
363
|
+
Returns
|
|
364
|
+
-------
|
|
365
|
+
self : GAHIB
|
|
366
|
+
"""
|
|
367
|
+
use_cuda = torch.cuda.is_available()
|
|
368
|
+
if use_cuda:
|
|
369
|
+
torch.cuda.reset_peak_memory_stats()
|
|
370
|
+
start_time = time.time()
|
|
371
|
+
|
|
372
|
+
with tqdm.tqdm(total=epochs, desc="Training", ncols=200) as pbar:
|
|
373
|
+
for epoch in range(epochs):
|
|
374
|
+
train_loss = self.train_epoch()
|
|
375
|
+
|
|
376
|
+
if (epoch + 1) % val_every == 0 or epoch == 0:
|
|
377
|
+
if compute_metrics:
|
|
378
|
+
val_loss, val_score = self.validate()
|
|
379
|
+
else:
|
|
380
|
+
val_loss = self.validate_loss()
|
|
381
|
+
val_score = None
|
|
382
|
+
|
|
383
|
+
if early_stop:
|
|
384
|
+
should_stop, improved = self.check_early_stopping(
|
|
385
|
+
val_loss, patience
|
|
386
|
+
)
|
|
387
|
+
|
|
388
|
+
postfix = {
|
|
389
|
+
"Train": f"{train_loss:.2f}",
|
|
390
|
+
"Val": f"{val_loss:.2f}",
|
|
391
|
+
"Best": f"{self.best_val_loss:.2f}",
|
|
392
|
+
"Pat": f"{self.patience_counter}/{patience}",
|
|
393
|
+
"Imp": "Y" if improved else "N",
|
|
394
|
+
}
|
|
395
|
+
if val_score is not None:
|
|
396
|
+
postfix.update({
|
|
397
|
+
"ARI": f"{val_score[0]:.2f}",
|
|
398
|
+
"NMI": f"{val_score[1]:.2f}",
|
|
399
|
+
"ASW": f"{val_score[2]:.2f}",
|
|
400
|
+
"CAL": f"{val_score[3]:.2f}",
|
|
401
|
+
"DAV": f"{val_score[4]:.2f}",
|
|
402
|
+
"COR": f"{val_score[5]:.2f}",
|
|
403
|
+
})
|
|
404
|
+
pbar.set_postfix(postfix)
|
|
405
|
+
|
|
406
|
+
if should_stop:
|
|
407
|
+
self.actual_epochs = epoch + 1
|
|
408
|
+
logger.info("Early stopping at epoch %d", epoch + 1)
|
|
409
|
+
logger.info("Best validation loss: %.4f", self.best_val_loss)
|
|
410
|
+
self.load_best_model()
|
|
411
|
+
break
|
|
412
|
+
else:
|
|
413
|
+
postfix = {
|
|
414
|
+
"Train": f"{train_loss:.2f}",
|
|
415
|
+
"Val": f"{val_loss:.2f}",
|
|
416
|
+
}
|
|
417
|
+
if val_score is not None:
|
|
418
|
+
postfix.update({
|
|
419
|
+
"ARI": f"{val_score[0]:.2f}",
|
|
420
|
+
"NMI": f"{val_score[1]:.2f}",
|
|
421
|
+
"ASW": f"{val_score[2]:.2f}",
|
|
422
|
+
"CAL": f"{val_score[3]:.2f}",
|
|
423
|
+
"DAV": f"{val_score[4]:.2f}",
|
|
424
|
+
"COR": f"{val_score[5]:.2f}",
|
|
425
|
+
})
|
|
426
|
+
pbar.set_postfix(postfix)
|
|
427
|
+
|
|
428
|
+
pbar.update(1)
|
|
429
|
+
else:
|
|
430
|
+
self.actual_epochs = epochs
|
|
431
|
+
|
|
432
|
+
self.train_time = time.time() - start_time
|
|
433
|
+
self.peak_memory_gb = (
|
|
434
|
+
torch.cuda.max_memory_allocated() / 1e9 if use_cuda else 0.0
|
|
435
|
+
)
|
|
436
|
+
return self
|
|
437
|
+
|
|
438
|
+
# ====================================================================
|
|
439
|
+
# Inference
|
|
440
|
+
# ====================================================================
|
|
441
|
+
|
|
442
|
+
def get_latent(self):
|
|
443
|
+
"""
|
|
444
|
+
Extract latent representations for all cells.
|
|
445
|
+
|
|
446
|
+
Returns
|
|
447
|
+
-------
|
|
448
|
+
latent : ndarray of shape (n_cells, latent_dim)
|
|
449
|
+
"""
|
|
450
|
+
return self.take_latent(
|
|
451
|
+
self.X_norm,
|
|
452
|
+
edge_index=self.edge_index,
|
|
453
|
+
edge_weight=self.edge_weight,
|
|
454
|
+
)
|
|
455
|
+
|
|
456
|
+
def get_centroid(self):
|
|
457
|
+
"""
|
|
458
|
+
Extract centroid (deterministic mean) for all cells (graph encoder only).
|
|
459
|
+
|
|
460
|
+
This returns the q_m output from the graph encoder, which is the
|
|
461
|
+
centroid-based representation from CCVGAE's coupling mechanism.
|
|
462
|
+
|
|
463
|
+
Returns
|
|
464
|
+
-------
|
|
465
|
+
centroid : ndarray of shape (n_cells, latent_dim)
|
|
466
|
+
"""
|
|
467
|
+
return self.take_centroid(
|
|
468
|
+
self.X_norm,
|
|
469
|
+
edge_index=self.edge_index,
|
|
470
|
+
edge_weight=self.edge_weight,
|
|
471
|
+
)
|
|
472
|
+
|
|
473
|
+
def get_test_latent(self):
|
|
474
|
+
"""
|
|
475
|
+
Extract latent representations for test set only.
|
|
476
|
+
|
|
477
|
+
Returns
|
|
478
|
+
-------
|
|
479
|
+
latent : ndarray of shape (n_test, latent_dim)
|
|
480
|
+
"""
|
|
481
|
+
return self.take_latent(
|
|
482
|
+
self.X_test_norm,
|
|
483
|
+
edge_index=self.edge_index,
|
|
484
|
+
edge_weight=self.edge_weight,
|
|
485
|
+
)
|
|
486
|
+
|
|
487
|
+
def get_bottleneck(self):
|
|
488
|
+
"""
|
|
489
|
+
Extract information bottleneck representations.
|
|
490
|
+
|
|
491
|
+
Returns
|
|
492
|
+
-------
|
|
493
|
+
bottleneck : ndarray of shape (n_cells, i_dim)
|
|
494
|
+
"""
|
|
495
|
+
x = torch.tensor(self.X_norm, dtype=torch.float32).to(self.device)
|
|
496
|
+
with torch.no_grad():
|
|
497
|
+
if self.encoder_type == "graph":
|
|
498
|
+
ei = torch.LongTensor(self.edge_index).to(self.device) if self.edge_index is not None else None
|
|
499
|
+
ew = torch.FloatTensor(self.edge_weight).to(self.device) if self.edge_weight is not None else None
|
|
500
|
+
outputs = self.nn(x, edge_index=ei, edge_weight=ew)
|
|
501
|
+
else:
|
|
502
|
+
outputs = self.nn(x)
|
|
503
|
+
le = outputs.le # Information bottleneck encoding
|
|
504
|
+
return le.cpu().numpy()
|
|
505
|
+
|
|
506
|
+
def get_resource_metrics(self):
|
|
507
|
+
"""
|
|
508
|
+
Get training resource usage metrics.
|
|
509
|
+
|
|
510
|
+
Returns
|
|
511
|
+
-------
|
|
512
|
+
metrics : dict
|
|
513
|
+
Dictionary with 'train_time', 'peak_memory_gb', 'actual_epochs'
|
|
514
|
+
"""
|
|
515
|
+
return {
|
|
516
|
+
"train_time": self.train_time,
|
|
517
|
+
"peak_memory_gb": self.peak_memory_gb,
|
|
518
|
+
"actual_epochs": self.actual_epochs,
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
def __repr__(self):
|
|
522
|
+
n_params = sum(p.numel() for p in self.nn.parameters())
|
|
523
|
+
parts = [
|
|
524
|
+
f"GAHIB(encoder={self.encoder_type!r}",
|
|
525
|
+
f"latent_dim={self.nn.latent_dim}",
|
|
526
|
+
f"n_cells={self.n_obs}",
|
|
527
|
+
f"n_genes={self.n_var}",
|
|
528
|
+
f"params={n_params:,}",
|
|
529
|
+
]
|
|
530
|
+
if self.encoder_type == "graph":
|
|
531
|
+
parts.append(f"graph={self.nn.encoder.conv_type}")
|
|
532
|
+
return ", ".join(parts) + ")"
|
|
533
|
+
|
|
534
|
+
def summary_dict(self):
|
|
535
|
+
"""Return a dictionary of the model configuration.
|
|
536
|
+
|
|
537
|
+
Returns
|
|
538
|
+
-------
|
|
539
|
+
config : dict
|
|
540
|
+
Dictionary with model configuration keys.
|
|
541
|
+
"""
|
|
542
|
+
n_params = sum(p.numel() for p in self.nn.parameters())
|
|
543
|
+
d = {
|
|
544
|
+
"encoder_type": self.encoder_type,
|
|
545
|
+
"parameters": n_params,
|
|
546
|
+
"latent_dim": self.nn.latent_dim,
|
|
547
|
+
"bottleneck_dim": self.nn.i_dim,
|
|
548
|
+
"input_dim": self.n_var,
|
|
549
|
+
"n_cells": self.n_obs,
|
|
550
|
+
"loss_type": self.loss_type,
|
|
551
|
+
"device": str(self.device),
|
|
552
|
+
}
|
|
553
|
+
if self.encoder_type == "graph":
|
|
554
|
+
d["graph_type"] = self.nn.encoder.conv_type
|
|
555
|
+
d["graph_decoder"] = self.nn.use_graph_decoder
|
|
556
|
+
d["n_edges"] = len(self.edge_weight) if self.edge_weight is not None else 0
|
|
557
|
+
return d
|
|
558
|
+
|
|
559
|
+
def summary(self):
|
|
560
|
+
"""Print a summary of the model configuration."""
|
|
561
|
+
d = self.summary_dict()
|
|
562
|
+
logger.info("=" * 60)
|
|
563
|
+
logger.info("GAHIB Model Summary")
|
|
564
|
+
logger.info("=" * 60)
|
|
565
|
+
for key, val in d.items():
|
|
566
|
+
label = key.replace("_", " ").title()
|
|
567
|
+
logger.info(" %-18s %s", label, f"{val:,}" if isinstance(val, int) and key == "parameters" else val)
|
|
568
|
+
logger.info("=" * 60)
|