spatial-aim 1.0.0__py3-none-any.whl

aim/__init__.py

@@ -0,0 +1,47 @@
+"""AIM (Annotation Independent Mapping): over-cluster an scRNA reference, agglomerate
+the subclusters into K states, and map ST spots onto those states across a K sweep.
+Public surface: ``AIMConfig``, ``MAPPING_CHOICES``, ``run``, ``SpotStateMapper``.
+
+These names are exposed lazily (PEP 562) so that importing ``aim``, or a
+submodule such as ``aim.reference_aligners.run_tangram`` from inside a reference
+aligner's own conda env, does not pull in the heavy sweep/analysis stack
+(scanpy, squidpy, ...), which is only present in ``aim_env``. The heavy modules
+load on first attribute access instead.
+"""
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+_LAZY = {
+    "AIMConfig": ("aim.aim_config", "AIMConfig"),
+    "LINKAGE_METHODS": ("aim.aim_config", "LINKAGE_METHODS"),
+    "MAPPING_CHOICES": ("aim.aim_config", "MAPPING_CHOICES"),
+    "SpotStateMapper": ("aim.mapping", "SpotStateMapper"),
+    "run": ("aim.sweep", "run"),
+}
+
+__all__ = [
+    "AIMConfig",
+    "LINKAGE_METHODS",
+    "MAPPING_CHOICES",
+    "run",
+    "SpotStateMapper",
+]
+
+
+def __getattr__(name: str):
+    try:
+        module_name, attr = _LAZY[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    return getattr(import_module(module_name), attr)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)
+
+
+if TYPE_CHECKING:  # let type checkers and IDEs see the real symbols
+    from aim.aim_config import LINKAGE_METHODS, MAPPING_CHOICES, AIMConfig
+    from aim.mapping import SpotStateMapper
+    from aim.sweep import run

