spatial-aim 1.3.0__tar.gz → 1.4.0__tar.gz

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-aim
-Version: 1.3.0
+Version: 1.4.0
 Summary: SpatialAIM — annotation-independent mapping of scRNA-seq references onto high-resolution spatial transcriptomics
 Author-email: Dominik Pysch <dominik.pysch@fau.de>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -705,7 +705,7 @@ Requires-Dist: umap-learn>=0.5
 Requires-Dist: tifffile>=2024.8
 Requires-Dist: zarr>=2.16
 Requires-Dist: scikit-image>=0.22
-Requires-Dist: streamlit>=1.40
+Requires-Dist: streamlit>=1.61
 Requires-Dist: plotly>=5.20
 Requires-Dist: kaleido>=0.2
 Provides-Extra: data
@@ -747,8 +747,8 @@ The spot→state step is **modular**. In principle, any scRNA to ST alignment to
 We implement two baseline mappers (`nearest_centroid`, `wann`) and three reference mappers (`tangram`,  `tacco`, `dot`).
 You are invited to add and try out your mapper of choice!
 
-If you want to replace the Leiden overclustering from Step 1 with your own annotations,
-`--start_from_annotation` takes an existing annotation's `L` cell types as the start clusters instead.
+If you also want to start Step 1 from your own annotations,
+`--annotation` runs the sweep a second time (once per annotation) with an existing annotation's `L` cell types as the start clusters.
 
 ![aim_figure](./docs/figure_2_1.png)
 
