imste 0.2.1__tar.gz

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.
Files changed (38) hide show
  1. imste-0.2.1/LICENSE +21 -0
  2. imste-0.2.1/PKG-INFO +544 -0
  3. imste-0.2.1/README.md +497 -0
  4. imste-0.2.1/imste/__init__.py +15 -0
  5. imste-0.2.1/imste/_api.py +28 -0
  6. imste-0.2.1/imste/_estimator.py +1106 -0
  7. imste-0.2.1/imste/_estimator_graph.py +241 -0
  8. imste-0.2.1/imste/_estimator_utils.py +249 -0
  9. imste-0.2.1/imste/_gravity.py +295 -0
  10. imste-0.2.1/imste/_mean_shift.py +87 -0
  11. imste-0.2.1/imste/_multilevel.py +259 -0
  12. imste-0.2.1/imste/_optimizer.py +355 -0
  13. imste-0.2.1/imste/_optimizer_mps.py +8 -0
  14. imste-0.2.1/imste/_optimizer_torch.py +296 -0
  15. imste-0.2.1/imste/_progress.py +261 -0
  16. imste-0.2.1/imste/_visualization_class_geometry.py +612 -0
  17. imste-0.2.1/imste/_visualization_core.py +607 -0
  18. imste-0.2.1/imste/_visualization_interactive.py +453 -0
  19. imste-0.2.1/imste/class_graph.py +444 -0
  20. imste-0.2.1/imste/inductive.py +394 -0
  21. imste-0.2.1/imste/losses.py +45 -0
  22. imste-0.2.1/imste/mst/__init__.py +62 -0
  23. imste-0.2.1/imste/mst/famst.py +963 -0
  24. imste-0.2.1/imste/mst/graph.py +141 -0
  25. imste-0.2.1/imste/mst/prim.py +283 -0
  26. imste-0.2.1/imste/visualization.py +31 -0
  27. imste-0.2.1/imste.egg-info/PKG-INFO +544 -0
  28. imste-0.2.1/imste.egg-info/SOURCES.txt +36 -0
  29. imste-0.2.1/imste.egg-info/dependency_links.txt +1 -0
  30. imste-0.2.1/imste.egg-info/requires.txt +28 -0
  31. imste-0.2.1/imste.egg-info/top_level.txt +1 -0
  32. imste-0.2.1/pyproject.toml +57 -0
  33. imste-0.2.1/setup.cfg +4 -0
  34. imste-0.2.1/tests/test_arxiv_notebook_helpers.py +60 -0
  35. imste-0.2.1/tests/test_estimator.py +753 -0
  36. imste-0.2.1/tests/test_famst.py +380 -0
  37. imste-0.2.1/tests/test_multilevel.py +82 -0
  38. imste-0.2.1/tests/test_optimizer.py +263 -0