aim/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m aim ...`` as an alias for the ``aim`` console script."""
+
+from aim.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aim/adata_schema.py

@@ -0,0 +1,80 @@
+"""Canonical obs/var/uns/obsm/obsp/layers key names for the sc/st AnnData
+objects, each with a one-line description of what it holds. ``L`` = number of
+start clusters (the partition the agglomeration tree is built over — either the
+all-gene Leiden over-clustering or a pre-existing annotation), ``G_shared`` =
+number of shared genes, ``K`` = number of states at the current cut.
+"""
+
+# ── adata_sc ───────────────────────────────────────────────────────────────
+
+# obs
+OBS_START_CLUSTER = "start_cluster"  # (n_cells,) int — start-cluster label (0..L-1): the all-gene Leiden over-cluster, or the annotated type in start-from-annotation mode
+OBS_LEIDEN_SHARED_GENES = (
+    "leiden_shared_genes"  # (n_cells,) int — Leiden label from shared genes only
+)
+OBS_COMPUTED_STATE = (
+    "computed_state"  # (n_cells,) str categorical — cell's state at the current K
+)
+
+# uns — start clusters + Leiden run parameters
+UNS_N_START_CLUSTERS = "n_start_clusters"  # int — start-cluster count L
+UNS_START_CLUSTER_NAMES = "start_cluster_names"  # list[str] — display name per start cluster, index-aligned to OBS_START_CLUSTER: the annotated type names, or "cluster_<i>" in Leiden mode
+UNS_LEIDEN_RESOLUTION_ALL_GENES = "leiden_resolution"  # float — resolution of the all-gene Leiden over-clustering (absent in start-from-annotation mode)
+UNS_LEIDEN_RESOLUTION_SHARED_GENES = (
+    "leiden_resolution_shared_genes"  # float — resolution (shared genes)
+)
+UNS_LEIDEN_NUMBER_STATES_SHARED_GENES = (
+    "leiden_number_states_shared_genes"  # int — cluster count (shared genes)
+)
+UNS_MODULARITY_SHARED_LEIDEN = "modularity_shared_leiden"  # float — modularity of the shared-gene Leiden partition (K-independent; cached across the sweep)
+
+# obsm/uns/obsp — shared-gene PCA + neighbor graph
+OBSM_PCA_SHARED_GENES = (
+    "X_pca_shared_genes"  # (n_cells x n_comps) — PCA of the shared-gene lognorm matrix
+)
+UNS_NEIGHBORS_SHARED_GENES = (
+    "neighbors_shared_genes"  # dict — scanpy neighbors params for the shared-gene graph
+)
+OBSP_DISTANCES_SHARED_GENES = "neighbors_shared_genes_distances"  # (n_cells x n_cells) sparse — neighbor distances
+OBSP_CONNECTIVITIES_SHARED_GENES = "neighbors_shared_genes_connectivities"  # (n_cells x n_cells) sparse — neighbor connectivities
+
+# uns — per-start-cluster aggregates, all column-aligned to UNS_SHARED_GENES
+UNS_SHARED_GENES = "shared_genes"  # list[str] — sc/st gene intersection; column order for every *_SHARED array
+UNS_START_CLUSTER_SIZES = "start_cluster_sizes"  # (L,) — cells per start cluster
+UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES = "start_cluster_expr_sums_shared"  # (L x G_shared) — summed raw expression per start cluster
+UNS_START_CLUSTER_CENTROIDS_SHARED_GENES = "start_cluster_centroids_shared"  # (L x G_shared) — mean raw expression per start cluster (all-zero rows set to 1e-6)
+UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES_NORM = "start_cluster_expr_sums_shared_norm"  # (L x G_shared) — summed lognorm expression per start cluster
+UNS_START_CLUSTER_CENTROIDS_SHARED_GENES_NORM = "start_cluster_centroids_shared_norm"  # (L x G_shared) — mean lognorm expression per start cluster
+
+# ── adata_st ───────────────────────────────────────────────────────────────
+
+# obsm/obs — one K's spot->state mapping
+OBSM_SPATIAL = "spatial"  # (n_spots x 2) — spatial coordinates
+OBSM_MAPPING_SOFT = (
+    "mapping_soft"  # (n_spots x K) — soft spot->state assignment P at the current K
+)
+OBS_MAPPING_HARD = (
+    "mapping_hard"  # (n_spots,) int — argmax state index (0..K-1) at the current K
+)
+OBS_MAPPING_STATE_CAT = "mapping_state"  # (n_spots,) str categorical — hard state label as a category, for squidpy neighbourhood tools (nhood_enrichment)
+OBS_MAPPING_CONFIDENCE = "mapping_confidence"  # (n_spots,) float in [0,1] — per-spot assignment confidence at the current K; absent when the mapper defines no confidence (reference)
+
+# obsm/obsp/uns — K-independent spatial/expression graphs, built once and reused across the K-sweep
+OBSP_SPATIAL_CONNECTIVITIES = "spatial_connectivities"  # (n_spots x n_spots) sparse — squidpy spatial KNN graph (local purity + neighbourhood enrichment)
+OBSP_ST_EXPR_CONNECTIVITIES = "expr_connectivities"  # (n_spots x n_spots) sparse — ST all-gene expression KNN graph for the mapping modularity
+UNS_NHOOD_ENRICHMENT = f"{OBS_MAPPING_STATE_CAT}_nhood_enrichment"  # dict {zscore, count} — squidpy neighbourhood-enrichment result over the mapped states
+
+# ── shared across adata_sc and adata_st ─────────────────────────────────────
+
+LAYER_LOGNORM = (
+    "lognorm"  # (n_obs x n_vars) — normalize_total(1e4) + log1p over all genes
+)
+OBSM_LOGNORM_SHARED_GENES = "lognorm_shared"  # (n_obs x G_shared) — normalize_total(1e4) + log1p over shared genes only, aligned to UNS_SHARED_GENES
+
+# ── scanpy default keys, referenced by name ─────────────────────────────────
+
+OBSM_PCA = "X_pca"  # (n_cells x n_comps) — PCA of the all-gene lognorm layer
+OBSM_UMAP = "X_umap"  # (n_cells x 2) — UMAP from the all-gene neighbor graph
+OBSM_UMAP_SHARED_GENES = (
+    "X_umap_shared_genes"  # (n_cells x 2) — UMAP from the shared-gene neighbor graph
+)

aim/aggregation.py

@@ -0,0 +1,118 @@
+"""Reference aggregation: per-start-cluster expression sums, sizes, and centroids,
+and the size-weighted per-state expression profiles M for a given K cut."""
+
+import numpy as np
+from anndata import AnnData
+
+from aim.adata_schema import (
+    OBS_START_CLUSTER,
+    OBSM_LOGNORM_SHARED_GENES,
+    UNS_SHARED_GENES,
+    UNS_START_CLUSTER_CENTROIDS_SHARED_GENES,
+    UNS_START_CLUSTER_CENTROIDS_SHARED_GENES_NORM,
+    UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES,
+    UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES_NORM,
+    UNS_START_CLUSTER_SIZES,
+)
+
+
+def _sum_by_cluster(
+    expr: np.ndarray, labels: np.ndarray, n_clusters: int
+) -> np.ndarray:
+    """Sum rows of ``expr`` into ``n_clusters`` buckets given per-row cluster labels."""
+    sums = np.zeros((n_clusters, expr.shape[1]), dtype=np.float32)
+    np.add.at(sums, labels, expr)
+    return sums
+
+
+def compute_start_cluster_aggregates(adata_sc: AnnData) -> None:
+    """
+    Aggregate the reference over its start clusters on the shared genes, raw and
+    normalized, storing the per-cluster sums, sizes, and centroids (all L x G_shared,
+    column-aligned to UNS_SHARED_GENES).
+
+    Mapper-facing and mode-independent: the start clusters are the Leiden
+    over-clusters or the annotated types, and this reads them the same way either way.
+
+    Requires: adata_sc.uns[UNS_SHARED_GENES], adata_sc.obsm[OBSM_LOGNORM_SHARED_GENES],
+    adata_sc.obs[OBS_START_CLUSTER].
+    Adds: adata_sc.uns[UNS_START_CLUSTER_SIZES],
+    adata_sc.uns[UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES],
+    adata_sc.uns[UNS_START_CLUSTER_CENTROIDS_SHARED_GENES],
+    adata_sc.uns[UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES_NORM],
+    adata_sc.uns[UNS_START_CLUSTER_CENTROIDS_SHARED_GENES_NORM].
+
+    All-zero raw centroid rows are nudged to a tiny uniform value so their cosine
+    distance stays defined for the agglomeration tree; the normalized centroids are not.
+    """
+    adata_shared = adata_sc[:, adata_sc.uns[UNS_SHARED_GENES]]
+
+    raw = adata_shared.X
+    if hasattr(raw, "toarray"):
+        raw = raw.toarray()
+    raw = np.asarray(raw, dtype=np.float32)
+
+    norm = adata_sc.obsm[OBSM_LOGNORM_SHARED_GENES]
+    if hasattr(norm, "toarray"):
+        norm = norm.toarray()
+    norm = np.asarray(norm, dtype=np.float32)
+
+    labels = adata_sc.obs[OBS_START_CLUSTER].astype(int).to_numpy()
+    n_clusters = int(labels.max()) + 1
+
+    sizes = np.bincount(labels, minlength=n_clusters).astype(np.float32)
+
+    expr_sums = _sum_by_cluster(raw, labels, n_clusters)
+    centroids = expr_sums / (sizes[:, None] + 1e-8)
+    zero_rows = np.where(~centroids.any(axis=1))[0]
+    if zero_rows.size:
+        centroids[zero_rows] = 1e-6
+
+    expr_sums_norm = _sum_by_cluster(norm, labels, n_clusters)
+    centroids_norm = expr_sums_norm / (sizes[:, None] + 1e-8)
+
+    adata_sc.uns[UNS_START_CLUSTER_SIZES] = sizes
+    adata_sc.uns[UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES] = expr_sums
+    adata_sc.uns[UNS_START_CLUSTER_CENTROIDS_SHARED_GENES] = centroids
+    adata_sc.uns[UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES_NORM] = expr_sums_norm
+    adata_sc.uns[UNS_START_CLUSTER_CENTROIDS_SHARED_GENES_NORM] = centroids_norm
+
+
+def _size_weighted_state_profiles(
+    labels_k: np.ndarray,
+    k: int,
+    expr_sums: np.ndarray,
+    sizes: np.ndarray,
+    eps: float,
+) -> np.ndarray:
+    """Pool per-start-cluster expression sums into size-weighted per-state means M
+    (k x G_shared): M[s] = sum of expr_sums over its start clusters / sum of sizes."""
+    state_sums = np.zeros((k, expr_sums.shape[1]), dtype=np.float32)
+    np.add.at(state_sums, labels_k, expr_sums)
+    state_sizes = np.zeros(k, dtype=np.float32)
+    np.add.at(state_sizes, labels_k, sizes)
+
+    m = state_sums / (state_sizes[:, None] + eps)
+    return m.astype(np.float32, copy=False)
+
+
+def assemble_state_profiles_shared_genes(
+    labels_k: np.ndarray,
+    k: int,
+    adata_sc: AnnData,
+    eps: float = 1e-8,
+) -> np.ndarray:
+    """
+    Size-weighted per-state raw expression profiles M (k x G_shared) for a
+    start-cluster->state label array (mean raw counts per state).
+
+    Requires: adata_sc.uns[UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES],
+    adata_sc.uns[UNS_START_CLUSTER_SIZES].
+    """
+    return _size_weighted_state_profiles(
+        labels_k,
+        k,
+        adata_sc.uns[UNS_START_CLUSTER_EXPR_SUMS_SHARED_GENES],
+        adata_sc.uns[UNS_START_CLUSTER_SIZES],
+        eps,
+    )

aim/aim_config.py

@@ -0,0 +1,76 @@
+"""Run configuration for AIM: the ``AIMConfig`` knobs, the mapper registry, and the
+``build_mapper`` factory that turns a config into a ``SpotStateMapper``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from aim.reference_aligners.registry import REFERENCE_ALIGNERS
+
+if TYPE_CHECKING:
+    from .mapping import SpotStateMapper
+
+# In-process mapping strategy names. Kept as plain strings (not derived from the
+# mapper classes) so ``MAPPING_CHOICES`` — used to build the CLI parser — needs no
+# import of the mapper modules. ``build_mapper`` below asserts these stay in sync
+# with the classes' own ``.name``.
+_INPROCESS_METHODS = ("nearest_centroid", "wann")
+# External reference aligners, all served by ReferenceMapper and selected by name.
+# Sourced from the aligner registry so adding one there is the only edit needed.
+_REFERENCE_METHODS = tuple(REFERENCE_ALIGNERS)
+
+MAPPING_CHOICES = _INPROCESS_METHODS + _REFERENCE_METHODS
+
+# Linkage choices for the agglomeration tree over the start clusters, first
+# entry being the default. Single source of truth: the CLI parser and the GUI
+# sidebar offer these, and ``tree.build_agglomeration_tree`` validates against them.
+LINKAGE_METHODS = ("average", "ward")
+
+
+@dataclass
+class AIMConfig:
+    """Per-run knobs for the AIM sweep: mapping choice, start clusters,
+    hyperparameters, and K range."""
+
+    mapping: str = "nearest_centroid"
+    leiden_resolution: float = 3.0
+    # Agglomeration-tree linkage: "average" (UPGMA) or "ward" (balanced states).
+    linkage_method: str = LINKAGE_METHODS[0]
+    # Start clusters (what the agglomeration tree is built over): None = Leiden
+    # over-clustering; an obs column name = use that annotation instead, in which
+    # case no all-gene Leiden is computed and K sweeps from the number of types.
+    start_from_annotation: str | None = None
+    # K sweep range
+    k_min: int | None = None
+    k_max: int | None = None
+    k_step: int = 1
+
+    def build_mapper(self) -> "SpotStateMapper":
+        """Build the ``SpotStateMapper`` named by ``self.mapping``.
+
+        The mapper modules are imported here, lazily, so merely reading
+        ``AIMConfig``/``MAPPING_CHOICES`` does not import them.
+        """
+        from .mapping import (
+            NearestCentroidMapper,
+            ReferenceMapper,
+            WANNMapper,
+        )
+
+        inprocess: dict[str, type[SpotStateMapper]] = {
+            NearestCentroidMapper.name: NearestCentroidMapper,
+            WANNMapper.name: WANNMapper,
+        }
+        assert tuple(inprocess) == _INPROCESS_METHODS, (
+            "MAPPING_CHOICES out of sync with mapper class names: "
+            f"{tuple(inprocess)} != {_INPROCESS_METHODS}"
+        )
+
+        if self.mapping in _REFERENCE_METHODS:
+            return ReferenceMapper(reference_method=self.mapping)
+        if self.mapping not in inprocess:
+            raise ValueError(
+                f"mapping must be one of {MAPPING_CHOICES}, got {self.mapping!r}"
+            )
+        return inprocess[self.mapping]()

