clone2vec 0.1.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.
@@ -0,0 +1,1204 @@
1
+ from __future__ import annotations
2
+
3
+ import scanpy as sc
4
+ import torch.nn as nn
5
+ import numpy as np
6
+ import scipy.sparse as sp
7
+ import pandas as pd
8
+
9
+ import torch
10
+ import random
11
+ import time
12
+ import sys
13
+
14
+ from typing import Literal
15
+ from tqdm import tqdm
16
+
17
+ logg = sc.logging
18
+
19
+ def _create_pairs(X: np.ndarray | sp.spmatrix) -> list[tuple[int, int]]:
20
+ """
21
+ Creates a list of pairs (row, col) from a sparse or dense count matrix X.
22
+
23
+ Parameters
24
+ ----------
25
+ X : np.ndarray or sp.spmatrix
26
+ Input matrix.
27
+
28
+ Returns
29
+ -------
30
+ list[tuple[int, int]]
31
+ List of pairs (i, j) where X[i, j] is non-zero.
32
+ """
33
+
34
+ if sp.issparse(X):
35
+ coo = X.tocoo()
36
+ data = coo.data
37
+ else:
38
+ coo = np.asarray(X)
39
+ rows, cols = np.nonzero(coo)
40
+ data = coo[rows, cols]
41
+ coo = type("obj", (object,), {"row": rows, "col": cols, "data": data})
42
+
43
+ rounded = np.round(data)
44
+ if not np.allclose(data, rounded):
45
+ raise ValueError("X contains non-integer counts.")
46
+
47
+ counts = rounded.astype(int)
48
+ if np.any(counts < 0):
49
+ raise ValueError("X contains negative counts.")
50
+
51
+ return [
52
+ (int(r), int(c))
53
+ for r, c, cnt in zip(coo.row, coo.col, counts)
54
+ for _ in range(cnt)
55
+ ]
56
+
57
+ class SkipGram(nn.Module):
58
+ """
59
+ A SkipGram model that dynamically defines its embedding size during fitting.
60
+ """
61
+
62
+ def __init__(self, z_dim: int, device: str | None = None):
63
+ """
64
+ Initialize the SkipGram model structure.
65
+
66
+ Parameters
67
+ ----------
68
+ z_dim : int
69
+ Dimensionality of the embedding space.
70
+ device : str or None, optional
71
+ Preferred compute device. If None, it will be auto-detected.
72
+ """
73
+ super().__init__()
74
+ self.z_dim = z_dim
75
+ self.device = device
76
+ self.log_softmax = nn.LogSoftmax(dim=1)
77
+
78
+ self.embedding = None
79
+ self.output = None
80
+ self.is_fitted_ = False
81
+
82
+ def _set_device(self, device: str | None) -> str:
83
+ """
84
+ Set the compute device for the model.
85
+
86
+ Parameters
87
+ ----------
88
+ device : str or None, optional
89
+ Device to use for training. If None, it will be auto-detected. Default is None.
90
+
91
+ Returns
92
+ -------
93
+ str
94
+ The selected compute device.
95
+ """
96
+ if device is None:
97
+ if torch.cuda.is_available():
98
+ final_device = "cuda"
99
+ elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
100
+ final_device = "mps"
101
+ else:
102
+ final_device = "cpu"
103
+ elif device == "cuda" and not torch.cuda.is_available():
104
+ logg.warning("CUDA not available. Falling back to CPU.")
105
+ final_device = "cpu"
106
+ elif device == "mps" and not (hasattr(torch.backends, "mps") and torch.backends.mps.is_available()):
107
+ logg.warning("MPS not available. Falling back to CPU.")
108
+ final_device = "cpu"
109
+ else:
110
+ final_device = device
111
+
112
+ self.device = final_device
113
+ self.to(final_device)
114
+ return final_device
115
+
116
+ def forward(self, input_word: torch.Tensor) -> torch.Tensor:
117
+ emb_input = self.embedding(input_word)
118
+ context_scores = self.output(emb_input)
119
+ return self.log_softmax(context_scores)
120
+
121
+ def _initialize_or_resize_layers(self, input_vocab_size: int, output_vocab_size: int):
122
+ """
123
+ Initialize or resize the embedding and output layers.
124
+
125
+ Parameters
126
+ ----------
127
+ input_vocab_size : int
128
+ Size of the input vocabulary.
129
+ output_vocab_size : int
130
+ Size of the output vocabulary.
131
+ """
132
+ if not self.is_fitted_:
133
+ self.embedding = nn.Embedding(input_vocab_size, self.z_dim)
134
+ self.output = nn.Linear(self.z_dim, output_vocab_size)
135
+ self.is_fitted_ = True
136
+ return
137
+
138
+ current_input_size = self.embedding.num_embeddings
139
+ current_output_size = self.output.out_features
140
+
141
+ if current_input_size != input_vocab_size:
142
+ new_embedding = nn.Embedding(input_vocab_size, self.z_dim)
143
+ copy_rows = min(current_input_size, input_vocab_size)
144
+ with torch.no_grad():
145
+ new_embedding.weight.data[:copy_rows] = self.embedding.weight.data[:copy_rows]
146
+ self.embedding = new_embedding
147
+
148
+ if current_output_size != output_vocab_size:
149
+ new_output = nn.Linear(self.z_dim, output_vocab_size)
150
+ copy_rows = min(current_output_size, output_vocab_size)
151
+ with torch.no_grad():
152
+ new_output.weight.data[:copy_rows] = self.output.weight.data[:copy_rows]
153
+ new_output.bias.data[:copy_rows] = self.output.bias.data[:copy_rows]
154
+ self.output = new_output
155
+
156
+ def fit(
157
+ self,
158
+ X: np.ndarray | sp.spmatrix,
159
+ random_state: int | None = 42,
160
+ batch_size: int = 128,
161
+ device: str | None = None,
162
+ learning_rate: float = 0.001,
163
+ early_stopping_patience: int = 5,
164
+ early_stopping_min_delta: float = 1e-4,
165
+ progress_bar: bool = True,
166
+ max_iter: int = 500,
167
+ return_model: bool = False,
168
+ init: Literal["svd", "random", "custom"] = "random",
169
+ init_embeddings: np.ndarray | None = None,
170
+ init_output_weight: np.ndarray | None = None,
171
+ ) -> np.ndarray | "SkipGram":
172
+ """
173
+ Fitting the SkipGram model to the input count matrix.
174
+
175
+ Parameters
176
+ ----------
177
+ X : np.ndarray or sp.spmatrix
178
+ Input count matrix.
179
+ random_state : int or None, optional
180
+ Random seed for reproducibility. Default is 42.
181
+ batch_size : int, optional
182
+ Batch size for training. Default is 128.
183
+ device : str or None, optional
184
+ Device to use for training. Default is None.
185
+ learning_rate : float, optional
186
+ Learning rate for Adam optimizer. Default is 0.001.
187
+ early_stopping_patience : int, optional
188
+ Patience for early stopping. Default is 5.
189
+ early_stopping_min_delta : float, optional
190
+ Minimum delta for early stopping. Default is 1e-4.
191
+ progress_bar : bool, optional
192
+ Whether to show a progress bar. Default is True.
193
+ max_iter : int, optional
194
+ Maximum number of iterations. Default is 500.
195
+ return_model : bool, optional
196
+ Whether to return the fitted model. Default is False.
197
+ init : Literal["svd", "random", "custom"], optional
198
+ Initialization method for embeddings. Default is "random".
199
+ init_embeddings : np.ndarray or None, optional
200
+ Custom initial embeddings. Default is None.
201
+ init_output_weight : np.ndarray or None, optional
202
+ Custom initial output weight. Default is None.
203
+
204
+ Returns
205
+ -------
206
+ np.ndarray or SkipGram
207
+ If return_model is True, returns the fitted model. Otherwise, returns the embeddings.
208
+ """
209
+ if random_state is not None:
210
+ torch.manual_seed(random_state)
211
+ np.random.seed(random_state)
212
+ random.seed(random_state)
213
+
214
+ input_vocab_size, output_vocab_size = X.shape
215
+ self._initialize_or_resize_layers(input_vocab_size, output_vocab_size)
216
+ self.learning_rate = learning_rate
217
+
218
+ device = self._set_device(device)
219
+
220
+ # Normalize init parameter
221
+ if init not in {"svd", "random", "custom"}:
222
+ logg.warning("init must be one of {'random', 'custom', 'svd'}. Falling back to 'svd'.")
223
+ init = "svd"
224
+
225
+ # If custom arrays are provided but init is not 'custom', accept them
226
+ if (init_embeddings is not None or init_output_weight is not None) and init != "custom":
227
+ init = "custom"
228
+
229
+ if init == "svd":
230
+ U0, V0 = self._compute_svd_init(X, self.z_dim)
231
+ with torch.no_grad():
232
+ self.embedding.weight.data = torch.from_numpy(U0.astype(np.float32)).to(device)
233
+ self.output.weight.data = torch.from_numpy(V0.astype(np.float32)).to(device)
234
+ self.output.bias.data.zero_()
235
+ elif init == "custom":
236
+ if init_embeddings is not None:
237
+ if init_embeddings.shape != (input_vocab_size, self.z_dim):
238
+ logg.warning(
239
+ f"init_embeddings shape {init_embeddings.shape} must be (vocab_size={input_vocab_size}, z_dim={self.z_dim}). Falling back to SVD."
240
+ )
241
+ U0, V0 = self._compute_svd_init(X, self.z_dim)
242
+ with torch.no_grad():
243
+ self.embedding.weight.data = torch.from_numpy(U0.astype(np.float32)).to(device)
244
+ self.output.weight.data = torch.from_numpy(V0.astype(np.float32)).to(device)
245
+ self.output.bias.data.zero_()
246
+ else:
247
+ with torch.no_grad():
248
+ self.embedding.weight.data = torch.from_numpy(init_embeddings.astype(np.float32)).to(device)
249
+ else:
250
+ U0, V0 = self._compute_svd_init(X, self.z_dim)
251
+ with torch.no_grad():
252
+ self.embedding.weight.data = torch.from_numpy(U0.astype(np.float32)).to(device)
253
+ self.output.weight.data = torch.from_numpy(V0.astype(np.float32)).to(device)
254
+ self.output.bias.data.zero_()
255
+
256
+ if init_output_weight is not None:
257
+ if init_output_weight.shape != (output_vocab_size, self.z_dim):
258
+ logg.warning(
259
+ f"init_output_weight shape {init_output_weight.shape} must be (vocab_size={output_vocab_size}, z_dim={self.z_dim}). Keeping current initialization."
260
+ )
261
+ else:
262
+ with torch.no_grad():
263
+ self.output.weight.data = torch.from_numpy(init_output_weight.astype(np.float32)).to(device)
264
+
265
+ with torch.no_grad():
266
+ if self.output.bias is not None:
267
+ self.output.bias.data.zero_()
268
+ else:
269
+ with torch.no_grad():
270
+ self.embedding.weight.data.uniform_(-1.0, 1.0)
271
+ self.output.weight.data.uniform_(-1.0, 1.0)
272
+ self.output.bias.data.zero_()
273
+
274
+ pairs = _create_pairs(X)
275
+ train_loader = torch.utils.data.DataLoader(
276
+ pairs,
277
+ batch_size=batch_size,
278
+ shuffle=True,
279
+ )
280
+ optimizer = torch.optim.Adam(self.parameters(), lr=learning_rate)
281
+ criterion = nn.NLLLoss()
282
+
283
+ if sc.settings.verbosity.value >= 2:
284
+ prefix = " "
285
+ progress_bar = True
286
+ else:
287
+ prefix = ""
288
+
289
+ if progress_bar:
290
+ cm = tqdm(
291
+ range(max_iter),
292
+ desc=prefix + "SG epochs",
293
+ dynamic_ncols=True,
294
+ leave=True,
295
+ file=sys.stdout,
296
+ )
297
+ else:
298
+ from contextlib import nullcontext
299
+ cm = nullcontext(range(max_iter))
300
+
301
+ patience_counter = 0
302
+ prev_loglik = None
303
+ self.loglik_history_ = []
304
+
305
+ with cm as iterator:
306
+ for epoch in iterator:
307
+ losses = []
308
+ for x_batch, y_batch in train_loader:
309
+ self.train()
310
+ x_batch, y_batch = x_batch.to(device), y_batch.to(device)
311
+
312
+ optimizer.zero_grad()
313
+ log_ps = self(x_batch)
314
+ loss = criterion(log_ps, y_batch)
315
+ loss.backward()
316
+ optimizer.step()
317
+ losses.append(loss.item())
318
+
319
+ current_loss = np.mean(losses) if losses else float("inf")
320
+ self.loglik_history_.append(-current_loss)
321
+ loglik = -current_loss
322
+
323
+ if prev_loglik is not None:
324
+ rel_delta = abs((loglik - prev_loglik) / (abs(prev_loglik) + 1e-9))
325
+ if rel_delta < early_stopping_min_delta:
326
+ patience_counter += 1
327
+ else:
328
+ patience_counter = 0
329
+ if progress_bar:
330
+ iterator.set_postfix({"loss": f"{current_loss:.4f}", "Δ": f"{rel_delta:.2e}"})
331
+ else:
332
+ if progress_bar:
333
+ iterator.set_postfix({"loss": f"{current_loss:.4f}"})
334
+
335
+ if patience_counter >= early_stopping_patience:
336
+ break
337
+ prev_loglik = loglik
338
+
339
+ if progress_bar:
340
+ if epoch == max_iter - 1:
341
+ tqdm.write(prefix + f"reached max_iter {max_iter}")
342
+ else:
343
+ tqdm.write(prefix + f"early stopping at epoch {epoch + 1}")
344
+
345
+ self.U = self.embedding.weight.data.cpu().numpy()
346
+ self.V = self.output.weight.data.cpu().numpy()
347
+ self.loglik_history_ = np.array(self.loglik_history_)
348
+
349
+ return self if return_model else self.U
350
+
351
+ def _compute_svd_init(
352
+ self,
353
+ X: np.ndarray | sp.spmatrix,
354
+ z_dim: int,
355
+ ) -> tuple[np.ndarray, np.ndarray]:
356
+ """
357
+ Compute SVD-based initialization for embeddings and output weights.
358
+
359
+ Parameters
360
+ ----------
361
+ X : np.ndarray or sp.spmatrix
362
+ Input count matrix.
363
+ z_dim : int
364
+ Target dimensionality.
365
+
366
+ Returns
367
+ -------
368
+ tuple[np.ndarray, np.ndarray]
369
+ Tuple of `(init_embeddings, init_output_weight)` arrays.
370
+ """
371
+ from scipy.sparse.linalg import svds
372
+ from scipy.linalg import svd
373
+
374
+ if sp.issparse(X):
375
+ X = X.tocsr().astype(np.float64)
376
+ X = X.copy()
377
+ X.data = np.log1p(X.data)
378
+ U, S, Vt = svds(X, k=z_dim)
379
+ order = np.argsort(S)[::-1]
380
+ S = S[order]
381
+ U = U[:, order]
382
+ Vt = Vt[order, :]
383
+ else:
384
+ X = np.asarray(X, dtype=np.float64)
385
+ U, S, Vt = svd(np.log1p(X), full_matrices=False)
386
+ U = U[:, :z_dim]
387
+ S = S[:z_dim]
388
+ Vt = Vt[:z_dim, :]
389
+
390
+ S_sqrt = np.sqrt(S)
391
+ init_embeddings = U * S_sqrt[np.newaxis, :]
392
+ init_output_weight = (Vt.T * S_sqrt[np.newaxis, :])
393
+ return init_embeddings.astype(np.float32), init_output_weight.astype(np.float32)
394
+
395
+ def project(
396
+ self,
397
+ X_new: np.ndarray | sp.spmatrix,
398
+ random_state: int | None = 42,
399
+ batch_size: int = 128,
400
+ device: str | None = None,
401
+ learning_rate: float = 0.001,
402
+ early_stopping_patience: int = 5,
403
+ early_stopping_min_delta: float = 1e-4,
404
+ progress_bar: bool = True,
405
+ max_iter: int = 500,
406
+ return_model: bool = False,
407
+ ) -> np.ndarray | "SkipGram":
408
+ """
409
+ Project new data onto the fitted SkipGram model.
410
+
411
+ Parameters
412
+ ----------
413
+ X_new : np.ndarray or sp.spmatrix
414
+ New count matrix to project.
415
+ random_state : int | None, optional
416
+ Random seed for reproducibility. Default is 42.
417
+ batch_size : int, optional
418
+ Batch size for training. Default is 128.
419
+ device : str | None, optional
420
+ Device to use for training. If None, it will be auto-detected. Default is None.
421
+ learning_rate : float, optional
422
+ Learning rate for Adam optimizer. Default is 0.001.
423
+ early_stopping_patience : int, optional
424
+ Patience for early stopping. Default is 5.
425
+ early_stopping_min_delta : float, optional
426
+ Minimum delta for early stopping. Default is 1e-4.
427
+ progress_bar : bool, optional
428
+ Whether to show a progress bar. Default is True.
429
+ max_iter : int, optional
430
+ Maximum number of iterations. Default is 500.
431
+ return_model : bool, optional
432
+ Whether to return the fitted model. Default is False.
433
+
434
+ Returns
435
+ -------
436
+ np.ndarray or SkipGram
437
+ Projected embeddings or the fitted model.
438
+ """
439
+ if not self.is_fitted_:
440
+ raise RuntimeError("Model must be fitted before projecting new data. Call fit() first.")
441
+
442
+ start = logg.info("projecting embeddings with SkipGram")
443
+
444
+ if random_state is not None:
445
+ torch.manual_seed(random_state)
446
+ np.random.seed(random_state)
447
+ random.seed(random_state)
448
+
449
+ n_new, n_old_vocab = X_new.shape
450
+ if n_old_vocab != self.output.out_features:
451
+ raise ValueError(f"X_new must have {self.output.out_features} columns, but got {n_old_vocab}.")
452
+
453
+ device = self._set_device(device)
454
+
455
+ self._initialize_or_resize_layers(n_new, self.output.out_features)
456
+
457
+ with torch.no_grad():
458
+ self.embedding.weight.data = torch.randn(n_new, self.z_dim, device=device) * 1e-4
459
+
460
+ self.output.requires_grad_(False)
461
+
462
+ pairs = _create_pairs(X_new)
463
+ train_loader = torch.utils.data.DataLoader(pairs, batch_size=batch_size, shuffle=True)
464
+
465
+ optimizer = torch.optim.Adam([self.embedding.weight], lr=learning_rate)
466
+ criterion = nn.NLLLoss()
467
+
468
+ if sc.settings.verbosity.value >= 2:
469
+ prefix = " "
470
+ progress_bar = True
471
+ else:
472
+ prefix = ""
473
+
474
+ if progress_bar:
475
+ cm = tqdm(
476
+ range(max_iter),
477
+ desc=prefix + "SG project epochs",
478
+ dynamic_ncols=True,
479
+ leave=True,
480
+ file=sys.stdout,
481
+ )
482
+ else:
483
+ from contextlib import nullcontext
484
+ cm = nullcontext(range(max_iter))
485
+ patience_counter = 0
486
+ prev_loglik = None
487
+ proj_loglik_history = []
488
+
489
+ with cm as iterator:
490
+ for epoch in iterator:
491
+ losses = []
492
+ for x_batch, y_batch in train_loader:
493
+ self.train()
494
+ x_batch = x_batch.to(device)
495
+ y_batch = y_batch.to(device)
496
+
497
+ optimizer.zero_grad()
498
+ log_ps = self(x_batch)
499
+ loss = criterion(log_ps, y_batch)
500
+ loss.backward()
501
+
502
+ optimizer.step()
503
+ losses.append(loss.item())
504
+
505
+ current_loss = np.mean(losses) if losses else float("inf")
506
+ loglik = -current_loss
507
+ proj_loglik_history.append(loglik)
508
+
509
+ if prev_loglik is not None:
510
+ rel_delta = abs((loglik - prev_loglik) / (abs(prev_loglik) + 1e-9))
511
+ if rel_delta < early_stopping_min_delta:
512
+ patience_counter += 1
513
+ else:
514
+ patience_counter = 0
515
+ if progress_bar:
516
+ iterator.set_postfix({"loss": f"{current_loss:.4f}", "Δ": f"{rel_delta:.2e}"})
517
+ else:
518
+ if progress_bar:
519
+ iterator.set_postfix({"loss": f"{current_loss:.4f}"})
520
+
521
+ if patience_counter >= early_stopping_patience:
522
+ break
523
+ prev_loglik = loglik
524
+
525
+ if progress_bar:
526
+ if epoch == max_iter - 1:
527
+ tqdm.write(prefix + f"reached max_iter {max_iter}")
528
+ else:
529
+ tqdm.write(prefix + f"early stopping at epoch {epoch + 1}")
530
+
531
+ self.output.requires_grad_(True)
532
+
533
+ self.U = self.embedding.weight.data.cpu().numpy()
534
+ self.project_loglik_history_ = np.array(proj_loglik_history)
535
+ return self if return_model else self.U
536
+
537
+ def clone2vec(
538
+ clones: sc.AnnData,
539
+ z_dim: int = 10,
540
+ obsp_key: str = "gex_adjacency",
541
+ mask_key: str | None = None,
542
+ max_iter: int = 500,
543
+ learning_rate: float | None = 0.001,
544
+ device: str | None = None,
545
+ progress_bar: bool = True,
546
+ obsm_key: str = "clone2vec",
547
+ uns_key: str = "clone2vec",
548
+ random_state: None | int = 4,
549
+ init: Literal["svd", "random", "custom"] = "svd",
550
+ init_obsm: str | None = None,
551
+ batch_size: int = 128,
552
+ early_stopping_patience: int = 5,
553
+ early_stopping_min_delta: float = 1e-4,
554
+ ) -> None:
555
+ """
556
+ Learn a clonal embedding using Skip-Gram and store the embeddings.
557
+
558
+ Parameters
559
+ ----------
560
+ clones : AnnData
561
+ The clone-level AnnData object, typically from `create_clone_adata`.
562
+ z_dim : int, optional
563
+ Dimensionality of the clonal embedding, by default 10.
564
+ obsp_key : str, optional
565
+ Key in `clones.obsp` for the graph to use, by default "gex_adjacency".
566
+ max_iter : int, optional
567
+ Maximum number of iterations for optimization, by default 500.
568
+ learning_rate : float | None, optional
569
+ Learning rate for optimization, by default 0.001.
570
+ device : str | None, optional
571
+ Device to use for computation, by default None.
572
+ progress_bar : bool, optional
573
+ Whether to show a progress bar, by default True.
574
+ obsm_key : str, optional
575
+ Key in `clones.obsm` to store the embeddings, by default "c2v".
576
+ uns_key: str, optional
577
+ Key in `clones.uns` to store the results, by default "c2v".
578
+ random_state : None | int, optional
579
+ Random state for reproducibility, by default 4.
580
+ init : Literal["svd", "random", "custom"], optional
581
+ Initialization method, if "svd", uses SVD on the log1p-transformed counts, by default "svd".
582
+ init_obsm : str | None, optional
583
+ Key in `clones.obsm` for custom initialization, by default None.
584
+ batch_size : int, optional
585
+ Batch size for optimization, by default 128.
586
+ early_stopping_patience : int, optional
587
+ Number of iterations with no improvement to wait before stopping, by default 5.
588
+ early_stopping_min_delta : float, optional
589
+ Minimum change in loss to qualify as an improvement, by default 1e-4.
590
+ """
591
+ start = logg.info("fitting clone2vec embeddings")
592
+ if obsp_key not in clones.obsp:
593
+ raise KeyError(f"Graph '{obsp_key}' not found in clones.obsp.")
594
+
595
+ start_time = time.time()
596
+
597
+ init_embeddings = None
598
+ init_output_weight = None
599
+ n_clones = clones.n_obs
600
+ if init not in {"random", "custom", "svd"}:
601
+ logg.warning("init must be one of {'random', 'custom', 'svd'}. Falling back to SVD.")
602
+ init = "svd"
603
+
604
+ if init == "custom":
605
+ if init_obsm is None:
606
+ logg.warning("init_obsm must be provided when init='custom'. Falling back to SVD.")
607
+ init = "svd"
608
+ elif init_obsm not in clones.obsm:
609
+ logg.warning(f"'{init_obsm}' not found in clones.obsm. Falling back to SVD.")
610
+ init = "svd"
611
+ else:
612
+ init_embeddings = np.asarray(clones.obsm[init_obsm])
613
+ if init_embeddings.shape[0] != n_clones:
614
+ logg.warning(
615
+ f"init_obsm embeddings have {init_embeddings.shape[0]} rows, expected {n_clones}. Falling back to SVD."
616
+ )
617
+ init = "svd"
618
+ init_embeddings = None
619
+ elif init_embeddings.shape[1] != z_dim:
620
+ logg.warning(
621
+ f"init_obsm embeddings have {init_embeddings.shape[1]} dims, expected {z_dim}. Falling back to SVD."
622
+ )
623
+ init = "svd"
624
+ init_embeddings = None
625
+
626
+ # Build training matrix (optionally augmented with mask columns)
627
+ X_base = clones.obsp[obsp_key]
628
+ if mask_key is not None:
629
+ try:
630
+ M = clones.obsm[mask_key]
631
+ except KeyError:
632
+ raise KeyError(f"mask_key '{mask_key}' not found in clones.obsm.")
633
+ M_vals = M.values if isinstance(M, pd.DataFrame) else M
634
+ var_names = list(clones.obs_names) + [f"mask{i+1}" for i in range(M_vals.shape[1])]
635
+ if sp.issparse(X_base):
636
+ if sp.issparse(M_vals):
637
+ X_train = sp.hstack([X_base, M_vals]).tocsr()
638
+ else:
639
+ X_train = sp.hstack([X_base, sp.csr_matrix(M_vals)])
640
+ else:
641
+ X_train = np.hstack([np.asarray(X_base), np.asarray(M_vals)])
642
+ else:
643
+ X_train = X_base
644
+ var_names = np.array(clones.obs_names).tolist()
645
+
646
+ model = SkipGram(z_dim=z_dim, device=device)
647
+ model.fit(
648
+ X_train,
649
+ learning_rate=learning_rate,
650
+ progress_bar=progress_bar,
651
+ device=device,
652
+ random_state=random_state,
653
+ max_iter=max_iter,
654
+ init=init,
655
+ init_embeddings=init_embeddings,
656
+ init_output_weight=init_output_weight,
657
+ batch_size=batch_size,
658
+ early_stopping_patience=early_stopping_patience,
659
+ early_stopping_min_delta=early_stopping_min_delta,
660
+ )
661
+
662
+ clones.obsm[obsm_key] = model.U
663
+ clones.uns[uns_key] = {
664
+ "init": {"z_dim": model.z_dim},
665
+ "output": {
666
+ "weight": model.output.weight.detach().cpu().numpy(),
667
+ "bias": model.output.bias.detach().cpu().numpy(),
668
+ },
669
+ "var_names": np.array(var_names).copy(),
670
+ "loss_history": -model.loglik_history_,
671
+ "training_time": time.time() - start_time,
672
+ "type": "fit",
673
+ }
674
+
675
+ lines = [
676
+ "added",
677
+ f" .obsm['{obsm_key}'] embedding matrix",
678
+ f" .uns['{uns_key}'] training details",
679
+ ]
680
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
681
+
682
+ def clone2vec_Poi(
683
+ clones: sc.AnnData,
684
+ z_dim: int = 10,
685
+ obsp_key: str = "gex_adjacency",
686
+ mask_key: str | None = None,
687
+ max_iter: int = 500,
688
+ tol: float = 1e-4,
689
+ learning_rate: float | None = 0.5,
690
+ device: str | None = None,
691
+ progress_bar: bool = True,
692
+ obsm_key: str = "clone2vec_Poi",
693
+ uns_key: str = "clone2vec_Poi",
694
+ random_state: None | int = 4,
695
+ col_size_factor: bool = True,
696
+ row_intercept: bool = True,
697
+ num_ccd_iter: int = 3,
698
+ adaptive_lr: bool = True,
699
+ slowing_loglik: bool = True,
700
+ lr_decay: float = 0.5,
701
+ min_learning_rate: float = 1e-5,
702
+ max_backtracks: int = 3,
703
+ batch_size_rows: int | None = None,
704
+ batch_size_cols: int | None = None,
705
+ init: str = "svd",
706
+ ) -> None | torch.nn.Module:
707
+ """
708
+ Learn a clonal embedding using `fastglmpca` [PMID: 39110511] Python implementation
709
+ and store the embeddings. When `col_size_factor` is True and `row_intercept` is True,
710
+ the results should be comparable with the regular `clone2vec`.
711
+
712
+ Parameters
713
+ ----------
714
+ clones : AnnData
715
+ The clone-level AnnData object, typically from `create_clone_adata`.
716
+ z_dim : int, optional
717
+ Dimensionality of the clonal embedding, by default 10.
718
+ obsp_key : str, optional
719
+ Key in `clones.obsp` for the graph to use, by default "gex_adjacency".
720
+ max_iter : int, optional
721
+ Maximum number of iterations for optimization, by default 500.
722
+ tol : float, optional
723
+ Tolerance for convergence, by default 1e-4.
724
+ learning_rate : float | None, optional
725
+ Learning rate for optimization, by default 0.5.
726
+ device : str | None, optional
727
+ Device to use for computation, by default None.
728
+ progress_bar : bool, optional
729
+ Whether to show a progress bar, by default True.
730
+ obsm_key : str, optional
731
+ Key in `clones.obsm` to store the embeddings, by default "clone2vec_Poi".
732
+ uns_key: str, optional
733
+ Key in `clones.uns` to store the model parameters, by default "clone2vec_Poi".
734
+ random_state : None | int, optional
735
+ Random state for reproducibility, by default 4.
736
+ col_size_factor : bool, optional
737
+ Whether to use column size factors, by default True.
738
+ row_intercept : bool, optional
739
+ Whether to use row intercepts, by default True.
740
+ num_ccd_iter : int, optional
741
+ Number of CCD iterations, by default 3.
742
+ adaptive_lr : bool, optional
743
+ If True, reduce learning rate on log-likelihood drops. Default is True.
744
+ slowing_loglik : bool, optional
745
+ If True, adaptively reduce learning rate when log-likelihood changing rate increases. Default is True.
746
+ lr_decay : float, optional
747
+ Multiplicative decay factor applied when log-likelihood decreases. Default is 0.5.
748
+ min_learning_rate : float, optional
749
+ Minimum allowed learning rate during adaptation. Default is 1e-5.
750
+ max_backtracks : int, optional
751
+ Maximum number of backtracking retries per iteration when log-likelihood decreases. Default is 3.
752
+ batch_size_rows : int | None, optional
753
+ Batch size for rows, by default None.
754
+ batch_size_cols : int | None, optional
755
+ Batch size for columns, by default None.
756
+ init : str, optional
757
+ Initialization method, by default "svd".
758
+
759
+ Returns
760
+ -------
761
+ None | torch.nn.Module
762
+ If `return_model` is True, returns the trained model.
763
+ """
764
+ try:
765
+ import fastglmpca
766
+ except ImportError:
767
+ raise ImportError("py-fastglmpca is not installed. Please install it to use this function via `pip install fastglmpca`")
768
+
769
+ start = logg.info("fitting clone2vec_Poi embeddings")
770
+ if obsp_key not in clones.obsp:
771
+ raise KeyError(f"Graph '{obsp_key}' not found in clones.obsp. Did you run `c2v.tl.clonal_nn(adata, clones)` before?")
772
+
773
+ start_time = time.time()
774
+
775
+ if sc.settings.verbosity.value >= 2:
776
+ prefix = " "
777
+ progress_bar = True
778
+ else:
779
+ prefix = ""
780
+
781
+ def custom_tqdm(x):
782
+ class _TqdmIter:
783
+ def __init__(self, iterable, desc, file):
784
+ try:
785
+ self._tqdm = tqdm(iterable, desc=desc, file=file, leave=True)
786
+ except Exception:
787
+ self._tqdm = iterable
788
+ self._closed = False
789
+ def __iter__(self):
790
+ return iter(self._tqdm)
791
+ def set_postfix(self, *args, **kwargs):
792
+ try:
793
+ if hasattr(self._tqdm, "set_postfix"):
794
+ self._tqdm.set_postfix(*args, **kwargs)
795
+ except Exception:
796
+ pass
797
+ def close(self):
798
+ try:
799
+ if hasattr(self._tqdm, "close") and not self._closed:
800
+ self._tqdm.close()
801
+ self._closed = True
802
+ except Exception:
803
+ pass
804
+ def __del__(self):
805
+ self.close()
806
+ return _TqdmIter(x, desc=prefix + "GLM-PCA epochs", file=sys.stdout)
807
+
808
+ if progress_bar:
809
+ custom_iter = custom_tqdm
810
+ else:
811
+ custom_iter = None
812
+
813
+ # Build training matrix (optionally augmented with mask columns)
814
+ X_base = clones.obsp[obsp_key]
815
+ if mask_key is not None:
816
+ try:
817
+ M = clones.obsm[mask_key]
818
+ except KeyError:
819
+ raise KeyError(f"mask_key '{mask_key}' not found in clones.obsm.")
820
+ M_vals = M.values if isinstance(M, pd.DataFrame) else M
821
+ var_names = list(clones.obs_names) + [f"mask{i+1}" for i in range(M_vals.shape[1])]
822
+ if sp.issparse(X_base):
823
+ if sp.issparse(M_vals):
824
+ X_train = sp.hstack([X_base, M_vals]).tocsr()
825
+ else:
826
+ X_train = sp.hstack([X_base, sp.csr_matrix(M_vals)])
827
+ else:
828
+ X_train = np.hstack([np.asarray(X_base), np.asarray(M_vals)])
829
+ else:
830
+ X_train = X_base
831
+ var_names = np.array(clones.obs_names).tolist()
832
+
833
+ model = fastglmpca.poisson(
834
+ X_train,
835
+ max_iter=max_iter,
836
+ n_pcs=z_dim,
837
+ tol=tol,
838
+ return_model=True,
839
+ learning_rate=learning_rate,
840
+ progress_bar=progress_bar,
841
+ device=device,
842
+ verbose=False,
843
+ seed=random_state,
844
+ col_size_factor=col_size_factor,
845
+ row_intercept=row_intercept,
846
+ num_ccd_iter=num_ccd_iter,
847
+ adaptive_lr=adaptive_lr,
848
+ slowing_loglik=slowing_loglik,
849
+ lr_decay=lr_decay,
850
+ min_learning_rate=min_learning_rate,
851
+ max_backtracks=max_backtracks,
852
+ batch_size_rows=batch_size_rows,
853
+ batch_size_cols=batch_size_cols,
854
+ init=init,
855
+ custom_iterator=custom_iter,
856
+ )
857
+
858
+ if obsm_key in clones.obsm:
859
+ logg.warning(f"obsm_key '{obsm_key}' already exists in clones.obsm. Overwriting.")
860
+ clones.obsm[obsm_key] = model.U
861
+
862
+ if uns_key in clones.uns:
863
+ logg.warning(f"uns_key '{uns_key}' already exists in clones.uns. Overwriting.")
864
+ clones.uns[uns_key] = {
865
+ "init": {
866
+ "n_pcs": model.n_pcs,
867
+ "col_size_factor": model.col_size_factor,
868
+ "row_intercept": model.row_intercept,
869
+ "adaptive_lr": model.adaptive_lr,
870
+ "slowing_loglik": model.slowing_loglik,
871
+ "lr_decay": model.lr_decay,
872
+ "min_learning_rate": model.min_learning_rate,
873
+ "max_backtracks": model.max_backtracks,
874
+ "batch_size_rows": model.batch_size_rows,
875
+ "batch_size_cols": model.batch_size_cols,
876
+ "num_ccd_iter": model.num_ccd_iter,
877
+ },
878
+ "weights": {
879
+ "V": model.V.copy(),
880
+ "d": model.d.copy(),
881
+ "col_offset": model.col_offset.cpu().numpy().copy(),
882
+ },
883
+ "loss_history": -np.array(model.loglik_history_),
884
+ "var_names": np.array(var_names).copy(),
885
+ "training_time": time.time() - start_time,
886
+ "type": "fit",
887
+ }
888
+
889
+ if model.row_intercept:
890
+ clones.uns[uns_key]["weights"]["row_offset"] = model.row_offset.cpu().numpy().copy()
891
+
892
+ lines = [
893
+ "added",
894
+ f" .obsm['{obsm_key}'] embedding matrix",
895
+ f" .uns['{uns_key}'] training details",
896
+ ]
897
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
898
+
899
+ def project_clone2vec(
900
+ clones_query: sc.AnnData,
901
+ clones_ref: sc.AnnData,
902
+ obsm_key_query: str = "ref_gex_adjacency",
903
+ uns_key_query: str = "clone2vec",
904
+ uns_key_ref: str = "clone2vec",
905
+ obsm_key: str = "clone2vec",
906
+ mask_key: str | None = None,
907
+ random_state: int | None = 42,
908
+ batch_size: int = 128,
909
+ device: str | None = None,
910
+ learning_rate: float = 0.001,
911
+ early_stopping_patience: int = 5,
912
+ early_stopping_min_delta: float = 1e-4,
913
+ progress_bar: bool = True,
914
+ max_iter: int = 500,
915
+ ) -> None:
916
+ """
917
+ Fitting of new clones to the reference clone2vec embeddings using kNN between query and reference datasets.
918
+ The function is using output embedding from the reference clone2vec model and optimizes only input embedding matrix,
919
+ therefore has much faster convergence than training the whole model.
920
+
921
+ Parameters
922
+ ----------
923
+ clones_query : sc.AnnData
924
+ The query clone-level AnnData object, typically from `create_clone_adata`.
925
+ clones_ref : sc.AnnData
926
+ The reference clone-level AnnData object, typically from `create_clone_adata`.
927
+ obsm_key_query : str, optional
928
+ Key in `clones_query.obsm` for the graph to use, by default "ref_gex_adjacency".
929
+ uns_key_query : str, optional
930
+ Key in `clones_query.uns` to store the model parameters, by default "clone2vec".
931
+ uns_key_ref : str, optional
932
+ Key in `clones_ref.uns` to store the model parameters, by default "clone2vec".
933
+ obsm_key : str, optional
934
+ Key in `clones_query.obsm` to store the embeddings, by default "clone2vec".
935
+ random_state : None | int, optional
936
+ Random state for reproducibility, by default 42.
937
+ batch_size : int, optional
938
+ Batch size for optimization, by default 128.
939
+ device : str | None, optional
940
+ Device to use for optimization, by default None.
941
+ learning_rate : float, optional
942
+ Learning rate for optimization, by default 0.001.
943
+ early_stopping_patience : int, optional
944
+ Number of iterations with no improvement to wait before stopping, by default 5.
945
+ early_stopping_min_delta : float, optional
946
+ Minimum change in the loss to be considered as an improvement, by default 1e-4.
947
+ progress_bar : bool, optional
948
+ Whether to show a progress bar, by default True.
949
+ max_iter : int, optional
950
+ Maximum number of iterations, by default 500.
951
+ """
952
+ start = logg.info("projecting clone2vec embeddings onto reference")
953
+ start_time = time.time()
954
+
955
+ try:
956
+ params = clones_ref.uns[uns_key_ref]
957
+ except KeyError:
958
+ raise KeyError(f"clone2vec embeddings not found in clones_ref.uns['{uns_key_ref}']. Did you run `clone2vec` before?")
959
+
960
+ model = SkipGram(**params["init"], device=device)
961
+ base_out = len(clones_ref)
962
+ extra_cols = 0
963
+ if mask_key is not None:
964
+ try:
965
+ M_tmp = clones_query.obsm[mask_key]
966
+ extra_cols = (M_tmp.values if isinstance(M_tmp, pd.DataFrame) else M_tmp).shape[1]
967
+ except KeyError:
968
+ extra_cols = 0
969
+ model._initialize_or_resize_layers(len(clones_query), base_out + extra_cols)
970
+ with torch.no_grad():
971
+ model.output.weight.data[:base_out] = torch.tensor(params["output"]["weight"])
972
+ model.output.bias.data[:base_out] = torch.tensor(params["output"]["bias"])
973
+ if extra_cols > 0:
974
+ model.output.weight.data[base_out:] = 0.0
975
+ model.output.bias.data[base_out:] = 0.0
976
+
977
+ try:
978
+ nn = clones_query.obsm[obsm_key_query]
979
+ except KeyError:
980
+ raise KeyError(f"obsm_key_query '{obsm_key_query}' not found in clones_query.obsm. It should contain nearest neighbours of the query clones from the reference dataset.")
981
+
982
+ if not isinstance(nn, pd.DataFrame):
983
+ if nn.shape[1] != len(clones_ref.obs_names):
984
+ raise ValueError(f"In the case of unnamed columns, clones_query.obsm['{obsm_key_query}'] should have {len(clones_ref.obs_names)} columns, but got {nn.shape[1]}.")
985
+ logg.warning(f"clones_query.obsm['{obsm_key_query}'] contains a matrix with unnamed columns. We're assuming that the order of neighbours is the same with clones_ref.obs_names")
986
+ else:
987
+ nn = nn.reindex(columns=clones_ref.obs_names, fill_value=0).values
988
+
989
+ if mask_key is not None:
990
+ try:
991
+ M = clones_query.obsm[mask_key]
992
+ except KeyError:
993
+ raise KeyError(f"mask_key '{mask_key}' not found in clones_query.obsm.")
994
+ M_vals = M.values if isinstance(M, pd.DataFrame) else M
995
+ if sp.issparse(nn):
996
+ nn = sp.hstack([nn, sp.csr_matrix(M_vals)])
997
+ else:
998
+ nn = np.hstack([np.asarray(nn), np.asarray(M_vals)])
999
+
1000
+ if obsm_key in clones_query.obsm:
1001
+ logg.warning(f"obsm_key '{obsm_key}' already exists in clones_query.obsm. Overwriting.")
1002
+
1003
+ clones_query.obsm[obsm_key] = model.project(
1004
+ X_new=nn,
1005
+ random_state=random_state,
1006
+ batch_size=batch_size,
1007
+ device=device,
1008
+ learning_rate=learning_rate,
1009
+ early_stopping_patience=early_stopping_patience,
1010
+ early_stopping_min_delta=early_stopping_min_delta,
1011
+ progress_bar=progress_bar,
1012
+ max_iter=max_iter,
1013
+ )
1014
+
1015
+ if uns_key_query in clones_query.uns:
1016
+ logg.warning(f"uns_key_query '{uns_key_query}' already exists in clones_query.uns. Overwriting.")
1017
+
1018
+ var_names = list(clones_ref.obs_names) + ([f"mask{i+1}" for i in range(M_vals.shape[1])] if mask_key is not None else [])
1019
+ clones_query.uns[uns_key_query] = {
1020
+ "init": {"z_dim": model.z_dim},
1021
+ "loss_history": -model.project_loglik_history_,
1022
+ "training_time": time.time() - start_time,
1023
+ "type": "project",
1024
+ "var_names": np.array(var_names).copy(),
1025
+ }
1026
+ lines = [
1027
+ "added",
1028
+ f" .obsm['{obsm_key}'] projected embeddings",
1029
+ f" .uns['{uns_key_query}'] training details",
1030
+ ]
1031
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
1032
+
1033
+ def project_clone2vec_Poi(
1034
+ clones_query: sc.AnnData,
1035
+ clones_ref: sc.AnnData,
1036
+ obsm_key_query: str = "ref_gex_adjacency",
1037
+ uns_key_query: str = "clone2vec_Poi_project",
1038
+ uns_key_ref: str = "clone2vec_Poi",
1039
+ obsm_key: str = "clone2vec_Poi",
1040
+ mask_key: str | None = None,
1041
+ max_iter: int = 500,
1042
+ tol: float = 1e-4,
1043
+ device: str | None = None,
1044
+ progress_bar: bool = True,
1045
+ random_state: int | None = 42,
1046
+ init: str = "svd",
1047
+ **kwargs,
1048
+ ):
1049
+ """
1050
+ Fitting of new clones to the reference clone2vec Poisson embeddings using kNN between query and reference datasets.
1051
+ The function is using output embedding from the reference clone2vec model and optimizes only input embedding matrix,
1052
+ therefore has much faster convergence than training the whole model.
1053
+
1054
+ Parameters
1055
+ ----------
1056
+ clones_query : AnnData
1057
+ The query clone-level AnnData object, typically from `create_clone_adata`.
1058
+ clones_ref : AnnData
1059
+ The reference clone-level AnnData object, typically from `create_clone_adata`.
1060
+ obsm_key_query : str, optional
1061
+ Key in `clones_query.obsm` for the graph to use, by default "ref_gex_adjacency".
1062
+ uns_key_query : str, optional
1063
+ Key in `clones_query.uns` to store the model parameters, by default "clone2vec".
1064
+ uns_key_ref : str, optional
1065
+ Key in `clones_ref.uns` to store the model parameters, by default "clone2vec".
1066
+ obsm_key : str, optional
1067
+ Key in `clones_query.obsm` to store the embeddings, by default "clone2vec".
1068
+ max_iter : int, optional
1069
+ Maximum number of iterations, by default 500.
1070
+ tol : float, optional
1071
+ Tolerance for convergence, by default 1e-4.
1072
+ device : str | None, optional
1073
+ Device to use for optimization, by default None.
1074
+ progress_bar : bool, optional
1075
+ Whether to show a progress bar, by default True.
1076
+ random_state : None | int, optional
1077
+ Random state for reproducibility, by default 42.
1078
+ init : str, optional
1079
+ Initialization method for the model, by default "svd".
1080
+ **kwargs
1081
+ Additional keyword arguments for the model.
1082
+ """
1083
+ try:
1084
+ import fastglmpca
1085
+ except ImportError:
1086
+ raise ImportError("py-fastglmpca is not installed. Please install it to use this function via `pip install fastglmpca`")
1087
+
1088
+ start = logg.info("projecting clone2vec_Poi embeddings onto reference")
1089
+ start_time = time.time()
1090
+
1091
+ try:
1092
+ params = clones_ref.uns[uns_key_ref]
1093
+ except KeyError:
1094
+ raise KeyError(f"clone2vec_Poi embeddings not found in clones_ref.uns['{uns_key_ref}']. Did you run `clone2vec_Poi` before?")
1095
+
1096
+ model = fastglmpca.PoissonGLMPCA(**params["init"], device=device)
1097
+ base_out = params["weights"]["V"].shape[0]
1098
+ extra_cols = 0
1099
+ model.V = params["weights"]["V"].copy()
1100
+ model.d = params["weights"]["d"].copy()
1101
+ if mask_key is not None:
1102
+ try:
1103
+ M_tmp = clones_query.obsm[mask_key]
1104
+ extra_cols = (M_tmp.values if isinstance(M_tmp, pd.DataFrame) else M_tmp).shape[1]
1105
+ except KeyError:
1106
+ extra_cols = 0
1107
+ if extra_cols > 0:
1108
+ model.V = np.vstack([model.V, np.zeros((extra_cols, model.V.shape[1]), dtype=model.V.dtype)])
1109
+ model.d = np.concatenate([model.d, np.zeros(extra_cols, dtype=model.d.dtype)])
1110
+ model.col_offset = params["weights"]["col_offset"]
1111
+ if "row_offset" in params["weights"]:
1112
+ model.row_offset = params["weights"]["row_offset"]
1113
+
1114
+ try:
1115
+ nn = clones_query.obsm[obsm_key_query]
1116
+ except KeyError:
1117
+ raise KeyError(f"obsm_key_query '{obsm_key_query}' not found in clones_query.obsm. It should contain nearest neighbours of the query clones from the reference dataset.")
1118
+
1119
+ if not isinstance(nn, pd.DataFrame):
1120
+ if nn.shape[1] != len(clones_ref.obs_names):
1121
+ raise ValueError(f"In the case of unnamed columns, clones_query.obsm['{obsm_key_query}'] should have {len(clones_ref.obs_names)} columns, but got {nn.shape[1]}.")
1122
+ logg.warning(f"clones_query.obsm['{obsm_key_query}'] contains a matrix with unnamed columns. We're assuming that the order of neighbours is the same with clones_ref.obs_names")
1123
+ else:
1124
+ nn = nn.reindex(columns=clones_ref.obs_names, fill_value=0).values
1125
+
1126
+ if mask_key is not None:
1127
+ try:
1128
+ M = clones_query.obsm[mask_key]
1129
+ except KeyError:
1130
+ raise KeyError(f"mask_key '{mask_key}' not found in clones_query.obsm.")
1131
+ M_vals = M.values if isinstance(M, pd.DataFrame) else M
1132
+ if sp.issparse(nn):
1133
+ nn = sp.hstack([nn, sp.csr_matrix(M_vals)])
1134
+ else:
1135
+ nn = np.hstack([np.asarray(nn), np.asarray(M_vals)])
1136
+
1137
+ if obsm_key in clones_query.obsm:
1138
+ logg.warning(f"obsm_key '{obsm_key}' already exists in clones_query.obsm. Overwriting.")
1139
+
1140
+ if sc.settings.verbosity.value >= 2:
1141
+ prefix = " "
1142
+ progress_bar = True
1143
+ else:
1144
+ prefix = ""
1145
+
1146
+ def custom_tqdm(x):
1147
+ class _TqdmIter:
1148
+ def __init__(self, iterable, desc, file):
1149
+ try:
1150
+ self._tqdm = tqdm(iterable, desc=desc, file=file, leave=True)
1151
+ except Exception:
1152
+ self._tqdm = iterable
1153
+ self._closed = False
1154
+ def __iter__(self):
1155
+ return iter(self._tqdm)
1156
+ def set_postfix(self, *args, **kwargs):
1157
+ try:
1158
+ if hasattr(self._tqdm, "set_postfix"):
1159
+ self._tqdm.set_postfix(*args, **kwargs)
1160
+ except Exception:
1161
+ pass
1162
+ def close(self):
1163
+ try:
1164
+ if hasattr(self._tqdm, "close") and not self._closed:
1165
+ self._tqdm.close()
1166
+ self._closed = True
1167
+ except Exception:
1168
+ pass
1169
+ def __del__(self):
1170
+ self.close()
1171
+ return _TqdmIter(x, desc=prefix + "GLM-PCA epochs", file=sys.stdout)
1172
+
1173
+ if progress_bar:
1174
+ custom_iter = custom_tqdm
1175
+ else:
1176
+ custom_iter = None
1177
+
1178
+ clones_query.obsm[obsm_key] = model.project(
1179
+ nn,
1180
+ max_iter=max_iter,
1181
+ tol=tol,
1182
+ progress_bar=progress_bar,
1183
+ init=init,
1184
+ seed=random_state,
1185
+ custom_iterator=custom_iter,
1186
+ )
1187
+
1188
+ if uns_key_query in clones_query.uns:
1189
+ logg.warning(f"uns_key_query '{uns_key_query}' already exists in clones_query.uns. Overwriting.")
1190
+
1191
+ var_names = list(clones_ref.obs_names) + ([f"mask{i+1}" for i in range(M_vals.shape[1])] if mask_key is not None else [])
1192
+ clones_query.uns[uns_key_query] = {
1193
+ "init": {"n_pcs": model.n_pcs},
1194
+ "loss_history": -np.array(model.project_loglik_history_),
1195
+ "training_time": time.time() - start_time,
1196
+ "type": "project",
1197
+ "var_names": np.array(var_names).copy(),
1198
+ }
1199
+ lines = [
1200
+ "added",
1201
+ f" .obsm['{obsm_key}'] projected embeddings",
1202
+ f" .uns['{uns_key_query}'] training details",
1203
+ ]
1204
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)