imste 0.2.1__tar.gz → 0.2.2__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 → imste-0.2.2}/PKG-INFO +11 -6
- {imste-0.2.1 → imste-0.2.2}/README.md +10 -5
- {imste-0.2.1 → imste-0.2.2}/imste/_api.py +8 -2
- {imste-0.2.1 → imste-0.2.2}/imste/_estimator_graph.py +43 -9
- {imste-0.2.1 → imste-0.2.2}/imste.egg-info/PKG-INFO +11 -6
- {imste-0.2.1 → imste-0.2.2}/pyproject.toml +1 -1
- {imste-0.2.1 → imste-0.2.2}/LICENSE +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/__init__.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_estimator.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_estimator_utils.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_gravity.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_mean_shift.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_multilevel.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_optimizer.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_optimizer_mps.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_optimizer_torch.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_progress.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_visualization_class_geometry.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_visualization_core.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/_visualization_interactive.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/class_graph.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/inductive.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/losses.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/mst/__init__.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/mst/famst.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/mst/graph.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/mst/prim.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste/visualization.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste.egg-info/SOURCES.txt +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste.egg-info/dependency_links.txt +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste.egg-info/requires.txt +0 -0
- {imste-0.2.1 → imste-0.2.2}/imste.egg-info/top_level.txt +0 -0
- {imste-0.2.1 → imste-0.2.2}/setup.cfg +0 -0
- {imste-0.2.1 → imste-0.2.2}/tests/test_arxiv_notebook_helpers.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/tests/test_estimator.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/tests/test_famst.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/tests/test_multilevel.py +0 -0
- {imste-0.2.1 → imste-0.2.2}/tests/test_optimizer.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: imste
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.2
|
|
4
4
|
Summary: Iterated Minimum Spanning Tree Embedding (IMSTE)
|
|
5
5
|
Author: Fabrizio Costa
|
|
6
6
|
License-Expression: MIT
|
|
@@ -161,7 +161,10 @@ X = StandardScaler().fit_transform(digits.data)
|
|
|
161
161
|
distance_matrix = cdist(X, X, metric="euclidean")
|
|
162
162
|
distance_graph = csr_matrix(distance_matrix)
|
|
163
163
|
|
|
164
|
-
|
|
164
|
+
# First fit IMSTE to X, then use that layout to initialize the graph fit.
|
|
165
|
+
graph_embedding = IteratedMinimumSpanningTreeEmbedder().fit_graph_transform(
|
|
166
|
+
distance_graph, X=X
|
|
167
|
+
)
|
|
165
168
|
|
|
166
169
|
plt.scatter(graph_embedding[:, 0], graph_embedding[:, 1], c=digits.target, cmap="tab10", s=10)
|
|
167
170
|
```
|
|
@@ -442,7 +445,9 @@ score into `[-1, 1]`. This preserves the relative scale between PCA axes. Set
|
|
|
442
445
|
`pca_init_scaling="none"` to preserve raw PCA score magnitudes, or
|
|
443
446
|
`pca_init=False` to use the seeded random initialization instead.
|
|
444
447
|
`fit_graph()` uses the same PCA initialization when `init_features` is supplied;
|
|
445
|
-
otherwise it uses random initialization.
|
|
448
|
+
otherwise it uses random initialization. `fit_graph_transform(graph, X=X)` first
|
|
449
|
+
fits IMSTE to `X` and uses that layout to initialize the graph fit. Pass
|
|
450
|
+
`init_coordinates` with shape
|
|
446
451
|
`(n_samples, n_components)` to start from explicit coordinates instead:
|
|
447
452
|
|
|
448
453
|
```python
|
|
@@ -517,7 +522,7 @@ optimization by passing an `IteratedMinimumSpanningTreeEmbedder` as `embedder`.
|
|
|
517
522
|
|
|
518
523
|
## Notebooks
|
|
519
524
|
|
|
520
|
-
Active experiment notebooks use concise dataset-based names. Dataset
|
|
525
|
+
Active experiment notebooks use concise dataset-based names. Dataset setup notebooks live in `notebooks/dataset_setup/`.
|
|
521
526
|
|
|
522
527
|
- [synthetic_exp](notebooks/synthetic_exp.ipynb): compare IMSTE and UMAP on controlled geometries.
|
|
523
528
|
- [biological_exp](notebooks/biological_exp.ipynb): inspect annotated biological datasets and trajectories.
|
|
@@ -525,9 +530,9 @@ Active experiment notebooks use concise dataset-based names. Dataset preparation
|
|
|
525
530
|
- [cifar10_exp](notebooks/cifar10_exp.ipynb): compare CIFAR-10 image-vector embeddings.
|
|
526
531
|
- [interactive](notebooks/interactive.ipynb): interactively refine a balanced arXiv layout with gravity followed by mean shift.
|
|
527
532
|
- [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.
|
|
533
|
+
- [tabula_sapiens_exp](notebooks/tabula_sapiens_exp.ipynb): load prepared Tabula Sapiens features and compare tissue and cell-type colorings on shared layouts.
|
|
529
534
|
|
|
530
|
-
Prepare source data with
|
|
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.
|
|
531
536
|
|
|
532
537
|
Earlier exploratory notebooks are in
|
|
533
538
|
[notebooks/archive](notebooks/archive/). This includes the [interactive 2D
|
|
@@ -114,7 +114,10 @@ X = StandardScaler().fit_transform(digits.data)
|
|
|
114
114
|
distance_matrix = cdist(X, X, metric="euclidean")
|
|
115
115
|
distance_graph = csr_matrix(distance_matrix)
|
|
116
116
|
|
|
117
|
-
|
|
117
|
+
# First fit IMSTE to X, then use that layout to initialize the graph fit.
|
|
118
|
+
graph_embedding = IteratedMinimumSpanningTreeEmbedder().fit_graph_transform(
|
|
119
|
+
distance_graph, X=X
|
|
120
|
+
)
|
|
118
121
|
|
|
119
122
|
plt.scatter(graph_embedding[:, 0], graph_embedding[:, 1], c=digits.target, cmap="tab10", s=10)
|
|
120
123
|
```
|
|
@@ -395,7 +398,9 @@ score into `[-1, 1]`. This preserves the relative scale between PCA axes. Set
|
|
|
395
398
|
`pca_init_scaling="none"` to preserve raw PCA score magnitudes, or
|
|
396
399
|
`pca_init=False` to use the seeded random initialization instead.
|
|
397
400
|
`fit_graph()` uses the same PCA initialization when `init_features` is supplied;
|
|
398
|
-
otherwise it uses random initialization.
|
|
401
|
+
otherwise it uses random initialization. `fit_graph_transform(graph, X=X)` first
|
|
402
|
+
fits IMSTE to `X` and uses that layout to initialize the graph fit. Pass
|
|
403
|
+
`init_coordinates` with shape
|
|
399
404
|
`(n_samples, n_components)` to start from explicit coordinates instead:
|
|
400
405
|
|
|
401
406
|
```python
|
|
@@ -470,7 +475,7 @@ optimization by passing an `IteratedMinimumSpanningTreeEmbedder` as `embedder`.
|
|
|
470
475
|
|
|
471
476
|
## Notebooks
|
|
472
477
|
|
|
473
|
-
Active experiment notebooks use concise dataset-based names. Dataset
|
|
478
|
+
Active experiment notebooks use concise dataset-based names. Dataset setup notebooks live in `notebooks/dataset_setup/`.
|
|
474
479
|
|
|
475
480
|
- [synthetic_exp](notebooks/synthetic_exp.ipynb): compare IMSTE and UMAP on controlled geometries.
|
|
476
481
|
- [biological_exp](notebooks/biological_exp.ipynb): inspect annotated biological datasets and trajectories.
|
|
@@ -478,9 +483,9 @@ Active experiment notebooks use concise dataset-based names. Dataset preparation
|
|
|
478
483
|
- [cifar10_exp](notebooks/cifar10_exp.ipynb): compare CIFAR-10 image-vector embeddings.
|
|
479
484
|
- [interactive](notebooks/interactive.ipynb): interactively refine a balanced arXiv layout with gravity followed by mean shift.
|
|
480
485
|
- [mnist_exp](notebooks/mnist_exp.ipynb): compare MNIST, Fashion-MNIST, and Kuzushiji-MNIST.
|
|
481
|
-
- [tabula_sapiens_exp](notebooks/tabula_sapiens_exp.ipynb): compare tissue and cell-type colorings on shared layouts.
|
|
486
|
+
- [tabula_sapiens_exp](notebooks/tabula_sapiens_exp.ipynb): load prepared Tabula Sapiens features and compare tissue and cell-type colorings on shared layouts.
|
|
482
487
|
|
|
483
|
-
Prepare source data with
|
|
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.
|
|
484
489
|
|
|
485
490
|
Earlier exploratory notebooks are in
|
|
486
491
|
[notebooks/archive](notebooks/archive/). This includes the [interactive 2D
|
|
@@ -13,16 +13,22 @@ from ._estimator import IteratedMinimumSpanningTreeEmbedder
|
|
|
13
13
|
def fit_graph_transform(
|
|
14
14
|
distance_graph: spmatrix,
|
|
15
15
|
*,
|
|
16
|
+
X: object | None = None,
|
|
16
17
|
init_features: object | None = None,
|
|
17
18
|
**estimator_params: Any,
|
|
18
19
|
) -> np.ndarray:
|
|
19
20
|
"""Fit IMSTE from a sparse distance graph and return its embedding.
|
|
20
21
|
|
|
21
|
-
``
|
|
22
|
-
|
|
22
|
+
If ``X`` is supplied, IMSTE first embeds those features, then uses that
|
|
23
|
+
layout to initialize optimization over ``distance_graph``. The graph
|
|
24
|
+
determines the final optimization objective. Alternatively,
|
|
25
|
+
``init_features`` supplies features for standardized-PCA initialization.
|
|
26
|
+
These two initialization options cannot be combined. Remaining keyword
|
|
27
|
+
arguments configure the estimator.
|
|
23
28
|
"""
|
|
24
29
|
estimator = IteratedMinimumSpanningTreeEmbedder(**estimator_params)
|
|
25
30
|
return estimator.fit_graph_transform(
|
|
26
31
|
distance_graph,
|
|
32
|
+
X=X,
|
|
27
33
|
init_features=init_features,
|
|
28
34
|
)
|
|
@@ -7,6 +7,7 @@ import time
|
|
|
7
7
|
import numpy as np
|
|
8
8
|
from scipy import sparse
|
|
9
9
|
from scipy.sparse import csr_matrix, issparse
|
|
10
|
+
from sklearn.base import clone
|
|
10
11
|
from sklearn.utils.validation import check_array, check_is_fitted
|
|
11
12
|
|
|
12
13
|
from .mst import iterated_graph_edges
|
|
@@ -19,6 +20,7 @@ class _EstimatorGraphMethods:
|
|
|
19
20
|
distance_graph: sparse.spmatrix,
|
|
20
21
|
*,
|
|
21
22
|
init_features: object | None = None,
|
|
23
|
+
init_coordinates: object | None = None,
|
|
22
24
|
) -> "IteratedMinimumSpanningTreeEmbedder":
|
|
23
25
|
"""Fit directly from a sparse graph whose stored values are distances.
|
|
24
26
|
|
|
@@ -33,12 +35,13 @@ class _EstimatorGraphMethods:
|
|
|
33
35
|
``init_features`` optionally supplies the sample-by-feature matrix used
|
|
34
36
|
for standardized PCA initialization. ``init_coordinates`` can instead
|
|
35
37
|
supply a complete initial embedding with one row per graph node and one
|
|
36
|
-
column per output dimension; it takes precedence over PCA
|
|
37
|
-
|
|
38
|
-
graph
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
38
|
+
column per output dimension; it takes precedence over PCA and the
|
|
39
|
+
estimator's ``init_coordinates`` parameter. All rows must follow the
|
|
40
|
+
graph's order. Initialization affects coordinates only; graph edges
|
|
41
|
+
still determine the optimization objective. Without either form of
|
|
42
|
+
initialization, the seeded random start is used. The fitted coordinates
|
|
43
|
+
are available as ``embedding_``; feature-based ``transform`` is
|
|
44
|
+
unavailable after ``fit_graph``.
|
|
42
45
|
"""
|
|
43
46
|
fit_started = time.perf_counter()
|
|
44
47
|
options = self._validated_fit_options()
|
|
@@ -74,6 +77,9 @@ class _EstimatorGraphMethods:
|
|
|
74
77
|
if options["gravity_enabled"] and initialization_features is not None:
|
|
75
78
|
if issparse(initialization_features):
|
|
76
79
|
raise ValueError("gravity refinement currently requires dense features.")
|
|
80
|
+
graph_initial_coordinates = (
|
|
81
|
+
self.init_coordinates if init_coordinates is None else init_coordinates
|
|
82
|
+
)
|
|
77
83
|
self._activate_progress_reporting()
|
|
78
84
|
graph_started = time.perf_counter()
|
|
79
85
|
edges, tree_ranks = iterated_graph_edges(
|
|
@@ -97,7 +103,7 @@ class _EstimatorGraphMethods:
|
|
|
97
103
|
resolved_device=options["resolved_device"],
|
|
98
104
|
schedule_by_rank=True,
|
|
99
105
|
initialization_features=initialization_features,
|
|
100
|
-
initial_coordinates=
|
|
106
|
+
initial_coordinates=graph_initial_coordinates,
|
|
101
107
|
**{
|
|
102
108
|
name: value
|
|
103
109
|
for name, value in options.items()
|
|
@@ -182,10 +188,38 @@ class _EstimatorGraphMethods:
|
|
|
182
188
|
self,
|
|
183
189
|
distance_graph: sparse.spmatrix,
|
|
184
190
|
*,
|
|
191
|
+
X: object | None = None,
|
|
185
192
|
init_features: object | None = None,
|
|
186
193
|
) -> np.ndarray:
|
|
187
|
-
"""Fit from a sparse distance graph and return the embedding array.
|
|
188
|
-
|
|
194
|
+
"""Fit from a sparse distance graph and return the embedding array.
|
|
195
|
+
|
|
196
|
+
If ``X`` is supplied, fit IMSTE to ``X`` first and use that embedding
|
|
197
|
+
to initialize optimization over ``distance_graph``. The graph remains
|
|
198
|
+
the objective for the final fit. ``init_features`` retains the direct
|
|
199
|
+
standardized-PCA initialization behavior of :meth:`fit_graph` and
|
|
200
|
+
cannot be combined with ``X``.
|
|
201
|
+
"""
|
|
202
|
+
if X is None:
|
|
203
|
+
self.fit_graph(distance_graph, init_features=init_features)
|
|
204
|
+
return self.embedding_.copy()
|
|
205
|
+
if init_features is not None:
|
|
206
|
+
raise ValueError("Pass either X or init_features, not both.")
|
|
207
|
+
if (
|
|
208
|
+
not sparse.issparse(distance_graph)
|
|
209
|
+
or distance_graph.ndim != 2
|
|
210
|
+
or distance_graph.shape[0] != distance_graph.shape[1]
|
|
211
|
+
):
|
|
212
|
+
raise ValueError("distance_graph must be a square SciPy sparse matrix.")
|
|
213
|
+
if distance_graph.shape[0] < 2:
|
|
214
|
+
raise ValueError("distance_graph must contain at least two samples.")
|
|
215
|
+
X_checked = check_array(
|
|
216
|
+
X, dtype=np.float64, ensure_2d=True, accept_sparse="csr"
|
|
217
|
+
)
|
|
218
|
+
if X_checked.shape[0] != distance_graph.shape[0]:
|
|
219
|
+
raise ValueError("X must have one row per distance_graph node.")
|
|
220
|
+
feature_estimator = clone(self)
|
|
221
|
+
initialization = feature_estimator.fit_transform(X_checked)
|
|
222
|
+
self.fit_graph(distance_graph, init_coordinates=initialization)
|
|
189
223
|
return self.embedding_.copy()
|
|
190
224
|
|
|
191
225
|
def transform(self, X: object) -> np.ndarray:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: imste
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.2
|
|
4
4
|
Summary: Iterated Minimum Spanning Tree Embedding (IMSTE)
|
|
5
5
|
Author: Fabrizio Costa
|
|
6
6
|
License-Expression: MIT
|
|
@@ -161,7 +161,10 @@ X = StandardScaler().fit_transform(digits.data)
|
|
|
161
161
|
distance_matrix = cdist(X, X, metric="euclidean")
|
|
162
162
|
distance_graph = csr_matrix(distance_matrix)
|
|
163
163
|
|
|
164
|
-
|
|
164
|
+
# First fit IMSTE to X, then use that layout to initialize the graph fit.
|
|
165
|
+
graph_embedding = IteratedMinimumSpanningTreeEmbedder().fit_graph_transform(
|
|
166
|
+
distance_graph, X=X
|
|
167
|
+
)
|
|
165
168
|
|
|
166
169
|
plt.scatter(graph_embedding[:, 0], graph_embedding[:, 1], c=digits.target, cmap="tab10", s=10)
|
|
167
170
|
```
|
|
@@ -442,7 +445,9 @@ score into `[-1, 1]`. This preserves the relative scale between PCA axes. Set
|
|
|
442
445
|
`pca_init_scaling="none"` to preserve raw PCA score magnitudes, or
|
|
443
446
|
`pca_init=False` to use the seeded random initialization instead.
|
|
444
447
|
`fit_graph()` uses the same PCA initialization when `init_features` is supplied;
|
|
445
|
-
otherwise it uses random initialization.
|
|
448
|
+
otherwise it uses random initialization. `fit_graph_transform(graph, X=X)` first
|
|
449
|
+
fits IMSTE to `X` and uses that layout to initialize the graph fit. Pass
|
|
450
|
+
`init_coordinates` with shape
|
|
446
451
|
`(n_samples, n_components)` to start from explicit coordinates instead:
|
|
447
452
|
|
|
448
453
|
```python
|
|
@@ -517,7 +522,7 @@ optimization by passing an `IteratedMinimumSpanningTreeEmbedder` as `embedder`.
|
|
|
517
522
|
|
|
518
523
|
## Notebooks
|
|
519
524
|
|
|
520
|
-
Active experiment notebooks use concise dataset-based names. Dataset
|
|
525
|
+
Active experiment notebooks use concise dataset-based names. Dataset setup notebooks live in `notebooks/dataset_setup/`.
|
|
521
526
|
|
|
522
527
|
- [synthetic_exp](notebooks/synthetic_exp.ipynb): compare IMSTE and UMAP on controlled geometries.
|
|
523
528
|
- [biological_exp](notebooks/biological_exp.ipynb): inspect annotated biological datasets and trajectories.
|
|
@@ -525,9 +530,9 @@ Active experiment notebooks use concise dataset-based names. Dataset preparation
|
|
|
525
530
|
- [cifar10_exp](notebooks/cifar10_exp.ipynb): compare CIFAR-10 image-vector embeddings.
|
|
526
531
|
- [interactive](notebooks/interactive.ipynb): interactively refine a balanced arXiv layout with gravity followed by mean shift.
|
|
527
532
|
- [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.
|
|
533
|
+
- [tabula_sapiens_exp](notebooks/tabula_sapiens_exp.ipynb): load prepared Tabula Sapiens features and compare tissue and cell-type colorings on shared layouts.
|
|
529
534
|
|
|
530
|
-
Prepare source data with
|
|
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.
|
|
531
536
|
|
|
532
537
|
Earlier exploratory notebooks are in
|
|
533
538
|
[notebooks/archive](notebooks/archive/). This includes the [interactive 2D
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|