@@ -864,8 +864,10 @@ spatialaim gui [--server_port 8501]
 
 Open the printed URL (default http://localhost:8501), set the inputs, pick one or multiple mapper(s), and click **Run**.
 As soon as both `.h5ad` paths are set, the GUI runs the same checks as [`spatialaim validate`](#validate-a-dataset-pair-spatialaim-validate) on that pair: a clean pair is confirmed with a tick in the sidebar, any error or warning is shown in a dialog you can close to continue anyway.
-The GUI writes each mapper's sweep to  `<output_dir>/<mapper>/`. The results using each mapper are visualized in different tabs. When having run multiple mappers, also a "Compare" tab appears.
-An optional **Segmentation path** (the ST slice's cell segmentation mask, see the sidebar's *Info*) is validated with the pair and passed to the runs; their mapper tabs then get a "Shape features" card (shape consistency and the cells' area / eccentricity / solidity per cell type), and the cell-type modal a "Shape features" view. Without it the GUI is unchanged.
+The GUI always runs from the Leiden over-clustering; pick annotations under *Also start from annotations* to additionally start from them (the same as `--annotation`).
+It writes the same layout as the CLI, `<output_dir>/<start>/<mapper>/`. The results are pages in a top navigation: **Overview** (a table of every starting point × mapper at its best overall K, sorted by the overall score; a selected row opens it in Explore), **Explore** (pick starting clusters, method and K in one control bar; switching start or method lands on that combination's best K), **Compare** (several methods of one starting point side by side, once two have finished) and **Single-cell reference**.
+Once an output folder holds results, its linkage is fixed. Mappers and annotations can still be added: the next *Run* computes every missing starting point × mapper combination. Output folders written by earlier versions (`<output_dir>/<mapper>/`) can still be opened and viewed.
+An optional **Segmentation path** (the ST slice's cell segmentation mask, see the sidebar's *Info*) is validated with the pair and passed to the runs; their Explore views then get a "Shape features" card (shape consistency and the cells' area / eccentricity / solidity per cell type), and the cell-type modal a "Shape features" view. Without it the GUI is unchanged.
 
 ### Run via CLI (`spatialaim run`)
 
@@ -881,10 +883,10 @@ The linkage of the agglomeration tree over the start clusters is chosen with `--
 - **`average`** (default): UPGMA — average pairwise distance; no size term, tends to peel small tight groups off a growing dominant state.
 - **`ward`**: Ward's criterion (R's `ward.D`); carries a size term and tends to produce balanced states.
 
-The **start clusters** the tree is built over come from the Leiden over-clustering by default.
-Pass `--start_from_annotation <obs_column>` to use a pre-existing annotation instead: its cell types become the start clusters, no over-clustering is computed at all,
-and `K` sweeps from the number of annotated types down (cells with no label are dropped).
-Give such runs their own `--output_dir`: a run root is named after the mapper alone, so the two modes would otherwise overwrite each other.
+The **start clusters** the tree is built over come from the Leiden over-clustering.
+Pass `--annotation <obs_column> [<obs_column> ...]` to additionally start from pre-existing annotations: the sweep then runs once from the Leiden clusters
+and once per annotation, whose cell types become the start clusters (`K` sweeps from the number of annotated types down).
+Every annotation must label every cell; a missing column or an unlabelled cell is an error (in batch mode, that pair fails).
 
 **Single pair**
 
@@ -895,7 +897,7 @@ spatialaim run --scdata path/to/sc.h5ad \
 		[--segmentation path/to/mask.tif] \
 		[--mapping nearest_centroid|wann|tangram|tacco|dot] \
 		[--linkage_method average|ward] \
-		[--start_from_annotation <obs_column>] \
+		[--annotation <obs_column> ...] \
 		[--leiden_resolution 3.0] \
 		[--k_min 1] [--k_max <L>] [--k_step 1] \
 		[--logging verbose]
@@ -912,7 +914,7 @@ spatialaim run --pairs_csv path/to/pairs.csv \
 		--output_dir path/to/out_dir \
 		[--mapping nearest_centroid|wann|tangram|tacco|dot] \
 		[--linkage_method average|ward] \
-		[--start_from_annotation <obs_column>] \
+		[--annotation <obs_column> ...] \
 		[--leiden_resolution 3.0] \
 		[--k_min 1] [--k_max <L>] [--k_step 1] \
 		[--logging verbose]
@@ -924,17 +926,18 @@ Each pair is written to `<out_dir>/<PairID>_<scName>__<stName>/`.
 
 ```
 <out_dir>/
-├── reference_scaffold.h5ad        # cached reference preparation, shared by all mappers
-└── <mapping>/                     # one folder per mapper, e.g. nearest_centroid/
-    ├── config.yaml                # the run's settings
-    ├── start_clustering.h5ad      # each reference cell's start cluster
-    ├── cell_shape_features.csv    # only with a segmentation mask: area, eccentricity, solidity per cell
-    ├── k_<kkk>/                   # one folder per K
-    │   ├── spot_to_state_mapping_soft.h5ad   # the mapping P (spots × K), plus confidence if the mapper has one
-    │   ├── start_cluster_to_state.csv        # which state each start cluster belongs to
-    │   └── analysis/data/                    # the metrics for this K (the GUI plots them)
-    ├── k_comparison.csv           # one row per K: all metrics and the K-selection scores
-    └── k_selection.json           # the suggested K, overall and per criterion
+├── reference_scaffold.h5ad        # cached reference preparation, shared by all starts and mappers
+├── cell_shape_features.csv        # only with a segmentation mask: area, eccentricity, solidity per cell
+└── <start>/                       # leiden/, plus annotation_<obs_column>/ per --annotation
+    ├── start_clustering.h5ad      # each reference cell's start cluster (shared by the mappers)
+    └── <mapping>/                 # one folder per mapper, e.g. nearest_centroid/
+        ├── config.yaml            # the run's settings (start_from_annotation: this start)
+        ├── k_<kkk>/               # one folder per K
+        │   ├── spot_to_state_mapping_soft.h5ad   # the mapping P (spots × K), plus confidence if the mapper has one
+        │   ├── start_cluster_to_state.csv        # which state each start cluster belongs to
+        │   └── analysis/                         # the metrics for this K (the GUI plots them)
+        ├── k_comparison.csv       # one row per K: all metrics and the K-selection scores
+        └── k_selection.json       # the suggested K, overall and per criterion
 ```
 
 **Sample-dataset example:**
@@ -950,7 +953,7 @@ spatialaim run \
 
 ### Annotation-based baseline
 
-There is no separate command for it: `spatialaim run --start_from_annotation <obs_column>` covers it.
+There is no separate command for it: `spatialaim run --annotation <obs_column>` covers it.
 The annotated types become the start clusters, and the sweep's **`K` = number-of-types** level is the baseline.
 
 ## For developers
@@ -1012,7 +1015,7 @@ ReferenceAligner("<name>", "<name>_env", "spatialaim.reference_aligners.run_<nam
 It is then selectable everywhere automatically:
 
 - `spatialaim gui` (it will be selectable in the sidebar)
-- `spatialaim run --mapping <name>` (as an SpatialAIM reference mapper, one alignment per `K`) — including `--start_from_annotation`, where it maps onto a pre-existing annotation
+- `spatialaim run --mapping <name>` (as an SpatialAIM reference mapper, one alignment per `K`) — including the `--annotation` starts, where it maps onto a pre-existing annotation
 
 **4. Create PR**
 

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/README.md

@@ -22,8 +22,8 @@ The spot→state step is **modular**. In principle, any scRNA to ST alignment to
 We implement two baseline mappers (`nearest_centroid`, `wann`) and three reference mappers (`tangram`,  `tacco`, `dot`).
 You are invited to add and try out your mapper of choice!
 
-If you want to replace the Leiden overclustering from Step 1 with your own annotations,
-`--start_from_annotation` takes an existing annotation's `L` cell types as the start clusters instead.
+If you also want to start Step 1 from your own annotations,
+`--annotation` runs the sweep a second time (once per annotation) with an existing annotation's `L` cell types as the start clusters.
 
 ![aim_figure](./docs/figure_2_1.png)
 
@@ -139,8 +139,10 @@ spatialaim gui [--server_port 8501]
 
 Open the printed URL (default http://localhost:8501), set the inputs, pick one or multiple mapper(s), and click **Run**.
 As soon as both `.h5ad` paths are set, the GUI runs the same checks as [`spatialaim validate`](#validate-a-dataset-pair-spatialaim-validate) on that pair: a clean pair is confirmed with a tick in the sidebar, any error or warning is shown in a dialog you can close to continue anyway.
-The GUI writes each mapper's sweep to  `<output_dir>/<mapper>/`. The results using each mapper are visualized in different tabs. When having run multiple mappers, also a "Compare" tab appears.
-An optional **Segmentation path** (the ST slice's cell segmentation mask, see the sidebar's *Info*) is validated with the pair and passed to the runs; their mapper tabs then get a "Shape features" card (shape consistency and the cells' area / eccentricity / solidity per cell type), and the cell-type modal a "Shape features" view. Without it the GUI is unchanged.
+The GUI always runs from the Leiden over-clustering; pick annotations under *Also start from annotations* to additionally start from them (the same as `--annotation`).
+It writes the same layout as the CLI, `<output_dir>/<start>/<mapper>/`. The results are pages in a top navigation: **Overview** (a table of every starting point × mapper at its best overall K, sorted by the overall score; a selected row opens it in Explore), **Explore** (pick starting clusters, method and K in one control bar; switching start or method lands on that combination's best K), **Compare** (several methods of one starting point side by side, once two have finished) and **Single-cell reference**.
+Once an output folder holds results, its linkage is fixed. Mappers and annotations can still be added: the next *Run* computes every missing starting point × mapper combination. Output folders written by earlier versions (`<output_dir>/<mapper>/`) can still be opened and viewed.
+An optional **Segmentation path** (the ST slice's cell segmentation mask, see the sidebar's *Info*) is validated with the pair and passed to the runs; their Explore views then get a "Shape features" card (shape consistency and the cells' area / eccentricity / solidity per cell type), and the cell-type modal a "Shape features" view. Without it the GUI is unchanged.
 
 ### Run via CLI (`spatialaim run`)
 
@@ -156,10 +158,10 @@ The linkage of the agglomeration tree over the start clusters is chosen with `--
 - **`average`** (default): UPGMA — average pairwise distance; no size term, tends to peel small tight groups off a growing dominant state.
 - **`ward`**: Ward's criterion (R's `ward.D`); carries a size term and tends to produce balanced states.
 
-The **start clusters** the tree is built over come from the Leiden over-clustering by default.
-Pass `--start_from_annotation <obs_column>` to use a pre-existing annotation instead: its cell types become the start clusters, no over-clustering is computed at all,
-and `K` sweeps from the number of annotated types down (cells with no label are dropped).
-Give such runs their own `--output_dir`: a run root is named after the mapper alone, so the two modes would otherwise overwrite each other.
+The **start clusters** the tree is built over come from the Leiden over-clustering.
+Pass `--annotation <obs_column> [<obs_column> ...]` to additionally start from pre-existing annotations: the sweep then runs once from the Leiden clusters
+and once per annotation, whose cell types become the start clusters (`K` sweeps from the number of annotated types down).
+Every annotation must label every cell; a missing column or an unlabelled cell is an error (in batch mode, that pair fails).
 
 **Single pair**
 
@@ -170,7 +172,7 @@ spatialaim run --scdata path/to/sc.h5ad \
 		[--segmentation path/to/mask.tif] \
 		[--mapping nearest_centroid|wann|tangram|tacco|dot] \
 		[--linkage_method average|ward] \
-		[--start_from_annotation <obs_column>] \
+		[--annotation <obs_column> ...] \
 		[--leiden_resolution 3.0] \
 		[--k_min 1] [--k_max <L>] [--k_step 1] \
 		[--logging verbose]
@@ -187,7 +189,7 @@ spatialaim run --pairs_csv path/to/pairs.csv \
 		--output_dir path/to/out_dir \
 		[--mapping nearest_centroid|wann|tangram|tacco|dot] \
 		[--linkage_method average|ward] \
-		[--start_from_annotation <obs_column>] \
+		[--annotation <obs_column> ...] \
 		[--leiden_resolution 3.0] \
 		[--k_min 1] [--k_max <L>] [--k_step 1] \
 		[--logging verbose]
@@ -199,17 +201,18 @@ Each pair is written to `<out_dir>/<PairID>_<scName>__<stName>/`.
 
 ```
 <out_dir>/
-├── reference_scaffold.h5ad        # cached reference preparation, shared by all mappers
-└── <mapping>/                     # one folder per mapper, e.g. nearest_centroid/
-    ├── config.yaml                # the run's settings
-    ├── start_clustering.h5ad      # each reference cell's start cluster
-    ├── cell_shape_features.csv    # only with a segmentation mask: area, eccentricity, solidity per cell
-    ├── k_<kkk>/                   # one folder per K
-    │   ├── spot_to_state_mapping_soft.h5ad   # the mapping P (spots × K), plus confidence if the mapper has one
-    │   ├── start_cluster_to_state.csv        # which state each start cluster belongs to
-    │   └── analysis/data/                    # the metrics for this K (the GUI plots them)
-    ├── k_comparison.csv           # one row per K: all metrics and the K-selection scores
-    └── k_selection.json           # the suggested K, overall and per criterion
+├── reference_scaffold.h5ad        # cached reference preparation, shared by all starts and mappers
+├── cell_shape_features.csv        # only with a segmentation mask: area, eccentricity, solidity per cell
+└── <start>/                       # leiden/, plus annotation_<obs_column>/ per --annotation
+    ├── start_clustering.h5ad      # each reference cell's start cluster (shared by the mappers)
+    └── <mapping>/                 # one folder per mapper, e.g. nearest_centroid/
+        ├── config.yaml            # the run's settings (start_from_annotation: this start)
+        ├── k_<kkk>/               # one folder per K
+        │   ├── spot_to_state_mapping_soft.h5ad   # the mapping P (spots × K), plus confidence if the mapper has one
+        │   ├── start_cluster_to_state.csv        # which state each start cluster belongs to
+        │   └── analysis/                         # the metrics for this K (the GUI plots them)
+        ├── k_comparison.csv       # one row per K: all metrics and the K-selection scores
+        └── k_selection.json       # the suggested K, overall and per criterion
 ```
 
 **Sample-dataset example:**
@@ -225,7 +228,7 @@ spatialaim run \
 
 ### Annotation-based baseline
 
-There is no separate command for it: `spatialaim run --start_from_annotation <obs_column>` covers it.
+There is no separate command for it: `spatialaim run --annotation <obs_column>` covers it.
 The annotated types become the start clusters, and the sweep's **`K` = number-of-types** level is the baseline.
 
 ## For developers
@@ -287,7 +290,7 @@ ReferenceAligner("<name>", "<name>_env", "spatialaim.reference_aligners.run_<nam
 It is then selectable everywhere automatically:
 
 - `spatialaim gui` (it will be selectable in the sidebar)
-- `spatialaim run --mapping <name>` (as an SpatialAIM reference mapper, one alignment per `K`) — including `--start_from_annotation`, where it maps onto a pre-existing annotation
+- `spatialaim run --mapping <name>` (as an SpatialAIM reference mapper, one alignment per `K`) — including the `--annotation` starts, where it maps onto a pre-existing annotation
 
 **4. Create PR**
 

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/environment.yml

@@ -27,7 +27,7 @@ dependencies:
     # --- core (pip-only) ---
     - igraph                # modularity (metrics.modularity)
     - leidenalg             # Leiden over-clustering
-    - squidpy               # spatial metrics (analysis.spatial_organization)
+    - squidpy               # spatial metrics (analysis.topology)
     # --- GUI only ---
     - streamlit
     - plotly

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/pyproject.toml

@@ -48,7 +48,7 @@ dependencies = [
     "zarr>=2.16",  # reading large masks in bands
     "scikit-image>=0.22",  # shape-consistency metric (regionprops), rasterising masks
     # GUI
-    "streamlit>=1.40",
+    "streamlit>=1.61",  # persist_state (sidebar survives st.switch_page)
     "plotly>=5.20",
     "kaleido>=0.2"
 ]

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/src/spatial_aim.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-aim
-Version: 1.3.0
+Version: 1.4.0
 Summary: SpatialAIM — annotation-independent mapping of scRNA-seq references onto high-resolution spatial transcriptomics
 Author-email: Dominik Pysch <dominik.pysch@fau.de>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -705,7 +705,7 @@ Requires-Dist: umap-learn>=0.5
 Requires-Dist: tifffile>=2024.8
 Requires-Dist: zarr>=2.16
 Requires-Dist: scikit-image>=0.22
-Requires-Dist: streamlit>=1.40
+Requires-Dist: streamlit>=1.61
 Requires-Dist: plotly>=5.20
 Requires-Dist: kaleido>=0.2
 Provides-Extra: data
@@ -747,8 +747,8 @@ The spot→state step is **modular**. In principle, any scRNA to ST alignment to
 We implement two baseline mappers (`nearest_centroid`, `wann`) and three reference mappers (`tangram`,  `tacco`, `dot`).
 You are invited to add and try out your mapper of choice!
 
-If you want to replace the Leiden overclustering from Step 1 with your own annotations,
-`--start_from_annotation` takes an existing annotation's `L` cell types as the start clusters instead.
+If you also want to start Step 1 from your own annotations,
+`--annotation` runs the sweep a second time (once per annotation) with an existing annotation's `L` cell types as the start clusters.
 
 ![aim_figure](./docs/figure_2_1.png)
 
@@ -864,8 +864,10 @@ spatialaim gui [--server_port 8501]
 
 Open the printed URL (default http://localhost:8501), set the inputs, pick one or multiple mapper(s), and click **Run**.
 As soon as both `.h5ad` paths are set, the GUI runs the same checks as [`spatialaim validate`](#validate-a-dataset-pair-spatialaim-validate) on that pair: a clean pair is confirmed with a tick in the sidebar, any error or warning is shown in a dialog you can close to continue anyway.
-The GUI writes each mapper's sweep to  `<output_dir>/<mapper>/`. The results using each mapper are visualized in different tabs. When having run multiple mappers, also a "Compare" tab appears.
-An optional **Segmentation path** (the ST slice's cell segmentation mask, see the sidebar's *Info*) is validated with the pair and passed to the runs; their mapper tabs then get a "Shape features" card (shape consistency and the cells' area / eccentricity / solidity per cell type), and the cell-type modal a "Shape features" view. Without it the GUI is unchanged.
+The GUI always runs from the Leiden over-clustering; pick annotations under *Also start from annotations* to additionally start from them (the same as `--annotation`).
+It writes the same layout as the CLI, `<output_dir>/<start>/<mapper>/`. The results are pages in a top navigation: **Overview** (a table of every starting point × mapper at its best overall K, sorted by the overall score; a selected row opens it in Explore), **Explore** (pick starting clusters, method and K in one control bar; switching start or method lands on that combination's best K), **Compare** (several methods of one starting point side by side, once two have finished) and **Single-cell reference**.
+Once an output folder holds results, its linkage is fixed. Mappers and annotations can still be added: the next *Run* computes every missing starting point × mapper combination. Output folders written by earlier versions (`<output_dir>/<mapper>/`) can still be opened and viewed.
+An optional **Segmentation path** (the ST slice's cell segmentation mask, see the sidebar's *Info*) is validated with the pair and passed to the runs; their Explore views then get a "Shape features" card (shape consistency and the cells' area / eccentricity / solidity per cell type), and the cell-type modal a "Shape features" view. Without it the GUI is unchanged.
 
 ### Run via CLI (`spatialaim run`)
 
@@ -881,10 +883,10 @@ The linkage of the agglomeration tree over the start clusters is chosen with `--
 - **`average`** (default): UPGMA — average pairwise distance; no size term, tends to peel small tight groups off a growing dominant state.
 - **`ward`**: Ward's criterion (R's `ward.D`); carries a size term and tends to produce balanced states.
 
-The **start clusters** the tree is built over come from the Leiden over-clustering by default.
-Pass `--start_from_annotation <obs_column>` to use a pre-existing annotation instead: its cell types become the start clusters, no over-clustering is computed at all,
-and `K` sweeps from the number of annotated types down (cells with no label are dropped).
-Give such runs their own `--output_dir`: a run root is named after the mapper alone, so the two modes would otherwise overwrite each other.
+The **start clusters** the tree is built over come from the Leiden over-clustering.
+Pass `--annotation <obs_column> [<obs_column> ...]` to additionally start from pre-existing annotations: the sweep then runs once from the Leiden clusters
+and once per annotation, whose cell types become the start clusters (`K` sweeps from the number of annotated types down).
+Every annotation must label every cell; a missing column or an unlabelled cell is an error (in batch mode, that pair fails).
 
 **Single pair**
 
@@ -895,7 +897,7 @@ spatialaim run --scdata path/to/sc.h5ad \
 		[--segmentation path/to/mask.tif] \
 		[--mapping nearest_centroid|wann|tangram|tacco|dot] \
 		[--linkage_method average|ward] \
-		[--start_from_annotation <obs_column>] \
+		[--annotation <obs_column> ...] \
 		[--leiden_resolution 3.0] \
 		[--k_min 1] [--k_max <L>] [--k_step 1] \
 		[--logging verbose]
@@ -912,7 +914,7 @@ spatialaim run --pairs_csv path/to/pairs.csv \
 		--output_dir path/to/out_dir \
 		[--mapping nearest_centroid|wann|tangram|tacco|dot] \
 		[--linkage_method average|ward] \
-		[--start_from_annotation <obs_column>] \
+		[--annotation <obs_column> ...] \
 		[--leiden_resolution 3.0] \
 		[--k_min 1] [--k_max <L>] [--k_step 1] \
 		[--logging verbose]
@@ -924,17 +926,18 @@ Each pair is written to `<out_dir>/<PairID>_<scName>__<stName>/`.
 
 ```
 <out_dir>/
-├── reference_scaffold.h5ad        # cached reference preparation, shared by all mappers
-└── <mapping>/                     # one folder per mapper, e.g. nearest_centroid/
-    ├── config.yaml                # the run's settings
-    ├── start_clustering.h5ad      # each reference cell's start cluster
-    ├── cell_shape_features.csv    # only with a segmentation mask: area, eccentricity, solidity per cell
-    ├── k_<kkk>/                   # one folder per K
-    │   ├── spot_to_state_mapping_soft.h5ad   # the mapping P (spots × K), plus confidence if the mapper has one
-    │   ├── start_cluster_to_state.csv        # which state each start cluster belongs to
-    │   └── analysis/data/                    # the metrics for this K (the GUI plots them)
-    ├── k_comparison.csv           # one row per K: all metrics and the K-selection scores
-    └── k_selection.json           # the suggested K, overall and per criterion
+├── reference_scaffold.h5ad        # cached reference preparation, shared by all starts and mappers
+├── cell_shape_features.csv        # only with a segmentation mask: area, eccentricity, solidity per cell
+└── <start>/                       # leiden/, plus annotation_<obs_column>/ per --annotation
+    ├── start_clustering.h5ad      # each reference cell's start cluster (shared by the mappers)
+    └── <mapping>/                 # one folder per mapper, e.g. nearest_centroid/
+        ├── config.yaml            # the run's settings (start_from_annotation: this start)
+        ├── k_<kkk>/               # one folder per K
+        │   ├── spot_to_state_mapping_soft.h5ad   # the mapping P (spots × K), plus confidence if the mapper has one
+        │   ├── start_cluster_to_state.csv        # which state each start cluster belongs to
+        │   └── analysis/                         # the metrics for this K (the GUI plots them)
+        ├── k_comparison.csv       # one row per K: all metrics and the K-selection scores
+        └── k_selection.json       # the suggested K, overall and per criterion
 ```
 
 **Sample-dataset example:**
@@ -950,7 +953,7 @@ spatialaim run \
 
 ### Annotation-based baseline
 
-There is no separate command for it: `spatialaim run --start_from_annotation <obs_column>` covers it.
+There is no separate command for it: `spatialaim run --annotation <obs_column>` covers it.
 The annotated types become the start clusters, and the sweep's **`K` = number-of-types** level is the baseline.
 
 ## For developers
@@ -1012,7 +1015,7 @@ ReferenceAligner("<name>", "<name>_env", "spatialaim.reference_aligners.run_<nam
 It is then selectable everywhere automatically:
 
 - `spatialaim gui` (it will be selectable in the sidebar)
-- `spatialaim run --mapping <name>` (as an SpatialAIM reference mapper, one alignment per `K`) — including `--start_from_annotation`, where it maps onto a pre-existing annotation
+- `spatialaim run --mapping <name>` (as an SpatialAIM reference mapper, one alignment per `K`) — including the `--annotation` starts, where it maps onto a pre-existing annotation
 
 **4. Create PR**
 

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/src/spatial_aim.egg-info/SOURCES.txt

@@ -39,7 +39,7 @@ src/spatialaim/analysis/loading.py
 src/spatialaim/analysis/reconstruction.py
 src/spatialaim/analysis/run.py
 src/spatialaim/analysis/shape_consistency.py
-src/spatialaim/analysis/spatial_organization.py
+src/spatialaim/analysis/topology.py
 src/spatialaim/analysis/compare_ks/__init__.py
 src/spatialaim/analysis/compare_ks/collect.py
 src/spatialaim/analysis/compare_ks/criteria.py
@@ -97,6 +97,8 @@ src/spatialaim/gui/views/choose_k.py
 src/spatialaim/gui/views/compare_tab.py
 src/spatialaim/gui/views/controls.py
 src/spatialaim/gui/views/mapper_tab.py
+src/spatialaim/gui/views/overview.py
+src/spatialaim/gui/views/pages.py
 src/spatialaim/gui/views/reference_tab.py
 src/spatialaim/gui/views/report.py
 src/spatialaim/gui/widgets/__init__.py
@@ -126,5 +128,8 @@ src/spatialaim/reference_aligners/run_tacco.py
 src/spatialaim/reference_aligners/run_tangram.py
 tests/test_cli.py
 tests/test_gui_imports.py
+tests/test_gui_overview.py
 tests/test_registry.py
-tests/test_sweep_sample.py
+tests/test_sweep_sample.py
+tests/test_topology.py
+tests/test_utils.py

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/src/spatial_aim.egg-info/requires.txt

@@ -11,7 +11,7 @@ umap-learn>=0.5
 tifffile>=2024.8
 zarr>=2.16
 scikit-image>=0.22
-streamlit>=1.40
+streamlit>=1.61
 plotly>=5.20
 kaleido>=0.2
 

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/src/spatial_aim.egg-info/scm_file_list.json

@@ -32,7 +32,7 @@
     "src/spatialaim/analysis/reconstruction.py",
     "src/spatialaim/analysis/run.py",
     "src/spatialaim/analysis/shape_consistency.py",
-    "src/spatialaim/analysis/spatial_organization.py",
+    "src/spatialaim/analysis/topology.py",
     "src/spatialaim/cli.py",
     "src/spatialaim/clustering.py",
     "src/spatialaim/config.py",
@@ -87,6 +87,8 @@
     "src/spatialaim/gui/views/compare_tab.py",
     "src/spatialaim/gui/views/controls.py",
     "src/spatialaim/gui/views/mapper_tab.py",
+    "src/spatialaim/gui/views/overview.py",
+    "src/spatialaim/gui/views/pages.py",
     "src/spatialaim/gui/views/reference_tab.py",
     "src/spatialaim/gui/views/report.py",
     "src/spatialaim/gui/widgets/__init__.py",
@@ -120,7 +122,10 @@
     "src/spatialaim/utils.py",
     "tests/test_cli.py",
     "tests/test_gui_imports.py",
+    "tests/test_gui_overview.py",
     "tests/test_registry.py",
-    "tests/test_sweep_sample.py"
+    "tests/test_sweep_sample.py",
+    "tests/test_topology.py",
+    "tests/test_utils.py"
   ]
 }

spatial_aim-1.4.0/src/spatial_aim.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.4.0",
+  "distance": 0,
+  "node": "g7f082dce40f94cc4775514abd354f0448788e940",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-30"
+}

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/src/spatialaim/adata_schema.py

@@ -8,9 +8,12 @@ Convention for the sc/st AnnData objects.
 # -------------------- adata_sc --------------------
 
 
-# (n_cells,) int — start-cluster label (0..L-1): the all-gene Leiden over-cluster, or the annotated type in start-from-annotation mode
+# (n_cells,) int — start-cluster label (0..L-1) of the current start: the all-gene Leiden over-cluster, or the annotated type for an annotation start
 OBS_START_CLUSTER = "start_cluster"
 
+# (n_cells,) int — all-gene Leiden over-cluster label; part of the start-independent scaffold, copied into OBS_START_CLUSTER for the Leiden start
+OBS_LEIDEN_ALL_GENES = "leiden_all_genes"
+
 # (n_cells,) int — Leiden label from shared genes only
 OBS_LEIDEN_SHARED_GENES = "leiden_shared_genes"
 
@@ -23,7 +26,7 @@ UNS_N_START_CLUSTERS = "n_start_clusters"
 # list[str] — display name per start cluster, index-aligned to OBS_START_CLUSTER: the annotated type names, or "cluster_<i>" in Leiden mode
 UNS_START_CLUSTER_NAMES = "start_cluster_names"
 
-# float — resolution of the all-gene Leiden over-clustering (absent in start-from-annotation mode)
+# float — resolution of the all-gene Leiden over-clustering
 UNS_LEIDEN_RESOLUTION_ALL_GENES = "leiden_resolution"
 
 # float — resolution (shared genes)
@@ -90,7 +93,7 @@ OBS_MAPPING_CONFIDENCE = "mapping_confidence"
 
 # obsm/obsp/uns — K-independent spatial/expression graphs, built once and reused across the K-sweep
 
-# (n_spots x n_spots) sparse — squidpy spatial KNN graph (local purity + neighbourhood enrichment)
+# (n_spots x n_spots) sparse — squidpy spatial KNN graph (the spatial assortativity)
 OBSP_SPATIAL_CONNECTIVITIES = "spatial_connectivities"
 
 # (n_spots x n_spots) sparse — ST all-gene expression KNN graph for the mapping modularity

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/src/spatialaim/analysis/coherence.py

@@ -1,6 +1,6 @@
 """
 Transcriptional coherence of one K's mapping: modularities of the states on the
-reference and ST expression graphs, and the per-state coherence for the GUI.
+reference and ST expression graphs.
 """
 
 from __future__ import annotations
@@ -8,7 +8,6 @@ import json
 import logging
 from pathlib import Path
 import numpy as np
-import pandas as pd
 import scanpy as sc
 from anndata import AnnData
 from spatialaim.adata_schema import (
@@ -28,12 +27,9 @@ def analyse_modularities(
     adata_st: AnnData,
     output_data_dir: Path,
 ):
-    """Write ``modularity_metrics.json`` and ``coherence_per_spot.csv``.
-
-    The modularity of the states on the reference's all-gene and shared-gene
-    kNN graphs and on the ST expression kNN graph, plus per state the chance
-    level of its coherence (see :func:`_per_state_coherence`).
-    """
+    """Write ``modularity_metrics.json``: the modularity of the states on the
+    reference's all-gene and shared-gene kNN graphs and on the ST expression
+    kNN graph."""
     cell_states = adata_sc.obs[OBS_COMPUTED_STATE].astype(int).to_numpy()
 
     modularity_all = compute_modularity(adata_sc, cell_states)
@@ -41,7 +37,6 @@ def analyse_modularities(
         adata_sc, cell_states, obsp_key=OBSP_CONNECTIVITIES_SHARED_GENES
     )
     modularity_st_expression = _spatial_expression_modularity(adata_st)
-    per_state = _per_state_coherence(adata_st, cell_states, output_data_dir)
 
     with open(output_data_dir / "modularity_metrics.json", "w") as f:
         json.dump(
@@ -49,7 +44,6 @@ def analyse_modularities(
                 "modularity_all": float(modularity_all),
                 "modularity_shared": float(modularity_shared),
                 "modularity_st_expression": float(modularity_st_expression),
-                "per_state": per_state,
             },
             f,
             indent=4,
@@ -78,37 +72,3 @@ def _spatial_expression_modularity(adata_st: AnnData) -> float:
     )
     hard_labels = adata_st.obs[OBS_MAPPING_HARD].astype(int).to_numpy()
     return compute_modularity(graph, hard_labels)
-
-
-def _per_state_coherence(
-    adata_st: AnnData, cell_states: np.ndarray, output_data_dir: Path
-) -> dict:
-    """Per spot, the share of its ST-expression neighbours mapped to its own
-    state (written to ``coherence_per_spot.csv``). Returns per state its chance
-    level, the state's share of spots; every reference state gets an entry,
-    also one without spots."""
-    hard = adata_st.obs[OBS_MAPPING_HARD].astype(int).to_numpy()
-    share = _same_label_share(hard, adata_st.obsp[OBSP_ST_EXPR_CONNECTIVITIES])
-    pd.DataFrame({"id": adata_st.obs_names, "same_label_share": share}).to_csv(
-        output_data_dir / "coherence_per_spot.csv", index=False
-    )
-    return {
-        str(int(s)): {"chance": float(np.mean(hard == s))}
-        for s in np.union1d(np.unique(hard), np.unique(cell_states))
-    }
-
-
-def _same_label_share(labels: np.ndarray, connectivities) -> np.ndarray:
-    """Per node, the share of its graph neighbours with its own label (NaN
-    without neighbours). Neighbours are the stored entries of its row, weights
-    ignored, itself excluded."""
-    A = connectivities.tocoo()
-    off = A.row != A.col
-    row, col = A.row[off], A.col[off]
-    n = A.shape[0]
-    same = np.bincount(
-        row, weights=(labels[row] == labels[col]).astype(np.float64), minlength=n
-    ).astype(np.int64)
-    degree = np.bincount(row, minlength=n).astype(np.int64)
-    with np.errstate(divide="ignore", invalid="ignore"):
-        return np.where(degree > 0, same / degree, np.nan)

{spatial_aim-1.3.0 → spatial_aim-1.4.0}/src/spatialaim/analysis/compare_ks/__init__.py

@@ -1,6 +1,6 @@
 from .criteria import CRITERIA, CRITERION, NULL_SUFFIX, SCATTER_PAIRS, Criterion
 from .run import compare_k_runs
-from .scoring import harmonic_mean, overall, scaled_curves, score_table
+from .scoring import curves, harmonic_mean, overall, score_table
 from .selection import best_ks, pareto_mask
 
 __all__ = [
@@ -11,9 +11,9 @@ __all__ = [
     "Criterion",
     "best_ks",
     "compare_k_runs",
+    "curves",
     "harmonic_mean",
     "overall",
     "pareto_mask",
-    "scaled_curves",
     "score_table",
 ]