topometry 1.0.2__tar.gz → 1.1.2__tar.gz

{topometry-1.0.2 → topometry-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topometry
-Version: 1.0.2
+Version: 1.1.2
 Summary: Tools for single-cell geometric analysis, clustering and visualization.
 Home-page: https://github.com/davisidarta/topometry
 Author: David Sidarta Oliveira
@@ -18,7 +18,17 @@ Requires-Dist: scikit-learn
 Requires-Dist: matplotlib
 Requires-Dist: pandas
 Requires-Dist: numba
+Requires-Dist: joblib
 Requires-Dist: setuptools
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: hnswlib; extra == "test"
+Requires-Dist: scanpy; extra == "test"
+Requires-Dist: anndata; extra == "test"
+Requires-Dist: scikit-misc; extra == "test"
+Requires-Dist: igraph; extra == "test"
+Requires-Dist: leidenalg; extra == "test"
+Requires-Dist: ipython; extra == "test"
 Dynamic: license-file
 
 [![Latest PyPI version](https://img.shields.io/pypi/v/topometry.svg)](https://pypi.org/project/topometry/)
@@ -73,6 +83,8 @@ Then you can install TopoMetry from PyPI:
 pip install topometry
 ```
 
+Neighbor search uses [hnswlib](https://github.com/nmslib/hnswlib) when it is installed (`pip install hnswlib`), which is recommended for all but small datasets. Without it, TopoMetry falls back to nmslib if present, and otherwise to scikit-learn's exact search. PaCMAP layouts need `pip install pacmap`.
+
 
 ## Tutorials and documentation
 
@@ -100,6 +112,39 @@ sc.pl.embedding(adata, basis='TopoPaCMAP', color='topo_clusters')
 adata.write_h5ad("pbmc3k_topometry.h5ad")
 ```
 
+## Changelog
+
+**v1.1.2** — Notebook display
+
+- Displaying a `TopOGraph` or `Kernel` in a Jupyter notebook, or listing its attributes with `dir()` or tab completion, failed with recent scikit-learn, which reads every attribute of an estimator: a `Kernel` property raised `ValueError`, and another started an all-pairs shortest-path computation. These objects now show their own text summary, and listing attributes evaluates nothing.
+- The PDF report named two `adata.obsm` keys that do not exist; it now names `X_ms_spectral_scaffold`.
+
+**v1.1.1** — Fixes to standing issues
+
+⚠️ Results computed with a cosine metric change, and `base_metric='cosine'` is the default. Analyses run with any release from 0.2.0.0 to 1.1.0 on a cosine metric should be re-run. Euclidean graphs and the default kernels are unchanged on the hnswlib and nmslib backends.
+
+- **Cosine neighbor graphs held similarities instead of distances.** Within each neighborhood the closest points got the lowest kernel weights. Neighbor sets were right; the weights were not. Cosine kernels, geodesics and intrinsic-dimension estimates are now computed on angles, and kernels have no self-loops.
+- **Neighbor search.** A missing backend falls back to the next available of hnswlib, nmslib and scikit-learn with a warning; every backend returns the same number of neighbors; `backend='nmslib'` is honoured; nmslib no longer returns squared distances for dense input.
+- **Kernel options that did not do what they say** now do: CkNN (`delta` is passed on and usually needs tuning), neighborhood expansion, `use_angular=False`, `pairwise=True`.
+- **Projections.** Isomap and the MDE recipes are run on distances rather than on the diffusion operator; UMAP and landmarks work; a standalone `Projector` builds proper affinities.
+- **Reproducibility.** With `n_jobs=1` and a `random_state`, two fits agree bit for bit. Eigenvector signs no longer flip between runs.
+- **TopOGraph.** `global_id`, `local_ids()`, `global_id_mle()` and `global_id_fsa()` return the estimates (the scaffold size is `n_scaffold_components`); `pseudotime` and `spectral_selectivity` pair each eigenvector with its own eigenvalue; saving no longer strips the fitted object.
+- **Riemannian diagnostics** keep the Laplacian sparse, and the plotting wrapper honours `diffusion_t` and `groupby`.
+- **Single-cell wrappers.** `tp.sc.preprocess` no longer modifies its input; BBKNN integration builds kernels from distances; PaCMAP is optional; `fit_adata` works without hnswlib.
+- Compatibility with current scikit-learn, SciPy and matplotlib.
+
+**v1.1.0** — Batch integration and data mapping
+- CCA-anchor batch correction (Seurat v3-style) via `tp.sc.run_cca_integration`
+- Reference atlas persistence (`save_cca_reference` / `load_cca_reference`) and sequential query mapping (`map_to_cca_reference`)
+- High-level preparation utilities (`prepare_for_integration`, `prepare_for_mapping`, `find_mapping_order`)
+- Neighbourhood-based integration quality metrics (`compute_all_integration_metrics`: kNN purity, kNN mixing, iLISI, cLISI, ARI, NMI)
+
+**v1.0.x** — Complete overhaul
+- Redesigned user API with `tp.sc.fit_adata` and `tp.sc.run_and_report` one-liner workflows
+- New utilities for single-cell analysis: intrinsic dimensionality, spectral selectivity, feature modes, graph-signal filtering, imputation
+- Overhauled geometry-preservation metrics (PF1, PJS, SP) and Riemannian diagnostics (pullback metric, deformation maps)
+- Full compatibility with the `scverse` ecosystem (scanpy, scVelo, AnnData)
+
 #### Citation
 
 ---

{topometry-1.0.2 → topometry-1.1.2}/README.md

@@ -50,6 +50,8 @@ Then you can install TopoMetry from PyPI:
 pip install topometry
 ```
 
+Neighbor search uses [hnswlib](https://github.com/nmslib/hnswlib) when it is installed (`pip install hnswlib`), which is recommended for all but small datasets. Without it, TopoMetry falls back to nmslib if present, and otherwise to scikit-learn's exact search. PaCMAP layouts need `pip install pacmap`.
+
 
 ## Tutorials and documentation
 
@@ -77,6 +79,39 @@ sc.pl.embedding(adata, basis='TopoPaCMAP', color='topo_clusters')
 adata.write_h5ad("pbmc3k_topometry.h5ad")
 ```
 
+## Changelog
+
+**v1.1.2** — Notebook display
+
+- Displaying a `TopOGraph` or `Kernel` in a Jupyter notebook, or listing its attributes with `dir()` or tab completion, failed with recent scikit-learn, which reads every attribute of an estimator: a `Kernel` property raised `ValueError`, and another started an all-pairs shortest-path computation. These objects now show their own text summary, and listing attributes evaluates nothing.
+- The PDF report named two `adata.obsm` keys that do not exist; it now names `X_ms_spectral_scaffold`.
+
+**v1.1.1** — Fixes to standing issues
+
+⚠️ Results computed with a cosine metric change, and `base_metric='cosine'` is the default. Analyses run with any release from 0.2.0.0 to 1.1.0 on a cosine metric should be re-run. Euclidean graphs and the default kernels are unchanged on the hnswlib and nmslib backends.
+
+- **Cosine neighbor graphs held similarities instead of distances.** Within each neighborhood the closest points got the lowest kernel weights. Neighbor sets were right; the weights were not. Cosine kernels, geodesics and intrinsic-dimension estimates are now computed on angles, and kernels have no self-loops.
+- **Neighbor search.** A missing backend falls back to the next available of hnswlib, nmslib and scikit-learn with a warning; every backend returns the same number of neighbors; `backend='nmslib'` is honoured; nmslib no longer returns squared distances for dense input.
+- **Kernel options that did not do what they say** now do: CkNN (`delta` is passed on and usually needs tuning), neighborhood expansion, `use_angular=False`, `pairwise=True`.
+- **Projections.** Isomap and the MDE recipes are run on distances rather than on the diffusion operator; UMAP and landmarks work; a standalone `Projector` builds proper affinities.
+- **Reproducibility.** With `n_jobs=1` and a `random_state`, two fits agree bit for bit. Eigenvector signs no longer flip between runs.
+- **TopOGraph.** `global_id`, `local_ids()`, `global_id_mle()` and `global_id_fsa()` return the estimates (the scaffold size is `n_scaffold_components`); `pseudotime` and `spectral_selectivity` pair each eigenvector with its own eigenvalue; saving no longer strips the fitted object.
+- **Riemannian diagnostics** keep the Laplacian sparse, and the plotting wrapper honours `diffusion_t` and `groupby`.
+- **Single-cell wrappers.** `tp.sc.preprocess` no longer modifies its input; BBKNN integration builds kernels from distances; PaCMAP is optional; `fit_adata` works without hnswlib.
+- Compatibility with current scikit-learn, SciPy and matplotlib.
+
+**v1.1.0** — Batch integration and data mapping
+- CCA-anchor batch correction (Seurat v3-style) via `tp.sc.run_cca_integration`
+- Reference atlas persistence (`save_cca_reference` / `load_cca_reference`) and sequential query mapping (`map_to_cca_reference`)
+- High-level preparation utilities (`prepare_for_integration`, `prepare_for_mapping`, `find_mapping_order`)
+- Neighbourhood-based integration quality metrics (`compute_all_integration_metrics`: kNN purity, kNN mixing, iLISI, cLISI, ARI, NMI)
+
+**v1.0.x** — Complete overhaul
+- Redesigned user API with `tp.sc.fit_adata` and `tp.sc.run_and_report` one-liner workflows
+- New utilities for single-cell analysis: intrinsic dimensionality, spectral selectivity, feature modes, graph-signal filtering, imputation
+- Overhauled geometry-preservation metrics (PF1, PJS, SP) and Riemannian diagnostics (pullback metric, deformation maps)
+- Full compatibility with the `scverse` ecosystem (scanpy, scVelo, AnnData)
+
 #### Citation
 
 ---

{topometry-1.0.2 → topometry-1.1.2}/pyproject.toml

@@ -4,3 +4,6 @@ requires = [
     "wheel"
 ]
 build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

{topometry-1.0.2 → topometry-1.1.2}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = topometry
-version = 1.0.2
+version = attr: topo.version.__version__
 author = David Sidarta Oliveira
 author_email = david.oliveira@dpag.ox.ac.uk
 description = Tools for single-cell geometric analysis, clustering and visualization.
@@ -22,10 +22,25 @@ install_requires =
 	matplotlib
 	pandas
 	numba
+	joblib
 	setuptools
 packages = find:
 python_requires = >=3.6
 
+[options.packages.find]
+include = topo*
+
+[options.extras_require]
+test = 
+	pytest
+	hnswlib
+	scanpy
+	anndata
+	scikit-misc
+	igraph
+	leidenalg
+	ipython
+
 [egg_info]
 tag_build = 
 tag_date = 0

topometry-1.1.2/tests/test_cca_integration.py

@@ -0,0 +1,248 @@
+import numpy as np
+import scipy.sparse as sp
+import pytest
+
+# CCA anchoring searches neighbors with hnswlib directly
+pytest.importorskip("hnswlib")
+import anndata
+from anndata import AnnData
+from topo.single_cell import run_cca_integration
+
+
+def _make_adata(n: int, p: int, label: str, seed: int,
+                n_types: int = 4) -> AnnData:
+    """
+    Structured toy data: n_types Gaussian clusters, integer counts,
+    ~80% sparsity. Passes _is_raw_counts() heuristic.
+    """
+    rng = np.random.default_rng(seed)
+    ct = rng.integers(0, n_types, n)
+    centers = rng.normal(0, 3, (n_types, p))
+    X = np.exp(centers[ct] + rng.normal(0, 0.8, (n, p)))
+    X[rng.random((n, p)) < 0.8] = 0.0
+    X = np.round(X).astype(np.float32)   # integer-valued floats → raw counts
+    a = AnnData(X=sp.csr_matrix(X))
+    a.obs_names = [f"{label}_c{i}" for i in range(n)]
+    a.var_names = [f"gene{j:04d}" for j in range(p)]
+    a.obs["batch"] = label
+    return a
+
+
+# ── Test 1: Basic two-batch, all adaptive params ──────────────────────
+def test_two_batch_adaptive():
+    a = _make_adata(300, 500, "A", seed=0)
+    b = _make_adata(280, 500, "B", seed=1)
+    result = run_cca_integration([a, b], scale_output=False)
+
+    assert result.n_obs == 580
+    # n_vars must equal the recorded n_features value
+    assert result.n_vars == result.uns["cca_integration"]["n_features"]
+    assert result.n_vars >= 100, "Expected at least 100 integration features"
+    assert sp.issparse(result.X)
+    assert result.X.dtype == np.float32
+    assert set(result.obs["batch"].unique()) == {"A", "B"}
+    assert "original" in result.layers
+    assert "cca_integration" in result.uns
+
+    meta = result.uns["cca_integration"]
+    assert meta["n_datasets"] == 2
+    assert meta["correction_mode"] == "symmetric"
+    assert meta["n_components"] == 30
+    assert meta["n_anchors_filt_per_merge"][0] > 0, \
+        "Structured data should yield anchors"
+    # All per-merge lists must have exactly N-1 = 1 entry for 2 datasets
+    for key in ["k_anchor_per_merge", "k_filter_per_merge",
+                "k_score_per_merge", "k_weight_per_merge",
+                "sd_bandwidth_per_merge", "n_anchors_raw_per_merge",
+                "n_anchors_filt_per_merge"]:
+        assert len(meta[key]) == 1, f"{key} should have 1 entry"
+
+
+# ── Test 2: Output is in log-normalised space (not z-scored) ──────────
+def test_output_is_lognorm_space():
+    a = _make_adata(300, 500, "A", seed=2)
+    b = _make_adata(300, 500, "B", seed=3)
+    result = run_cca_integration([a, b], scale_output=False)
+
+    X = result.X.toarray()
+    assert X.mean() > 0.0,  "Mean must be > 0 in lognorm space"
+    assert X.max()  > 1.0,  "Max must be > 1 in lognorm space"
+    assert X.min()  >= 0.0, "Values must be >= 0 (clamp enforced)"
+
+    X_orig = result.layers["original"].toarray()
+    assert X_orig.mean() > 0.0
+    assert X_orig.max()  > 1.0
+    assert X_orig.min()  >= 0.0
+
+
+# ── Test 3: Symmetric correction — both batches shift ─────────────────
+def test_symmetric_correction_both_batches_shift():
+    a = _make_adata(300, 500, "A", seed=4)
+    b = _make_adata(300, 500, "B", seed=5)
+    result = run_cca_integration([a, b], scale_output=False)
+
+    X_orig = result.layers["original"].toarray()
+    X_corr = result.X.toarray()
+    batch  = result.obs["batch"].values
+
+    idx_a = np.where(batch == "A")[0]
+    idx_b = np.where(batch == "B")[0]
+
+    shift_a = np.abs(X_corr[idx_a].mean() - X_orig[idx_a].mean())
+    shift_b = np.abs(X_corr[idx_b].mean() - X_orig[idx_b].mean())
+    assert shift_a > 0.0, "Batch A must shift (symmetric correction)"
+    assert shift_b > 0.0, "Batch B must shift (symmetric correction)"
+
+
+# ── Test 4: Single AnnData + batch_key ────────────────────────────────
+def test_single_adata_batch_key():
+    a = _make_adata(200, 400, "A", seed=6)
+    b = _make_adata(200, 400, "B", seed=7)
+    combined = anndata.concat([a, b])
+    result = run_cca_integration(combined, batch_key="batch", scale_output=False)
+    assert result.n_obs == 400
+    assert set(result.obs["batch"].unique()) == {"A", "B"}
+
+
+# ── Test 5: Three-batch guide tree ────────────────────────────────────
+def test_three_batches_guide_tree():
+    batches = [_make_adata(150, 400, f"B{i}", seed=i) for i in range(3)]
+    result  = run_cca_integration(batches, scale_output=False)
+    assert result.n_obs == 450
+    assert set(result.obs["batch"].unique()) == {"B0", "B1", "B2"}
+    meta = result.uns["cca_integration"]
+    assert len(meta["merge_order"])           == 2
+    assert len(meta["n_anchors_filt_per_merge"]) == 2
+    assert len(meta["n_anchors_raw_per_merge"])  == 2
+    assert len(meta["k_anchor_per_merge"])    == 2
+    assert len(meta["sd_bandwidth_per_merge"]) == 2
+
+
+# ── Test 6: Manual hyperparameters respected ──────────────────────────
+def test_manual_hyperparameters():
+    a = _make_adata(200, 400, "A", seed=8)
+    b = _make_adata(200, 400, "B", seed=9)
+    result = run_cca_integration(
+        [a, b],
+        n_features=200, n_components=15,
+        k_anchor=5, k_filter=60, k_score=20, k_weight=50,
+        sd_bandwidth=1.0, scale_output=False)
+    assert result.n_vars == 200
+    meta = result.uns["cca_integration"]
+    assert meta["n_components"]               == 15
+    assert meta["k_anchor_per_merge"][0]      == 5
+    assert meta["k_score_per_merge"][0]       == 20
+    assert meta["k_filter_per_merge"][0]      == 60
+    assert meta["sd_bandwidth_per_merge"][0]  == 1.0
+    assert meta["k_weight_per_merge"][0]      == 50
+
+
+# ── Test 7: Zero-anchor fallback — no crash ───────────────────────────
+def test_zero_anchor_fallback():
+    import warnings
+    X_a = sp.random(40, 100, density=0.1, format="csr", random_state=0)
+    X_b = sp.random(40, 100, density=0.1, format="csr", random_state=1)
+    a = AnnData(X=X_a.astype(np.float32))
+    b = AnnData(X=X_b.astype(np.float32))
+    a.obs_names = [f"A{i}" for i in range(40)]
+    b.obs_names = [f"B{i}" for i in range(40)]
+    a.var_names = b.var_names = [f"g{j}" for j in range(100)]
+    a.obs["batch"] = "A"
+    b.obs["batch"] = "B"
+    with warnings.catch_warnings(record=True):
+        warnings.simplefilter("always")
+        result = run_cca_integration(
+            [a, b], n_features=80, n_components=5,
+            k_anchor=2, k_filter=0, scale_output=False)
+    assert result.n_obs == 80
+
+
+# ── Test 8: raw >= filt anchor counts ─────────────────────────────────
+def test_anchor_counts_raw_ge_filtered():
+    a = _make_adata(200, 400, "A", seed=10)
+    b = _make_adata(200, 400, "B", seed=11)
+    result = run_cca_integration([a, b], scale_output=False)
+    meta = result.uns["cca_integration"]
+    assert meta["n_anchors_raw_per_merge"][0]  >= \
+           meta["n_anchors_filt_per_merge"][0] >= 0
+
+
+# ── Test 9: Corrected values non-negative ─────────────────────────────
+def test_corrected_values_nonnegative():
+    a = _make_adata(300, 500, "A", seed=14)
+    b = _make_adata(300, 500, "B", seed=15)
+    result = run_cca_integration([a, b], scale_output=False)
+    X = result.X.toarray()
+    assert X.min() >= 0.0, f"Min corrected value is {X.min():.4f} < 0"
+
+
+# ── Test 10: Multithreaded — no gross divergence ───────────────────────
+def test_multithreaded_no_gross_divergence():
+    a = _make_adata(200, 400, "A", seed=12)
+    b = _make_adata(200, 400, "B", seed=13)
+    r1 = run_cca_integration([a.copy(), b.copy()], n_jobs=1, seed=0, scale_output=False)
+    r2 = run_cca_integration([a.copy(), b.copy()], n_jobs=2, seed=0, scale_output=False)
+    diff = np.abs((r1.X - r2.X).toarray())
+    assert diff.max() < 0.5, \
+        f"Multithreaded result diverges too much: max diff = {diff.max():.4f}"
+
+
+# ── Test 11: Real data smoke test ─────────────────────────────────────
+def test_pbmc3k_smoke():
+    import scanpy as sc_
+    adata = sc_.datasets.pbmc3k()
+    rng = np.random.default_rng(42)
+    adata.obs["batch"] = rng.choice(["b1", "b2"], size=adata.n_obs)
+
+    result = run_cca_integration(adata, batch_key="batch", n_jobs=2, scale_output=False)
+
+    assert result.n_obs == adata.n_obs
+    assert sp.issparse(result.X)
+    assert result.X.dtype == np.float32
+
+    meta = result.uns["cca_integration"]
+    assert meta["n_anchors_filt_per_merge"][0] > 0, \
+        "Expected anchors on structured PBMC data"
+    assert meta["correction_mode"] == "symmetric"
+    assert result.n_vars == meta["n_features"]
+
+    X = result.X.toarray()
+    assert X.mean()  > 0.0,  "Output must be in lognorm space"
+    assert X.min()  >= 0.0,  "Output must be >= 0"
+
+    print(
+        f"\nPBMC smoke: {result.n_obs} cells, {result.n_vars} features\n"
+        f"  k_anchor:    {meta['k_anchor_per_merge']}\n"
+        f"  n_anchors:   raw={meta['n_anchors_raw_per_merge']}  "
+        f"filt={meta['n_anchors_filt_per_merge']}\n"
+        f"  sd_bandwidth:{meta['sd_bandwidth_per_merge']}"
+    )
+
+
+# ── Test 12: CCA gene loadings from raw U ─────────────────────────────
+def test_cca_gene_loadings_from_raw_u():
+    """
+    U_k must be computed from raw singular vectors, not row-normalised ones.
+    Verify that column norms of U_k are 1.0 and cc_a rows are unit-norm.
+    """
+    from topo.single_cell import _compute_cca
+    rng = np.random.default_rng(0)
+    n_a, n_b, p = 80, 60, 200
+    X_a = rng.standard_normal((n_a, p)).astype(np.float32)
+    X_b = rng.standard_normal((n_b, p)).astype(np.float32)
+    cc_a, cc_b, U_k = _compute_cca(X_a, X_b, n_components=10, seed=0)
+
+    # U_k columns must be unit-norm (column-normalised)
+    col_norms = np.linalg.norm(U_k, axis=0)
+    np.testing.assert_allclose(col_norms, 1.0, atol=1e-5,
+        err_msg="U_k column norms must equal 1.0 (column-normalised)")
+
+    # cc_a rows must be unit-norm (row-normalised)
+    row_norms = np.linalg.norm(cc_a, axis=1)
+    np.testing.assert_allclose(row_norms, 1.0, atol=1e-5,
+        err_msg="cc_a row norms must equal 1.0 (row-normalised)")
+
+    # Shape checks
+    assert U_k.shape == (p, min(10, min(n_a, n_b) - 1))
+    assert cc_a.shape[0] == n_a
+    assert cc_b.shape[0] == n_b

topometry-1.1.2/tests/test_cca_mapping.py

@@ -0,0 +1,205 @@
+import numpy as np
+import scipy.sparse as sp
+import pytest
+
+# CCA anchoring searches neighbors with hnswlib directly
+pytest.importorskip("hnswlib")
+import anndata
+from anndata import AnnData
+from pathlib import Path
+from topo.single_cell import (
+    run_cca_integration,
+    save_cca_reference,
+    load_cca_reference,
+    map_to_cca_reference,
+)
+
+
+def _make_adata(n, p, label, seed, n_types=4):
+    """Same helper as in test_cca_integration.py."""
+    rng = np.random.default_rng(seed)
+    ct = rng.integers(0, n_types, n)
+    centers = rng.normal(0, 3, (n_types, p))
+    X = np.exp(centers[ct] + rng.normal(0, 0.8, (n, p)))
+    X[rng.random((n, p)) < 0.8] = 0.0
+    X = np.round(X).astype(np.float32)
+    a = AnnData(X=sp.csr_matrix(X))
+    a.obs_names = [f"{label}_c{i}" for i in range(n)]
+    a.var_names = [f"gene{j:04d}" for j in range(p)]
+    a.obs["batch"] = label
+    return a
+
+
+@pytest.fixture
+def reference(tmp_path):
+    """A completed integration result saved to disk."""
+    a = _make_adata(200, 400, "A", seed=0)
+    b = _make_adata(200, 400, "B", seed=1)
+    adata_int = run_cca_integration([a, b], scale_output=False)
+    ref_path = tmp_path / "reference.h5ad"
+    save_cca_reference(adata_int, ref_path)
+    return adata_int, ref_path
+
+
+# ── Test 1: run_cca_integration stores reference fields ──────────────────
+def test_integration_stores_reference_fields():
+    a = _make_adata(200, 400, "A", seed=0)
+    b = _make_adata(200, 400, "B", seed=1)
+    result = run_cca_integration([a, b], scale_output=False)
+
+    assert "cca_loadings" in result.varm, \
+        "varm['cca_loadings'] must be stored by run_cca_integration"
+    assert "X_cca" in result.obsm, \
+        "obsm['X_cca'] must be stored by run_cca_integration"
+    assert "ref_mu"    in result.uns["cca_integration"]
+    assert "ref_sigma" in result.uns["cca_integration"]
+
+    U_k      = result.varm["cca_loadings"]
+    cc_ref   = result.obsm["X_cca"]
+    n_comp   = result.uns["cca_integration"]["n_components"]
+
+    assert U_k.shape    == (result.n_vars, n_comp), \
+        f"Expected ({result.n_vars}, {n_comp}), got {U_k.shape}"
+    assert cc_ref.shape == (result.n_obs, n_comp), \
+        f"Expected ({result.n_obs}, {n_comp}), got {cc_ref.shape}"
+
+
+# ── Test 2: save and load round-trip ─────────────────────────────────────
+def test_save_load_roundtrip(tmp_path, reference):
+    adata_int, ref_path = reference
+    loaded = load_cca_reference(ref_path)
+
+    assert loaded.n_obs  == adata_int.n_obs
+    assert loaded.n_vars == adata_int.n_vars
+    assert "cca_loadings" in loaded.varm
+    assert "X_cca"        in loaded.obsm
+    np.testing.assert_allclose(
+        loaded.varm["cca_loadings"],
+        adata_int.varm["cca_loadings"], atol=1e-5)
+
+
+# ── Test 3: load_cca_reference raises on missing fields ──────────────────
+def test_load_raises_on_missing_fields(tmp_path):
+    bad = AnnData(X=sp.csr_matrix(np.ones((10, 5), dtype=np.float32)))
+    bad.obs_names = [f"c{i}" for i in range(10)]
+    bad.var_names = [f"g{j}" for j in range(5)]
+    bad_path = tmp_path / "bad.h5ad"
+    bad.write_h5ad(bad_path)
+    with pytest.raises(ValueError, match="missing required fields"):
+        load_cca_reference(bad_path)
+
+
+# ── Test 4: query_only — basic structure ─────────────────────────────────
+def test_query_only_basic(reference):
+    adata_int, _ = reference
+    query = _make_adata(80, 400, "Q", seed=5)
+    result = map_to_cca_reference(query, adata_int, mode="query_only")
+
+    assert result.n_obs == 80
+    assert result.n_vars == adata_int.n_vars
+    assert sp.issparse(result.X)
+    assert result.X.dtype == np.float32
+    assert "original" in result.layers
+    assert "cca_mapping" in result.uns
+    assert result.uns["cca_mapping"]["mode"] == "query_only"
+
+
+# ── Test 5: query_only — corrected values non-negative ───────────────────
+def test_query_only_nonnegative(reference):
+    adata_int, _ = reference
+    query = _make_adata(80, 400, "Q", seed=6)
+    result = map_to_cca_reference(query, adata_int, mode="query_only")
+    X = result.X.toarray()
+    assert X.min() >= 0.0, f"Corrected values must be >= 0, got min={X.min()}"
+
+
+# ── Test 6: query_only — reference stays frozen ───────────────────────────
+def test_query_only_reference_frozen(reference):
+    adata_int, _ = reference
+    X_ref_before = adata_int.X.toarray().copy()
+    query = _make_adata(80, 400, "Q", seed=7)
+    _ = map_to_cca_reference(query, adata_int, mode="query_only")
+    X_ref_after = adata_int.X.toarray()
+    np.testing.assert_array_equal(X_ref_before, X_ref_after,
+        err_msg="Reference expression must not be modified in query_only mode")
+
+
+# ── Test 7: query_only — query cells shift ───────────────────────────────
+def test_query_only_cells_shift(reference):
+    adata_int, _ = reference
+    query = _make_adata(150, 400, "Q", seed=8)
+    result = map_to_cca_reference(query, adata_int, mode="query_only")
+    X_corr = result.X.toarray()
+    X_orig = result.layers["original"].toarray()
+    assert np.abs(X_corr - X_orig).max() > 0.0, \
+        "Corrected and original query expression should differ"
+
+
+# ── Test 8: query_only from disk ─────────────────────────────────────────
+def test_query_only_from_path(tmp_path, reference):
+    adata_int, ref_path = reference
+    query = _make_adata(80, 400, "Q", seed=9)
+    result = map_to_cca_reference(query, ref_path, mode="query_only")
+    assert result.n_obs == 80
+
+
+# ── Test 9: partial gene coverage — warn and impute ──────────────────────
+def test_partial_gene_coverage_warns(reference):
+    import warnings
+    adata_int, _ = reference
+    features = list(adata_int.var_names)
+    query_full = _make_adata(80, 400, "Q", seed=10)
+    query_partial = query_full[:, query_full.var_names[:300]].copy()
+    coverage = len([g for g in features if g in set(query_partial.var_names)])
+    frac = coverage / len(features)
+    if frac >= 0.8:
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            result = map_to_cca_reference(
+                query_partial, adata_int, mode="query_only")
+        assert result.n_obs == 80
+    else:
+        with pytest.raises(ValueError, match="covers only"):
+            map_to_cca_reference(
+                query_partial, adata_int,
+                mode="query_only", min_shared_features=0.8)
+
+
+# ── Test 10: full_reintegration — output contains all cells ──────────────
+def test_full_reintegration_all_cells(reference):
+    adata_int, _ = reference
+    n_ref = adata_int.n_obs
+    query = _make_adata(80, 400, "Q", seed=11)
+    result = map_to_cca_reference(query, adata_int, mode="full_reintegration")
+    assert result.n_obs == n_ref + 80
+    assert result.n_vars == adata_int.n_vars
+
+
+# ── Test 11: full_reintegration — feature set preserved ──────────────────
+def test_full_reintegration_features_fixed(reference):
+    adata_int, _ = reference
+    query = _make_adata(80, 400, "Q", seed=12)
+    result = map_to_cca_reference(query, adata_int, mode="full_reintegration")
+    assert list(result.var_names) == list(adata_int.var_names), \
+        "full_reintegration must preserve the reference feature set"
+
+
+# ── Test 12: invalid mode raises ─────────────────────────────────────────
+def test_invalid_mode_raises(reference):
+    adata_int, _ = reference
+    query = _make_adata(80, 400, "Q", seed=13)
+    with pytest.raises(ValueError, match="mode must be"):
+        map_to_cca_reference(query, adata_int, mode="invalid")
+
+
+# ── Test 13: query_only — run log populated ──────────────────────────────
+def test_query_only_run_log(reference):
+    adata_int, _ = reference
+    query = _make_adata(150, 400, "Q", seed=14)
+    result = map_to_cca_reference(query, adata_int, mode="query_only")
+    meta = result.uns["cca_mapping"]
+    assert isinstance(meta["n_anchors_raw"],  int)
+    assert isinstance(meta["n_anchors_filt"], int)
+    assert meta["n_anchors_raw"] >= meta["n_anchors_filt"] >= 0
+    assert meta["projection_method"] == "back_projected_U_k"
+    assert meta["n_ref_cells"] == adata_int.n_obs