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.
- clone2vec/__init__.py +23 -0
- clone2vec/associations.py +1117 -0
- clone2vec/catboost.py +622 -0
- clone2vec/datasets.py +94 -0
- clone2vec/eigenvalues.py +187 -0
- clone2vec/embeddings.py +1204 -0
- clone2vec/integration.py +511 -0
- clone2vec/plotting.py +3540 -0
- clone2vec/preprocessing.py +660 -0
- clone2vec/seurat.py +720 -0
- clone2vec/tools.py +633 -0
- clone2vec/utils.py +618 -0
- clone2vec-0.1.0.dist-info/METADATA +86 -0
- clone2vec-0.1.0.dist-info/RECORD +16 -0
- clone2vec-0.1.0.dist-info/WHEEL +5 -0
- clone2vec-0.1.0.dist-info/top_level.txt +1 -0
clone2vec/embeddings.py
ADDED
|
@@ -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)
|