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/__init__.py +15 -0
- imste/_api.py +28 -0
- imste/_estimator.py +1106 -0
- imste/_estimator_graph.py +241 -0
- imste/_estimator_utils.py +249 -0
- imste/_gravity.py +295 -0
- imste/_mean_shift.py +87 -0
- imste/_multilevel.py +259 -0
- imste/_optimizer.py +355 -0
- imste/_optimizer_mps.py +8 -0
- imste/_optimizer_torch.py +296 -0
- imste/_progress.py +261 -0
- imste/_visualization_class_geometry.py +612 -0
- imste/_visualization_core.py +607 -0
- imste/_visualization_interactive.py +453 -0
- imste/class_graph.py +444 -0
- imste/inductive.py +394 -0
- imste/losses.py +45 -0
- imste/mst/__init__.py +62 -0
- imste/mst/famst.py +963 -0
- imste/mst/graph.py +141 -0
- imste/mst/prim.py +283 -0
- imste/visualization.py +31 -0
- imste-0.2.1.dist-info/METADATA +544 -0
- imste-0.2.1.dist-info/RECORD +28 -0
- imste-0.2.1.dist-info/WHEEL +5 -0
- imste-0.2.1.dist-info/licenses/LICENSE +21 -0
- imste-0.2.1.dist-info/top_level.txt +1 -0
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()
|