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.
Files changed (44) hide show
  1. {imste-0.2.2 → imste-0.8.0}/PKG-INFO +57 -17
  2. {imste-0.2.2 → imste-0.8.0}/README.md +51 -16
  3. {imste-0.2.2 → imste-0.8.0}/imste/__init__.py +2 -0
  4. {imste-0.2.2 → imste-0.8.0}/imste/_estimator.py +214 -4
  5. {imste-0.2.2 → imste-0.8.0}/imste/_estimator_graph.py +25 -2
  6. {imste-0.2.2 → imste-0.8.0}/imste/_gravity.py +108 -3
  7. imste-0.8.0/imste/_preprocessing.py +158 -0
  8. imste-0.8.0/imste/_tuning.py +309 -0
  9. {imste-0.2.2 → imste-0.8.0}/imste/_visualization_class_geometry.py +37 -8
  10. imste-0.2.2/imste/class_graph.py → imste-0.8.0/imste/_visualization_class_graph.py +4 -204
  11. {imste-0.2.2 → imste-0.8.0}/imste/_visualization_interactive.py +2 -0
  12. imste-0.8.0/imste/class_graph.py +263 -0
  13. {imste-0.2.2 → imste-0.8.0}/imste/visualization.py +2 -0
  14. {imste-0.2.2 → imste-0.8.0}/imste.egg-info/PKG-INFO +57 -17
  15. {imste-0.2.2 → imste-0.8.0}/imste.egg-info/SOURCES.txt +7 -1
  16. {imste-0.2.2 → imste-0.8.0}/imste.egg-info/requires.txt +7 -0
  17. {imste-0.2.2 → imste-0.8.0}/pyproject.toml +6 -2
  18. imste-0.8.0/tests/test_preprocessing.py +107 -0
  19. imste-0.8.0/tests/test_tuning.py +195 -0
  20. imste-0.8.0/tests/test_visualization.py +68 -0
  21. {imste-0.2.2 → imste-0.8.0}/LICENSE +0 -0
  22. {imste-0.2.2 → imste-0.8.0}/imste/_api.py +0 -0
  23. {imste-0.2.2 → imste-0.8.0}/imste/_estimator_utils.py +0 -0
  24. {imste-0.2.2 → imste-0.8.0}/imste/_mean_shift.py +0 -0
  25. {imste-0.2.2 → imste-0.8.0}/imste/_multilevel.py +0 -0
  26. {imste-0.2.2 → imste-0.8.0}/imste/_optimizer.py +0 -0
  27. {imste-0.2.2 → imste-0.8.0}/imste/_optimizer_mps.py +0 -0
  28. {imste-0.2.2 → imste-0.8.0}/imste/_optimizer_torch.py +0 -0
  29. {imste-0.2.2 → imste-0.8.0}/imste/_progress.py +0 -0
  30. {imste-0.2.2 → imste-0.8.0}/imste/_visualization_core.py +0 -0
  31. {imste-0.2.2 → imste-0.8.0}/imste/inductive.py +0 -0
  32. {imste-0.2.2 → imste-0.8.0}/imste/losses.py +0 -0
  33. {imste-0.2.2 → imste-0.8.0}/imste/mst/__init__.py +0 -0
  34. {imste-0.2.2 → imste-0.8.0}/imste/mst/famst.py +0 -0
  35. {imste-0.2.2 → imste-0.8.0}/imste/mst/graph.py +0 -0
  36. {imste-0.2.2 → imste-0.8.0}/imste/mst/prim.py +0 -0
  37. {imste-0.2.2 → imste-0.8.0}/imste.egg-info/dependency_links.txt +0 -0
  38. {imste-0.2.2 → imste-0.8.0}/imste.egg-info/top_level.txt +0 -0
  39. {imste-0.2.2 → imste-0.8.0}/setup.cfg +0 -0
  40. {imste-0.2.2 → imste-0.8.0}/tests/test_arxiv_notebook_helpers.py +0 -0
  41. {imste-0.2.2 → imste-0.8.0}/tests/test_estimator.py +0 -0
  42. {imste-0.2.2 → imste-0.8.0}/tests/test_famst.py +0 -0
  43. {imste-0.2.2 → imste-0.8.0}/tests/test_multilevel.py +0 -0
  44. {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.2.2
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
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24307529.svg)](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 numeric data. It
52
- builds a weighted graph from ranked minimum spanning trees, then
53
- optimizes one coordinate vector per sample.
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
- For maintainers preparing a release, see the
93
- [release guide](docs/releasing.md).
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.class_graph.plot_class_mixture_mst`. It fits full-covariance Gaussian
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
- - [cifar10_exp](notebooks/cifar10_exp.ipynb): compare CIFAR-10 image-vector embeddings.
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-10](notebooks/dataset_setup/prepare_cifar10_dataset.ipynb), and [Tabula Sapiens](notebooks/dataset_setup/prepare_tabula_sapiens_dataset.ipynb) setup notebooks.
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
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24307529.svg)](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 numeric data. It
5
- builds a weighted graph from ranked minimum spanning trees, then
6
- optimizes one coordinate vector per sample.
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
- For maintainers preparing a release, see the
46
- [release guide](docs/releasing.md).
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.class_graph.plot_class_mixture_mst`. It fits full-covariance Gaussian
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
- - [cifar10_exp](notebooks/cifar10_exp.ipynb): compare CIFAR-10 image-vector embeddings.
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-10](notebooks/dataset_setup/prepare_cifar10_dataset.ipynb), and [Tabula Sapiens](notebooks/dataset_setup/prepare_tabula_sapiens_dataset.ipynb) setup notebooks.
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
- gravity_enabled = gravity_strength > 0.0 and self.metric == "euclidean"
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
- del y # Unsupervised: labels are intentionally never used.
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,