imste-0.2.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Fabrizio Costa
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
imste-0.2.1/PKG-INFO ADDED
@@ -0,0 +1,544 @@
1
+ Metadata-Version: 2.4
2
+ Name: imste
3
+ Version: 0.2.1
4
+ Summary: Iterated Minimum Spanning Tree Embedding (IMSTE)
5
+ Author: Fabrizio Costa
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/fabriziocosta/IteratedMinimumSpanningTree
8
+ Project-URL: Repository, https://github.com/fabriziocosta/IteratedMinimumSpanningTree
9
+ Project-URL: Issues, https://github.com/fabriziocosta/IteratedMinimumSpanningTree/issues
10
+ Project-URL: Documentation, https://github.com/fabriziocosta/IteratedMinimumSpanningTree/tree/main/docs
11
+ Keywords: embedding,dimensionality-reduction,minimum-spanning-tree,manifold-learning
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: numpy>=1.23
22
+ Requires-Dist: scipy>=1.9
23
+ Requires-Dist: scikit-learn>=1.2
24
+ Requires-Dist: numba>=0.58
25
+ Requires-Dist: joblib>=1.3
26
+ Requires-Dist: pynndescent>=0.5.13
27
+ Requires-Dist: rinnd>=0.3.1
28
+ Requires-Dist: igraph>=0.11
29
+ Requires-Dist: leidenalg>=0.10
30
+ Provides-Extra: gpu
31
+ Requires-Dist: torch>=2.0; extra == "gpu"
32
+ Provides-Extra: test
33
+ Requires-Dist: pytest>=7; extra == "test"
34
+ Requires-Dist: pandas>=2.0; extra == "test"
35
+ Requires-Dist: torch>=2.0; extra == "test"
36
+ Provides-Extra: notebook
37
+ Requires-Dist: matplotlib>=3.7; extra == "notebook"
38
+ Requires-Dist: pandas>=2.0; extra == "notebook"
39
+ Requires-Dist: umap-learn>=0.6.0; extra == "notebook"
40
+ Requires-Dist: plotly>=5.18; extra == "notebook"
41
+ Requires-Dist: ipywidgets>=8; extra == "notebook"
42
+ Requires-Dist: psutil>=5.9; extra == "notebook"
43
+ Requires-Dist: datashader>=0.15; extra == "notebook"
44
+ Requires-Dist: tqdm>=4.65; extra == "notebook"
45
+ Requires-Dist: yt>=4.4; extra == "notebook"
46
+ Dynamic: license-file
47
+
48
+ # IMSTE
49
+
50
+ **Iterated Minimum Spanning Tree Embedding (IMSTE)** is a scikit-learn
51
+ transformer for learning low-dimensional coordinates from numeric data. It
52
+ builds a weighted graph from ranked minimum spanning trees, then
53
+ optimizes one coordinate vector per sample.
54
+
55
+ The package has two explicit estimators: `IteratedMinimumSpanningTreeEmbedder`
56
+ learns coordinates for the training rows, while `InductiveIMSTE` also learns
57
+ an MLP that maps new rows into that space.
58
+
59
+ ## Install
60
+
61
+ After the first PyPI release, install the core package with:
62
+
63
+ ```bash
64
+ python -m pip install imste
65
+ ```
66
+
67
+ From a source checkout:
68
+
69
+ ```bash
70
+ python -m pip install .
71
+ ```
72
+
73
+ For the PyTorch GPU optimizer, inductive estimator, and differentiable loss
74
+ functions, install the optional PyTorch extra:
75
+
76
+ ```bash
77
+ python -m pip install "imste[gpu]"
78
+ ```
79
+
80
+ From a source checkout, use `python -m pip install ".[gpu]"` instead.
81
+
82
+ CPU use does not require PyTorch; `device="auto"` falls back to the CPU
83
+ optimizer when PyTorch or a supported GPU is unavailable. For notebooks, install
84
+ the optional plotting and widget dependencies:
85
+
86
+ ```bash
87
+ python -m pip install "imste[notebook]"
88
+ ```
89
+
90
+ From a source checkout, use `python -m pip install ".[notebook]"` instead.
91
+
92
+ For maintainers preparing a release, see the
93
+ [release guide](docs/releasing.md).
94
+
95
+ Both estimators accept dense arrays and SciPy CSR matrices. The graph builders
96
+ keep CSR inputs sparse. `InductiveIMSTE` densifies only each MLP mini-batch.
97
+ The default FAMST graph builder uses RINND for dense Euclidean inputs and
98
+ PyNNDescent for sparse inputs. Both are core dependencies. The neighbor-search
99
+ backend can be selected independently from the optimizer's `device`; on dense
100
+ MPS inputs, exact chunked search is also available. To use only the exact Prim
101
+ builder, select `mst_method="prim"`.
102
+
103
+ For an existing sparse graph whose stored values are distances, use
104
+ `fit_graph()` or `fit_graph_transform()` instead of passing the matrix to
105
+ `fit()` (which treats rows as feature vectors). Supply a square SciPy sparse matrix with finite,
106
+ non-negative values. Each stored off-diagonal entry is an edge; implicit zeros
107
+ are absent edges, while explicitly stored zero-distance edges are retained.
108
+ Edges are treated as undirected, and reciprocal entries use the smaller
109
+ distance. Disconnected components remain separate spanning forests. Each
110
+ iteration prefers unused edges; when needed, it reuses short edges and
111
+ increments their rank. The optimizer uses the usual inverse-rank attraction
112
+ weights. Optionally pass `init_features` with one feature row per graph node to
113
+ seed the coordinates from standardized PCA scores. These features affect only
114
+ initialization; the supplied graph remains the optimizer's objective. Without
115
+ `init_features`, seeded random initialization is used. Use `fit_graph()` when
116
+ you need the fitted estimator and `fit_graph_transform()` when you only need
117
+ the embedding array.
118
+
119
+ ## Quick start
120
+
121
+ IMSTE uses Euclidean distance by default and also supports cosine distance
122
+ with `metric="cosine"`. Gravity is automatically skipped for cosine fits;
123
+ mean shift remains available. Scale features first when they have different ranges.
124
+ This small example uses scikit-learn's built-in
125
+ digits dataset, so it does not need a download:
126
+
127
+ ```python
128
+ import matplotlib.pyplot as plt
129
+ from sklearn.datasets import load_digits
130
+ from sklearn.preprocessing import StandardScaler
131
+
132
+ from imste import IteratedMinimumSpanningTreeEmbedder
133
+
134
+ digits = load_digits()
135
+ X = StandardScaler().fit_transform(digits["data"])
136
+
137
+ mapper = IteratedMinimumSpanningTreeEmbedder()
138
+ embedding = mapper.fit_transform(X)
139
+
140
+ plt.scatter(embedding[:, 0], embedding[:, 1], c=digits.target, cmap="tab10", s=10)
141
+ ```
142
+
143
+ ### Fit from a distance graph
144
+
145
+ This example builds a complete pairwise distance graph from the built-in
146
+ digits data, then calls `fit_graph_transform()` to return only the embedding:
147
+
148
+ ```python
149
+ import matplotlib.pyplot as plt
150
+ from scipy.sparse import csr_matrix
151
+ from sklearn.datasets import load_digits
152
+ from scipy.spatial.distance import cdist
153
+ from sklearn.preprocessing import StandardScaler
154
+
155
+ from imste import IteratedMinimumSpanningTreeEmbedder
156
+
157
+ digits = load_digits()
158
+ X = StandardScaler().fit_transform(digits.data)
159
+
160
+ # The complete digits distance matrix is small enough to hold in memory.
161
+ distance_matrix = cdist(X, X, metric="euclidean")
162
+ distance_graph = csr_matrix(distance_matrix)
163
+
164
+ graph_embedding = IteratedMinimumSpanningTreeEmbedder().fit_graph_transform(distance_graph)
165
+
166
+ plt.scatter(graph_embedding[:, 0], graph_embedding[:, 1], c=digits.target, cmap="tab10", s=10)
167
+ ```
168
+
169
+ Pairwise distance matrices grow quadratically, so for larger datasets prefer
170
+ constructing a sparse neighbor graph directly.
171
+
172
+ For larger datasets, FAMST is the default sparse approximate builder. To use
173
+ the exact Prim builder instead, set `mst_method="prim"`:
174
+
175
+ ```python
176
+ mapper = IteratedMinimumSpanningTreeEmbedder(
177
+ n_msts=5,
178
+ mst_method="famst",
179
+ mst_neighbors=15,
180
+ mst_inter_component_edges=5,
181
+ random_state=42,
182
+ )
183
+ embedding = mapper.fit_transform(X)
184
+ ```
185
+
186
+ FAMST starts with an approximate k-nearest-neighbor graph. It samples up to
187
+ `mst_representatives_per_component` points from each component, builds an exact
188
+ MST over those representatives, and searches bridge candidates only for the
189
+ unique component pairs crossed by that MST. The default representative cap is
190
+ 10. It refines those connections and extracts trees from the sparse candidate
191
+ graph. FAMST can increase the neighbor count when needed, up to
192
+ `mst_max_neighbors` (by default, four times `mst_neighbors`). If earlier trees
193
+ leave a local bottleneck, later trees reuse only the edges needed to reconnect
194
+ the residual components. Every reuse increments that edge's rank, lowering its
195
+ attraction weight to `1 / rank`. The requested `n_msts` is therefore the number
196
+ of tree iterations, not a promise that every edge is unique across trees. The
197
+ result is approximate and is not guaranteed to match the trees from the
198
+ complete graph for the selected metric. Cosine metric uses exact Prim even
199
+ when `mst_method="famst"`, since FAMST's refinement is Euclidean-specific.
200
+ The sparse mode also samples negative pairs without
201
+ allocating the core estimator's quadratic adjacency bit matrix. The
202
+ implementation follows Almansoori and Telek's
203
+ [FAMST paper](https://arxiv.org/abs/2507.14261).
204
+
205
+ The optimizer normally attracts along ranked MST edges only. For a denser
206
+ local objective, `include_knn_attraction=True` also attracts along FAMST's
207
+ approximate candidate-neighbor edges as rank-one positive edges. This option
208
+ is available for Euclidean `fit(X)` calls with `mst_method="famst"`; it
209
+ increases optimization graph size
210
+ and can change neighborhood fidelity. The
211
+ [balanced arXiv experiment notebook](notebooks/arxiv_balanced_exp.ipynb)
212
+ compares this option with PCA/multilevel and UMAP-warm-start initializations on
213
+ a deterministic, class-balanced subset.
214
+
215
+ The labels are not passed to the estimator. Use them afterward to color or
216
+ score a visualization if needed.
217
+
218
+ ## How it works
219
+
220
+ ### Build a graph
221
+
222
+ The estimator computes pairwise distances using `metric`, constructs `n_msts`
223
+ spanning-tree iterations, and joins their ranked edges into one graph. An edge
224
+ used for the first time receives that tree's rank. When a bottleneck requires
225
+ reusing it, its rank increments by one, so the repeated edge receives less
226
+ weight. For the approximate FAMST graph, an edge of rank `r` is scheduled once
227
+ every `r` epochs on average. Exact Prim processes every edge each epoch and
228
+ scales its attraction by `1 / r`. Both modes use the same normalized
229
+ inverse-rank objective. The estimator exposes these integer ranks as
230
+ `graph_ranks_` and weights as `graph_weights_ = 1 / rank`.
231
+
232
+ ### Optimize coordinates
233
+
234
+ The embedding objective uses squared Euclidean distances. For an embedded pair
235
+ `i, j`, let `d² = sum((y_i - y_j) ** 2)`. Graph edges use logarithmic
236
+ attraction, `log1p(d² + epsilon)`. Sampled non-edges use logistic repulsion,
237
+ `softplus((logistic_margin - d²) / logistic_temperature)`.
238
+
239
+ `lambda_rep` sets the repulsion share of the objective; attraction receives
240
+ `1 - lambda_rep`. Positive and negative updates use the corresponding mean
241
+ reductions; attraction uses `sum(1 / graph_ranks_)` as its normalizer. Each
242
+ positive edge contributes `negative_ratio`
243
+ sampled non-neighbors from each eligible endpoint. The CPU Numba optimizer uses
244
+ float32 coordinates, linear learning-rate decay, and recenters once per epoch.
245
+ It rescales the mean objective by sample count to retain a useful per-coordinate
246
+ SGD step size. The optional GPU backend applies each epoch's edge updates as a
247
+ batch, so its update trajectory differs from the sequential CPU optimizer.
248
+ Fixed seeds reproduce CPU runs with the same implementation; GPU batch
249
+ accumulation can introduce small floating-point differences. CPU and GPU
250
+ coordinates need not match each other or the former Adam optimizer.
251
+
252
+ The default `mst_method="famst"` builds an approximate sparse graph. It can
253
+ increase the neighbor count as needed, subject to `mst_max_neighbors`, then
254
+ reuse bottleneck edges with an increasing rank penalty. Select
255
+ `mst_method="prim"` for exact trees. Dense input uses quadratic pairwise
256
+ memory; CSR input avoids the all-pairs distance matrix but still takes
257
+ quadratic time.
258
+
259
+ ## Choose how to transform rows
260
+
261
+ ### Transductive: training rows only
262
+
263
+ Use the core estimator when you want optimized coordinates for the fitted
264
+ rows. Its `transform` accepts only the exact training matrix in its original
265
+ row order; it raises an error for new or reordered rows.
266
+
267
+ ```python
268
+ from imste import IteratedMinimumSpanningTreeEmbedder
269
+
270
+ mapper = IteratedMinimumSpanningTreeEmbedder(n_msts=10).fit(X_train)
271
+ Z_train = mapper.transform(X_train)
272
+ ```
273
+
274
+ ### Inductive: map new rows with an MLP
275
+
276
+ Import `InductiveIMSTE` from the explicit `imste.inductive` module. It fits a
277
+ transductive IMSTE embedding, then trains an MLP to predict those coordinates:
278
+
279
+ ```python
280
+ from imste import IteratedMinimumSpanningTreeEmbedder
281
+ from imste.inductive import InductiveIMSTE
282
+
283
+ mapper = InductiveIMSTE(
284
+ embedder=IteratedMinimumSpanningTreeEmbedder(
285
+ n_msts=10,
286
+ random_state=42,
287
+ ),
288
+ n_layers=6,
289
+ layer_size=128,
290
+ dropout=0.1,
291
+ min_epochs=100,
292
+ patience=20,
293
+ ).fit(X_train)
294
+
295
+ Z_train = mapper.transform(X_train) # MLP predictions for training rows
296
+ Z_new = mapper.transform(X_new) # MLP predictions for new rows
297
+ Z_reference = mapper.reference_embedding_ # exact optimized IMSTE coordinates
298
+ ```
299
+
300
+ `InductiveIMSTE.transform` always uses the MLP, including for training rows.
301
+ Its `reference_embedding_` contains the exact transductive coordinates that
302
+ serve as MLP targets. The MLP standardizes its inputs and targets, holds out
303
+ 10% of the input rows for validation, and restores the checkpoint with the
304
+ best validation loss. The IMSTE coordinates use all input rows; the validation
305
+ split only controls MLP early stopping. Predictions approximate the reference
306
+ embedding and do not extend or re-optimize its graph.
307
+
308
+ ## Render an embedding
309
+
310
+ Reusable Matplotlib renderers for the KDE density-parent tree, kNN hull union,
311
+ and fitted ellipses, plus an interactive label-guided force viewer, live in
312
+ `imste.visualization`. Install the notebook extras first
313
+ (`python -m pip install "imste[notebook]"`), then pass
314
+ an embedding and either a one-dimensional label vector or a metadata DataFrame.
315
+ For dense embeddings, `render_datashader_embedding` rasterizes the point cloud
316
+ instead of drawing every point individually. It returns a Datashader image,
317
+ supports categorical labels and custom colors, and accepts coordinate ranges
318
+ for zoomed views. Set `spread_px` to enlarge all marks by a fixed pixel radius,
319
+ or use `max_spread_px` for density-aware spreading of sparse regions.
320
+
321
+ ```python
322
+ from imste.visualization import (
323
+ interactive_force,
324
+ plot_density_parent_tree,
325
+ plot_ellipses,
326
+ plot_knn_union,
327
+ render_datashader_embedding,
328
+ )
329
+ from IPython.display import display
330
+
331
+ fig, ax = plot_knn_union(
332
+ mapper, labels, k=7, cv_neighbors=30, cv_splits=5,
333
+ distance_std_threshold=0.75,
334
+ )
335
+ fig, ax = plot_ellipses(
336
+ mapper, labels, k=7, n_std=2.0, max_ellipses_per_region=2,
337
+ )
338
+ fig, ax = plot_density_parent_tree(mapper, labels, label_key="cell_type")
339
+ viewer = interactive_force(
340
+ mapper, labels, initial_k=10, initial_iterations=20,
341
+ )
342
+ display(viewer)
343
+ image = render_datashader_embedding(mapper, labels, width=1200, height=900)
344
+ display(image)
345
+ ```
346
+
347
+ For a DataFrame, select its label column with `label_key="cell_type"`. Each
348
+ renderer returns its Matplotlib figure and axes, except `interactive_force`,
349
+ which returns an `ipywidgets` viewer. The force controls adjust same-label
350
+ springs, different-label repulsion, iteration count, and movement. Renderers
351
+ accept a fitted `IteratedMinimumSpanningTreeEmbedder` or `InductiveIMSTE`
352
+ directly; they use `embedding_` or the inductive model's `reference_embedding_`.
353
+ Raw coordinate arrays remain supported.
354
+
355
+ For class-level graph overlays across one or more embeddings, use
356
+ `imste.class_graph.plot_class_mixture_mst`. It fits full-covariance Gaussian
357
+ mixtures per class in each 2D embedding, connects their component centers with
358
+ iterated MSTs, and maps symmetric cross-component posterior probability to
359
+ edge opacity. For each edge, the two endpoint Gaussian densities form an
360
+ equal-prior pairwise posterior, evaluated on the samples assigned to the
361
+ opposite component in each direction. The directional probabilities are
362
+ averaged to score the edge; chance-level overlap (0.5) is fully opaque. It
363
+ returns the figure, plot axes, and a table of per-edge scores.
364
+
365
+ To compare the class-pair relations selected by two embedding graphs, use
366
+ `imste.class_graph.compare_class_graph_relations`. It collapses component
367
+ edges to unordered class pairs, removes duplicate edges across MST iterations,
368
+ and ranks relations present in only one graph by mean chance-normalized edge
369
+ error. The per-edge maximum and component pairs remain available for review.
370
+
371
+ ## Parameters
372
+
373
+ For the experiment notebooks, the main settings to adjust are:
374
+
375
+ ```python
376
+ IMSTE_N_MSTS = 3
377
+ IMSTE_N_EPOCHS = 200
378
+ IMSTE_GRAVITY_STRENGTH = 0.2
379
+ IMSTE_MEAN_SHIFT_ITERATIONS = 1
380
+ ```
381
+
382
+ These set the number of MSTs, optimizer epochs, gravity strength, and mean-shift
383
+ iterations. Keep the other IMSTE settings at their defaults unless a specific
384
+ experiment calls for changing them. The table below lists the estimator's
385
+ library defaults; notebook recommendations can intentionally differ.
386
+
387
+ | Parameter | Default | Meaning |
388
+ | --- | ---: | --- |
389
+ | `n_msts` | `15` | Number of spanning-tree iterations; bottleneck edge reuse is penalized by incrementing its rank |
390
+ | `n_components` | `2` | Embedding dimensions |
391
+ | `pca_init` | `True` | Initialize `fit(X)` with PCA on feature-wise standardized inputs; extra PCA dimensions are zero-filled |
392
+ | `pca_init_scaling` | `"global"` | Apply one uniform scale to fit all PCA coordinates into `[-1, 1]`, or use `"none"` to preserve raw magnitudes |
393
+ | `multilevel_init` | `True` | Use rank-only graph coarsening and coarse-to-fine initialization |
394
+ | `multilevel_reduction_ratio` | `32` | Approximate number of nodes represented by each node per coarsening level |
395
+ | `multilevel_base_size` | `512` | Stop coarsening at or below this graph size |
396
+ | `multilevel_epochs` | `1` | Refinement epochs at each coarsened graph level |
397
+ | `n_epochs` | `200` | Coordinate-optimization epochs |
398
+ | `batch_size` | `131072` | Maximum active edges per GPU update batch; ignored by CPU optimizer |
399
+ | `learning_rate` | `0.05` | Coordinate optimizer learning rate |
400
+ | `negative_ratio` | `5` | Non-neighbors sampled per endpoint of each positive edge |
401
+ | `lambda_rep` | `0.5` | Repulsion share, from 0 to 1 |
402
+ | `logistic_margin` | `1.0` | Squared-distance margin for repulsion |
403
+ | `logistic_temperature` | `0.5` | Logistic repulsion softness; must be positive |
404
+ | `epsilon` | `1e-4` | Smoothing for the logarithmic attraction |
405
+ | `random_state` | `42` | Seed for initialization, shuffling, and sampling |
406
+ | `device` | `"auto"` | Selects MPS on Apple Silicon, CUDA when available, then CPU; `"cpu"`, `"mps"`, and `"cuda"` can be selected explicitly |
407
+ | `metric` | `"euclidean"` | Feature distance for the graph: `"euclidean"` or `"cosine"` |
408
+ | `mst_method` | `"famst"` | Sparse approximate `"famst"` or exact dense `"prim"` |
409
+ | `mst_neighbor_backend` | `"auto"` | `"auto"`, `"rinnd"`, `"pynndescent"`, or `"mps_exact"` FAMST neighbor search |
410
+ | `mst_neighbors` | `15` | Initial candidate neighbors for FAMST |
411
+ | `include_knn_attraction` | `False` | Also attract along FAMST candidate-neighbor edges in Euclidean `fit(X)` |
412
+ | `gravity_neighbors` | `15` | Feature-space neighbors for the RINND/Leiden region graph |
413
+ | `gravity_resolution` | `1.0` | Leiden partition resolution |
414
+ | `gravity_strength` | `0.2` | Attraction toward each density-weighted region core; set to `0` to disable gravity; skipped automatically with `metric="cosine"` |
415
+ | `mean_shift_iterations` | `1` | Number of mean-shift refinement iterations after gravity; set to `0` to disable mean shift |
416
+ | `mean_shift_step_size` | `0.5` | Fraction of each mean-shift update applied per iteration |
417
+ | `gravity_core_quantile` | `0.95` | Within-region density quantile defining the core points |
418
+ | `gravity_mass_power` | `0.5` | Exponent controlling point and region mass effects |
419
+ | `gravity_pack_regions` | `False` | After gravity, translate Leiden regions onto a compact ring while preserving each region's internal shape |
420
+ | `gravity_pack_radius_quantile` | `0.9` | Quantile used to estimate region radii for ring packing |
421
+ | `gravity_pack_gap_fraction` | `0.25` | Gap between packed regions as a fraction of their median radius |
422
+ | `mst_inter_component_edges` | `5` | Candidate connections per FAMST component pair |
423
+ | `mst_representatives_per_component` | `10` | Maximum representatives per component for selecting FAMST bridge pairs |
424
+ | `mst_max_neighbors` | `None` | FAMST neighbor cap; defaults to four times `mst_neighbors` |
425
+
426
+ Fitted estimators expose `graph_construction_time_`,
427
+ `multilevel_initialization_time_`, `final_embedding_optimization_time_`,
428
+ `embedding_optimization_time_`, and `fit_time_` in seconds. With `verbose=True`,
429
+ the fit summary reports each macro phase separately. GPU negative sampling and
430
+ coordinate updates are timed together to avoid per-batch Metal event recording
431
+ on long fits.
432
+
433
+ When gravity follows a feature-based FAMST fit, it reuses the fitted Euclidean
434
+ neighbor search when that graph contains enough valid neighbors. The
435
+ `gravity_neighbor_graph_reused_` and `gravity_neighbor_search_time_` attributes
436
+ report reuse and any fresh-search time. Prim fits and graph-only fits use a
437
+ fresh search when gravity has features available.
438
+
439
+ By default, `fit(X)` starts coordinate optimization from PCA scores computed
440
+ after feature-wise standardization and uniformly scaled by the maximum absolute
441
+ score into `[-1, 1]`. This preserves the relative scale between PCA axes. Set
442
+ `pca_init_scaling="none"` to preserve raw PCA score magnitudes, or
443
+ `pca_init=False` to use the seeded random initialization instead.
444
+ `fit_graph()` uses the same PCA initialization when `init_features` is supplied;
445
+ otherwise it uses random initialization. Pass `init_coordinates` with shape
446
+ `(n_samples, n_components)` to start from explicit coordinates instead:
447
+
448
+ ```python
449
+ mapper = IteratedMinimumSpanningTreeEmbedder(
450
+ n_msts=5,
451
+ init_coordinates=umap_coordinates,
452
+ )
453
+ embedding = mapper.fit_transform(X)
454
+ ```
455
+ The coordinate rows must correspond to `X` in the same order. Explicit
456
+ coordinates take precedence over `pca_init` and are used at their supplied scale.
457
+
458
+ Gravity uses the density-core method as an optional second phase for dense
459
+ Euclidean inputs with at least two embedding dimensions. Its Leiden regions
460
+ can be translated onto a compact
461
+ ring with `gravity_pack_regions=True`. This rigid translation preserves
462
+ within-region distances, but changes distances between regions; use it when a
463
+ compact region view is more useful than preserving the fitted global layout.
464
+
465
+ Set `multilevel_init=True` to initialize from the fitted ranked graph instead.
466
+ The initializer scores graph edges by inverse rank, coarsens each connected
467
+ component independently, then lays out the smallest graph from PCA of pooled
468
+ group features when `pca_init=True` (the default). With `pca_init=False`, it
469
+ uses seeded random coordinates instead. The layout then expands and refines
470
+ the graph level by level. Coarse-level
471
+ quotient edges use summed inverse-rank weights and run on the estimator's
472
+ selected CPU or GPU optimizer. The final fit still uses the original graph and
473
+ its normal rank scheduling. Explicit `init_coordinates` skip this process; if
474
+ the graph cannot be reduced, the configured PCA or random initialization is
475
+ used.
476
+
477
+ The selected optimizer device is available as `mapper.device_` after fitting.
478
+ `device="auto"` selects Apple's Metal Performance Shaders backend on Apple
479
+ Silicon, CUDA when available on other systems, and CPU otherwise. The batched
480
+ optimizer uses the selected GPU, while CPU remains the fallback. The independent
481
+ `mst_neighbor_backend="auto"` setting prefers RINND for dense Euclidean FAMST
482
+ inputs, while `"mps_exact"` selects exact chunked neighbor search on MPS. Explicit
483
+ GPU selection requires the matching PyTorch backend to be available. For example:
484
+
485
+ ```python
486
+ mapper = IteratedMinimumSpanningTreeEmbedder(
487
+ n_msts=5,
488
+ n_epochs=500,
489
+ device="mps",
490
+ random_state=42,
491
+ )
492
+ embedding = mapper.fit_transform(X)
493
+ ```
494
+
495
+ The GPU optimizer samples negative pairs and computes updates for each batch on
496
+ the GPU, then applies batches sequentially. A rare exact CPU fallback handles
497
+ unusually dense neighborhoods. GPU and CPU builds can use different
498
+ neighbor-search methods, so their graph and embedding can differ. Larger batches
499
+ can improve GPU utilization and use more memory; changing the batch size also
500
+ changes the GPU update trajectory. CPU runs ignore this setting.
501
+
502
+ ### MLP parameters
503
+
504
+ | Parameter | Default | Meaning |
505
+ | --- | ---: | --- |
506
+ | `n_layers` | `6` | Hidden layers in `InductiveIMSTE` |
507
+ | `layer_size` | `128` | Units in each hidden layer |
508
+ | `dropout` | `0.1` | Dropout probability |
509
+ | `epochs` | `200` | Maximum MLP training epochs |
510
+ | `min_epochs` | `100` | Minimum epochs before early stopping |
511
+ | `patience` | `20` | Epochs without validation improvement before stopping |
512
+ | `batch_size` | `256` | Rows per MLP update and prediction batch |
513
+ | `learning_rate` | `0.001` | MLP optimizer learning rate |
514
+
515
+ These are `InductiveIMSTE` parameters. Configure the graph and coordinate
516
+ optimization by passing an `IteratedMinimumSpanningTreeEmbedder` as `embedder`.
517
+
518
+ ## Notebooks
519
+
520
+ Active experiment notebooks use concise dataset-based names. Dataset preparation notebooks live in their corresponding folders under `data/`.
521
+
522
+ - [synthetic_exp](notebooks/synthetic_exp.ipynb): compare IMSTE and UMAP on controlled geometries.
523
+ - [biological_exp](notebooks/biological_exp.ipynb): inspect annotated biological datasets and trajectories.
524
+ - [arxiv_exp](notebooks/arxiv_exp.ipynb): compare embeddings of the prepared arXiv sample.
525
+ - [cifar10_exp](notebooks/cifar10_exp.ipynb): compare CIFAR-10 image-vector embeddings.
526
+ - [interactive](notebooks/interactive.ipynb): interactively refine a balanced arXiv layout with gravity followed by mean shift.
527
+ - [mnist_exp](notebooks/mnist_exp.ipynb): compare MNIST, Fashion-MNIST, and Kuzushiji-MNIST.
528
+ - [tabula_sapiens_exp](notebooks/tabula_sapiens_exp.ipynb): compare tissue and cell-type colorings on shared layouts.
529
+
530
+ Prepare source data with [the arXiv preparation notebook](data/arxiv/prepare_dataset.ipynb) and [the CIFAR-10 preparation notebook](data/cifar10/prepare_dataset.ipynb).
531
+
532
+ Earlier exploratory notebooks are in
533
+ [notebooks/archive](notebooks/archive/). This includes the [interactive 2D
534
+ embedding](notebooks/archive/digits_2d_interactive.ipynb), [interactive 3D
535
+ embedding](notebooks/archive/digits_3d_interactive.ipynb), [parameter
536
+ sweep](notebooks/archive/digits_parameter_sweep.ipynb), and [MST scaling
537
+ benchmark](notebooks/archive/mst_scaling_benchmark.ipynb).
538
+
539
+ Python helper modules used by the notebooks are in [notebooks/src](notebooks/src/).
540
+ For the full method description and equations, see the
541
+ [IMSTE whitepaper](docs/whitepaper.md). For a detailed walkthrough of
542
+ rank-only multilevel initialization, see the
543
+ [multilevel initialization guide](docs/multilevel-initialization.md).
544
+ The package is distributed under the [MIT License](LICENSE).