aim/analysis/__init__.py

@@ -0,0 +1,13 @@
+"""Post-mapping analysis package; exposes ``run_analysis``."""
+
+__all__ = ["run_analysis"]
+
+
+def __getattr__(name: str):
+    # Lazy import to avoid an import cycle: analysis.analysis imports metrics,
+    # which imports leaf helpers from this package.
+    if name == "run_analysis":
+        from .analysis import run_analysis
+
+        return run_analysis
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

aim/analysis/analysis.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from anndata import AnnData
+
+from .biology import (
+    analyse_substate_coherence,
+    analyse_modularities,
+)
+from .confidence import analyse_spot_confidence
+from .reconstruction import analyse_reconstruction
+from .topology import analyse_spatial_organization
+
+from .loading import (
+    load_spot_to_state_mapping_soft_and_hard,
+    load_start_cluster_to_state,
+    infer_cell_to_state_cluster,
+)
+from .onehot import analyse_spot_to_state_one_hotness
+
+logger = logging.getLogger(__name__)
+
+
+def run_analysis(adata_sc: AnnData, adata_st: AnnData, run_dir: Path) -> None:
+    """Run the full post-mapping analysis for one K, writing machine-readable
+    metrics under ``run_dir/analysis/data/``.
+
+    Loads this K's mapping and computes state stats, one-hotness, spatial
+    organisation, substate coherence, reconstruction cosine similarity and
+    modularity. No figures are rendered: the interactive GUI (``python -m gui``)
+    builds every plot on demand from these outputs.
+
+    Requires: adata_sc.obs[OBS_START_CLUSTER],
+        adata_sc.obs[OBS_LEIDEN_SHARED_GENES],
+        adata_sc.uns[UNS_START_CLUSTER_CENTROIDS_SHARED_GENES_NORM] (and the further
+        uns keys read by the delegate analyses). run_dir must contain
+        spot_to_state_mapping_soft.h5ad and start_cluster_to_state.csv.
+    Adds: adata_st.obsm[OBSM_MAPPING_SOFT], adata_st.obs[OBS_MAPPING_HARD],
+        adata_sc.obs[OBS_COMPUTED_STATE].
+    """
+
+    run_dir = Path(run_dir)
+    analysis_dir = run_dir / "analysis"
+    data_dir = analysis_dir / "data"
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    # Load start-cluster to state mapping & infer cell to state mapping
+    start_cluster_to_state = load_start_cluster_to_state(run_dir)
+    infer_cell_to_state_cluster(adata_sc, start_cluster_to_state)
+
+    # Load spot to state mapping
+    load_spot_to_state_mapping_soft_and_hard(run_dir, adata_st)
+
+    # logger.info("Computing one-hot metrics...")
+    analyse_spot_to_state_one_hotness(adata_st, data_dir)
+
+    # logger.info("Summarising per-spot mapping confidence (if available)...")
+    analyse_spot_confidence(adata_st, data_dir)
+
+    # logger.info("Computing spatial organisation of mapped spots...")
+    analyse_spatial_organization(adata_st, data_dir)
+
+    # logger.info("Computing substate merge coherence...")
+    analyse_substate_coherence(adata_sc, start_cluster_to_state, data_dir)
+
+    # logger.info("Computing reconstruction cosine similarities...")
+    analyse_reconstruction(adata_sc, adata_st, start_cluster_to_state, data_dir)
+
+    # logger.info("Computing modularity for computed assignment...")
+    analyse_modularities(adata_sc, adata_st, data_dir)

