imste 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.
imste/_estimator.py ADDED
@@ -0,0 +1,1106 @@
1
+ """Scikit-learn estimator for IMSTE embeddings."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
6
+ from collections.abc import Callable
7
+
8
+ import numpy as np
9
+ from scipy.sparse import csr_matrix, issparse
10
+ from sklearn.base import BaseEstimator, TransformerMixin
11
+ from sklearn.utils.validation import check_array
12
+
13
+ from ._estimator_graph import _EstimatorGraphMethods
14
+ from ._estimator_utils import (
15
+ _append_candidate_attraction_edges,
16
+ _finite_nonnegative,
17
+ _positive_integer,
18
+ _sample_negative_targets,
19
+ _sample_sparse_negative_targets,
20
+ _scale_initialization_coordinates,
21
+ _standardized_pca_initialization,
22
+ )
23
+ from ._optimizer import optimize_embedding
24
+ from ._multilevel import (
25
+ _canonical_edges,
26
+ aggregate_features_by_group,
27
+ build_multilevel_hierarchy,
28
+ expand_coordinates,
29
+ )
30
+ from .mst import build_mst_edges
31
+ from .mst.prim import (
32
+ _cosine_safe_normalize,
33
+ iterated_prim_distance_edges as _iterated_mst_edges,
34
+ )
35
+
36
+
37
+ class IteratedMinimumSpanningTreeEmbedder(
38
+ _EstimatorGraphMethods, TransformerMixin, BaseEstimator
39
+ ):
40
+ """Learn training-row coordinates from ranked iterated spanning trees.
41
+
42
+ Trees use unused edges where possible. When a residual graph has a local
43
+ bottleneck, only the edges needed to reconnect its components are reused;
44
+ each reuse increments that edge's rank and lowers its attraction weight.
45
+
46
+ This is the transductive estimator. ``transform`` returns the learned
47
+ coordinates only for the exact training matrix in its original row order.
48
+ Use :class:`imste.inductive.InductiveIMSTE` to project new rows.
49
+ Dense arrays and SciPy CSR matrices are supported.
50
+
51
+ Parameters
52
+ ----------
53
+ n_msts : int, default=15
54
+ Number of spanning-tree iterations to construct. Bottleneck edges may
55
+ be reused, with their rank incremented each time.
56
+ n_components : int, default=2
57
+ Number of embedding coordinates per sample.
58
+ pca_init : bool, default=True
59
+ Initialize ``fit(X)`` coordinates from PCA on standardized features.
60
+ ``fit_graph`` also uses PCA when ``init_features`` is supplied. Extra
61
+ coordinates beyond the available PCA dimensions are zero. The existing
62
+ random initialization is used when false or when graph features are absent.
63
+ pca_init_scaling : {'global', 'none'}, default='global'
64
+ Apply one uniform scale so all PCA coordinates fit in ``[-1, 1]``, or
65
+ preserve the raw PCA score magnitudes. Does not affect random initialization.
66
+ init_coordinates : array-like of shape (n_samples, n_components), default=None
67
+ Explicit starting coordinates for optimization. These take precedence
68
+ over PCA and random initialization and must follow the input row order.
69
+ multilevel_init : bool, default=True
70
+ Initialize from a rank-only multilevel coarsening of the fitted graph.
71
+ Explicit ``init_coordinates`` take precedence. If coarsening makes no
72
+ progress, the configured PCA or seeded random initialization is used.
73
+ When ``pca_init=True`` and features are available, initialize the
74
+ coarsest graph from PCA of its pooled group features; otherwise use a
75
+ seeded random start at the coarsest level.
76
+ multilevel_reduction_ratio : int, default=32
77
+ Approximate reduction factor for each coarsening level.
78
+ multilevel_base_size : int, default=512
79
+ Stop coarsening once a level has at most this many nodes.
80
+ multilevel_epochs : int, default=1
81
+ Refinement epochs at each coarsened level.
82
+ n_epochs : int, default=200
83
+ Number of optimization epochs.
84
+ batch_size : int, default=131072
85
+ Maximum active edges per GPU update batch. Ignored by the CPU optimizer.
86
+ learning_rate : float, default=0.05
87
+ Base SGD step size; updates are sample-scaled and decay linearly by epoch.
88
+ negative_ratio : int, default=5
89
+ Number of sampled non-neighbors per endpoint of each positive edge.
90
+ lambda_rep : float, default=0.5
91
+ Repulsion share in the objective, from zero to one.
92
+ logistic_margin : float, default=1.0
93
+ Squared-distance margin used by logistic repulsion.
94
+ logistic_temperature : float, default=0.5
95
+ Positive temperature controlling logistic repulsion softness.
96
+ random_state : int or None, default=42
97
+ Seed controlling initialization, edge ordering, and negative sampling.
98
+ epsilon : float, default=1e-4
99
+ Smoothing added to squared distances in the logarithmic attraction.
100
+ device : {'auto', 'cpu', 'mps', 'cuda'}, default='auto'
101
+ ``'auto'`` selects MPS on Apple Silicon, CUDA when available, and CPU
102
+ otherwise. ``'cpu'`` selects the Numba optimizer; ``'mps'`` and
103
+ ``'cuda'`` select their corresponding PyTorch GPU backends.
104
+ mst_method : {'prim', 'famst'}, default='famst'
105
+ ``'prim'`` constructs exact trees; CSR inputs avoid an all-pairs
106
+ distance matrix but still take quadratic time.
107
+ ``'famst'`` uses a sparse neighbor graph and FAMST-style component
108
+ connection and refinement. Both modes reuse an edge only when required
109
+ to connect a residual bottleneck, incrementing its rank for each reuse.
110
+ FAMST uses the backend selected by ``mst_neighbor_backend``.
111
+ mst_neighbor_backend : {'auto', 'rinnd', 'pynndescent', 'mps_exact'}, default='auto'
112
+ Neighbor search backend for dense Euclidean FAMST inputs. ``'auto'``
113
+ prefers RINND when available, otherwise it uses the existing device-based
114
+ choice. RINND search does not change the optimizer selected by ``device``.
115
+ metric : {'euclidean', 'cosine'}, default='euclidean'
116
+ Feature distance used to construct the spanning-tree graph. Cosine
117
+ distance with FAMST uses the exact Prim backend.
118
+ mst_neighbors : int, default=15
119
+ Minimum initial approximate-neighbor count for ``mst_method='famst'``.
120
+ FAMST targets the larger of this value and ``2 * n_msts``, subject to
121
+ ``mst_max_neighbors``.
122
+ include_knn_attraction : bool, default=False
123
+ Include FAMST's approximate candidate-neighbor edges as additional
124
+ rank-one attractive edges alongside the ranked spanning trees. This
125
+ makes local neighborhoods denser and is available for Euclidean FAMST
126
+ fits.
127
+ gravity_strength : float, default=0.2
128
+ Attraction toward density-weighted region cores after IMSTE. Set to zero
129
+ to disable gravity. Gravity requires dense Euclidean features and at
130
+ least two embedding dimensions; it refines the first two. It is skipped
131
+ automatically when ``metric='cosine'``.
132
+ gravity_neighbors : int, default=15
133
+ Feature-space neighbors used to build gravity regions.
134
+ gravity_resolution : float, default=1.0
135
+ Leiden resolution used to identify gravity regions.
136
+ gravity_core_quantile : float, default=0.95
137
+ Within-region density quantile defining the core points.
138
+ gravity_mass_power : float, default=0.5
139
+ Exponent controlling how region and point density affect gravity.
140
+ gravity_pack_regions : bool, default=False
141
+ After gravity, translate each Leiden region as a rigid group onto a
142
+ compact ring. This preserves within-region distances but changes
143
+ distances between regions.
144
+ gravity_pack_radius_quantile : float, default=0.9
145
+ Within-region radial quantile used to estimate each region's ring size.
146
+ gravity_pack_gap_fraction : float, default=0.25
147
+ Gap between ring regions as a fraction of their median estimated radius.
148
+ mean_shift_neighbors : int, default=100
149
+ Number of neighbors from the starting 2D layout used for Gaussian mean shift.
150
+ mean_shift_bandwidth_factor : float, default=5.0
151
+ Gaussian bandwidth as a multiple of the median current 2D distance to
152
+ the selected neighbor count.
153
+ mean_shift_step_size : float, default=0.5
154
+ Interpolation from each coordinate toward its kernel-weighted mean, in
155
+ the interval [0, 1].
156
+ mean_shift_iterations : int, default=1
157
+ Mean-shift iterations applied after gravity. Zero disables mean shift.
158
+ mst_inter_component_edges : int, default=5
159
+ FAMST candidate edges retained between each component pair selected by
160
+ the representative MST.
161
+ mst_representatives_per_component : int, default=10
162
+ Maximum points sampled from each ANN component to select bridge-search
163
+ component pairs with a representative MST.
164
+ mst_max_neighbors : int or None, default=None
165
+ Maximum approximate-neighbor count. ``None`` allows the FAMST builder to
166
+ increase the count up to four times its starting neighbor count before
167
+ reusing residual bottleneck edges.
168
+ progress_callback : callable or None, default=None
169
+ Optional function called with ``(completed_epochs, total_epochs)`` after
170
+ each optimization epoch, including multilevel refinement epochs.
171
+ mst_progress_callback : callable or None, default=None
172
+ Optional function called with ``(completed, total, detail)`` during MST
173
+ construction and multilevel coarsening/refinement. FAMST's detail
174
+ includes its current neighbor count.
175
+ verbose : bool, default=False
176
+ Print timestamped fit stages and display progress bars for graph
177
+ construction, multilevel initialization, and optimization.
178
+ """
179
+
180
+ def __init__(
181
+ self,
182
+ n_msts: int = 15,
183
+ n_components: int = 2,
184
+ n_epochs: int = 200,
185
+ batch_size: int = 131072,
186
+ learning_rate: float = 0.05,
187
+ negative_ratio: int = 5,
188
+ lambda_rep: float = 0.5,
189
+ random_state: int | None = 42,
190
+ epsilon: float = 1e-4,
191
+ device: str = "auto",
192
+ logistic_margin: float = 1.0,
193
+ logistic_temperature: float = 0.5,
194
+ mst_method: str = "famst",
195
+ mst_neighbors: int = 15,
196
+ mst_inter_component_edges: int = 5,
197
+ mst_max_neighbors: int | None = None,
198
+ progress_callback: Callable[[int, int], None] | None = None,
199
+ mst_progress_callback: Callable[[int, int, str], None] | None = None,
200
+ verbose: bool = False,
201
+ mst_representatives_per_component: int = 10,
202
+ pca_init: bool = True,
203
+ pca_init_scaling: str = "global",
204
+ init_coordinates: object | None = None,
205
+ multilevel_init: bool = True,
206
+ multilevel_reduction_ratio: int = 32,
207
+ multilevel_base_size: int = 512,
208
+ multilevel_epochs: int = 1,
209
+ metric: str = "euclidean",
210
+ mst_neighbor_backend: str = "auto",
211
+ include_knn_attraction: bool = False,
212
+ gravity_neighbors: int = 15,
213
+ gravity_resolution: float = 1.0,
214
+ gravity_strength: float = 0.2,
215
+ gravity_core_quantile: float = 0.95,
216
+ gravity_mass_power: float = 0.5,
217
+ gravity_pack_regions: bool = False,
218
+ gravity_pack_radius_quantile: float = 0.9,
219
+ gravity_pack_gap_fraction: float = 0.25,
220
+ mean_shift_neighbors: int = 100,
221
+ mean_shift_bandwidth_factor: float = 5.0,
222
+ mean_shift_step_size: float = 0.5,
223
+ mean_shift_iterations: int = 1,
224
+ ) -> None:
225
+ self.n_msts = n_msts
226
+ self.n_components = n_components
227
+ self.n_epochs = n_epochs
228
+ self.batch_size = batch_size
229
+ self.learning_rate = learning_rate
230
+ self.negative_ratio = negative_ratio
231
+ self.lambda_rep = lambda_rep
232
+ self.random_state = random_state
233
+ self.pca_init = pca_init
234
+ self.epsilon = epsilon
235
+ self.device = device
236
+ self.logistic_margin = logistic_margin
237
+ self.logistic_temperature = logistic_temperature
238
+ self.mst_method = mst_method
239
+ self.mst_neighbors = mst_neighbors
240
+ self.mst_inter_component_edges = mst_inter_component_edges
241
+ self.mst_max_neighbors = mst_max_neighbors
242
+ self.progress_callback = progress_callback
243
+ self.mst_progress_callback = mst_progress_callback
244
+ self.verbose = verbose
245
+ self._active_progress_callback = progress_callback
246
+ self._active_mst_progress_callback = mst_progress_callback
247
+ self._progress_reporter = None
248
+ self.mst_representatives_per_component = mst_representatives_per_component
249
+ self.pca_init_scaling = pca_init_scaling
250
+ self.init_coordinates = init_coordinates
251
+ self.multilevel_init = multilevel_init
252
+ self.multilevel_reduction_ratio = multilevel_reduction_ratio
253
+ self.multilevel_base_size = multilevel_base_size
254
+ self.multilevel_epochs = multilevel_epochs
255
+ self.metric = metric
256
+ self.mst_neighbor_backend = mst_neighbor_backend
257
+ self.include_knn_attraction = include_knn_attraction
258
+ self.gravity_neighbors = gravity_neighbors
259
+ self.gravity_resolution = gravity_resolution
260
+ self.gravity_strength = gravity_strength
261
+ self.gravity_core_quantile = gravity_core_quantile
262
+ self.gravity_mass_power = gravity_mass_power
263
+ self.gravity_pack_regions = gravity_pack_regions
264
+ self.gravity_pack_radius_quantile = gravity_pack_radius_quantile
265
+ self.gravity_pack_gap_fraction = gravity_pack_gap_fraction
266
+ self.mean_shift_neighbors = mean_shift_neighbors
267
+ self.mean_shift_bandwidth_factor = mean_shift_bandwidth_factor
268
+ self.mean_shift_step_size = mean_shift_step_size
269
+ self.mean_shift_iterations = mean_shift_iterations
270
+
271
+ def _validated_fit_options(self) -> dict[str, object]:
272
+ if not isinstance(self.verbose, (bool, np.bool_)):
273
+ raise ValueError("verbose must be a boolean.")
274
+ n_msts = _positive_integer("n_msts", self.n_msts)
275
+ n_components = _positive_integer("n_components", self.n_components)
276
+ n_epochs = _positive_integer("n_epochs", self.n_epochs, allow_zero=True)
277
+ batch_size = _positive_integer("batch_size", self.batch_size)
278
+ negative_ratio = _positive_integer(
279
+ "negative_ratio", self.negative_ratio, allow_zero=True
280
+ )
281
+ mst_neighbors = _positive_integer("mst_neighbors", self.mst_neighbors)
282
+ inter_component_edges = _positive_integer(
283
+ "mst_inter_component_edges", self.mst_inter_component_edges
284
+ )
285
+ representatives_per_component = _positive_integer(
286
+ "mst_representatives_per_component",
287
+ self.mst_representatives_per_component,
288
+ )
289
+ multilevel_reduction_ratio = _positive_integer(
290
+ "multilevel_reduction_ratio", self.multilevel_reduction_ratio
291
+ )
292
+ multilevel_base_size = _positive_integer(
293
+ "multilevel_base_size", self.multilevel_base_size
294
+ )
295
+ multilevel_epochs = _positive_integer(
296
+ "multilevel_epochs", self.multilevel_epochs, allow_zero=True
297
+ )
298
+ max_neighbors = (
299
+ None
300
+ if self.mst_max_neighbors is None
301
+ else _positive_integer("mst_max_neighbors", self.mst_max_neighbors)
302
+ )
303
+ if self.mst_method not in {"prim", "famst"}:
304
+ raise ValueError("mst_method must be either 'prim' or 'famst'.")
305
+ if self.mst_neighbor_backend not in {
306
+ "auto", "rinnd", "pynndescent", "mps_exact"
307
+ }:
308
+ raise ValueError(
309
+ "mst_neighbor_backend must be one of 'auto', 'rinnd', "
310
+ "'pynndescent', or 'mps_exact'."
311
+ )
312
+ if self.metric not in {"euclidean", "cosine"}:
313
+ raise ValueError("metric must be either 'euclidean' or 'cosine'.")
314
+ if self.mst_method == "famst" and self.metric != "euclidean":
315
+ if self.mst_neighbor_backend in {"rinnd", "mps_exact"}:
316
+ raise ValueError(
317
+ f"mst_neighbor_backend={self.mst_neighbor_backend!r} "
318
+ "requires dense Euclidean FAMST input."
319
+ )
320
+ if self.mst_method == "prim" and self.mst_neighbor_backend != "auto":
321
+ raise ValueError(
322
+ "mst_neighbor_backend applies only when mst_method='famst'."
323
+ )
324
+ if not isinstance(self.include_knn_attraction, (bool, np.bool_)):
325
+ raise ValueError("include_knn_attraction must be a boolean.")
326
+ if self.include_knn_attraction and self.mst_method != "famst":
327
+ raise ValueError("include_knn_attraction requires mst_method='famst'.")
328
+ if self.include_knn_attraction and self.metric != "euclidean":
329
+ raise ValueError("include_knn_attraction requires metric='euclidean'.")
330
+ gravity_strength = _finite_nonnegative(
331
+ "gravity_strength", self.gravity_strength
332
+ )
333
+ gravity_enabled = gravity_strength > 0.0 and self.metric == "euclidean"
334
+ if not gravity_enabled:
335
+ gravity_strength = 0.0
336
+ if gravity_enabled and n_components < 2:
337
+ raise ValueError("gravity refinement requires n_components >= 2.")
338
+ gravity_neighbors = _positive_integer(
339
+ "gravity_neighbors", self.gravity_neighbors
340
+ )
341
+ gravity_resolution = _finite_nonnegative(
342
+ "gravity_resolution", self.gravity_resolution, strictly_positive=True
343
+ )
344
+ gravity_core_quantile = _finite_nonnegative(
345
+ "gravity_core_quantile", self.gravity_core_quantile
346
+ )
347
+ if gravity_core_quantile > 1.0:
348
+ raise ValueError("gravity_core_quantile must be in [0, 1].")
349
+ gravity_mass_power = _finite_nonnegative(
350
+ "gravity_mass_power", self.gravity_mass_power
351
+ )
352
+ if not isinstance(self.gravity_pack_regions, (bool, np.bool_)):
353
+ raise ValueError("gravity_pack_regions must be a boolean.")
354
+ gravity_pack_radius_quantile = _finite_nonnegative(
355
+ "gravity_pack_radius_quantile", self.gravity_pack_radius_quantile
356
+ )
357
+ if not 0.0 < gravity_pack_radius_quantile < 1.0:
358
+ raise ValueError("gravity_pack_radius_quantile must be between 0 and 1.")
359
+ gravity_pack_gap_fraction = _finite_nonnegative(
360
+ "gravity_pack_gap_fraction", self.gravity_pack_gap_fraction
361
+ )
362
+ mean_shift_neighbors = _positive_integer(
363
+ "mean_shift_neighbors", self.mean_shift_neighbors
364
+ )
365
+ mean_shift_bandwidth_factor = _finite_nonnegative(
366
+ "mean_shift_bandwidth_factor", self.mean_shift_bandwidth_factor,
367
+ strictly_positive=True,
368
+ )
369
+ mean_shift_step_size = _finite_nonnegative(
370
+ "mean_shift_step_size", self.mean_shift_step_size
371
+ )
372
+ if mean_shift_step_size > 1.0:
373
+ raise ValueError("mean_shift_step_size must be in [0, 1].")
374
+ mean_shift_iterations = _positive_integer(
375
+ "mean_shift_iterations", self.mean_shift_iterations, allow_zero=True
376
+ )
377
+ if mean_shift_iterations and n_components < 2:
378
+ raise ValueError("mean shift requires n_components >= 2.")
379
+ learning_rate = _finite_nonnegative(
380
+ "learning_rate", self.learning_rate, strictly_positive=True
381
+ )
382
+ lambda_rep = _finite_nonnegative("lambda_rep", self.lambda_rep)
383
+ if lambda_rep > 1.0:
384
+ raise ValueError("lambda_rep must be between 0 and 1 inclusive.")
385
+ epsilon = _finite_nonnegative("epsilon", self.epsilon, strictly_positive=True)
386
+ logistic_margin = _finite_nonnegative("logistic_margin", self.logistic_margin)
387
+ logistic_temperature = _finite_nonnegative(
388
+ "logistic_temperature", self.logistic_temperature, strictly_positive=True
389
+ )
390
+ if not isinstance(self.pca_init, (bool, np.bool_)):
391
+ raise ValueError("pca_init must be a boolean.")
392
+ if not isinstance(self.multilevel_init, (bool, np.bool_)):
393
+ raise ValueError("multilevel_init must be a boolean.")
394
+ if not isinstance(self.pca_init_scaling, str) or self.pca_init_scaling not in {
395
+ "global",
396
+ "none",
397
+ }:
398
+ raise ValueError("pca_init_scaling must be either 'global' or 'none'.")
399
+ if self.device not in {"auto", "cpu", "mps", "cuda"}:
400
+ raise ValueError("device must be one of 'auto', 'cpu', 'mps', or 'cuda'.")
401
+ resolved_device = "cpu"
402
+ if self.device != "cpu":
403
+ try:
404
+ import torch
405
+ except ImportError:
406
+ if self.device != "auto":
407
+ raise RuntimeError(
408
+ f"device={self.device!r} requires PyTorch with a GPU backend. "
409
+ "Install it with `python -m pip install 'imste[gpu]'`."
410
+ )
411
+ else:
412
+ mps_backend = getattr(torch.backends, "mps", None)
413
+ mps_available = (
414
+ mps_backend is not None and mps_backend.is_available()
415
+ )
416
+ cuda_available = torch.cuda.is_available()
417
+ if self.device == "mps":
418
+ if not mps_available:
419
+ raise RuntimeError(
420
+ "device='mps' requires an MPS-capable PyTorch installation "
421
+ "on a Mac with a supported Apple GPU."
422
+ )
423
+ resolved_device = "mps"
424
+ elif self.device == "cuda":
425
+ if not cuda_available:
426
+ raise RuntimeError(
427
+ "device='cuda' requires an available CUDA-capable GPU."
428
+ )
429
+ resolved_device = "cuda"
430
+ elif mps_available:
431
+ resolved_device = "mps"
432
+ elif cuda_available:
433
+ resolved_device = "cuda"
434
+ return {
435
+ "n_msts": n_msts,
436
+ "n_components": n_components,
437
+ "n_epochs": n_epochs,
438
+ "batch_size": batch_size,
439
+ "negative_ratio": negative_ratio,
440
+ "mst_neighbors": mst_neighbors,
441
+ "inter_component_edges": inter_component_edges,
442
+ "representatives_per_component": representatives_per_component,
443
+ "max_neighbors": max_neighbors,
444
+ "mst_neighbor_backend": self.mst_neighbor_backend,
445
+ "include_knn_attraction": bool(self.include_knn_attraction),
446
+ "learning_rate": learning_rate,
447
+ "lambda_rep": lambda_rep,
448
+ "epsilon": epsilon,
449
+ "logistic_margin": logistic_margin,
450
+ "logistic_temperature": logistic_temperature,
451
+ "pca_init": bool(self.pca_init),
452
+ "multilevel_init": bool(self.multilevel_init),
453
+ "multilevel_reduction_ratio": multilevel_reduction_ratio,
454
+ "multilevel_base_size": multilevel_base_size,
455
+ "multilevel_epochs": multilevel_epochs,
456
+ "pca_init_scaling": self.pca_init_scaling,
457
+ "resolved_device": resolved_device,
458
+ "metric": self.metric,
459
+ "gravity_enabled": gravity_enabled,
460
+ "gravity_neighbors": gravity_neighbors,
461
+ "gravity_resolution": gravity_resolution,
462
+ "gravity_strength": gravity_strength,
463
+ "gravity_core_quantile": gravity_core_quantile,
464
+ "gravity_mass_power": gravity_mass_power,
465
+ "gravity_pack_regions": bool(self.gravity_pack_regions),
466
+ "gravity_pack_radius_quantile": gravity_pack_radius_quantile,
467
+ "gravity_pack_gap_fraction": gravity_pack_gap_fraction,
468
+ "mean_shift_neighbors": mean_shift_neighbors,
469
+ "mean_shift_bandwidth_factor": mean_shift_bandwidth_factor,
470
+ "mean_shift_step_size": mean_shift_step_size,
471
+ "mean_shift_iterations": mean_shift_iterations,
472
+ }
473
+
474
+ def _activate_progress_reporting(self) -> None:
475
+ """Combine user callbacks with the built-in verbose progress display."""
476
+ self._active_progress_callback = self.progress_callback
477
+ self._active_mst_progress_callback = self.mst_progress_callback
478
+ self._progress_reporter = None
479
+ if not self.verbose:
480
+ return
481
+
482
+ from ._progress import IMSTEProgressReporter
483
+
484
+ reporter = IMSTEProgressReporter(self)
485
+ reporter.start()
486
+ self._progress_reporter = reporter
487
+
488
+ def report_epochs(completed: int, total: int) -> None:
489
+ if self.progress_callback is not None:
490
+ self.progress_callback(completed, total)
491
+ reporter.epoch_callback(completed, total)
492
+
493
+ def report_stages(completed: int, total: int, detail: str) -> None:
494
+ if self.mst_progress_callback is not None:
495
+ self.mst_progress_callback(completed, total, detail)
496
+ reporter.mst_callback(completed, total, detail)
497
+
498
+ self._active_progress_callback = report_epochs
499
+ self._active_mst_progress_callback = report_stages
500
+
501
+ def _fit_edges(
502
+ self,
503
+ *,
504
+ n_samples: int,
505
+ n_components: int,
506
+ edges: np.ndarray,
507
+ tree_ranks: np.ndarray,
508
+ fit_started: float,
509
+ resolved_device: str,
510
+ schedule_by_rank: bool,
511
+ X_checked: object | None = None,
512
+ X_original: object | None = None,
513
+ initialization_features: object | None = None,
514
+ initial_coordinates: object | None = None,
515
+ **options,
516
+ ) -> "IteratedMinimumSpanningTreeEmbedder":
517
+ """Optimize coordinates from a graph and attach fitted diagnostics.
518
+
519
+ ``X_checked`` distinguishes feature-based fits from ``fit_graph``.
520
+ Feature inputs can provide PCA initialization, while
521
+ ``initial_coordinates`` directly supplies the optimizer's starting
522
+ coordinates when present.
523
+ """
524
+ embedding_started = time.perf_counter()
525
+ self.multilevel_initialization_time_ = 0.0
526
+ rng = np.random.RandomState(self.random_state)
527
+ seed = int(rng.randint(0, np.iinfo(np.int32).max))
528
+ pca_features = (
529
+ X_checked if initialization_features is None else initialization_features
530
+ )
531
+ if initial_coordinates is not None:
532
+ coordinates = check_array(
533
+ initial_coordinates, dtype=np.float64, ensure_2d=True
534
+ )
535
+ if coordinates.shape != (n_samples, n_components):
536
+ raise ValueError(
537
+ "init_coordinates must have shape "
538
+ f"({n_samples}, {n_components}); got {coordinates.shape}."
539
+ )
540
+ coordinates = coordinates.astype(np.float32, copy=True)
541
+ elif options["multilevel_init"]:
542
+ multilevel_started = time.perf_counter()
543
+ coordinates = self._multilevel_initialization(
544
+ n_samples,
545
+ n_components,
546
+ edges,
547
+ tree_ranks,
548
+ resolved_device,
549
+ pca_features,
550
+ options,
551
+ )
552
+ self.multilevel_initialization_time_ = (
553
+ time.perf_counter() - multilevel_started
554
+ )
555
+ if self._progress_reporter is not None:
556
+ self._progress_reporter.multilevel_finished()
557
+ self._progress_reporter.phase_finished(
558
+ "Multilevel initialization",
559
+ self.multilevel_initialization_time_,
560
+ )
561
+ if coordinates is None:
562
+ coordinates = self._default_initialization(
563
+ rng, pca_features, n_samples, n_components, options
564
+ )
565
+ elif pca_features is not None and options["pca_init"]:
566
+ coordinates = _standardized_pca_initialization(
567
+ pca_features, n_components, self.random_state
568
+ )
569
+ coordinates = _scale_initialization_coordinates(
570
+ coordinates, options["pca_init_scaling"]
571
+ ).astype(np.float32)
572
+ else:
573
+ coordinates = (
574
+ rng.standard_normal((n_samples, n_components)) * 1e-3
575
+ ).astype(np.float32)
576
+ optimizer_profile = {"negative_sampling": 0.0, "coordinate_updates": 0.0}
577
+
578
+ def record_optimizer_timing(
579
+ sampling_seconds: float, update_seconds: float
580
+ ) -> None:
581
+ optimizer_profile["negative_sampling"] += sampling_seconds
582
+ optimizer_profile["coordinate_updates"] += update_seconds
583
+
584
+ optimizer = optimize_embedding
585
+ if resolved_device in {"mps", "cuda"}:
586
+ from functools import partial
587
+
588
+ from ._optimizer_torch import optimize_embedding_torch
589
+
590
+ optimizer = partial(
591
+ optimize_embedding_torch, device_type=resolved_device
592
+ )
593
+ optimizer_batch_size = options["batch_size"]
594
+ else:
595
+ optimizer_batch_size = None
596
+ optimizer_kwargs = dict(
597
+ n_epochs=options["n_epochs"],
598
+ learning_rate=options["learning_rate"],
599
+ negative_ratio=options["negative_ratio"],
600
+ lambda_rep=options["lambda_rep"],
601
+ epsilon=options["epsilon"],
602
+ margin=options["logistic_margin"],
603
+ temperature=options["logistic_temperature"],
604
+ random_state=seed,
605
+ schedule_by_rank=schedule_by_rank,
606
+ progress_callback=self._active_progress_callback,
607
+ timing_callback=record_optimizer_timing,
608
+ )
609
+ if optimizer_batch_size is not None:
610
+ optimizer_kwargs["batch_size"] = optimizer_batch_size
611
+ if self._active_mst_progress_callback is not None:
612
+ self._active_mst_progress_callback(
613
+ 0,
614
+ max(options["n_epochs"], 1),
615
+ "Final embedding optimization",
616
+ )
617
+ final_optimization_started = time.perf_counter()
618
+ optimizer(coordinates, edges, tree_ranks, **optimizer_kwargs)
619
+ self.final_embedding_optimization_time_ = (
620
+ time.perf_counter() - final_optimization_started
621
+ )
622
+ if self._progress_reporter is not None:
623
+ self._progress_reporter.phase_finished(
624
+ "Final embedding optimization",
625
+ self.final_embedding_optimization_time_,
626
+ )
627
+ if self._active_mst_progress_callback is not None:
628
+ self._active_mst_progress_callback(
629
+ options["n_epochs"],
630
+ max(options["n_epochs"], 1),
631
+ "Final embedding optimization",
632
+ )
633
+
634
+ self.embedding_optimization_time_ = time.perf_counter() - embedding_started
635
+ self.optimizer_negative_sampling_time_ = optimizer_profile["negative_sampling"]
636
+ self.optimizer_coordinate_update_time_ = optimizer_profile["coordinate_updates"]
637
+ self.device_ = resolved_device
638
+ self.embedding_ = coordinates.copy()
639
+ self.graph_edges_ = edges.copy()
640
+ self.graph_ranks_ = tree_ranks.copy()
641
+ self.graph_weights_ = 1.0 / tree_ranks.astype(np.float64)
642
+ if X_checked is not None:
643
+ if hasattr(self, "n_samples_fit_"):
644
+ del self.n_samples_fit_
645
+ self.n_features_in_ = X_checked.shape[1]
646
+ if hasattr(X_original, "columns") and all(
647
+ isinstance(column, str) for column in X_original.columns
648
+ ):
649
+ self.feature_names_in_ = np.asarray(X_original.columns, dtype=object)
650
+ elif hasattr(self, "feature_names_in_"):
651
+ del self.feature_names_in_
652
+ self.X_fit_ = X_checked.copy()
653
+ self.graph_input_ = False
654
+ else:
655
+ for name in ("n_features_in_", "feature_names_in_", "X_fit_"):
656
+ if hasattr(self, name):
657
+ delattr(self, name)
658
+ self.n_samples_fit_ = n_samples
659
+ self.graph_input_ = True
660
+ self.fit_time_ = time.perf_counter() - fit_started
661
+ return self
662
+
663
+ def _default_initialization(
664
+ self, rng, pca_features, n_samples, n_components, options
665
+ ):
666
+ if pca_features is not None and options["pca_init"]:
667
+ coordinates = _standardized_pca_initialization(
668
+ pca_features, n_components, self.random_state
669
+ )
670
+ return _scale_initialization_coordinates(
671
+ coordinates, options["pca_init_scaling"]
672
+ ).astype(np.float32)
673
+ return (rng.standard_normal((n_samples, n_components)) * 1e-3).astype(
674
+ np.float32
675
+ )
676
+
677
+ def _multilevel_initialization(
678
+ self,
679
+ n_samples,
680
+ n_components,
681
+ edges,
682
+ ranks,
683
+ resolved_device,
684
+ pca_features,
685
+ options,
686
+ ):
687
+ levels = build_multilevel_hierarchy(
688
+ n_samples,
689
+ edges,
690
+ ranks,
691
+ reduction_ratio=options["multilevel_reduction_ratio"],
692
+ base_size=options["multilevel_base_size"],
693
+ progress_callback=self._active_mst_progress_callback,
694
+ )
695
+ if not levels:
696
+ return None
697
+ if self._progress_reporter is not None:
698
+ self._progress_reporter.begin_multilevel_refinement(
699
+ len(levels), options["multilevel_epochs"]
700
+ )
701
+
702
+ quotient_edges = np.asarray(edges, dtype=np.int64)
703
+ quotient_weights = 1.0 / np.asarray(ranks, dtype=np.float64)
704
+ n_nodes = n_samples
705
+ for labels, _, _ in levels:
706
+ n_nodes = int(labels.max()) + 1
707
+ if quotient_edges.size:
708
+ left, right = labels[quotient_edges[:, 0]], labels[quotient_edges[:, 1]]
709
+ crossing = left != right
710
+ quotient_edges, quotient_weights = _canonical_edges(
711
+ np.column_stack((left[crossing], right[crossing])),
712
+ quotient_weights[crossing],
713
+ )
714
+ else:
715
+ quotient_edges = np.empty((0, 2), dtype=np.int64)
716
+ quotient_weights = np.empty(0, dtype=np.float64)
717
+
718
+ if pca_features is not None and options["pca_init"]:
719
+ if n_nodes < 2:
720
+ coordinates = np.zeros((n_nodes, n_components), dtype=np.float32)
721
+ else:
722
+ coarse_labels = np.arange(n_samples, dtype=np.int64)
723
+ for labels, _, _ in levels:
724
+ coarse_labels = labels[coarse_labels]
725
+ coarse_features = aggregate_features_by_group(
726
+ pca_features, coarse_labels
727
+ )
728
+ coordinates = _standardized_pca_initialization(
729
+ coarse_features, n_components, self.random_state
730
+ )
731
+ coordinates = _scale_initialization_coordinates(
732
+ coordinates, options["pca_init_scaling"]
733
+ ).astype(np.float32)
734
+ else:
735
+ seed_rng = np.random.RandomState(self.random_state)
736
+ coordinates = (
737
+ seed_rng.standard_normal((n_nodes, n_components)) * 1e-3
738
+ ).astype(np.float32)
739
+ optimizer = optimize_embedding
740
+ if resolved_device in {"mps", "cuda"}:
741
+ from functools import partial
742
+
743
+ from ._optimizer_torch import optimize_embedding_torch
744
+
745
+ optimizer = partial(
746
+ optimize_embedding_torch, device_type=resolved_device
747
+ )
748
+ for level_index in range(len(levels), -1, -1):
749
+ level_edges = quotient_edges if level_index == len(levels) else None
750
+ level_weights = quotient_weights if level_index == len(levels) else None
751
+ if level_index != len(levels):
752
+ labels, level_edges, level_weights = levels[level_index]
753
+ if self._active_mst_progress_callback is not None:
754
+ self._active_mst_progress_callback(
755
+ 0,
756
+ max(n_samples, 1),
757
+ f"Expanding level {len(levels) - level_index}",
758
+ )
759
+ coordinates = expand_coordinates(
760
+ labels,
761
+ level_edges,
762
+ level_weights,
763
+ coordinates,
764
+ random_state=None
765
+ if self.random_state is None
766
+ else self.random_state + level_index,
767
+ )
768
+ if self._active_mst_progress_callback is not None:
769
+ self._active_mst_progress_callback(
770
+ n_samples,
771
+ max(n_samples, 1),
772
+ f"Expanded level {len(levels) - level_index}",
773
+ )
774
+ if level_edges.size and options["multilevel_epochs"]:
775
+ if self._active_mst_progress_callback is not None:
776
+ self._active_mst_progress_callback(
777
+ 0,
778
+ options["multilevel_epochs"],
779
+ f"Refining level {level_index + 1}",
780
+ )
781
+ kwargs = dict(
782
+ n_epochs=options["multilevel_epochs"],
783
+ learning_rate=options["learning_rate"],
784
+ negative_ratio=options["negative_ratio"],
785
+ lambda_rep=options["lambda_rep"],
786
+ epsilon=options["epsilon"],
787
+ margin=options["logistic_margin"],
788
+ temperature=options["logistic_temperature"],
789
+ random_state=None
790
+ if self.random_state is None
791
+ else self.random_state + level_index,
792
+ schedule_by_rank=False,
793
+ edge_weights=level_weights,
794
+ progress_callback=self._active_progress_callback,
795
+ )
796
+ if resolved_device in {"mps", "cuda"}:
797
+ kwargs["batch_size"] = options["batch_size"]
798
+ ranks_at_level = np.ones(len(level_edges), dtype=np.int32)
799
+ optimizer(coordinates, level_edges, ranks_at_level, **kwargs)
800
+ if self._active_mst_progress_callback is not None:
801
+ self._active_mst_progress_callback(
802
+ options["multilevel_epochs"],
803
+ options["multilevel_epochs"],
804
+ f"Refined level {level_index + 1}",
805
+ )
806
+ return coordinates
807
+
808
+ @staticmethod
809
+ def _feature_neighbor_graph(
810
+ features: object,
811
+ neighbors: int,
812
+ metric: str,
813
+ ) -> tuple[np.ndarray, np.ndarray]:
814
+ """Build the original feature-space KNN graph used by refinements."""
815
+ from sklearn.neighbors import NearestNeighbors
816
+
817
+ n_samples = features.shape[0]
818
+ k = min(int(neighbors), n_samples - 1)
819
+ index = NearestNeighbors(
820
+ n_neighbors=min(k + 1, n_samples), metric=metric, n_jobs=-1
821
+ ).fit(features)
822
+ distances, indices = index.kneighbors(features, return_distance=True)
823
+ result_indices = np.empty((n_samples, k), dtype=np.int64)
824
+ result_distances = np.empty((n_samples, k), dtype=np.float64)
825
+ for row in range(n_samples):
826
+ keep = indices[row] != row
827
+ row_indices = indices[row, keep][:k]
828
+ row_distances = distances[row, keep][:k]
829
+ order = np.argsort(row_distances, kind="stable")
830
+ result_indices[row] = row_indices[order]
831
+ result_distances[row] = row_distances[order]
832
+ return result_indices, result_distances
833
+
834
+ def _apply_mean_shift(
835
+ self,
836
+ options: dict[str, object],
837
+ ) -> None:
838
+ """Apply mean shift after gravity using base-layout neighbors."""
839
+ self.embedding_before_mean_shift_ = self.embedding_.copy()
840
+ self.mean_shift_neighbor_search_time_ = 0.0
841
+ self.mean_shift_time_ = 0.0
842
+ self.mean_shift_iterations_ = 0
843
+ iterations = int(options["mean_shift_iterations"])
844
+ step_size = float(options["mean_shift_step_size"])
845
+ self.mean_shift_neighbor_graph_reused_ = False
846
+ if iterations == 0 or step_size == 0.0:
847
+ return
848
+
849
+ from ._mean_shift import embedding_neighbor_indices, gaussian_mean_shift_layout
850
+
851
+ started = time.perf_counter()
852
+ base_layout = self.embedding_before_gravity_[:, :2]
853
+ neighbor_indices = embedding_neighbor_indices(
854
+ base_layout,
855
+ min(int(options["mean_shift_neighbors"]), len(self.embedding_) - 1),
856
+ )
857
+ self.mean_shift_neighbor_search_time_ = time.perf_counter() - started
858
+ self.mean_shift_neighbor_graph_reused_ = True
859
+ refined, diagnostics = gaussian_mean_shift_layout(
860
+ self.embedding_[:, :2],
861
+ neighbor_indices=neighbor_indices,
862
+ neighbors=min(int(options["mean_shift_neighbors"]), len(self.embedding_) - 1),
863
+ bandwidth_factor=float(options["mean_shift_bandwidth_factor"]),
864
+ step_size=step_size,
865
+ iterations=iterations,
866
+ )
867
+ self.embedding_[:, :2] = refined
868
+ self.mean_shift_time_ = time.perf_counter() - started
869
+ self.mean_shift_iterations_ = int(diagnostics["iterations"])
870
+
871
+ def fit(self, X: object, y: object = None) -> "IteratedMinimumSpanningTreeEmbedder":
872
+ """Fit the embedding and store coordinates for the input rows.
873
+
874
+ Dense and CSR feature matrices are accepted. By default, standardized
875
+ PCA scores are uniformly scaled by their global maximum absolute value
876
+ so every coordinate fits in ``[-1, 1]``. Set
877
+ ``pca_init_scaling="none"`` to preserve raw magnitudes, or
878
+ ``pca_init=False`` to use the seeded random start. Supplying
879
+ ``init_coordinates`` starts from those coordinates instead and takes
880
+ precedence over either setting.
881
+
882
+ Successful fits expose stage timings in seconds: `graph_construction_time_`,
883
+ `multilevel_initialization_time_`, `final_embedding_optimization_time_`,
884
+ `embedding_optimization_time_`, `optimizer_negative_sampling_time_`,
885
+ `optimizer_coordinate_update_time_`, and total `fit_time_`. Gravity fits
886
+ also expose `gravity_neighbor_search_time_` and
887
+ `gravity_neighbor_graph_reused_`. Feature based FAMST gravity fits expose
888
+ the high-dimensional graph used by gravity as
889
+ `feature_neighbor_graph_`. Mean shift runs after gravity and exposes
890
+ its stage time and iteration count. GPU backends report negative
891
+ sampling and coordinate updates as one combined duration to avoid
892
+ per-batch device event recording on long fits.
893
+ """
894
+ fit_started = time.perf_counter()
895
+ del y # Unsupervised: labels are intentionally never used.
896
+ options = self._validated_fit_options()
897
+ for name in ("feature_neighbor_graph_", "feature_neighbor_graph_reused_"):
898
+ if hasattr(self, name):
899
+ delattr(self, name)
900
+ X_checked = check_array(
901
+ X, dtype=np.float64, ensure_2d=True, accept_sparse="csr"
902
+ )
903
+ if issparse(X_checked):
904
+ X_checked = csr_matrix(X_checked)
905
+ # Cosine distance depends only on row direction. Normalize with a
906
+ # scale-first algorithm so very large finite inputs cannot overflow
907
+ # scikit-learn's dot products during distance calculation or PCA init.
908
+ metric_features = (
909
+ _cosine_safe_normalize(X_checked)
910
+ if options["metric"] == "cosine"
911
+ else X_checked
912
+ )
913
+ n_samples = X_checked.shape[0]
914
+ if n_samples < 2:
915
+ raise ValueError("X must contain at least two samples to construct an MST.")
916
+ if options["include_knn_attraction"] and n_samples <= max(
917
+ options["mst_neighbors"], 2 * options["n_msts"]
918
+ ) + 1:
919
+ raise ValueError(
920
+ "include_knn_attraction requires enough samples for FAMST "
921
+ "approximate-neighbor search."
922
+ )
923
+ self._activate_progress_reporting()
924
+ graph_started = time.perf_counter()
925
+ candidate_neighbor_edges: list[np.ndarray] = []
926
+ gravity_neighbor_graphs: list[tuple[np.ndarray, np.ndarray]] = []
927
+ candidate_edges_callback = (
928
+ candidate_neighbor_edges.append
929
+ if options["include_knn_attraction"]
930
+ else None
931
+ )
932
+
933
+ refinements_need_graph = options["gravity_enabled"]
934
+ feature_graph_width = options["gravity_neighbors"]
935
+ reuse_graph_for_refinements = (
936
+ self.mst_method == "famst"
937
+ and options["metric"] == "euclidean"
938
+ and not issparse(X_checked)
939
+ )
940
+
941
+ def capture_gravity_neighbor_graph(
942
+ indices: np.ndarray, distances: np.ndarray
943
+ ) -> None:
944
+ gravity_neighbor_graphs.append((indices, distances))
945
+
946
+ edges, tree_ranks = build_mst_edges(
947
+ metric_features,
948
+ n_msts=options["n_msts"],
949
+ random_state=self.random_state,
950
+ method=self.mst_method,
951
+ neighbors=options["mst_neighbors"],
952
+ inter_component_edges=options["inter_component_edges"],
953
+ max_neighbors=options["max_neighbors"],
954
+ representatives_per_component=options["representatives_per_component"],
955
+ neighbor_device=options["resolved_device"],
956
+ neighbor_backend=options["mst_neighbor_backend"],
957
+ progress_callback=self._active_mst_progress_callback,
958
+ return_ranks=True,
959
+ metric=options["metric"],
960
+ candidate_edges_callback=candidate_edges_callback,
961
+ neighbor_graph_callback=capture_gravity_neighbor_graph
962
+ if reuse_graph_for_refinements else None,
963
+ neighbor_graph_neighbors=feature_graph_width
964
+ if reuse_graph_for_refinements else None,
965
+ )
966
+ tree_ranks = np.asarray(tree_ranks, dtype=np.int32)
967
+ if options["include_knn_attraction"]:
968
+ if not candidate_neighbor_edges:
969
+ raise RuntimeError(
970
+ "FAMST did not expose candidate neighbors for attraction; "
971
+ "try a larger input or disable include_knn_attraction."
972
+ )
973
+ edges, tree_ranks = _append_candidate_attraction_edges(
974
+ edges,
975
+ tree_ranks,
976
+ candidate_neighbor_edges[-1],
977
+ n_samples,
978
+ )
979
+ self.graph_construction_time_ = time.perf_counter() - graph_started
980
+ if self._progress_reporter is not None:
981
+ self._progress_reporter.phase_finished(
982
+ "MST graph construction", self.graph_construction_time_
983
+ )
984
+ self._fit_edges(
985
+ n_samples=n_samples,
986
+ n_components=options["n_components"],
987
+ edges=edges,
988
+ tree_ranks=tree_ranks,
989
+ fit_started=fit_started,
990
+ resolved_device=options["resolved_device"],
991
+ schedule_by_rank=self.mst_method != "prim",
992
+ X_checked=X_checked,
993
+ X_original=X,
994
+ initialization_features=metric_features,
995
+ initial_coordinates=self.init_coordinates,
996
+ **{
997
+ name: value
998
+ for name, value in options.items()
999
+ if name not in {
1000
+ "n_components", "n_msts", "resolved_device",
1001
+ "mst_neighbor_backend", "include_knn_attraction",
1002
+ "gravity_neighbors", "gravity_resolution",
1003
+ "gravity_strength", "gravity_core_quantile",
1004
+ "gravity_mass_power",
1005
+ "gravity_pack_regions", "gravity_pack_radius_quantile",
1006
+ "gravity_pack_gap_fraction",
1007
+ "gravity_enabled", "mean_shift_neighbors",
1008
+ "mean_shift_bandwidth_factor", "mean_shift_step_size",
1009
+ "mean_shift_iterations",
1010
+ }
1011
+ },
1012
+ )
1013
+ self.embedding_before_gravity_ = self.embedding_.copy()
1014
+ self.imste_fit_time_ = self.fit_time_
1015
+ feature_neighbor_graph = gravity_neighbor_graphs[-1] if gravity_neighbor_graphs else None
1016
+ if feature_neighbor_graph is not None:
1017
+ self.feature_neighbor_graph_ = feature_neighbor_graph
1018
+ self.feature_neighbor_graph_reused_ = True
1019
+ else:
1020
+ self.feature_neighbor_graph_reused_ = False
1021
+ if refinements_need_graph and feature_neighbor_graph is None:
1022
+ feature_neighbor_graph = self._feature_neighbor_graph(
1023
+ metric_features,
1024
+ feature_graph_width,
1025
+ options["metric"],
1026
+ )
1027
+ self.feature_neighbor_graph_ = feature_neighbor_graph
1028
+ if options["gravity_enabled"] and n_samples >= 3:
1029
+ if issparse(X_checked):
1030
+ raise ValueError("gravity refinement currently requires dense features.")
1031
+ from ._gravity import density_gravity_layout
1032
+
1033
+ gravity_started = time.perf_counter()
1034
+ gravity_embedding, gravity_diagnostics = density_gravity_layout(
1035
+ X_checked,
1036
+ self.embedding_before_gravity_[:, :2],
1037
+ neighbors=min(options["gravity_neighbors"], n_samples - 1),
1038
+ resolution=options["gravity_resolution"],
1039
+ random_state=42 if self.random_state is None else self.random_state,
1040
+ core_quantile=options["gravity_core_quantile"],
1041
+ strength=options["gravity_strength"],
1042
+ mass_power=options["gravity_mass_power"],
1043
+ pack_regions=options["gravity_pack_regions"],
1044
+ pack_radius_quantile=options["gravity_pack_radius_quantile"],
1045
+ pack_gap_fraction=options["gravity_pack_gap_fraction"],
1046
+ feature_neighbor_graph=feature_neighbor_graph,
1047
+ feature_neighbor_metric=(
1048
+ "euclidean" if feature_neighbor_graph is not None else None
1049
+ ),
1050
+ )
1051
+ self.embedding_ = self.embedding_before_gravity_.copy()
1052
+ self.embedding_[:, :2] = gravity_embedding
1053
+ self.gravity_membership_ = gravity_diagnostics["membership"]
1054
+ self.gravity_point_mass_ = gravity_diagnostics["point_mass"]
1055
+ self.gravity_region_count_ = int(gravity_diagnostics["region_count"])
1056
+ self.gravity_regions_packed_ = bool(gravity_diagnostics["regions_packed"])
1057
+ self.gravity_graph_construction_time_ = float(
1058
+ gravity_diagnostics["graph_seconds"]
1059
+ )
1060
+ self.gravity_neighbor_search_time_ = float(
1061
+ gravity_diagnostics["neighbor_search_seconds"]
1062
+ )
1063
+ self.gravity_neighbor_graph_reused_ = bool(
1064
+ gravity_diagnostics["neighbor_graph_reused"]
1065
+ )
1066
+ self.gravity_force_time_ = float(gravity_diagnostics["force_seconds"])
1067
+ self.gravity_time_ = time.perf_counter() - gravity_started
1068
+ else:
1069
+ self.gravity_region_count_ = 0
1070
+ self.gravity_regions_packed_ = False
1071
+ self.gravity_graph_construction_time_ = 0.0
1072
+ self.gravity_neighbor_search_time_ = 0.0
1073
+ self.gravity_neighbor_graph_reused_ = False
1074
+ self.gravity_force_time_ = 0.0
1075
+ self.gravity_time_ = 0.0
1076
+ for name in ("gravity_membership_", "gravity_point_mass_"):
1077
+ if hasattr(self, name):
1078
+ delattr(self, name)
1079
+ if hasattr(self, "gravity_skipped_reason_"):
1080
+ del self.gravity_skipped_reason_
1081
+ self._apply_mean_shift(options)
1082
+ self.fit_time_ = time.perf_counter() - fit_started
1083
+ if self._progress_reporter is not None:
1084
+ self._progress_reporter.finish()
1085
+ return self
1086
+
1087
+ def fit_transform(
1088
+ self,
1089
+ X: object,
1090
+ y: object = None,
1091
+ *,
1092
+ return_intermediate: bool = False,
1093
+ ) -> np.ndarray | tuple[np.ndarray, np.ndarray]:
1094
+ """Fit and return final coordinates, optionally with the base layout.
1095
+
1096
+ When ``return_intermediate=True``, return a pair containing the
1097
+ optimized IMSTE coordinates before refinement and the final coordinates
1098
+ after gravity and mean shift. Disabled refinements leave the corresponding
1099
+ stage unchanged.
1100
+ """
1101
+ if not isinstance(return_intermediate, (bool, np.bool_)):
1102
+ raise ValueError("return_intermediate must be a boolean.")
1103
+ self.fit(X, y=y)
1104
+ if return_intermediate:
1105
+ return self.embedding_before_gravity_.copy(), self.embedding_.copy()
1106
+ return self.embedding_.copy()