imste 0.2.2__tar.gz → 0.8.0__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.2 → imste-0.8.0}/PKG-INFO +57 -17
- {imste-0.2.2 → imste-0.8.0}/README.md +51 -16
- {imste-0.2.2 → imste-0.8.0}/imste/__init__.py +2 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_estimator.py +214 -4
- {imste-0.2.2 → imste-0.8.0}/imste/_estimator_graph.py +25 -2
- {imste-0.2.2 → imste-0.8.0}/imste/_gravity.py +108 -3
- imste-0.8.0/imste/_preprocessing.py +158 -0
- imste-0.8.0/imste/_tuning.py +309 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_visualization_class_geometry.py +37 -8
- imste-0.2.2/imste/class_graph.py → imste-0.8.0/imste/_visualization_class_graph.py +4 -204
- {imste-0.2.2 → imste-0.8.0}/imste/_visualization_interactive.py +2 -0
- imste-0.8.0/imste/class_graph.py +263 -0
- {imste-0.2.2 → imste-0.8.0}/imste/visualization.py +2 -0
- {imste-0.2.2 → imste-0.8.0}/imste.egg-info/PKG-INFO +57 -17
- {imste-0.2.2 → imste-0.8.0}/imste.egg-info/SOURCES.txt +7 -1
- {imste-0.2.2 → imste-0.8.0}/imste.egg-info/requires.txt +7 -0
- {imste-0.2.2 → imste-0.8.0}/pyproject.toml +6 -2
- imste-0.8.0/tests/test_preprocessing.py +107 -0
- imste-0.8.0/tests/test_tuning.py +195 -0
- imste-0.8.0/tests/test_visualization.py +68 -0
- {imste-0.2.2 → imste-0.8.0}/LICENSE +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_api.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_estimator_utils.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_mean_shift.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_multilevel.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_optimizer.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_optimizer_mps.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_optimizer_torch.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_progress.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/_visualization_core.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/inductive.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/losses.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/mst/__init__.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/mst/famst.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/mst/graph.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste/mst/prim.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste.egg-info/dependency_links.txt +0 -0
- {imste-0.2.2 → imste-0.8.0}/imste.egg-info/top_level.txt +0 -0
- {imste-0.2.2 → imste-0.8.0}/setup.cfg +0 -0
- {imste-0.2.2 → imste-0.8.0}/tests/test_arxiv_notebook_helpers.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/tests/test_estimator.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/tests/test_famst.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/tests/test_multilevel.py +0 -0
- {imste-0.2.2 → imste-0.8.0}/tests/test_optimizer.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: imste
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.8.0
|
|
4
4
|
Summary: Iterated Minimum Spanning Tree Embedding (IMSTE)
|
|
5
5
|
Author: Fabrizio Costa
|
|
6
6
|
License-Expression: MIT
|
|
@@ -33,6 +33,7 @@ Provides-Extra: test
|
|
|
33
33
|
Requires-Dist: pytest>=7; extra == "test"
|
|
34
34
|
Requires-Dist: pandas>=2.0; extra == "test"
|
|
35
35
|
Requires-Dist: torch>=2.0; extra == "test"
|
|
36
|
+
Requires-Dist: matplotlib>=3.7; extra == "test"
|
|
36
37
|
Provides-Extra: notebook
|
|
37
38
|
Requires-Dist: matplotlib>=3.7; extra == "notebook"
|
|
38
39
|
Requires-Dist: pandas>=2.0; extra == "notebook"
|
|
@@ -43,14 +44,23 @@ Requires-Dist: psutil>=5.9; extra == "notebook"
|
|
|
43
44
|
Requires-Dist: datashader>=0.15; extra == "notebook"
|
|
44
45
|
Requires-Dist: tqdm>=4.65; extra == "notebook"
|
|
45
46
|
Requires-Dist: yt>=4.4; extra == "notebook"
|
|
47
|
+
Provides-Extra: tuning
|
|
48
|
+
Requires-Dist: scikit-optimize>=0.10.2; extra == "tuning"
|
|
49
|
+
Provides-Extra: preprocessing
|
|
50
|
+
Requires-Dist: sentence-transformers[image]>=6.3; extra == "preprocessing"
|
|
46
51
|
Dynamic: license-file
|
|
47
52
|
|
|
48
53
|
# IMSTE
|
|
49
54
|
|
|
55
|
+
[](https://doi.org/10.5281/zenodo.24307529)
|
|
56
|
+
|
|
57
|
+
<p align="center"><img src="docs/images/imste-arxiv-example.png" alt="IMSTE embedding example" width="700"></p>
|
|
58
|
+
|
|
50
59
|
**Iterated Minimum Spanning Tree Embedding (IMSTE)** is a scikit-learn
|
|
51
|
-
transformer for learning low-dimensional coordinates from
|
|
52
|
-
builds a weighted graph from ranked minimum spanning trees, then
|
|
53
|
-
|
|
60
|
+
transformer for learning low-dimensional coordinates from feature vectors. It
|
|
61
|
+
builds a weighted graph from ranked minimum spanning trees, then optimizes one
|
|
62
|
+
coordinate vector per sample. Optional `.preprocessor(...)` presets accept raw
|
|
63
|
+
text, images, or graph objects and vectorize them before fitting IMSTE.
|
|
54
64
|
|
|
55
65
|
The package has two explicit estimators: `IteratedMinimumSpanningTreeEmbedder`
|
|
56
66
|
learns coordinates for the training rows, while `InductiveIMSTE` also learns
|
|
@@ -89,8 +99,15 @@ python -m pip install "imste[notebook]"
|
|
|
89
99
|
|
|
90
100
|
From a source checkout, use `python -m pip install ".[notebook]"` instead.
|
|
91
101
|
|
|
92
|
-
|
|
93
|
-
[
|
|
102
|
+
To embed raw text and images before fitting IMSTE, install the optional model
|
|
103
|
+
integration with `python -m pip install "imste[preprocessing]"`. The graph
|
|
104
|
+
preset needs NSPPK, installed from its repository with
|
|
105
|
+
`python -m pip install git+https://github.com/Xfcosta/NSPPK.git`. See the
|
|
106
|
+
[preprocessing guide](docs/preprocessing-guide.md) for built-in modality presets
|
|
107
|
+
and custom scikit-learn transformers.
|
|
108
|
+
|
|
109
|
+
To tune IMSTE against labeled 2D separation, install the optional Bayesian
|
|
110
|
+
optimization dependency with `python -m pip install "imste[tuning]"`.
|
|
94
111
|
|
|
95
112
|
Both estimators accept dense arrays and SciPy CSR matrices. The graph builders
|
|
96
113
|
keep CSR inputs sparse. `InductiveIMSTE` densifies only each MLP mini-batch.
|
|
@@ -140,6 +157,34 @@ embedding = mapper.fit_transform(X)
|
|
|
140
157
|
plt.scatter(embedding[:, 0], embedding[:, 1], c=digits.target, cmap="tab10", s=10)
|
|
141
158
|
```
|
|
142
159
|
|
|
160
|
+
### Tune a labeled 2D embedding
|
|
161
|
+
|
|
162
|
+
`tune()` searches estimator parameters using a combined score of 60% mean 5-fold
|
|
163
|
+
k-NN accuracy and 40% robust spatial coverage. Coverage estimates how evenly
|
|
164
|
+
points occupy a robustly scaled 2D grid, so a few outliers cannot dominate it.
|
|
165
|
+
Each trial fits an unsupervised embedding on all feature rows; labels are used
|
|
166
|
+
only for scoring. With no `search_space`, it tunes `n_msts` (3–30),
|
|
167
|
+
`learning_rate` (0.01–0.1), `negative_ratio` (1–10), `gravity_strength`
|
|
168
|
+
(0.0–1.0), and `mean_shift_iterations` (0–5). Set `coverage_weight=0` to
|
|
169
|
+
optimize accuracy alone. Numeric tuples are inclusive bounds, while lists are
|
|
170
|
+
categorical choices. Integer or continuous dimensions are inferred from the
|
|
171
|
+
current value of each estimator parameter. The default budget is 40 trials,
|
|
172
|
+
with 20 initial Latin hypercube samples. The estimator's default
|
|
173
|
+
`n_epochs=200` applies to each trial.
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
mapper = IteratedMinimumSpanningTreeEmbedder(random_state=42)
|
|
177
|
+
search = mapper.tune(X, digits.target)
|
|
178
|
+
|
|
179
|
+
print(search.best_params, search.best_score, search.best_coverage)
|
|
180
|
+
embedding = mapper.embedding_
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
The best settings are refitted on all rows and stored on `mapper`; the returned
|
|
184
|
+
scikit-optimize result contains the search history and final embedding.
|
|
185
|
+
See the [tuning guide](docs/tuning-guide.md) for the combined accuracy and
|
|
186
|
+
coverage objective, result fields, and live-progress callback.
|
|
187
|
+
|
|
143
188
|
### Fit from a distance graph
|
|
144
189
|
|
|
145
190
|
This example builds a complete pairwise distance graph from the built-in
|
|
@@ -356,7 +401,7 @@ directly; they use `embedding_` or the inductive model's `reference_embedding_`.
|
|
|
356
401
|
Raw coordinate arrays remain supported.
|
|
357
402
|
|
|
358
403
|
For class-level graph overlays across one or more embeddings, use
|
|
359
|
-
`imste.
|
|
404
|
+
`imste.visualization.plot_class_mixture_mst`. It fits full-covariance Gaussian
|
|
360
405
|
mixtures per class in each 2D embedding, connects their component centers with
|
|
361
406
|
iterated MSTs, and maps symmetric cross-component posterior probability to
|
|
362
407
|
edge opacity. For each edge, the two endpoint Gaussian densities form an
|
|
@@ -415,6 +460,7 @@ library defaults; notebook recommendations can intentionally differ.
|
|
|
415
460
|
| `gravity_neighbors` | `15` | Feature-space neighbors for the RINND/Leiden region graph |
|
|
416
461
|
| `gravity_resolution` | `1.0` | Leiden partition resolution |
|
|
417
462
|
| `gravity_strength` | `0.2` | Attraction toward each density-weighted region core; set to `0` to disable gravity; skipped automatically with `metric="cosine"` |
|
|
463
|
+
| `gravity_min_dist` | `0.0` | Local repulsion floor after gravity, as a fraction of the median pre-gravity nearest-neighbor distance; `0` disables it and values above `1` request stronger expansion |
|
|
418
464
|
| `mean_shift_iterations` | `1` | Number of mean-shift refinement iterations after gravity; set to `0` to disable mean shift |
|
|
419
465
|
| `mean_shift_step_size` | `0.5` | Fraction of each mean-shift update applied per iteration |
|
|
420
466
|
| `gravity_core_quantile` | `0.95` | Within-region density quantile defining the core points |
|
|
@@ -525,21 +571,15 @@ optimization by passing an `IteratedMinimumSpanningTreeEmbedder` as `embedder`.
|
|
|
525
571
|
Active experiment notebooks use concise dataset-based names. Dataset setup notebooks live in `notebooks/dataset_setup/`.
|
|
526
572
|
|
|
527
573
|
- [synthetic_exp](notebooks/synthetic_exp.ipynb): compare IMSTE and UMAP on controlled geometries.
|
|
528
|
-
- [biological_exp](notebooks/biological_exp.ipynb): inspect annotated biological datasets and trajectories.
|
|
574
|
+
- [biological_exp](notebooks/biological_exp.ipynb): inspect annotated biological datasets and trajectories. Prepare its local inputs with [prepare_biological_datasets](notebooks/dataset_setup/prepare_biological_datasets.ipynb).
|
|
529
575
|
- [arxiv_exp](notebooks/arxiv_exp.ipynb): compare embeddings of the prepared arXiv sample.
|
|
530
|
-
- [
|
|
576
|
+
- [cifar100_exp](notebooks/cifar100_exp.ipynb): compare CIFAR-100 image embeddings with superclass hues and fine-class shades.
|
|
531
577
|
- [interactive](notebooks/interactive.ipynb): interactively refine a balanced arXiv layout with gravity followed by mean shift.
|
|
532
578
|
- [mnist_exp](notebooks/mnist_exp.ipynb): compare MNIST, Fashion-MNIST, and Kuzushiji-MNIST.
|
|
579
|
+
- [tune_mnist](notebooks/tune_mnist.ipynb): choose MNIST, Fashion-MNIST, or Kuzushiji-MNIST, then tune IMSTE on a balanced sample and watch trial results live.
|
|
533
580
|
- [tabula_sapiens_exp](notebooks/tabula_sapiens_exp.ipynb): load prepared Tabula Sapiens features and compare tissue and cell-type colorings on shared layouts.
|
|
534
581
|
|
|
535
|
-
Prepare source data with the [arXiv](notebooks/dataset_setup/prepare_arxiv_dataset.ipynb), [CIFAR-
|
|
536
|
-
|
|
537
|
-
Earlier exploratory notebooks are in
|
|
538
|
-
[notebooks/archive](notebooks/archive/). This includes the [interactive 2D
|
|
539
|
-
embedding](notebooks/archive/digits_2d_interactive.ipynb), [interactive 3D
|
|
540
|
-
embedding](notebooks/archive/digits_3d_interactive.ipynb), [parameter
|
|
541
|
-
sweep](notebooks/archive/digits_parameter_sweep.ipynb), and [MST scaling
|
|
542
|
-
benchmark](notebooks/archive/mst_scaling_benchmark.ipynb).
|
|
582
|
+
Prepare source data with the [arXiv](notebooks/dataset_setup/prepare_arxiv_dataset.ipynb), [CIFAR-100](notebooks/dataset_setup/prepare_cifar100_dataset.ipynb), and [Tabula Sapiens](notebooks/dataset_setup/prepare_tabula_sapiens_dataset.ipynb) setup notebooks.
|
|
543
583
|
|
|
544
584
|
Python helper modules used by the notebooks are in [notebooks/src](notebooks/src/).
|
|
545
585
|
For the full method description and equations, see the
|
|
@@ -1,9 +1,14 @@
|
|
|
1
1
|
# IMSTE
|
|
2
2
|
|
|
3
|
+
[](https://doi.org/10.5281/zenodo.24307529)
|
|
4
|
+
|
|
5
|
+
<p align="center"><img src="docs/images/imste-arxiv-example.png" alt="IMSTE embedding example" width="700"></p>
|
|
6
|
+
|
|
3
7
|
**Iterated Minimum Spanning Tree Embedding (IMSTE)** is a scikit-learn
|
|
4
|
-
transformer for learning low-dimensional coordinates from
|
|
5
|
-
builds a weighted graph from ranked minimum spanning trees, then
|
|
6
|
-
|
|
8
|
+
transformer for learning low-dimensional coordinates from feature vectors. It
|
|
9
|
+
builds a weighted graph from ranked minimum spanning trees, then optimizes one
|
|
10
|
+
coordinate vector per sample. Optional `.preprocessor(...)` presets accept raw
|
|
11
|
+
text, images, or graph objects and vectorize them before fitting IMSTE.
|
|
7
12
|
|
|
8
13
|
The package has two explicit estimators: `IteratedMinimumSpanningTreeEmbedder`
|
|
9
14
|
learns coordinates for the training rows, while `InductiveIMSTE` also learns
|
|
@@ -42,8 +47,15 @@ python -m pip install "imste[notebook]"
|
|
|
42
47
|
|
|
43
48
|
From a source checkout, use `python -m pip install ".[notebook]"` instead.
|
|
44
49
|
|
|
45
|
-
|
|
46
|
-
[
|
|
50
|
+
To embed raw text and images before fitting IMSTE, install the optional model
|
|
51
|
+
integration with `python -m pip install "imste[preprocessing]"`. The graph
|
|
52
|
+
preset needs NSPPK, installed from its repository with
|
|
53
|
+
`python -m pip install git+https://github.com/Xfcosta/NSPPK.git`. See the
|
|
54
|
+
[preprocessing guide](docs/preprocessing-guide.md) for built-in modality presets
|
|
55
|
+
and custom scikit-learn transformers.
|
|
56
|
+
|
|
57
|
+
To tune IMSTE against labeled 2D separation, install the optional Bayesian
|
|
58
|
+
optimization dependency with `python -m pip install "imste[tuning]"`.
|
|
47
59
|
|
|
48
60
|
Both estimators accept dense arrays and SciPy CSR matrices. The graph builders
|
|
49
61
|
keep CSR inputs sparse. `InductiveIMSTE` densifies only each MLP mini-batch.
|
|
@@ -93,6 +105,34 @@ embedding = mapper.fit_transform(X)
|
|
|
93
105
|
plt.scatter(embedding[:, 0], embedding[:, 1], c=digits.target, cmap="tab10", s=10)
|
|
94
106
|
```
|
|
95
107
|
|
|
108
|
+
### Tune a labeled 2D embedding
|
|
109
|
+
|
|
110
|
+
`tune()` searches estimator parameters using a combined score of 60% mean 5-fold
|
|
111
|
+
k-NN accuracy and 40% robust spatial coverage. Coverage estimates how evenly
|
|
112
|
+
points occupy a robustly scaled 2D grid, so a few outliers cannot dominate it.
|
|
113
|
+
Each trial fits an unsupervised embedding on all feature rows; labels are used
|
|
114
|
+
only for scoring. With no `search_space`, it tunes `n_msts` (3–30),
|
|
115
|
+
`learning_rate` (0.01–0.1), `negative_ratio` (1–10), `gravity_strength`
|
|
116
|
+
(0.0–1.0), and `mean_shift_iterations` (0–5). Set `coverage_weight=0` to
|
|
117
|
+
optimize accuracy alone. Numeric tuples are inclusive bounds, while lists are
|
|
118
|
+
categorical choices. Integer or continuous dimensions are inferred from the
|
|
119
|
+
current value of each estimator parameter. The default budget is 40 trials,
|
|
120
|
+
with 20 initial Latin hypercube samples. The estimator's default
|
|
121
|
+
`n_epochs=200` applies to each trial.
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
mapper = IteratedMinimumSpanningTreeEmbedder(random_state=42)
|
|
125
|
+
search = mapper.tune(X, digits.target)
|
|
126
|
+
|
|
127
|
+
print(search.best_params, search.best_score, search.best_coverage)
|
|
128
|
+
embedding = mapper.embedding_
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The best settings are refitted on all rows and stored on `mapper`; the returned
|
|
132
|
+
scikit-optimize result contains the search history and final embedding.
|
|
133
|
+
See the [tuning guide](docs/tuning-guide.md) for the combined accuracy and
|
|
134
|
+
coverage objective, result fields, and live-progress callback.
|
|
135
|
+
|
|
96
136
|
### Fit from a distance graph
|
|
97
137
|
|
|
98
138
|
This example builds a complete pairwise distance graph from the built-in
|
|
@@ -309,7 +349,7 @@ directly; they use `embedding_` or the inductive model's `reference_embedding_`.
|
|
|
309
349
|
Raw coordinate arrays remain supported.
|
|
310
350
|
|
|
311
351
|
For class-level graph overlays across one or more embeddings, use
|
|
312
|
-
`imste.
|
|
352
|
+
`imste.visualization.plot_class_mixture_mst`. It fits full-covariance Gaussian
|
|
313
353
|
mixtures per class in each 2D embedding, connects their component centers with
|
|
314
354
|
iterated MSTs, and maps symmetric cross-component posterior probability to
|
|
315
355
|
edge opacity. For each edge, the two endpoint Gaussian densities form an
|
|
@@ -368,6 +408,7 @@ library defaults; notebook recommendations can intentionally differ.
|
|
|
368
408
|
| `gravity_neighbors` | `15` | Feature-space neighbors for the RINND/Leiden region graph |
|
|
369
409
|
| `gravity_resolution` | `1.0` | Leiden partition resolution |
|
|
370
410
|
| `gravity_strength` | `0.2` | Attraction toward each density-weighted region core; set to `0` to disable gravity; skipped automatically with `metric="cosine"` |
|
|
411
|
+
| `gravity_min_dist` | `0.0` | Local repulsion floor after gravity, as a fraction of the median pre-gravity nearest-neighbor distance; `0` disables it and values above `1` request stronger expansion |
|
|
371
412
|
| `mean_shift_iterations` | `1` | Number of mean-shift refinement iterations after gravity; set to `0` to disable mean shift |
|
|
372
413
|
| `mean_shift_step_size` | `0.5` | Fraction of each mean-shift update applied per iteration |
|
|
373
414
|
| `gravity_core_quantile` | `0.95` | Within-region density quantile defining the core points |
|
|
@@ -478,21 +519,15 @@ optimization by passing an `IteratedMinimumSpanningTreeEmbedder` as `embedder`.
|
|
|
478
519
|
Active experiment notebooks use concise dataset-based names. Dataset setup notebooks live in `notebooks/dataset_setup/`.
|
|
479
520
|
|
|
480
521
|
- [synthetic_exp](notebooks/synthetic_exp.ipynb): compare IMSTE and UMAP on controlled geometries.
|
|
481
|
-
- [biological_exp](notebooks/biological_exp.ipynb): inspect annotated biological datasets and trajectories.
|
|
522
|
+
- [biological_exp](notebooks/biological_exp.ipynb): inspect annotated biological datasets and trajectories. Prepare its local inputs with [prepare_biological_datasets](notebooks/dataset_setup/prepare_biological_datasets.ipynb).
|
|
482
523
|
- [arxiv_exp](notebooks/arxiv_exp.ipynb): compare embeddings of the prepared arXiv sample.
|
|
483
|
-
- [
|
|
524
|
+
- [cifar100_exp](notebooks/cifar100_exp.ipynb): compare CIFAR-100 image embeddings with superclass hues and fine-class shades.
|
|
484
525
|
- [interactive](notebooks/interactive.ipynb): interactively refine a balanced arXiv layout with gravity followed by mean shift.
|
|
485
526
|
- [mnist_exp](notebooks/mnist_exp.ipynb): compare MNIST, Fashion-MNIST, and Kuzushiji-MNIST.
|
|
527
|
+
- [tune_mnist](notebooks/tune_mnist.ipynb): choose MNIST, Fashion-MNIST, or Kuzushiji-MNIST, then tune IMSTE on a balanced sample and watch trial results live.
|
|
486
528
|
- [tabula_sapiens_exp](notebooks/tabula_sapiens_exp.ipynb): load prepared Tabula Sapiens features and compare tissue and cell-type colorings on shared layouts.
|
|
487
529
|
|
|
488
|
-
Prepare source data with the [arXiv](notebooks/dataset_setup/prepare_arxiv_dataset.ipynb), [CIFAR-
|
|
489
|
-
|
|
490
|
-
Earlier exploratory notebooks are in
|
|
491
|
-
[notebooks/archive](notebooks/archive/). This includes the [interactive 2D
|
|
492
|
-
embedding](notebooks/archive/digits_2d_interactive.ipynb), [interactive 3D
|
|
493
|
-
embedding](notebooks/archive/digits_3d_interactive.ipynb), [parameter
|
|
494
|
-
sweep](notebooks/archive/digits_parameter_sweep.ipynb), and [MST scaling
|
|
495
|
-
benchmark](notebooks/archive/mst_scaling_benchmark.ipynb).
|
|
530
|
+
Prepare source data with the [arXiv](notebooks/dataset_setup/prepare_arxiv_dataset.ipynb), [CIFAR-100](notebooks/dataset_setup/prepare_cifar100_dataset.ipynb), and [Tabula Sapiens](notebooks/dataset_setup/prepare_tabula_sapiens_dataset.ipynb) setup notebooks.
|
|
496
531
|
|
|
497
532
|
Python helper modules used by the notebooks are in [notebooks/src](notebooks/src/).
|
|
498
533
|
For the full method description and equations, see the
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
from ._estimator import IteratedMinimumSpanningTreeEmbedder
|
|
4
4
|
from ._api import fit_graph_transform
|
|
5
|
+
from ._tuning import spatial_coverage_score
|
|
5
6
|
from .losses import (
|
|
6
7
|
log_attraction_loss,
|
|
7
8
|
logistic_repulsion_loss,
|
|
@@ -10,6 +11,7 @@ from .losses import (
|
|
|
10
11
|
__all__ = [
|
|
11
12
|
"IteratedMinimumSpanningTreeEmbedder",
|
|
12
13
|
"fit_graph_transform",
|
|
14
|
+
"spatial_coverage_score",
|
|
13
15
|
"log_attraction_loss",
|
|
14
16
|
"logistic_repulsion_loss",
|
|
15
17
|
]
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
5
|
import time
|
|
6
|
-
from collections.abc import Callable
|
|
6
|
+
from collections.abc import Callable, Mapping
|
|
7
7
|
|
|
8
8
|
import numpy as np
|
|
9
9
|
from scipy.sparse import csr_matrix, issparse
|
|
@@ -129,6 +129,11 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
129
129
|
to disable gravity. Gravity requires dense Euclidean features and at
|
|
130
130
|
least two embedding dimensions; it refines the first two. It is skipped
|
|
131
131
|
automatically when ``metric='cosine'``.
|
|
132
|
+
gravity_min_dist : float, default=0.0
|
|
133
|
+
Optional local-distance floor after gravity, expressed as a
|
|
134
|
+
fraction of the median pre-gravity nearest-neighbor distance among
|
|
135
|
+
feature-space neighbors. Zero disables repulsion. Values above 1 request
|
|
136
|
+
stronger expansion.
|
|
132
137
|
gravity_neighbors : int, default=15
|
|
133
138
|
Feature-space neighbors used to build gravity regions.
|
|
134
139
|
gravity_resolution : float, default=1.0
|
|
@@ -175,6 +180,9 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
175
180
|
verbose : bool, default=False
|
|
176
181
|
Print timestamped fit stages and display progress bars for graph
|
|
177
182
|
construction, multilevel initialization, and optimization.
|
|
183
|
+
input_preprocessor : {'text', 'image', 'graph'} or transformer, default=None
|
|
184
|
+
Optional raw-input transformer to fit before IMSTE. Use
|
|
185
|
+
:meth:`preprocessor` to select a modality preset with its options.
|
|
178
186
|
"""
|
|
179
187
|
|
|
180
188
|
def __init__(
|
|
@@ -212,6 +220,7 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
212
220
|
gravity_neighbors: int = 15,
|
|
213
221
|
gravity_resolution: float = 1.0,
|
|
214
222
|
gravity_strength: float = 0.2,
|
|
223
|
+
gravity_min_dist: float = 0.0,
|
|
215
224
|
gravity_core_quantile: float = 0.95,
|
|
216
225
|
gravity_mass_power: float = 0.5,
|
|
217
226
|
gravity_pack_regions: bool = False,
|
|
@@ -221,6 +230,7 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
221
230
|
mean_shift_bandwidth_factor: float = 5.0,
|
|
222
231
|
mean_shift_step_size: float = 0.5,
|
|
223
232
|
mean_shift_iterations: int = 1,
|
|
233
|
+
input_preprocessor: object | str | None = None,
|
|
224
234
|
) -> None:
|
|
225
235
|
self.n_msts = n_msts
|
|
226
236
|
self.n_components = n_components
|
|
@@ -258,6 +268,7 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
258
268
|
self.gravity_neighbors = gravity_neighbors
|
|
259
269
|
self.gravity_resolution = gravity_resolution
|
|
260
270
|
self.gravity_strength = gravity_strength
|
|
271
|
+
self.gravity_min_dist = gravity_min_dist
|
|
261
272
|
self.gravity_core_quantile = gravity_core_quantile
|
|
262
273
|
self.gravity_mass_power = gravity_mass_power
|
|
263
274
|
self.gravity_pack_regions = gravity_pack_regions
|
|
@@ -267,6 +278,7 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
267
278
|
self.mean_shift_bandwidth_factor = mean_shift_bandwidth_factor
|
|
268
279
|
self.mean_shift_step_size = mean_shift_step_size
|
|
269
280
|
self.mean_shift_iterations = mean_shift_iterations
|
|
281
|
+
self.input_preprocessor = input_preprocessor
|
|
270
282
|
|
|
271
283
|
def _validated_fit_options(self) -> dict[str, object]:
|
|
272
284
|
if not isinstance(self.verbose, (bool, np.bool_)):
|
|
@@ -330,9 +342,15 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
330
342
|
gravity_strength = _finite_nonnegative(
|
|
331
343
|
"gravity_strength", self.gravity_strength
|
|
332
344
|
)
|
|
333
|
-
|
|
345
|
+
gravity_min_dist = _finite_nonnegative(
|
|
346
|
+
"gravity_min_dist", self.gravity_min_dist
|
|
347
|
+
)
|
|
348
|
+
gravity_enabled = (
|
|
349
|
+
gravity_strength > 0.0 or gravity_min_dist > 0.0
|
|
350
|
+
) and self.metric == "euclidean"
|
|
334
351
|
if not gravity_enabled:
|
|
335
352
|
gravity_strength = 0.0
|
|
353
|
+
gravity_min_dist = 0.0
|
|
336
354
|
if gravity_enabled and n_components < 2:
|
|
337
355
|
raise ValueError("gravity refinement requires n_components >= 2.")
|
|
338
356
|
gravity_neighbors = _positive_integer(
|
|
@@ -460,6 +478,7 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
460
478
|
"gravity_neighbors": gravity_neighbors,
|
|
461
479
|
"gravity_resolution": gravity_resolution,
|
|
462
480
|
"gravity_strength": gravity_strength,
|
|
481
|
+
"gravity_min_dist": gravity_min_dist,
|
|
463
482
|
"gravity_core_quantile": gravity_core_quantile,
|
|
464
483
|
"gravity_mass_power": gravity_mass_power,
|
|
465
484
|
"gravity_pack_regions": bool(self.gravity_pack_regions),
|
|
@@ -868,6 +887,37 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
868
887
|
self.mean_shift_time_ = time.perf_counter() - started
|
|
869
888
|
self.mean_shift_iterations_ = int(diagnostics["iterations"])
|
|
870
889
|
|
|
890
|
+
def _apply_gravity_min_dist_floor(
|
|
891
|
+
self,
|
|
892
|
+
options: dict[str, object],
|
|
893
|
+
feature_neighbor_graph: tuple[np.ndarray, np.ndarray] | None,
|
|
894
|
+
) -> None:
|
|
895
|
+
"""Reapply the local spacing floor after all layout refinements."""
|
|
896
|
+
fraction = float(options["gravity_min_dist"])
|
|
897
|
+
if (
|
|
898
|
+
not options["gravity_enabled"]
|
|
899
|
+
or fraction == 0.0
|
|
900
|
+
or feature_neighbor_graph is None
|
|
901
|
+
):
|
|
902
|
+
return
|
|
903
|
+
|
|
904
|
+
from ._gravity import _apply_local_distance_floor
|
|
905
|
+
|
|
906
|
+
started = time.perf_counter()
|
|
907
|
+
refined, diagnostics = _apply_local_distance_floor(
|
|
908
|
+
self.embedding_[:, :2],
|
|
909
|
+
feature_neighbor_graph[0],
|
|
910
|
+
fraction,
|
|
911
|
+
reference_embedding=self.embedding_before_gravity_[:, :2],
|
|
912
|
+
)
|
|
913
|
+
self.embedding_[:, :2] = refined
|
|
914
|
+
self.gravity_min_dist_used_ = float(diagnostics["min_dist_threshold"])
|
|
915
|
+
self.gravity_min_dist_reference_ = float(diagnostics["min_dist_reference"])
|
|
916
|
+
self.gravity_min_dist_pairs_adjusted_ = int(
|
|
917
|
+
diagnostics["min_dist_pairs_adjusted"]
|
|
918
|
+
)
|
|
919
|
+
self.gravity_time_ += time.perf_counter() - started
|
|
920
|
+
|
|
871
921
|
def fit(self, X: object, y: object = None) -> "IteratedMinimumSpanningTreeEmbedder":
|
|
872
922
|
"""Fit the embedding and store coordinates for the input rows.
|
|
873
923
|
|
|
@@ -892,7 +942,20 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
892
942
|
per-batch device event recording on long fits.
|
|
893
943
|
"""
|
|
894
944
|
fit_started = time.perf_counter()
|
|
895
|
-
|
|
945
|
+
if self.input_preprocessor is None:
|
|
946
|
+
if hasattr(self, "preprocessor_"):
|
|
947
|
+
del self.preprocessor_
|
|
948
|
+
else:
|
|
949
|
+
from sklearn.base import clone
|
|
950
|
+
|
|
951
|
+
from ._preprocessing import fit_transform_input, make_preprocessor
|
|
952
|
+
|
|
953
|
+
configured = self.input_preprocessor
|
|
954
|
+
if isinstance(configured, str):
|
|
955
|
+
configured = make_preprocessor(configured)
|
|
956
|
+
self.preprocessor_ = clone(configured)
|
|
957
|
+
X = fit_transform_input(self.preprocessor_, X, y)
|
|
958
|
+
del y # Labels are available to an optional supervised preprocessor only.
|
|
896
959
|
options = self._validated_fit_options()
|
|
897
960
|
for name in ("feature_neighbor_graph_", "feature_neighbor_graph_reused_"):
|
|
898
961
|
if hasattr(self, name):
|
|
@@ -902,6 +965,11 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
902
965
|
)
|
|
903
966
|
if issparse(X_checked):
|
|
904
967
|
X_checked = csr_matrix(X_checked)
|
|
968
|
+
if self.mst_method == "famst":
|
|
969
|
+
# FAMST's approximate-neighbor backends operate on dense
|
|
970
|
+
# features. Keep accepting sparse caller input, but convert it
|
|
971
|
+
# here so selecting the approximate method is sufficient.
|
|
972
|
+
X_checked = X_checked.toarray()
|
|
905
973
|
# Cosine distance depends only on row direction. Normalize with a
|
|
906
974
|
# scale-first algorithm so very large finite inputs cannot overflow
|
|
907
975
|
# scikit-learn's dot products during distance calculation or PCA init.
|
|
@@ -1000,7 +1068,7 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
1000
1068
|
"n_components", "n_msts", "resolved_device",
|
|
1001
1069
|
"mst_neighbor_backend", "include_knn_attraction",
|
|
1002
1070
|
"gravity_neighbors", "gravity_resolution",
|
|
1003
|
-
"gravity_strength", "gravity_core_quantile",
|
|
1071
|
+
"gravity_strength", "gravity_min_dist", "gravity_core_quantile",
|
|
1004
1072
|
"gravity_mass_power",
|
|
1005
1073
|
"gravity_pack_regions", "gravity_pack_radius_quantile",
|
|
1006
1074
|
"gravity_pack_gap_fraction",
|
|
@@ -1039,6 +1107,7 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
1039
1107
|
random_state=42 if self.random_state is None else self.random_state,
|
|
1040
1108
|
core_quantile=options["gravity_core_quantile"],
|
|
1041
1109
|
strength=options["gravity_strength"],
|
|
1110
|
+
min_dist=0.0,
|
|
1042
1111
|
mass_power=options["gravity_mass_power"],
|
|
1043
1112
|
pack_regions=options["gravity_pack_regions"],
|
|
1044
1113
|
pack_radius_quantile=options["gravity_pack_radius_quantile"],
|
|
@@ -1054,6 +1123,11 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
1054
1123
|
self.gravity_point_mass_ = gravity_diagnostics["point_mass"]
|
|
1055
1124
|
self.gravity_region_count_ = int(gravity_diagnostics["region_count"])
|
|
1056
1125
|
self.gravity_regions_packed_ = bool(gravity_diagnostics["regions_packed"])
|
|
1126
|
+
self.gravity_min_dist_used_ = float(gravity_diagnostics["min_dist_threshold"])
|
|
1127
|
+
self.gravity_min_dist_reference_ = float(gravity_diagnostics["min_dist_reference"])
|
|
1128
|
+
self.gravity_min_dist_pairs_adjusted_ = int(
|
|
1129
|
+
gravity_diagnostics["min_dist_pairs_adjusted"]
|
|
1130
|
+
)
|
|
1057
1131
|
self.gravity_graph_construction_time_ = float(
|
|
1058
1132
|
gravity_diagnostics["graph_seconds"]
|
|
1059
1133
|
)
|
|
@@ -1068,6 +1142,9 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
1068
1142
|
else:
|
|
1069
1143
|
self.gravity_region_count_ = 0
|
|
1070
1144
|
self.gravity_regions_packed_ = False
|
|
1145
|
+
self.gravity_min_dist_used_ = 0.0
|
|
1146
|
+
self.gravity_min_dist_reference_ = 0.0
|
|
1147
|
+
self.gravity_min_dist_pairs_adjusted_ = 0
|
|
1071
1148
|
self.gravity_graph_construction_time_ = 0.0
|
|
1072
1149
|
self.gravity_neighbor_search_time_ = 0.0
|
|
1073
1150
|
self.gravity_neighbor_graph_reused_ = False
|
|
@@ -1079,11 +1156,144 @@ class IteratedMinimumSpanningTreeEmbedder(
|
|
|
1079
1156
|
if hasattr(self, "gravity_skipped_reason_"):
|
|
1080
1157
|
del self.gravity_skipped_reason_
|
|
1081
1158
|
self._apply_mean_shift(options)
|
|
1159
|
+
self._apply_gravity_min_dist_floor(options, feature_neighbor_graph)
|
|
1082
1160
|
self.fit_time_ = time.perf_counter() - fit_started
|
|
1083
1161
|
if self._progress_reporter is not None:
|
|
1084
1162
|
self._progress_reporter.finish()
|
|
1085
1163
|
return self
|
|
1086
1164
|
|
|
1165
|
+
def preprocessor(self, preprocessor: str | object, **options: object):
|
|
1166
|
+
"""Attach an input transformer for raw text, images, graphs, or features.
|
|
1167
|
+
|
|
1168
|
+
``preprocessor`` may be ``'text'`` or ``'image'`` for the optional
|
|
1169
|
+
EmbeddingGemma 2 model, ``'graph'`` for NSPPK, or any scikit-learn-
|
|
1170
|
+
compatible transformer. The transformer is fitted before IMSTE when
|
|
1171
|
+
:meth:`fit` or :meth:`fit_transform` is called. This method configures
|
|
1172
|
+
and returns this estimator for chaining.
|
|
1173
|
+
|
|
1174
|
+
Text and image presets accept ``model_name`` (default
|
|
1175
|
+
``'google/embeddinggemma-2'``), ``batch_size`` (default 32), and
|
|
1176
|
+
``device`` (default ``None``). Graph preset options are passed to
|
|
1177
|
+
``NSPPK``. Custom transformers do not accept additional options.
|
|
1178
|
+
|
|
1179
|
+
Parameters
|
|
1180
|
+
----------
|
|
1181
|
+
preprocessor : {'text', 'image', 'graph'} or transformer
|
|
1182
|
+
Modality preset or transformer implementing ``fit`` and
|
|
1183
|
+
``transform``.
|
|
1184
|
+
**options
|
|
1185
|
+
Preset-specific options.
|
|
1186
|
+
|
|
1187
|
+
Returns
|
|
1188
|
+
-------
|
|
1189
|
+
self
|
|
1190
|
+
The configured IMSTE estimator.
|
|
1191
|
+
"""
|
|
1192
|
+
from ._preprocessing import make_preprocessor
|
|
1193
|
+
|
|
1194
|
+
self.input_preprocessor = make_preprocessor(
|
|
1195
|
+
preprocessor, options=options
|
|
1196
|
+
)
|
|
1197
|
+
return self
|
|
1198
|
+
|
|
1199
|
+
def tune(
|
|
1200
|
+
self,
|
|
1201
|
+
X: object,
|
|
1202
|
+
y: object,
|
|
1203
|
+
*,
|
|
1204
|
+
search_space: Mapping[str, object] | None = None,
|
|
1205
|
+
k: int = 5,
|
|
1206
|
+
n_samples: int = 40,
|
|
1207
|
+
n_initial_points: int = 20,
|
|
1208
|
+
coverage_weight: float = 0.4,
|
|
1209
|
+
trial_callback: Callable[[dict[str, object]], None] | None = None,
|
|
1210
|
+
verbose: bool = False,
|
|
1211
|
+
):
|
|
1212
|
+
"""Tune settings for k-NN accuracy and spatial coverage of a 2D layout.
|
|
1213
|
+
|
|
1214
|
+
Each search trial fits IMSTE once on all rows in ``X``; labels are
|
|
1215
|
+
used only to score that transductive embedding with shuffled,
|
|
1216
|
+
stratified five-fold cross-validation. Numeric ``(low, high)`` tuples
|
|
1217
|
+
define inclusive bounds, with integer or continuous dimensions inferred
|
|
1218
|
+
from the current estimator parameter type. Sequences define categorical
|
|
1219
|
+
choices. If ``search_space`` is omitted, the search varies ``n_msts``
|
|
1220
|
+
from 3 to 30, ``learning_rate`` from 0.01 to 0.1, ``negative_ratio``
|
|
1221
|
+
from 1 to 10, ``gravity_strength`` from 0.0 to 1.0, and
|
|
1222
|
+
``mean_shift_iterations`` from 0 to 5. The first
|
|
1223
|
+
``min(n_initial_points, n_samples)`` trials use
|
|
1224
|
+
Latin hypercube sampling; remaining trials use Gaussian-process Bayesian
|
|
1225
|
+
optimization.
|
|
1226
|
+
|
|
1227
|
+
Trials maximize ``(1 - coverage_weight) * accuracy +
|
|
1228
|
+
coverage_weight * spatial_coverage``. Spatial coverage is normalized
|
|
1229
|
+
to [0, 1] from a robust, quantile-scaled 2D occupancy entropy score.
|
|
1230
|
+
The default ``coverage_weight=0.4`` gives accuracy 60% of the objective;
|
|
1231
|
+
set it to zero to tune accuracy alone.
|
|
1232
|
+
|
|
1233
|
+
``trial_callback``, when supplied, is called after each completed trial
|
|
1234
|
+
with its accuracy, coverage and objective scores, the best-so-far
|
|
1235
|
+
metrics and parameters, and a copy of that trial's embedding. This is
|
|
1236
|
+
useful for displaying live progress in a notebook.
|
|
1237
|
+
|
|
1238
|
+
``verbose`` controls progress output from the optimizer and trial/final
|
|
1239
|
+
estimator fits. It defaults to ``False``; ``trial_callback`` remains
|
|
1240
|
+
independent and is silent when omitted.
|
|
1241
|
+
|
|
1242
|
+
The best configuration is then fitted on all rows and stored on this
|
|
1243
|
+
estimator. The returned scikit-optimize ``OptimizeResult`` contains the
|
|
1244
|
+
separate trial metrics, the selected parameters, and final embedding.
|
|
1245
|
+
``best_score`` remains the selected trial's accuracy;
|
|
1246
|
+
``best_objective`` is the value optimized by Bayesian search.
|
|
1247
|
+
``n_components`` is fixed to 2 during tuning.
|
|
1248
|
+
|
|
1249
|
+
Parameters
|
|
1250
|
+
----------
|
|
1251
|
+
X, y : array-like
|
|
1252
|
+
Feature rows and corresponding single-output class labels.
|
|
1253
|
+
search_space : mapping
|
|
1254
|
+
Estimator parameter names mapped to numeric ``(low, high)`` bounds
|
|
1255
|
+
or categorical choice sequences. ``None`` uses defaults for
|
|
1256
|
+
``n_msts`` (3–30), ``learning_rate`` (0.01–0.1), ``negative_ratio``
|
|
1257
|
+
(1–10), ``gravity_strength`` (0.0–1.0), and
|
|
1258
|
+
``mean_shift_iterations`` (0–5).
|
|
1259
|
+
k : int, default=5
|
|
1260
|
+
Number of neighbors in the k-NN scoring classifier.
|
|
1261
|
+
n_samples : int, default=40
|
|
1262
|
+
Total number of parameter configurations to evaluate, including
|
|
1263
|
+
initial Latin hypercube trials.
|
|
1264
|
+
n_initial_points : int, default=20
|
|
1265
|
+
Maximum number of initial Latin hypercube trials.
|
|
1266
|
+
coverage_weight : float, default=0.4
|
|
1267
|
+
Weight of spatial coverage in the combined objective, from zero to
|
|
1268
|
+
one. Accuracy receives the remaining weight.
|
|
1269
|
+
trial_callback : callable or None, default=None
|
|
1270
|
+
Function receiving a trial-result dictionary after each evaluation.
|
|
1271
|
+
verbose : bool, default=False
|
|
1272
|
+
Whether to show optimizer and estimator fit progress.
|
|
1273
|
+
|
|
1274
|
+
Returns
|
|
1275
|
+
-------
|
|
1276
|
+
scikit-optimize OptimizeResult
|
|
1277
|
+
Search history with accuracy, coverage and combined objective
|
|
1278
|
+
scores, plus the best fitted embedding. The estimator exposes
|
|
1279
|
+
``best_params_``, ``best_score_``, ``best_coverage_``,
|
|
1280
|
+
``best_objective_``, and ``tune_result_``.
|
|
1281
|
+
"""
|
|
1282
|
+
from ._tuning import tune_estimator
|
|
1283
|
+
|
|
1284
|
+
return tune_estimator(
|
|
1285
|
+
self,
|
|
1286
|
+
X,
|
|
1287
|
+
y,
|
|
1288
|
+
search_space=search_space,
|
|
1289
|
+
k=k,
|
|
1290
|
+
n_samples=n_samples,
|
|
1291
|
+
n_initial_points=n_initial_points,
|
|
1292
|
+
coverage_weight=coverage_weight,
|
|
1293
|
+
trial_callback=trial_callback,
|
|
1294
|
+
verbose=verbose,
|
|
1295
|
+
)
|
|
1296
|
+
|
|
1087
1297
|
def fit_transform(
|
|
1088
1298
|
self,
|
|
1089
1299
|
X: object,
|