aim/analysis/biology.py

@@ -0,0 +1,205 @@
+"""Start-cluster merge coherence and computed-state modularity for the post-mapping
+analysis."""
+
+from __future__ import annotations
+
+import logging
+import json
+from pathlib import Path
+
+import numpy as np
+import scanpy as sc
+from anndata import AnnData
+
+from aim.adata_schema import (
+    LAYER_LOGNORM,
+    OBS_COMPUTED_STATE,
+    OBS_LEIDEN_SHARED_GENES,
+    OBS_MAPPING_HARD,
+    OBSP_CONNECTIVITIES_SHARED_GENES,
+    OBSP_ST_EXPR_CONNECTIVITIES,
+    UNS_MODULARITY_SHARED_LEIDEN,
+    UNS_START_CLUSTER_CENTROIDS_SHARED_GENES_NORM,
+)
+from aim.metrics.biology import (
+    _pairwise_cosine_stats,
+    start_cluster_state_groups,
+    compute_modularity,
+)
+
+logger = logging.getLogger(__name__)
+
+
+N_PERM_COHERENCE = 200  # permutations for the substate-coherence null
+SIG_ALPHA = 0.05  # p-value threshold for "significant"
+
+
+def analyse_substate_coherence(
+    adata_sc: AnnData,
+    labels_k: np.ndarray,
+    output_data_dir: Path,
+    n_perm: int = N_PERM_COHERENCE,
+    seed: int = 0,
+):
+    """Coherence of the start clusters merged into each state.
+
+    For every state merging >=2 start clusters (with at least one start cluster in
+    another state), permutation-tests the mean/median pairwise cosine similarity
+    of the merged start clusters' ``centroids`` (L x G_shared) against ``n_perm``
+    same-sized random draws of start clusters from other states. All-zero (empty)
+    centroid rows are dropped. ``labels_k`` (L,) is the start-cluster->state grouping.
+
+    Writes biology_metrics.json under output_data_dir.
+    """
+
+    centroids = adata_sc.uns[UNS_START_CLUSTER_CENTROIDS_SHARED_GENES_NORM]
+    groups = start_cluster_state_groups(labels_k)
+    # Only start clusters with a non-zero centroid: a zero centroid has undefined
+    # cosine similarity.
+    valid_start_clusters = {
+        int(l) for l in range(len(centroids)) if np.any(centroids[l] != 0.0)
+    }
+
+    per_state: dict[int, dict] = {}
+    for state, state_start_clusters in sorted(groups.items()):
+        targets = [l for l in state_start_clusters if l in valid_start_clusters]
+        others = [l for l in valid_start_clusters if l not in state_start_clusters]
+        if len(targets) < 2:
+            per_state[state] = {
+                "n_start_clusters_merged": len(targets),
+                "skipped_reason": "fewer than 2 non-empty merged start clusters",
+            }
+            continue
+        if not others:
+            per_state[state] = {
+                "n_start_clusters_merged": len(targets),
+                "skipped_reason": "no start clusters in other states to draw a null from",
+            }
+            continue
+
+        rng = np.random.default_rng(seed + state)
+        obs_mean, obs_median = _pairwise_cosine_stats(centroids[targets])
+
+        n_draw = len(targets)
+        replace = n_draw > len(others)
+        others_arr = np.array(others)
+        null_means = np.empty(n_perm)
+        for i in range(n_perm):
+            draw = rng.choice(others_arr, size=n_draw, replace=replace)
+            null_means[i], _ = _pairwise_cosine_stats(centroids[draw])
+
+        p_mean = float((null_means >= obs_mean).mean())
+        z_mean = float((obs_mean - null_means.mean()) / (null_means.std() + 1e-12))
+        per_state[state] = {
+            "n_start_clusters_merged": len(targets),
+            "mean_cossim": obs_mean,
+            "median_cossim": obs_median,
+            "null_mean": float(null_means.mean()),
+            "p_value_mean": p_mean,
+            "z_score_mean": z_mean,
+            "skipped_reason": None,
+        }
+
+    tested = [m for m in per_state.values() if m.get("skipped_reason") is None]
+    if tested:
+        aggregate = {
+            "n_tested_states": len(tested),
+            "mean_cossim": float(np.mean([m["mean_cossim"] for m in tested])),
+            "mean_z_score": float(np.mean([m["z_score_mean"] for m in tested])),
+            "frac_significant": float(
+                np.mean([m["p_value_mean"] < SIG_ALPHA for m in tested])
+            ),
+        }
+    else:
+        aggregate = {
+            "n_tested_states": 0,
+            "mean_cossim": float("nan"),
+            "mean_z_score": float("nan"),
+            "frac_significant": float("nan"),
+        }
+
+    with open(output_data_dir / "biology_metrics.json", "w") as f:
+        json.dump(
+            {"n_perm": int(n_perm), "aggregate": aggregate, "per_state": per_state},
+            f,
+            indent=4,
+        )
+
+
+def _spatial_expression_modularity(adata_st: AnnData) -> float:
+    """Modularity of the hard spot->state labels on the ST expression KNN graph.
+
+    Measures transcriptional coherence of the mapping within the spatial data:
+    builds an expression KNN graph over all genes of ``adata_st`` (PCA of the
+    lognorm layer + scanpy neighbors, matching the reference all-genes graph)
+    and computes the modularity of ``adata_st.obs[OBS_MAPPING_HARD]`` on it.
+
+    Requires: adata_st.layers[LAYER_LOGNORM], adata_st.obs[OBS_MAPPING_HARD].
+    """
+    # The expression KNN graph is K-independent (only the hard labels change per
+    # K), so build it once and cache the connectivities on adata_st.
+    if OBSP_ST_EXPR_CONNECTIVITIES not in adata_st.obsp:
+        # Throwaway AnnData so the PCA / neighbor graph never touches adata_st.
+        st_expr = AnnData(
+            X=adata_st.layers[LAYER_LOGNORM].copy(),
+            obs=adata_st.obs[[]].copy(),
+            var=adata_st.var[[]].copy(),
+        )
+        n = min(30, st_expr.n_obs - 1, st_expr.n_vars - 1)
+        sc.pp.pca(st_expr, n_comps=n)
+        sc.pp.neighbors(st_expr)
+        adata_st.obsp[OBSP_ST_EXPR_CONNECTIVITIES] = st_expr.obsp["connectivities"]
+
+    graph = AnnData(
+        X=np.zeros((adata_st.n_obs, 1), dtype=np.float32),
+        obsp={"connectivities": adata_st.obsp[OBSP_ST_EXPR_CONNECTIVITIES]},
+    )
+    hard_labels = adata_st.obs[OBS_MAPPING_HARD].astype(int).to_numpy()
+    return compute_modularity(graph, hard_labels)
+
+
+def analyse_modularities(
+    adata_sc: AnnData,
+    adata_st: AnnData,
+    output_data_dir: Path,
+):
+    """Modularity of the computed-state partition on the reference KNN graphs.
+
+    Also measures transcriptional coherence of the mapping within the spatial
+    data via ``_spatial_expression_modularity`` (hard spot->state labels on the
+    ST expression KNN graph over all genes).
+
+    Requires: adata_sc.obs[OBS_COMPUTED_STATE], adata_sc.obs[OBS_LEIDEN_SHARED_GENES],
+        adata_sc.obsp[OBSP_CONNECTIVITIES_SHARED_GENES],
+        adata_st.layers[LAYER_LOGNORM], adata_st.obs[OBS_MAPPING_HARD].
+    Writes modularity_metrics.json under output_data_dir.
+    """
+
+    cell_states = adata_sc.obs[OBS_COMPUTED_STATE].astype(int).to_numpy()
+
+    modularity_all = compute_modularity(adata_sc, cell_states)
+    modularity_shared = compute_modularity(
+        adata_sc, cell_states, obsp_key=OBSP_CONNECTIVITIES_SHARED_GENES
+    )
+    # The shared-gene Leiden partition does not depend on K, so compute its
+    # modularity once and cache it on adata_sc.
+    if UNS_MODULARITY_SHARED_LEIDEN not in adata_sc.uns:
+        adata_sc.uns[UNS_MODULARITY_SHARED_LEIDEN] = compute_modularity(
+            adata_sc,
+            adata_sc.obs[OBS_LEIDEN_SHARED_GENES].astype(int).to_numpy(),
+            obsp_key=OBSP_CONNECTIVITIES_SHARED_GENES,
+        )
+    modularity_shared_leiden = adata_sc.uns[UNS_MODULARITY_SHARED_LEIDEN]
+    modularity_st_expression = _spatial_expression_modularity(adata_st)
+
+    with open(output_data_dir / "modularity_metrics.json", "w") as f:
+        json.dump(
+            {
+                "modularity_all": float(modularity_all),
+                "modularity_shared": float(modularity_shared),
+                "modularity_shared_leiden": float(modularity_shared_leiden),
+                "modularity_st_expression": float(modularity_st_expression),
+            },
+            f,
+            indent=4,
+        )

