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/DRE.py ADDED
@@ -0,0 +1,430 @@
1
+ import numpy as np
2
+ import pandas as pd
3
+ from sklearn.metrics import pairwise_distances
4
+ from scipy.stats import spearmanr
5
+ import time
6
+ import warnings
7
+ from typing import Dict, Tuple
8
+
9
+
10
+ class DimensionalityReductionEvaluator:
11
+ """
12
+ Dimensionality reduction quality evaluator.
13
+
14
+ Core metrics:
15
+ - distance_correlation: global distance correlation (global structure preservation)
16
+ - Q_global: global quality
17
+ - Q_local: local quality
18
+
19
+ Features:
20
+ - Efficient, vectorized computation
21
+ - Focus on key evaluation metrics
22
+ - Complementary to the single-cell latent space evaluation framework
23
+ """
24
+
25
+ def __init__(self, verbose: bool = True):
26
+ """
27
+ Initialize the evaluator.
28
+
29
+ Args:
30
+ verbose: whether to print detailed information
31
+ """
32
+ self.verbose = verbose
33
+
34
+ def _log(self, message: str):
35
+ if self.verbose:
36
+ print(message)
37
+
38
+ def _validate_inputs(self, X_high: np.ndarray, X_low: np.ndarray, k: int):
39
+ """Validate input parameters."""
40
+ if not isinstance(X_high, np.ndarray) or not isinstance(X_low, np.ndarray):
41
+ raise TypeError("Input data must be NumPy arrays.")
42
+
43
+ if X_high.shape[0] != X_low.shape[0]:
44
+ raise ValueError(
45
+ f"High- and low-dimensional data must have the same number of samples: "
46
+ f"{X_high.shape[0]} vs {X_low.shape[0]}"
47
+ )
48
+
49
+ if k >= X_high.shape[0]:
50
+ raise ValueError(f"k ({k}) must be smaller than the number of samples ({X_high.shape[0]}).")
51
+
52
+ if X_high.ndim != 2 or X_low.ndim != 2:
53
+ raise ValueError("Input data must be 2D arrays.")
54
+
55
+ # ==================== 1. Distance correlation ====================
56
+
57
+ def distance_correlation_score(self, X_high: np.ndarray, X_low: np.ndarray) -> float:
58
+ """
59
+ Compute distance correlation (Spearman correlation) between distances
60
+ in the high- and low-dimensional spaces.
61
+
62
+ Args:
63
+ X_high: high-dimensional data
64
+ X_low: low-dimensional data
65
+
66
+ Returns:
67
+ float: distance correlation score (values near 1 indicate good global structure preservation)
68
+ """
69
+ try:
70
+ self._log("Computing distance matrices...")
71
+
72
+ D_high = pairwise_distances(X_high)
73
+ D_low = pairwise_distances(X_low)
74
+
75
+ distance_corr_tuple = spearmanr(D_high.ravel(), D_low.ravel())
76
+ # spearmanr returns (correlation, pvalue); extract first element robustly
77
+ distance_corr = distance_corr_tuple[0] if isinstance(distance_corr_tuple, tuple) else distance_corr_tuple # type: ignore[index]
78
+ # Cast to native float for downstream type stability
79
+ return float(distance_corr) if not np.isnan(distance_corr) else 0.0 # type: ignore[arg-type]
80
+
81
+ except Exception as e:
82
+ warnings.warn(f"Error computing distance correlation: {e}")
83
+ return 0.0
84
+
85
+ # ==================== 2. Ranking matrix ====================
86
+
87
+ def get_ranking_matrix(self, distance_matrix: np.ndarray) -> np.ndarray:
88
+ """
89
+ Compute the ranking matrix (optimized).
90
+
91
+ Args:
92
+ distance_matrix: pairwise distance matrix
93
+
94
+ Returns:
95
+ np.ndarray: ranking matrix
96
+ """
97
+ try:
98
+ n = distance_matrix.shape[0]
99
+
100
+ # Get sorted indices row-wise
101
+ sorted_indices = np.argsort(distance_matrix, axis=1)
102
+
103
+ ranking_matrix = np.zeros((n, n), dtype=np.int32)
104
+
105
+ # Assign ranks row-wise
106
+ for i in range(n):
107
+ ranking_matrix[i, sorted_indices[i]] = np.arange(n)
108
+
109
+ # Exclude self: set diagonal to 0 and shift others by -1
110
+ mask = np.eye(n, dtype=bool)
111
+ ranking_matrix[~mask] = ranking_matrix[~mask] - 1
112
+ ranking_matrix[mask] = 0
113
+
114
+ return ranking_matrix
115
+
116
+ except Exception as e:
117
+ warnings.warn(f"Error computing ranking matrix: {e}")
118
+ n = distance_matrix.shape[0]
119
+ return np.zeros((n, n), dtype=np.int32)
120
+
121
+ # ==================== 3. Co-ranking matrix ====================
122
+
123
+ def get_coranking_matrix(self, rank_high: np.ndarray, rank_low: np.ndarray) -> np.ndarray:
124
+ """
125
+ Compute the co-ranking matrix (optimized).
126
+
127
+ Args:
128
+ rank_high: ranking matrix in high-dimensional space
129
+ rank_low: ranking matrix in low-dimensional space
130
+
131
+ Returns:
132
+ np.ndarray: co-ranking matrix
133
+ """
134
+ try:
135
+ n = rank_high.shape[0]
136
+ corank = np.zeros((n - 1, n - 1), dtype=np.int32)
137
+
138
+ mask = (rank_high > 0) & (rank_low > 0)
139
+ valid_high = rank_high[mask] - 1 # convert to 0-based
140
+ valid_low = rank_low[mask] - 1
141
+
142
+ valid_mask = (valid_high < n - 1) & (valid_low < n - 1)
143
+ valid_high = valid_high[valid_mask]
144
+ valid_low = valid_low[valid_mask]
145
+
146
+ np.add.at(corank, (valid_high, valid_low), 1)
147
+
148
+ return corank
149
+
150
+ except Exception as e:
151
+ warnings.warn(f"Error computing co-ranking matrix: {e}")
152
+ n = rank_high.shape[0]
153
+ return np.zeros((n - 1, n - 1), dtype=np.int32)
154
+
155
+ # ==================== 4. Q metrics ====================
156
+
157
+ def compute_qnx_series(self, corank: np.ndarray) -> np.ndarray:
158
+ """
159
+ Compute the Q_NX series.
160
+
161
+ Args:
162
+ corank: co-ranking matrix
163
+
164
+ Returns:
165
+ np.ndarray: sequence of Q_NX values
166
+ """
167
+ try:
168
+ n = corank.shape[0] + 1
169
+ qnx_values = []
170
+ Qnx_cum = 0
171
+
172
+ for K in range(1, n - 1):
173
+ if K - 1 < corank.shape[0]:
174
+ intrusions = np.sum(corank[:K, K - 1]) if K - 1 < corank.shape[1] else 0
175
+ extrusions = np.sum(corank[K - 1, :K]) if K - 1 < corank.shape[0] else 0
176
+ diagonal = corank[K - 1, K - 1] if K - 1 < min(corank.shape) else 0
177
+
178
+ Qnx_increment = intrusions + extrusions - diagonal
179
+ Qnx_cum += Qnx_increment
180
+
181
+ qnx_normalized = Qnx_cum / (K * n)
182
+ qnx_values.append(qnx_normalized)
183
+
184
+ return np.array(qnx_values)
185
+
186
+ except Exception as e:
187
+ warnings.warn(f"Error computing Q_NX series: {e}")
188
+ return np.array([0.0])
189
+
190
+ def get_q_local_global(self, qnx_values: np.ndarray) -> Tuple[float, float, int]:
191
+ """
192
+ Compute scalar local and global quality metrics.
193
+
194
+ Args:
195
+ qnx_values: Q_NX value sequence
196
+
197
+ Returns:
198
+ tuple: (Q_local, Q_global, K_max)
199
+ """
200
+ try:
201
+ if len(qnx_values) == 0:
202
+ return 0.0, 0.0, 1
203
+
204
+ lcmc = np.copy(qnx_values)
205
+ N = len(qnx_values)
206
+
207
+ for j in range(N):
208
+ lcmc[j] = lcmc[j] - j / N
209
+
210
+ K_max = np.argmax(lcmc) + 1
211
+
212
+ if K_max > 0:
213
+ Q_local = np.mean(qnx_values[:K_max])
214
+ else:
215
+ Q_local = qnx_values[0] if len(qnx_values) > 0 else 0.0
216
+
217
+ if K_max < len(qnx_values):
218
+ Q_global = np.mean(qnx_values[K_max:])
219
+ else:
220
+ Q_global = qnx_values[-1] if len(qnx_values) > 0 else 0.0
221
+
222
+ # Explicitly cast to native Python types
223
+ return float(Q_local), float(Q_global), int(K_max)
224
+
225
+ except Exception as e:
226
+ warnings.warn(f"Error computing Q metrics: {e}")
227
+ return 0.0, 0.0, 1
228
+
229
+ # ==================== 5. Comprehensive evaluation ====================
230
+
231
+ def comprehensive_evaluation(
232
+ self, X_high: np.ndarray, X_low: np.ndarray, k: int = 10
233
+ ) -> Dict[str, float]:
234
+ """
235
+ Comprehensive evaluation of dimensionality reduction quality.
236
+
237
+ Args:
238
+ X_high: high-dimensional data, shape = (n_samples, n_features_high)
239
+ X_low: low-dimensional data, shape = (n_samples, n_features_low)
240
+ k: number of neighbors considered
241
+
242
+ Returns:
243
+ dict: dictionary with core evaluation metrics
244
+ """
245
+ self._validate_inputs(X_high, X_low, k)
246
+
247
+ self._log(f"Starting dimensionality reduction evaluation (n_samples={X_high.shape[0]}, k={k})...")
248
+
249
+ results: Dict[str, float] = {}
250
+
251
+ # 1. Distance correlation
252
+ self._log("Computing distance correlation...")
253
+ results['distance_correlation'] = self.distance_correlation_score(X_high, X_low)
254
+
255
+ # 2. Ranking matrices
256
+ self._log("Computing ranking matrices...")
257
+ D_high = pairwise_distances(X_high)
258
+ D_low = pairwise_distances(X_low)
259
+
260
+ rank_high = self.get_ranking_matrix(D_high)
261
+ rank_low = self.get_ranking_matrix(D_low)
262
+
263
+ # 3. Co-ranking matrix
264
+ self._log("Computing co-ranking matrix...")
265
+ corank = self.get_coranking_matrix(rank_high, rank_low)
266
+
267
+ # 4. Q metrics
268
+ self._log("Computing Q metrics...")
269
+ qnx_values = self.compute_qnx_series(corank)
270
+ Q_local, Q_global, K_max = self.get_q_local_global(qnx_values)
271
+
272
+ results['Q_local'] = float(Q_local)
273
+ results['Q_global'] = float(Q_global)
274
+ results['K_max'] = int(K_max)
275
+
276
+ overall_quality = float(np.mean([
277
+ results['distance_correlation'],
278
+ results['Q_local'],
279
+ results['Q_global'],
280
+ ]))
281
+ results['overall_quality'] = overall_quality
282
+
283
+ if self.verbose:
284
+ self._print_results(results)
285
+
286
+ return results
287
+
288
+ def _print_results(self, results: Dict[str, float]):
289
+ """Print a formatted summary of evaluation results."""
290
+
291
+ print("\n" + "=" * 60)
292
+ print(" Dimensionality Reduction Quality")
293
+ print("=" * 60)
294
+
295
+ print("\n[Core Metrics]")
296
+ print(f" Distance correlation: {results['distance_correlation']:.4f} ★")
297
+ print(" └─ Values near 1 indicate good global structure preservation")
298
+
299
+ print(f"\n Local quality (Q_local): {results['Q_local']:.4f} ★")
300
+ print(" └─ Values near 1 indicate good local structure preservation")
301
+
302
+ print(f"\n Global quality (Q_global): {results['Q_global']:.4f} ★")
303
+ print(" └─ Values near 1 indicate good global structure preservation")
304
+
305
+ print("\n[Auxiliary]")
306
+ print(f" Local–global split point (K_max): {results['K_max']}")
307
+
308
+ overall_quality = results['overall_quality']
309
+
310
+ print("\n[Overall Assessment]")
311
+ print(f" Mean quality score: {overall_quality:.4f}")
312
+
313
+ if overall_quality >= 0.8:
314
+ quality_level = "Excellent"
315
+ elif overall_quality >= 0.6:
316
+ quality_level = "Good"
317
+ elif overall_quality >= 0.4:
318
+ quality_level = "Fair"
319
+ else:
320
+ quality_level = "Needs improvement"
321
+
322
+ print(f" Quality level: {quality_level}")
323
+
324
+ print("=" * 60)
325
+
326
+ def compare_methods(self, method_results_dict: Dict[str, Tuple[np.ndarray, np.ndarray]], k: int = 10) -> pd.DataFrame:
327
+ """
328
+ Compare multiple dimensionality reduction methods.
329
+
330
+ Args:
331
+ method_results_dict: mapping {method_name: (X_high, X_low)}
332
+ k: number of neighbors considered
333
+
334
+ Returns:
335
+ DataFrame: comparison table of methods
336
+ """
337
+ comparison_results = []
338
+
339
+ for method_name, (X_high, X_low) in method_results_dict.items():
340
+ self._log(f"\nEvaluating method: {method_name}")
341
+
342
+ original_verbose = self.verbose
343
+ self.verbose = False
344
+
345
+ results = self.comprehensive_evaluation(X_high, X_low, k)
346
+
347
+ self.verbose = original_verbose
348
+
349
+ overall_quality = float(np.mean([
350
+ results['distance_correlation'],
351
+ results['Q_Local'],
352
+ results['Q_Global'],
353
+ ]))
354
+
355
+ comparison_results.append({
356
+ 'Method': method_name,
357
+ 'Distance_Correlation': results['distance_correlation'],
358
+ 'Q_Local': results['Q_local'],
359
+ 'Q_Global': results['Q_global'],
360
+ 'Overall_Quality': overall_quality,
361
+ })
362
+
363
+ df = pd.DataFrame(comparison_results)
364
+ df = df.sort_values('Overall_Quality', ascending=False)
365
+
366
+ if self.verbose:
367
+ self._print_comparison_table(df)
368
+
369
+ return df
370
+
371
+ def _print_comparison_table(self, df: pd.DataFrame):
372
+ """Print a formatted comparison table of methods."""
373
+
374
+ print(f"\n{'=' * 90}")
375
+ print(" Dimensionality Reduction Method Comparison")
376
+ print('=' * 90)
377
+
378
+ pd.set_option('display.float_format', '{:.4f}'.format)
379
+ pd.set_option('display.max_columns', None)
380
+ pd.set_option('display.width', None)
381
+
382
+ print(df.to_string(index=False))
383
+
384
+ print(
385
+ f"\nBest method: {df.iloc[0]['Method']} "
386
+ f"(Overall score: {df.iloc[0]['Overall_Quality']:.4f})"
387
+ )
388
+
389
+ print('=' * 90)
390
+
391
+
392
+ # ==================== Convenience functions ====================
393
+
394
+ def evaluate_dimensionality_reduction(
395
+ X_high: np.ndarray, X_low: np.ndarray, k: int = 10, verbose: bool = True
396
+ ) -> Dict[str, float]:
397
+ """
398
+ Convenience function to evaluate the quality of a dimensionality reduction.
399
+
400
+ Args:
401
+ X_high: high-dimensional data
402
+ X_low: low-dimensional data
403
+ k: number of neighbors considered
404
+ verbose: whether to print detailed output
405
+
406
+ Returns:
407
+ dict: evaluation results
408
+ """
409
+ evaluator = DimensionalityReductionEvaluator(verbose=verbose)
410
+ return evaluator.comprehensive_evaluation(X_high, X_low, k)
411
+
412
+
413
+ def compare_dimensionality_reduction_methods(
414
+ method_results_dict: Dict[str, Tuple[np.ndarray, np.ndarray]],
415
+ k: int = 10,
416
+ verbose: bool = True,
417
+ ) -> pd.DataFrame:
418
+ """
419
+ Convenience function to compare different dimensionality reduction methods.
420
+
421
+ Args:
422
+ method_results_dict: mapping {method_name: (X_high, X_low)}
423
+ k: number of neighbors considered
424
+ verbose: whether to print detailed output
425
+
426
+ Returns:
427
+ DataFrame: comparison results
428
+ """
429
+ evaluator = DimensionalityReductionEvaluator(verbose=verbose)
430
+ return evaluator.compare_methods(method_results_dict, k)