iaode 0.2.1__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.
- iaode/BEN.py +438 -0
- iaode/DRE.py +430 -0
- iaode/LSE.py +635 -0
- iaode/__init__.py +103 -0
- iaode/agent.py +850 -0
- iaode/annotation.py +592 -0
- iaode/datasets.py +330 -0
- iaode/environment.py +298 -0
- iaode/mixin.py +359 -0
- iaode/model.py +486 -0
- iaode/module.py +576 -0
- iaode/utils.py +327 -0
- iaode-0.2.1.dist-info/METADATA +697 -0
- iaode-0.2.1.dist-info/RECORD +17 -0
- iaode-0.2.1.dist-info/WHEEL +5 -0
- iaode-0.2.1.dist-info/licenses/LICENSE +21 -0
- iaode-0.2.1.dist-info/top_level.txt +1 -0
iaode/LSE.py
ADDED
|
@@ -0,0 +1,635 @@
|
|
|
1
|
+
import numpy as np
|
|
2
|
+
import pandas as pd
|
|
3
|
+
from sklearn.decomposition import PCA
|
|
4
|
+
from scipy.stats import entropy, skew, kurtosis
|
|
5
|
+
from scipy.linalg import svd, norm
|
|
6
|
+
import warnings
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class SingleCellLatentSpaceEvaluator:
|
|
10
|
+
"""
|
|
11
|
+
Latent space quality evaluator tailored to single-cell data.
|
|
12
|
+
|
|
13
|
+
Especially suitable for:
|
|
14
|
+
- Single-cell trajectory data (development, differentiation, etc.)
|
|
15
|
+
- Single-cell steady-state population data
|
|
16
|
+
- Time-series single-cell data
|
|
17
|
+
|
|
18
|
+
Key properties:
|
|
19
|
+
- Metric interpretations adapted for trajectory data
|
|
20
|
+
- Low isotropy = good (strong directionality)
|
|
21
|
+
- Low participation ratio = good (information concentration)
|
|
22
|
+
- High spectral decay = good (dimensional efficiency)
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
def __init__(self, data_type="trajectory", verbose=True):
|
|
26
|
+
"""
|
|
27
|
+
Initialize the evaluator.
|
|
28
|
+
|
|
29
|
+
Args:
|
|
30
|
+
data_type: "trajectory" or "steady_state"
|
|
31
|
+
verbose: whether to print detailed logs
|
|
32
|
+
"""
|
|
33
|
+
self.data_type = data_type
|
|
34
|
+
self.verbose = verbose
|
|
35
|
+
|
|
36
|
+
# Adjust preferences according to data type
|
|
37
|
+
if data_type == "trajectory":
|
|
38
|
+
self.isotropy_preference = "low" # trajectories prefer low isotropy
|
|
39
|
+
self.participation_preference = "low" # trajectories prefer low participation ratio
|
|
40
|
+
else: # steady_state
|
|
41
|
+
self.isotropy_preference = "high" # steady state prefers high isotropy
|
|
42
|
+
self.participation_preference = "high" # steady state prefers high participation ratio
|
|
43
|
+
|
|
44
|
+
def _log(self, message):
|
|
45
|
+
if self.verbose:
|
|
46
|
+
print(message)
|
|
47
|
+
|
|
48
|
+
# ==================== 1. Refined manifold dimensionality consistency ====================
|
|
49
|
+
|
|
50
|
+
def manifold_dimensionality_score_v2(self, latent_space,
|
|
51
|
+
variance_thresholds=[0.8, 0.9, 0.95],
|
|
52
|
+
use_multiple_methods=True):
|
|
53
|
+
"""
|
|
54
|
+
Refined manifold dimensionality consistency metric.
|
|
55
|
+
Fixes the issue in the original version where all methods yielded the same score.
|
|
56
|
+
|
|
57
|
+
Args:
|
|
58
|
+
latent_space: latent coordinates
|
|
59
|
+
variance_thresholds: list of variance thresholds
|
|
60
|
+
use_multiple_methods: whether to combine multiple methods
|
|
61
|
+
|
|
62
|
+
Returns:
|
|
63
|
+
float: dimensional efficiency score (0–1)
|
|
64
|
+
"""
|
|
65
|
+
try:
|
|
66
|
+
if latent_space.shape[1] == 1:
|
|
67
|
+
return 1.0
|
|
68
|
+
|
|
69
|
+
# Center data
|
|
70
|
+
centered_data = latent_space - np.mean(latent_space, axis=0)
|
|
71
|
+
|
|
72
|
+
# PCA
|
|
73
|
+
pca = PCA().fit(centered_data)
|
|
74
|
+
explained_variance_ratio = pca.explained_variance_ratio_
|
|
75
|
+
explained_variance = pca.explained_variance_
|
|
76
|
+
|
|
77
|
+
dimension_scores = []
|
|
78
|
+
|
|
79
|
+
# Method 1: multi-threshold dimensional efficiency
|
|
80
|
+
for threshold in variance_thresholds:
|
|
81
|
+
cumsum = np.cumsum(explained_variance_ratio)
|
|
82
|
+
effective_dims = np.where(cumsum >= threshold)[0]
|
|
83
|
+
|
|
84
|
+
if len(effective_dims) > 0:
|
|
85
|
+
effective_dim = effective_dims[0] + 1
|
|
86
|
+
# Fewer dimensions to reach the threshold = higher efficiency
|
|
87
|
+
efficiency = 1.0 - (effective_dim - 1) / (latent_space.shape[1] - 1)
|
|
88
|
+
dimension_scores.append(efficiency)
|
|
89
|
+
|
|
90
|
+
# Method 2: Kaiser criterion efficiency
|
|
91
|
+
normalized_eigenvalues = explained_variance / np.mean(explained_variance)
|
|
92
|
+
kaiser_dim = np.sum(normalized_eigenvalues > 1.0)
|
|
93
|
+
kaiser_efficiency = 1.0 - (kaiser_dim - 1) / (latent_space.shape[1] - 1)
|
|
94
|
+
|
|
95
|
+
# Method 3: elbow method
|
|
96
|
+
if len(explained_variance) > 2:
|
|
97
|
+
ratios = explained_variance[:-1] / explained_variance[1:]
|
|
98
|
+
elbow_dim = np.argmax(ratios) + 1
|
|
99
|
+
elbow_efficiency = 1.0 - (elbow_dim - 1) / (latent_space.shape[1] - 1)
|
|
100
|
+
else:
|
|
101
|
+
elbow_efficiency = 1.0
|
|
102
|
+
|
|
103
|
+
# Method 4: spectral decay
|
|
104
|
+
if len(explained_variance) > 1:
|
|
105
|
+
log_eigenvals = np.log(explained_variance + 1e-10)
|
|
106
|
+
x = np.arange(len(log_eigenvals))
|
|
107
|
+
|
|
108
|
+
if len(x) > 1:
|
|
109
|
+
slope = np.polyfit(x, log_eigenvals, 1)[0]
|
|
110
|
+
# More negative slope => faster decay => stronger concentration
|
|
111
|
+
decay_score = 1.0 / (1.0 + np.exp(slope))
|
|
112
|
+
else:
|
|
113
|
+
decay_score = 0.5
|
|
114
|
+
else:
|
|
115
|
+
decay_score = 0.5
|
|
116
|
+
|
|
117
|
+
# Aggregate score
|
|
118
|
+
if use_multiple_methods:
|
|
119
|
+
all_scores = dimension_scores + [kaiser_efficiency, elbow_efficiency, decay_score]
|
|
120
|
+
final_score = np.mean([s for s in all_scores if s is not None])
|
|
121
|
+
else:
|
|
122
|
+
final_score = np.mean(dimension_scores) if dimension_scores else 0.5
|
|
123
|
+
|
|
124
|
+
return np.clip(final_score, 0.0, 1.0)
|
|
125
|
+
|
|
126
|
+
except Exception as e:
|
|
127
|
+
warnings.warn(f"Error computing manifold dimensionality consistency: {e}")
|
|
128
|
+
return 0.5
|
|
129
|
+
|
|
130
|
+
# ==================== 2. Intrinsic efficiency metrics ====================
|
|
131
|
+
|
|
132
|
+
def spectral_decay_rate(self, latent_space):
|
|
133
|
+
"""Spectral decay rate — higher means better concentration across dimensions."""
|
|
134
|
+
try:
|
|
135
|
+
centered_data = latent_space - np.mean(latent_space, axis=0)
|
|
136
|
+
U, s, Vt = svd(centered_data, full_matrices=False)
|
|
137
|
+
eigenvalues = s**2 / (len(latent_space) - 1)
|
|
138
|
+
|
|
139
|
+
if len(eigenvalues) < 2:
|
|
140
|
+
return 1.0
|
|
141
|
+
|
|
142
|
+
# Fit exponential decay in log space
|
|
143
|
+
log_eigenvals = np.log(eigenvalues + 1e-10)
|
|
144
|
+
x = np.arange(len(log_eigenvals))
|
|
145
|
+
|
|
146
|
+
slope, _ = np.polyfit(x, log_eigenvals, 1)
|
|
147
|
+
normalized_decay = 1.0 / (1.0 + np.exp(slope))
|
|
148
|
+
|
|
149
|
+
# Concentration of the first eigenvalue
|
|
150
|
+
concentration = eigenvalues[0] / np.sum(eigenvalues)
|
|
151
|
+
|
|
152
|
+
# Combined score
|
|
153
|
+
spectral_score = 0.6 * normalized_decay + 0.4 * concentration
|
|
154
|
+
|
|
155
|
+
return np.clip(spectral_score, 0.0, 1.0)
|
|
156
|
+
|
|
157
|
+
except Exception as e:
|
|
158
|
+
warnings.warn(f"Error computing spectral decay rate: {e}")
|
|
159
|
+
return 0.5
|
|
160
|
+
|
|
161
|
+
def participation_ratio_score(self, latent_space):
|
|
162
|
+
"""
|
|
163
|
+
Participation ratio score.
|
|
164
|
+
|
|
165
|
+
For trajectory data: lower is better (information more concentrated).
|
|
166
|
+
For steady-state data: higher is better (more even spread).
|
|
167
|
+
"""
|
|
168
|
+
try:
|
|
169
|
+
centered_data = latent_space - np.mean(latent_space, axis=0)
|
|
170
|
+
cov_matrix = np.cov(centered_data.T)
|
|
171
|
+
eigenvalues = np.linalg.eigvals(cov_matrix)
|
|
172
|
+
eigenvalues = np.real(eigenvalues)
|
|
173
|
+
eigenvalues = eigenvalues[eigenvalues > 1e-10]
|
|
174
|
+
|
|
175
|
+
if len(eigenvalues) == 0:
|
|
176
|
+
return 0.0
|
|
177
|
+
|
|
178
|
+
# Participation ratio
|
|
179
|
+
sum_eigenvals = np.sum(eigenvalues)
|
|
180
|
+
sum_eigenvals_squared = np.sum(eigenvalues**2)
|
|
181
|
+
|
|
182
|
+
if sum_eigenvals_squared > 0:
|
|
183
|
+
participation_ratio = sum_eigenvals**2 / sum_eigenvals_squared
|
|
184
|
+
max_participation = len(eigenvalues)
|
|
185
|
+
normalized_pr = participation_ratio / max_participation
|
|
186
|
+
else:
|
|
187
|
+
normalized_pr = 0.0
|
|
188
|
+
|
|
189
|
+
# Adjust according to data type
|
|
190
|
+
if self.participation_preference == "low":
|
|
191
|
+
# trajectories prefer low participation
|
|
192
|
+
score = 1.0 - normalized_pr
|
|
193
|
+
else:
|
|
194
|
+
# steady state prefers high participation
|
|
195
|
+
score = normalized_pr
|
|
196
|
+
|
|
197
|
+
return np.clip(score, 0.0, 1.0)
|
|
198
|
+
|
|
199
|
+
except Exception as e:
|
|
200
|
+
warnings.warn(f"Error computing participation ratio: {e}")
|
|
201
|
+
return 0.5
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def isotropy_anisotropy_score(self, latent_space):
|
|
205
|
+
"""
|
|
206
|
+
Isotropy/anisotropy score (enhanced version).
|
|
207
|
+
|
|
208
|
+
For trajectory data: low isotropy (high anisotropy) is better (strong directionality).
|
|
209
|
+
For steady-state data: high isotropy is better (uniform spreading).
|
|
210
|
+
|
|
211
|
+
Enhancements:
|
|
212
|
+
- Log transforms for higher sensitivity and reduced saturation
|
|
213
|
+
- Multiple complementary measures to improve discriminability
|
|
214
|
+
- Adaptive sensitivity via nonlinear mappings
|
|
215
|
+
"""
|
|
216
|
+
try:
|
|
217
|
+
centered_data = latent_space - np.mean(latent_space, axis=0)
|
|
218
|
+
cov_matrix = np.cov(centered_data.T)
|
|
219
|
+
eigenvalues = np.linalg.eigvals(cov_matrix)
|
|
220
|
+
eigenvalues = np.real(eigenvalues)
|
|
221
|
+
eigenvalues = eigenvalues[eigenvalues > 1e-12]
|
|
222
|
+
|
|
223
|
+
if len(eigenvalues) < 2:
|
|
224
|
+
return 1.0
|
|
225
|
+
|
|
226
|
+
eigenvalues = np.sort(eigenvalues)[::-1]
|
|
227
|
+
|
|
228
|
+
# Method 1: log-ellipticity (mitigates saturation)
|
|
229
|
+
log_ellipticity = np.log(eigenvalues[0]) - np.log(eigenvalues[-1] + 1e-12)
|
|
230
|
+
enhanced_ellipticity = np.tanh(log_ellipticity / 4.0)
|
|
231
|
+
|
|
232
|
+
# Method 2: multi-level condition numbers
|
|
233
|
+
condition_ratios = []
|
|
234
|
+
for i in range(len(eigenvalues) - 1):
|
|
235
|
+
ratio = eigenvalues[i] / (eigenvalues[i + 1] + 1e-12)
|
|
236
|
+
condition_ratios.append(np.log(ratio))
|
|
237
|
+
|
|
238
|
+
mean_log_condition = np.mean(condition_ratios)
|
|
239
|
+
enhanced_condition = np.tanh(mean_log_condition / 2.0)
|
|
240
|
+
|
|
241
|
+
# Method 3: variance of adjacent ratios
|
|
242
|
+
ratios = eigenvalues[:-1] / (eigenvalues[1:] + 1e-12)
|
|
243
|
+
ratio_variance = np.var(np.log(ratios))
|
|
244
|
+
ratio_anisotropy = np.tanh(ratio_variance)
|
|
245
|
+
|
|
246
|
+
# Method 4: entropy-based anisotropy
|
|
247
|
+
eigenval_probs = eigenvalues / np.sum(eigenvalues)
|
|
248
|
+
eigenval_entropy = -np.sum(eigenval_probs * np.log(eigenval_probs + 1e-12))
|
|
249
|
+
max_entropy = np.log(len(eigenvalues))
|
|
250
|
+
entropy_isotropy = eigenval_entropy / max_entropy if max_entropy > 0 else 0
|
|
251
|
+
entropy_anisotropy = 1.0 - entropy_isotropy
|
|
252
|
+
|
|
253
|
+
# Method 5: dominance of the first principal component
|
|
254
|
+
primary_dominance = (
|
|
255
|
+
eigenvalues[0] / np.sum(eigenvalues[1:]) if len(eigenvalues) > 1 else 1
|
|
256
|
+
)
|
|
257
|
+
dominance_anisotropy = np.tanh(np.log(primary_dominance + 1) / 2.0)
|
|
258
|
+
|
|
259
|
+
# Method 6: inverse effective dimensionality
|
|
260
|
+
participation_ratio = (np.sum(eigenvalues)**2) / np.sum(eigenvalues**2)
|
|
261
|
+
effective_dim_anisotropy = 1.0 - (participation_ratio / len(eigenvalues))
|
|
262
|
+
|
|
263
|
+
# Weighted combination
|
|
264
|
+
anisotropy_components = [
|
|
265
|
+
enhanced_ellipticity * 0.25,
|
|
266
|
+
enhanced_condition * 0.25,
|
|
267
|
+
ratio_anisotropy * 0.20,
|
|
268
|
+
entropy_anisotropy * 0.15,
|
|
269
|
+
dominance_anisotropy * 0.10,
|
|
270
|
+
effective_dim_anisotropy * 0.05,
|
|
271
|
+
]
|
|
272
|
+
|
|
273
|
+
weighted_anisotropy = np.sum(anisotropy_components)
|
|
274
|
+
|
|
275
|
+
# Adjust based on data type
|
|
276
|
+
if self.isotropy_preference == "low":
|
|
277
|
+
# trajectories favor high anisotropy
|
|
278
|
+
score = weighted_anisotropy
|
|
279
|
+
else:
|
|
280
|
+
# steady state favors low anisotropy (high isotropy)
|
|
281
|
+
score = 1.0 - weighted_anisotropy
|
|
282
|
+
|
|
283
|
+
return np.clip(score, 0.0, 1.0)
|
|
284
|
+
|
|
285
|
+
except Exception as e:
|
|
286
|
+
warnings.warn(f"Error in isotropy/anisotropy analysis: {e}")
|
|
287
|
+
return 0.5
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
# ==================== 3. Single-cell–specific metrics ====================
|
|
291
|
+
|
|
292
|
+
def trajectory_directionality_score(self, latent_space):
|
|
293
|
+
"""
|
|
294
|
+
Trajectory directionality score.
|
|
295
|
+
Quantifies how strongly a dominant developmental axis is expressed.
|
|
296
|
+
"""
|
|
297
|
+
try:
|
|
298
|
+
pca = PCA()
|
|
299
|
+
pca.fit(latent_space)
|
|
300
|
+
explained_var = pca.explained_variance_ratio_
|
|
301
|
+
|
|
302
|
+
if len(explained_var) >= 2:
|
|
303
|
+
main_dominance = explained_var[0]
|
|
304
|
+
|
|
305
|
+
other_variance = np.sum(explained_var[1:])
|
|
306
|
+
if other_variance > 1e-10:
|
|
307
|
+
dominance_ratio = explained_var[0] / other_variance
|
|
308
|
+
directionality = dominance_ratio / (1.0 + dominance_ratio)
|
|
309
|
+
else:
|
|
310
|
+
directionality = 1.0
|
|
311
|
+
else:
|
|
312
|
+
directionality = 1.0
|
|
313
|
+
|
|
314
|
+
return np.clip(directionality, 0.0, 1.0)
|
|
315
|
+
|
|
316
|
+
except Exception as e:
|
|
317
|
+
warnings.warn(f"Error computing trajectory directionality: {e}")
|
|
318
|
+
return 0.5
|
|
319
|
+
|
|
320
|
+
def noise_resilience_score(self, latent_space):
|
|
321
|
+
"""
|
|
322
|
+
Noise resilience score.
|
|
323
|
+
Assesses how well the latent space filters out technical noise.
|
|
324
|
+
"""
|
|
325
|
+
try:
|
|
326
|
+
pca = PCA()
|
|
327
|
+
pca.fit(latent_space)
|
|
328
|
+
explained_variance = pca.explained_variance_
|
|
329
|
+
|
|
330
|
+
if len(explained_variance) > 1:
|
|
331
|
+
signal_variance = np.sum(explained_variance[:2]) # first two PCs
|
|
332
|
+
noise_variance = np.sum(explained_variance[2:]) if len(explained_variance) > 2 else 0
|
|
333
|
+
|
|
334
|
+
if noise_variance > 1e-10:
|
|
335
|
+
snr = signal_variance / noise_variance
|
|
336
|
+
noise_resilience = min(snr / 10.0, 1.0) # normalized
|
|
337
|
+
else:
|
|
338
|
+
noise_resilience = 1.0
|
|
339
|
+
else:
|
|
340
|
+
noise_resilience = 1.0
|
|
341
|
+
|
|
342
|
+
return np.clip(noise_resilience, 0.0, 1.0)
|
|
343
|
+
|
|
344
|
+
except Exception as e:
|
|
345
|
+
warnings.warn(f"Error computing noise resilience: {e}")
|
|
346
|
+
return 0.5
|
|
347
|
+
|
|
348
|
+
# ==================== 4. Comprehensive evaluation framework ====================
|
|
349
|
+
|
|
350
|
+
def comprehensive_evaluation(self, latent_space):
|
|
351
|
+
"""
|
|
352
|
+
Comprehensive latent space evaluation for single-cell data.
|
|
353
|
+
|
|
354
|
+
Args:
|
|
355
|
+
latent_space: latent coordinates
|
|
356
|
+
|
|
357
|
+
Returns:
|
|
358
|
+
dict: full set of evaluation results
|
|
359
|
+
"""
|
|
360
|
+
|
|
361
|
+
self._log(f"Starting comprehensive evaluation for single-cell data ({self.data_type})...")
|
|
362
|
+
|
|
363
|
+
results = {}
|
|
364
|
+
|
|
365
|
+
# 1. Core manifold metrics
|
|
366
|
+
self._log("Computing manifold dimensionality metrics...")
|
|
367
|
+
results['manifold_dimensionality'] = self.manifold_dimensionality_score_v2(latent_space)
|
|
368
|
+
|
|
369
|
+
# 2. Spectral metrics
|
|
370
|
+
self._log("Computing spectral metrics...")
|
|
371
|
+
results['spectral_decay_rate'] = self.spectral_decay_rate(latent_space)
|
|
372
|
+
results['participation_ratio'] = self.participation_ratio_score(latent_space)
|
|
373
|
+
results['anisotropy_score'] = self.isotropy_anisotropy_score(latent_space)
|
|
374
|
+
|
|
375
|
+
# 3. Single-cell–specific metrics
|
|
376
|
+
self._log("Computing single-cell–specific metrics...")
|
|
377
|
+
results['trajectory_directionality'] = self.trajectory_directionality_score(latent_space)
|
|
378
|
+
|
|
379
|
+
# 4. Technical quality metrics
|
|
380
|
+
self._log("Computing technical quality metrics...")
|
|
381
|
+
results['noise_resilience'] = self.noise_resilience_score(latent_space)
|
|
382
|
+
|
|
383
|
+
# 5. Aggregate scores
|
|
384
|
+
self._log("Computing aggregate scores...")
|
|
385
|
+
|
|
386
|
+
core_metrics = [
|
|
387
|
+
results['manifold_dimensionality'],
|
|
388
|
+
results['spectral_decay_rate'],
|
|
389
|
+
results['participation_ratio'],
|
|
390
|
+
results['anisotropy_score'],
|
|
391
|
+
]
|
|
392
|
+
results['core_quality'] = np.mean(core_metrics)
|
|
393
|
+
|
|
394
|
+
if self.data_type == "trajectory":
|
|
395
|
+
# Trajectories: emphasize directionality
|
|
396
|
+
final_components = [
|
|
397
|
+
results['core_quality'] * 0.5,
|
|
398
|
+
results['trajectory_directionality'] * 0.3,
|
|
399
|
+
results['noise_resilience'] * 0.2,
|
|
400
|
+
]
|
|
401
|
+
else:
|
|
402
|
+
# Steady state: emphasize core manifold quality
|
|
403
|
+
final_components = [
|
|
404
|
+
results['core_quality'] * 0.7,
|
|
405
|
+
results['noise_resilience'] * 0.3,
|
|
406
|
+
]
|
|
407
|
+
|
|
408
|
+
results['overall_quality'] = np.sum(final_components)
|
|
409
|
+
|
|
410
|
+
# Add interpretation
|
|
411
|
+
results['data_type'] = self.data_type
|
|
412
|
+
results['interpretation'] = self._generate_interpretation(results)
|
|
413
|
+
|
|
414
|
+
if self.verbose:
|
|
415
|
+
self._print_comprehensive_results(results)
|
|
416
|
+
|
|
417
|
+
return results
|
|
418
|
+
|
|
419
|
+
def _generate_interpretation(self, results):
|
|
420
|
+
"""Generate a qualitative interpretation of the results."""
|
|
421
|
+
|
|
422
|
+
interpretation = {
|
|
423
|
+
'quality_level': '',
|
|
424
|
+
'strengths': [],
|
|
425
|
+
'weaknesses': [],
|
|
426
|
+
'recommendations': [],
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
overall = results['overall_quality']
|
|
430
|
+
|
|
431
|
+
# Quality level
|
|
432
|
+
if overall >= 0.8:
|
|
433
|
+
interpretation['quality_level'] = "Excellent"
|
|
434
|
+
elif overall >= 0.6:
|
|
435
|
+
interpretation['quality_level'] = "Good"
|
|
436
|
+
elif overall >= 0.4:
|
|
437
|
+
interpretation['quality_level'] = "Fair"
|
|
438
|
+
else:
|
|
439
|
+
interpretation['quality_level'] = "Needs improvement"
|
|
440
|
+
|
|
441
|
+
thresholds = {'high': 0.7, 'medium': 0.5, 'low': 0.3}
|
|
442
|
+
|
|
443
|
+
# Strengths
|
|
444
|
+
if results['manifold_dimensionality'] > thresholds['high']:
|
|
445
|
+
interpretation['strengths'].append("High dimensional compression efficiency")
|
|
446
|
+
|
|
447
|
+
if results['spectral_decay_rate'] > thresholds['high']:
|
|
448
|
+
interpretation['strengths'].append("Strong eigenvalue decay")
|
|
449
|
+
|
|
450
|
+
if results['anisotropy_score'] > thresholds['high']:
|
|
451
|
+
if self.data_type == "trajectory":
|
|
452
|
+
interpretation['strengths'].append("Strong trajectory directionality")
|
|
453
|
+
else:
|
|
454
|
+
interpretation['strengths'].append("Uniform spatial distribution")
|
|
455
|
+
|
|
456
|
+
if results['participation_ratio'] > thresholds['high']:
|
|
457
|
+
if self.data_type == "trajectory":
|
|
458
|
+
interpretation['strengths'].append("High information concentration")
|
|
459
|
+
else:
|
|
460
|
+
interpretation['strengths'].append("Balanced use of dimensions")
|
|
461
|
+
|
|
462
|
+
if results['trajectory_directionality'] > thresholds['high']:
|
|
463
|
+
interpretation['strengths'].append("Clear dominant developmental axis")
|
|
464
|
+
|
|
465
|
+
# Weaknesses
|
|
466
|
+
if results['noise_resilience'] < thresholds['medium']:
|
|
467
|
+
interpretation['weaknesses'].append("Insufficient noise filtering")
|
|
468
|
+
|
|
469
|
+
if results['trajectory_directionality'] < thresholds['medium']:
|
|
470
|
+
interpretation['weaknesses'].append("Dominant developmental axis is weak")
|
|
471
|
+
|
|
472
|
+
if results['core_quality'] < thresholds['medium']:
|
|
473
|
+
interpretation['weaknesses'].append("Low core manifold quality")
|
|
474
|
+
|
|
475
|
+
# Recommendations
|
|
476
|
+
if overall < 0.6:
|
|
477
|
+
interpretation['recommendations'].append("Consider adjusting dimensionality reduction parameters")
|
|
478
|
+
interpretation['recommendations'].append("Add or refine preprocessing steps")
|
|
479
|
+
|
|
480
|
+
if results['noise_resilience'] < 0.4:
|
|
481
|
+
interpretation['recommendations'].append("Strengthen noise filtering")
|
|
482
|
+
|
|
483
|
+
if self.data_type == "trajectory" and results['trajectory_directionality'] < 0.5:
|
|
484
|
+
interpretation['recommendations'].append("Optimize preservation of trajectory directionality")
|
|
485
|
+
|
|
486
|
+
return interpretation
|
|
487
|
+
|
|
488
|
+
def _print_comprehensive_results(self, results):
|
|
489
|
+
"""Print human-readable summary of the evaluation."""
|
|
490
|
+
|
|
491
|
+
print("\n" + "=" * 80)
|
|
492
|
+
print(f" Single-cell ({self.data_type.upper()}) Latent Space Quality Evaluation")
|
|
493
|
+
print("=" * 80)
|
|
494
|
+
|
|
495
|
+
# Core metrics
|
|
496
|
+
print(f"\n[Core Manifold Metrics]")
|
|
497
|
+
print(f" Manifold dimensionality consistency: {results['manifold_dimensionality']:.4f} ★")
|
|
498
|
+
print(f" Spectral decay rate: {results['spectral_decay_rate']:.4f} (higher is better)")
|
|
499
|
+
print(
|
|
500
|
+
f" Participation ratio score: {results['participation_ratio']:.4f} "
|
|
501
|
+
f"({'lower is better' if self.participation_preference == 'low' else 'higher is better'})"
|
|
502
|
+
)
|
|
503
|
+
print(
|
|
504
|
+
f" Anisotropy score: {results['anisotropy_score']:.4f} "
|
|
505
|
+
f"({'higher anisotropy preferred' if self.isotropy_preference == 'low' else 'lower anisotropy preferred'})"
|
|
506
|
+
)
|
|
507
|
+
|
|
508
|
+
# Single-cell–specific
|
|
509
|
+
print(f"\n[Single-cell Specific Metrics]")
|
|
510
|
+
print(f" Trajectory directionality: {results['trajectory_directionality']:.4f} (higher is better)")
|
|
511
|
+
|
|
512
|
+
# Technical quality
|
|
513
|
+
print(f"\n[Technical Quality Metrics]")
|
|
514
|
+
print(f" Noise resilience: {results['noise_resilience']:.4f} (higher is better)")
|
|
515
|
+
|
|
516
|
+
# Aggregate
|
|
517
|
+
print(f"\n[Aggregate Scores]")
|
|
518
|
+
print(f" Core quality score: {results['core_quality']:.4f}")
|
|
519
|
+
print(f" Overall quality score: {results['overall_quality']:.4f} ★★★")
|
|
520
|
+
|
|
521
|
+
# Interpretation
|
|
522
|
+
interp = results['interpretation']
|
|
523
|
+
print(f"\n[Interpretation]")
|
|
524
|
+
print(f" Quality level: {interp['quality_level']}")
|
|
525
|
+
|
|
526
|
+
if interp['strengths']:
|
|
527
|
+
print(f" Strengths: {', '.join(interp['strengths'])}")
|
|
528
|
+
|
|
529
|
+
if interp['weaknesses']:
|
|
530
|
+
print(f" Weaknesses: {', '.join(interp['weaknesses'])}")
|
|
531
|
+
|
|
532
|
+
if interp['recommendations']:
|
|
533
|
+
print(f" Recommendations: {', '.join(interp['recommendations'])}")
|
|
534
|
+
|
|
535
|
+
print("=" * 80)
|
|
536
|
+
|
|
537
|
+
def compare_methods(self, method_results_dict):
|
|
538
|
+
"""
|
|
539
|
+
Compare different dimensionality reduction methods.
|
|
540
|
+
|
|
541
|
+
Args:
|
|
542
|
+
method_results_dict: dict mapping method name to latent_space
|
|
543
|
+
|
|
544
|
+
Returns:
|
|
545
|
+
DataFrame: comparison table of evaluation metrics
|
|
546
|
+
"""
|
|
547
|
+
|
|
548
|
+
comparison_results = []
|
|
549
|
+
|
|
550
|
+
for method_name, latent_space in method_results_dict.items():
|
|
551
|
+
self._log(f"\nEvaluating method: {method_name}")
|
|
552
|
+
|
|
553
|
+
# Temporarily disable verbose printing
|
|
554
|
+
original_verbose = self.verbose
|
|
555
|
+
self.verbose = False
|
|
556
|
+
|
|
557
|
+
results = self.comprehensive_evaluation(latent_space)
|
|
558
|
+
|
|
559
|
+
# Restore verbosity setting
|
|
560
|
+
self.verbose = original_verbose
|
|
561
|
+
|
|
562
|
+
comparison_results.append({
|
|
563
|
+
'Method': method_name,
|
|
564
|
+
'Overall_Quality': results['overall_quality'],
|
|
565
|
+
'Manifold_Dimensionality': results['manifold_dimensionality'],
|
|
566
|
+
'Spectral_Decay': results['spectral_decay_rate'],
|
|
567
|
+
'Participation_Ratio': results['participation_ratio'],
|
|
568
|
+
'Anisotropy_Score': results['anisotropy_score'],
|
|
569
|
+
'Trajectory_Directionality': results['trajectory_directionality'],
|
|
570
|
+
'Noise_Resilience': results['noise_resilience'],
|
|
571
|
+
'Quality_Level': results['interpretation']['quality_level'],
|
|
572
|
+
})
|
|
573
|
+
|
|
574
|
+
df = pd.DataFrame(comparison_results)
|
|
575
|
+
|
|
576
|
+
# Sort by overall quality
|
|
577
|
+
df = df.sort_values('Overall_Quality', ascending=False)
|
|
578
|
+
|
|
579
|
+
if self.verbose:
|
|
580
|
+
self._print_comparison_table(df)
|
|
581
|
+
|
|
582
|
+
return df
|
|
583
|
+
|
|
584
|
+
def _print_comparison_table(self, df):
|
|
585
|
+
"""Print a formatted comparison table."""
|
|
586
|
+
|
|
587
|
+
print(f"\n{'=' * 100}")
|
|
588
|
+
print(f" Dimensionality Reduction Method Comparison ({self.data_type.upper()} data)")
|
|
589
|
+
print('=' * 100)
|
|
590
|
+
|
|
591
|
+
pd.set_option('display.float_format', '{:.4f}'.format)
|
|
592
|
+
pd.set_option('display.max_columns', None)
|
|
593
|
+
pd.set_option('display.width', None)
|
|
594
|
+
|
|
595
|
+
print(df.to_string(index=False))
|
|
596
|
+
|
|
597
|
+
print(f"\nBest method: {df.iloc[0]['Method']} (Overall score: {df.iloc[0]['Overall_Quality']:.4f})")
|
|
598
|
+
|
|
599
|
+
print('=' * 100)
|
|
600
|
+
|
|
601
|
+
|
|
602
|
+
# ==================== Convenience functions ====================
|
|
603
|
+
|
|
604
|
+
def evaluate_single_cell_latent_space(latent_space, data_type="trajectory", verbose=True):
|
|
605
|
+
"""
|
|
606
|
+
Convenience function: evaluate the quality of a single-cell latent space.
|
|
607
|
+
|
|
608
|
+
Args:
|
|
609
|
+
latent_space: latent coordinates
|
|
610
|
+
data_type: "trajectory" or "steady_state"
|
|
611
|
+
verbose: whether to print detailed logs
|
|
612
|
+
|
|
613
|
+
Returns:
|
|
614
|
+
dict: evaluation results
|
|
615
|
+
"""
|
|
616
|
+
|
|
617
|
+
evaluator = SingleCellLatentSpaceEvaluator(data_type=data_type, verbose=verbose)
|
|
618
|
+
return evaluator.comprehensive_evaluation(latent_space)
|
|
619
|
+
|
|
620
|
+
|
|
621
|
+
def compare_single_cell_methods(method_results_dict, data_type="trajectory", verbose=True):
|
|
622
|
+
"""
|
|
623
|
+
Convenience function: compare multiple single-cell dimensionality reduction methods.
|
|
624
|
+
|
|
625
|
+
Args:
|
|
626
|
+
method_results_dict: dict mapping method name to latent_space
|
|
627
|
+
data_type: "trajectory" or "steady_state"
|
|
628
|
+
verbose: whether to print detailed logs
|
|
629
|
+
|
|
630
|
+
Returns:
|
|
631
|
+
DataFrame: comparison results
|
|
632
|
+
"""
|
|
633
|
+
|
|
634
|
+
evaluator = SingleCellLatentSpaceEvaluator(data_type=data_type, verbose=verbose)
|
|
635
|
+
return evaluator.compare_methods(method_results_dict)
|