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.
- imste-0.2.1/LICENSE +21 -0
- imste-0.2.1/PKG-INFO +544 -0
- imste-0.2.1/README.md +497 -0
- imste-0.2.1/imste/__init__.py +15 -0
- imste-0.2.1/imste/_api.py +28 -0
- imste-0.2.1/imste/_estimator.py +1106 -0
- imste-0.2.1/imste/_estimator_graph.py +241 -0
- imste-0.2.1/imste/_estimator_utils.py +249 -0
- imste-0.2.1/imste/_gravity.py +295 -0
- imste-0.2.1/imste/_mean_shift.py +87 -0
- imste-0.2.1/imste/_multilevel.py +259 -0
- imste-0.2.1/imste/_optimizer.py +355 -0
- imste-0.2.1/imste/_optimizer_mps.py +8 -0
- imste-0.2.1/imste/_optimizer_torch.py +296 -0
- imste-0.2.1/imste/_progress.py +261 -0
- imste-0.2.1/imste/_visualization_class_geometry.py +612 -0
- imste-0.2.1/imste/_visualization_core.py +607 -0
- imste-0.2.1/imste/_visualization_interactive.py +453 -0
- imste-0.2.1/imste/class_graph.py +444 -0
- imste-0.2.1/imste/inductive.py +394 -0
- imste-0.2.1/imste/losses.py +45 -0
- imste-0.2.1/imste/mst/__init__.py +62 -0
- imste-0.2.1/imste/mst/famst.py +963 -0
- imste-0.2.1/imste/mst/graph.py +141 -0
- imste-0.2.1/imste/mst/prim.py +283 -0
- imste-0.2.1/imste/visualization.py +31 -0
- imste-0.2.1/imste.egg-info/PKG-INFO +544 -0
- imste-0.2.1/imste.egg-info/SOURCES.txt +36 -0
- imste-0.2.1/imste.egg-info/dependency_links.txt +1 -0
- imste-0.2.1/imste.egg-info/requires.txt +28 -0
- imste-0.2.1/imste.egg-info/top_level.txt +1 -0
- imste-0.2.1/pyproject.toml +57 -0
- imste-0.2.1/setup.cfg +4 -0
- imste-0.2.1/tests/test_arxiv_notebook_helpers.py +60 -0
- imste-0.2.1/tests/test_estimator.py +753 -0
- imste-0.2.1/tests/test_famst.py +380 -0
- imste-0.2.1/tests/test_multilevel.py +82 -0
- 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).
|