aim/analysis/confidence.py

@@ -0,0 +1,49 @@
+"""Per-spot mapping-confidence summary for the post-mapping analysis.
+
+Only produced when the mapper defined a confidence (``obs[OBS_MAPPING_CONFIDENCE]``,
+loaded by ``loading.py``); the reference mappers define none, so the step is a
+no-op for them and the GUI simply omits the confidence view.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from anndata import AnnData
+
+from aim.adata_schema import OBS_MAPPING_CONFIDENCE
+
+logger = logging.getLogger(__name__)
+
+
+def analyse_spot_confidence(adata_st: AnnData, data_dir: Path) -> None:
+    """Summarise the per-spot mapping confidence, when the mapper defined one.
+
+    Requires: adata_st.obs[OBS_MAPPING_CONFIDENCE] (skipped if absent). Writes
+    confidence_per_spot.csv and confidence_summary.json under data_dir.
+    """
+    if OBS_MAPPING_CONFIDENCE not in adata_st.obs:
+        logger.info("No per-spot confidence for this mapping; skipping.")
+        return
+
+    conf = adata_st.obs[OBS_MAPPING_CONFIDENCE].to_numpy(dtype=float)
+
+    pd.DataFrame({"id": adata_st.obs_names, "confidence": conf}).to_csv(
+        data_dir / "confidence_per_spot.csv", index=False
+    )
+    summary = {
+        "n_spots": int(conf.size),
+        "mean": float(np.mean(conf)),
+        "median": float(np.median(conf)),
+        "min": float(np.min(conf)),
+        "max": float(np.max(conf)),
+        "std": float(np.std(conf)),
+        "frac_above_0.5": float(np.mean(conf >= 0.5)),
+        "frac_above_0.9": float(np.mean(conf >= 0.9)),
+    }
+    with open(data_dir / "confidence_summary.json", "w") as f:
+        json.dump(summary, f, indent=2)