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/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)