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