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.
Files changed (38) hide show
  1. {imste-0.2.1 → imste-0.2.2}/PKG-INFO +11 -6
  2. {imste-0.2.1 → imste-0.2.2}/README.md +10 -5
  3. {imste-0.2.1 → imste-0.2.2}/imste/_api.py +8 -2
  4. {imste-0.2.1 → imste-0.2.2}/imste/_estimator_graph.py +43 -9
  5. {imste-0.2.1 → imste-0.2.2}/imste.egg-info/PKG-INFO +11 -6
  6. {imste-0.2.1 → imste-0.2.2}/pyproject.toml +1 -1
  7. {imste-0.2.1 → imste-0.2.2}/LICENSE +0 -0
  8. {imste-0.2.1 → imste-0.2.2}/imste/__init__.py +0 -0
  9. {imste-0.2.1 → imste-0.2.2}/imste/_estimator.py +0 -0
  10. {imste-0.2.1 → imste-0.2.2}/imste/_estimator_utils.py +0 -0
  11. {imste-0.2.1 → imste-0.2.2}/imste/_gravity.py +0 -0
  12. {imste-0.2.1 → imste-0.2.2}/imste/_mean_shift.py +0 -0
  13. {imste-0.2.1 → imste-0.2.2}/imste/_multilevel.py +0 -0
  14. {imste-0.2.1 → imste-0.2.2}/imste/_optimizer.py +0 -0
  15. {imste-0.2.1 → imste-0.2.2}/imste/_optimizer_mps.py +0 -0
  16. {imste-0.2.1 → imste-0.2.2}/imste/_optimizer_torch.py +0 -0
  17. {imste-0.2.1 → imste-0.2.2}/imste/_progress.py +0 -0
  18. {imste-0.2.1 → imste-0.2.2}/imste/_visualization_class_geometry.py +0 -0
  19. {imste-0.2.1 → imste-0.2.2}/imste/_visualization_core.py +0 -0
  20. {imste-0.2.1 → imste-0.2.2}/imste/_visualization_interactive.py +0 -0
  21. {imste-0.2.1 → imste-0.2.2}/imste/class_graph.py +0 -0
  22. {imste-0.2.1 → imste-0.2.2}/imste/inductive.py +0 -0
  23. {imste-0.2.1 → imste-0.2.2}/imste/losses.py +0 -0
  24. {imste-0.2.1 → imste-0.2.2}/imste/mst/__init__.py +0 -0
  25. {imste-0.2.1 → imste-0.2.2}/imste/mst/famst.py +0 -0
  26. {imste-0.2.1 → imste-0.2.2}/imste/mst/graph.py +0 -0
  27. {imste-0.2.1 → imste-0.2.2}/imste/mst/prim.py +0 -0
  28. {imste-0.2.1 → imste-0.2.2}/imste/visualization.py +0 -0
  29. {imste-0.2.1 → imste-0.2.2}/imste.egg-info/SOURCES.txt +0 -0
  30. {imste-0.2.1 → imste-0.2.2}/imste.egg-info/dependency_links.txt +0 -0
  31. {imste-0.2.1 → imste-0.2.2}/imste.egg-info/requires.txt +0 -0
  32. {imste-0.2.1 → imste-0.2.2}/imste.egg-info/top_level.txt +0 -0
  33. {imste-0.2.1 → imste-0.2.2}/setup.cfg +0 -0
  34. {imste-0.2.1 → imste-0.2.2}/tests/test_arxiv_notebook_helpers.py +0 -0
  35. {imste-0.2.1 → imste-0.2.2}/tests/test_estimator.py +0 -0
  36. {imste-0.2.1 → imste-0.2.2}/tests/test_famst.py +0 -0
  37. {imste-0.2.1 → imste-0.2.2}/tests/test_multilevel.py +0 -0
  38. {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.1
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
- graph_embedding = IteratedMinimumSpanningTreeEmbedder().fit_graph_transform(distance_graph)
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. Pass `init_coordinates` with shape
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 preparation notebooks live in their corresponding folders under `data/`.
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 [the arXiv preparation notebook](data/arxiv/prepare_dataset.ipynb) and [the CIFAR-10 preparation notebook](data/cifar10/prepare_dataset.ipynb).
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
- graph_embedding = IteratedMinimumSpanningTreeEmbedder().fit_graph_transform(distance_graph)
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. Pass `init_coordinates` with shape
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 preparation notebooks live in their corresponding folders under `data/`.
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 [the arXiv preparation notebook](data/arxiv/prepare_dataset.ipynb) and [the CIFAR-10 preparation notebook](data/cifar10/prepare_dataset.ipynb).
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
- ``init_features`` optionally supplies one feature row per graph node for
22
- PCA initialization. Remaining keyword arguments configure the estimator.
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. All rows
37
- must follow the graph's order. Initialization affects coordinates only;
38
- graph edges still determine the optimization objective. Without either
39
- form of initialization, the seeded random start is used. The fitted
40
- coordinates are available as ``embedding_``; feature-based ``transform``
41
- is unavailable after ``fit_graph``.
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=self.init_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
- self.fit_graph(distance_graph, init_features=init_features)
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.1
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
- graph_embedding = IteratedMinimumSpanningTreeEmbedder().fit_graph_transform(distance_graph)
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. Pass `init_coordinates` with shape
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 preparation notebooks live in their corresponding folders under `data/`.
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 [the arXiv preparation notebook](data/arxiv/prepare_dataset.ipynb) and [the CIFAR-10 preparation notebook](data/cifar10/prepare_dataset.ipynb).
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
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "imste"
7
- version = "0.2.1"
7
+ version = "0.2.2"
8
8
  description = "Iterated Minimum Spanning Tree Embedding (IMSTE)"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
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