Merge pull request #30 from quadbio/feat/naming

Enhanced numerical obs mapping support and method consistency

Author: Marius1311

.gitignore

@@ -19,6 +19,7 @@ __pycache__/
 /docs/generated/
 /docs/_build/
 .ipynb_checkpoints/
+/docs/notebooks/tutorials/test_adata.ipynb
 
 # datasets and models
 *.h5ad

README.md

@@ -53,7 +53,7 @@ With a joint embedding in ``.obsm["X_joint"]`` at hand, the simplest way to use
 ```Python
 from cellmapper import CellMapper
 
-cmap = CellMapper(query, reference).fit(
+cmap = CellMapper(query, reference).map(
     use_rep="X_joint", obs_keys="celltype", obsm_keys="X_umap", layer_key="X"
     )
 ```

docs/notebooks/tutorials/spatial_mapping.ipynb

@@ -156,7 +156,7 @@ def evaluate_label_transfer(
 
         if pred_postfix is None or conf_postfix is None:
             raise ValueError(
-                "Label transfer has not been performed. Either call transfer_labels() first "
+                "Label transfer has not been performed. Either call map_obs() first "
                 "or provide prediction_postfix and confidence_postfix parameters."
             )
 
@@ -219,7 +219,7 @@ def plot_confusion_matrix(
             Additional keyword arguments to pass to ConfusionMatrixDisplay.
         """
         if self.prediction_postfix is None or self.confidence_postfix is None:
-            raise ValueError("Label transfer has not been performed. Call transfer_labels() first.")
+            raise ValueError("Label transfer has not been performed. Call map_obs() first.")
 
         # Extract true and predicted labels
         y_true = self.query.obs[label_key].dropna()
@@ -336,7 +336,7 @@ def _get_aligned_expression_arrays(self, layer_key: str) -> tuple[np.ndarray, np
         """
         if self.query_imputed is None:
             raise ValueError(
-                "Imputed query data not found. Either run transfer_expression() first or set query_imputed manually."
+                "Imputed query data not found. Either run map_layers() first or set query_imputed manually."
             )
         shared_genes = list(self.query_imputed.var_names.intersection(self.query.var_names))
         if len(shared_genes) == 0:

docs/notebooks/tutorials/spatial_smoothing.ipynb

@@ -59,6 +59,15 @@ def adata_pbmc3k(precomputed_leiden):
     # PCA
     sc.tl.pca(adata, mask_var="highly_variable")
 
+    # Compute diffusion pseudotime for testing numerical obs mapping
+    # First compute neighbors and diffusion map
+    sc.pp.neighbors(adata, n_neighbors=15, use_rep="X_pca")
+    sc.tl.diffmap(adata)
+
+    # Set root cell for pseudotime computation (use first cell)
+    adata.uns["iroot"] = 0
+    sc.tl.dpt(adata)
+
     # Load precomputed leiden clustering
     adata.obs["leiden"] = precomputed_leiden.astype("str").astype("category")
 

src/cellmapper/model/cellmapper.py

@@ -8,7 +8,7 @@ class TestEvaluate:
     @pytest.mark.parametrize("method", ["pearson", "spearman", "js", "rmse"])
     @pytest.mark.parametrize("groupby", ["batch", "modality"])
     def test_evaluate_expression_transfer_layers_and_methods(self, cmap, eval_layer, method, groupby):
-        cmap.transfer_expression(layer_key="X")
+        cmap.map_layers(key="X")
         cmap.evaluate_expression_transfer(layer_key=eval_layer, method=method, groupby=groupby)
         metrics = cmap.expression_transfer_metrics
         assert metrics["method"] == method

src/cellmapper/model/evaluate.py

@@ -1,6 +1,7 @@
 import numpy as np
 import pytest
 from scipy.sparse import issparse
+from scipy.stats import pearsonr
 
 from cellmapper.model.cellmapper import CellMapper
 
@@ -18,17 +19,17 @@ class TestQueryToReferenceMapping:
     """Tests for query-to-reference mapping functionality in CellMapper."""
 
     def test_label_transfer(self, cmap, expected_label_transfer_metrics):
-        cmap.transfer_labels(obs_keys="leiden")
+        cmap.map_obs(key="leiden")
         cmap.evaluate_label_transfer(label_key="leiden")
         assert_metrics_close(cmap.label_transfer_metrics, expected_label_transfer_metrics)
 
     def test_embedding_transfer(self, cmap):
-        cmap.transfer_embeddings(obsm_keys="X_pca")
+        cmap.map_obsm(key="X_pca")
         assert "X_pca_pred" in cmap.query.obsm
         assert cmap.query.obsm["X_pca_pred"].shape[0] == cmap.query.n_obs
 
     def test_expression_transfer(self, cmap, expected_expression_transfer_metrics):
-        cmap.transfer_expression(layer_key="X")
+        cmap.map_layers(key="X")
         cmap.evaluate_expression_transfer(layer_key="X", method="pearson")
         assert_metrics_close(cmap.expression_transfer_metrics, expected_expression_transfer_metrics)
 
@@ -41,7 +42,7 @@ def test_compute_mapping_matrix_all_methods(self, cmap, method):
 
     @pytest.mark.parametrize("layer_key", ["X", "counts"])
     def test_expression_transfer_layers(self, cmap, layer_key):
-        cmap.transfer_expression(layer_key=layer_key)
+        cmap.map_layers(key=layer_key)
         assert cmap.query_imputed is not None
         assert cmap.query_imputed.X.shape[0] == cmap.query.n_obs
 
@@ -58,7 +59,7 @@ def test_expression_transfer_layers(self, cmap, layer_key):
         ],
     )
     def test_fit_various_combinations(self, cmap, obs_keys, obsm_keys, layer_key):
-        cmap.fit(obs_keys=obs_keys, obsm_keys=obsm_keys, layer_key=layer_key)
+        cmap.map(obs_keys=obs_keys, obsm_keys=obsm_keys, layer_key=layer_key)
         if obs_keys is not None:
             keys = [obs_keys] if isinstance(obs_keys, str) else obs_keys
             for key in keys:
@@ -71,11 +72,11 @@ def test_fit_various_combinations(self, cmap, obs_keys, obsm_keys, layer_key):
             assert cmap.query_imputed is not None
             assert cmap.query_imputed.X.shape[0] == cmap.query.n_obs
 
-    def test_transfer_labels_self_mapping(self, query_reference_adata):
+    def test_map_obs_self_mapping(self, query_reference_adata):
         """Check mapping to self."""
         _, reference = query_reference_adata
         cm = CellMapper(reference, reference)
-        cm.fit(
+        cm.map(
             knn_method="sklearn",
             mapping_method="jaccard",
             obs_keys="leiden",
@@ -174,13 +175,13 @@ def test_query_imputed_invalid_type(self, cmap):
         with pytest.raises(TypeError):
             cmap.query_imputed = [1, 2, 3]
 
-    def test_query_imputed_integration_with_transfer_expression(self, cmap, random_imputed_data):
-        """Test that transfer_expression correctly uses the query_imputed property."""
+    def test_query_imputed_integration_with_map_layers(self, cmap, random_imputed_data):
+        """Test that map_layers correctly uses the query_imputed property."""
         # First check query_imputed is None
         assert cmap.query_imputed is None
 
-        # Transfer expression
-        cmap.transfer_expression(layer_key="X")
+        # Map expression
+        cmap.map_layers(key="X")
 
         # Verify query_imputed was set
         assert cmap.query_imputed is not None
@@ -255,3 +256,51 @@ def test_compute_neighbors_fallback(self, cmap, n_comps, fallback_representation
         assert key_added in cmap.query.obsm
         assert cmap.reference.obsm[key_added].shape[1] == n_comps
         assert cmap.query.obsm[key_added].shape[1] == n_comps
+
+    def test_map_obs_numerical_data_type_detection(self, query_reference_adata):
+        """Test that numerical data types are correctly detected in map_obs."""
+        query, reference = query_reference_adata
+
+        # Add some numerical data to reference
+        reference.obs["numerical_score"] = np.random.rand(reference.n_obs)
+        reference.obs["integer_score"] = np.random.randint(0, 100, reference.n_obs)
+
+        # Create CellMapper and compute mapping matrix
+        cmap = CellMapper(query=query, reference=reference)
+        cmap.compute_neighbors(n_neighbors=30, use_rep="X_pca", method="sklearn")
+        cmap.compute_mapping_matrix(method="gaussian")
+
+        # Test float and integer data
+        for key in ["numerical_score", "integer_score"]:
+            cmap.map_obs(key=key)
+            assert f"{key}_pred" in cmap.query.obs
+            assert cmap.query.obs[f"{key}_pred"].dtype.kind == "f"
+
+    def test_map_obs_pseudotime_cross_mapping(self, query_reference_adata):
+        """Test mapping pseudotime values in cross-mapping mode - should still have reasonable correlation."""
+        query, reference = query_reference_adata
+
+        # Create CellMapper and compute mapping matrix
+        cmap = CellMapper(query=query, reference=reference)
+        cmap.compute_neighbors(n_neighbors=30, use_rep="X_pca", method="sklearn")
+        cmap.compute_mapping_matrix(method="gaussian")
+
+        # Map pseudotime
+        cmap.map_obs(key="dpt_pseudotime")
+
+        # Check that pseudotime was mapped
+        assert "dpt_pseudotime_pred" in cmap.query.obs
+        assert cmap.query.obs["dpt_pseudotime_pred"].dtype == reference.obs["dpt_pseudotime"].dtype
+
+        # Check correlation between actual and predicted pseudotime in query subset
+        # (Note: query is a subset of the original data, so we can compare)
+        query_original_pt = query.obs["dpt_pseudotime"]
+        query_predicted_pt = cmap.query.obs["dpt_pseudotime_pred"]
+
+        correlation, _ = pearsonr(query_original_pt, query_predicted_pt)
+
+        # Cross-mapping should still have reasonably high correlation, though lower than self-mapping
+        assert correlation > 0.99, f"Cross-mapping pseudotime correlation too low: {correlation}"
+
+        # Verify no confidence scores for numerical data
+        assert "dpt_pseudotime_conf" not in cmap.query.obs

tests/conftest.py

@@ -15,26 +15,26 @@ def test_self_mapping_initialization(self, adata_pbmc3k):
         assert cm.reference is adata_pbmc3k
         assert cm.query is adata_pbmc3k
 
-    def test_identity_mapping(self, adata_pbmc3k):
+    @pytest.mark.parametrize("obs_key", ["leiden", "dpt_pseudotime"])
+    def test_identity_mapping(self, adata_pbmc3k, obs_key):
         """Test that with n_neighbors=1, self-mapping preserves original labels exactly."""
         # Initialize with self-mapping
         cm = CellMapper(adata_pbmc3k)
-        cm.fit(
+        cm.map(
             knn_method="sklearn",
             mapping_method="jaccard",
-            obs_keys="leiden",
+            obs_keys=obs_key,
             use_rep="X_pca",
             n_neighbors=1,
-            prediction_postfix="transfer",
+            prediction_postfix="pred",
         )
 
         # With n_neighbors=1, labels should be perfectly preserved
-        assert "leiden_transfer" in adata_pbmc3k.obs
-        assert len(adata_pbmc3k.obs["leiden_transfer"]) == len(adata_pbmc3k.obs["leiden"])
-        # Check that all predicted labels are valid categories
-        assert set(adata_pbmc3k.obs["leiden_transfer"].cat.categories) <= set(adata_pbmc3k.obs["leiden"].cat.categories)
+        assert f"{obs_key}_pred" in adata_pbmc3k.obs
+        assert len(adata_pbmc3k.obs[f"{obs_key}_pred"]) == len(adata_pbmc3k.obs[obs_key])
+
         # Labels should match exactly when n_neighbors=1
-        assert adata_pbmc3k.obs["leiden_transfer"].equals(adata_pbmc3k.obs["leiden"])
+        assert adata_pbmc3k.obs[f"{obs_key}_pred"].equals(adata_pbmc3k.obs[obs_key])
 
     def test_all_operations_self_mapping(self, adata_pbmc3k):
         """Test the full pipeline in self-mapping mode."""
@@ -46,16 +46,16 @@ def test_all_operations_self_mapping(self, adata_pbmc3k):
         cm.compute_mapping_matrix(method="gaussian")
 
         # Test label transfer
-        cm.transfer_labels(obs_keys="leiden")
+        cm.map_obs(key="leiden")
         assert "leiden_pred" in cm.query.obs
         # With n_neighbors>1, self-mapped labels might not be 100% identical
 
         # Test embedding transfer
-        cm.transfer_embeddings(obsm_keys="X_pca")
+        cm.map_obsm(key="X_pca")
         assert "X_pca_pred" in cm.query.obsm
 
         # Test expression transfer
-        cm.transfer_expression(layer_key="X")
+        cm.map_layers(key="X")
         assert cm.query_imputed is not None
 
         # Test evaluation functions
@@ -84,7 +84,7 @@ def test_load_scanpy_distances(self, adata_spatial, n_neighbors):
 
         # Test the full pipeline with precomputed distances
         cm.compute_mapping_matrix(method="gaussian")
-        cm.transfer_labels(obs_keys="leiden")
+        cm.map_obs(key="leiden")
 
         assert "leiden_pred" in cm.query.obs
         assert "leiden_conf" in cm.query.obs
@@ -143,7 +143,7 @@ def test_load_squidpy_distances(self, adata_spatial, squidpy_params):
 
         # Test the mapping pipeline
         cm.compute_mapping_matrix(method="gaussian")
-        cm.transfer_labels(obs_keys="leiden")
+        cm.map_obs(key="leiden")
 
         assert "leiden_pred" in cm.query.obs
         assert "leiden_conf" in cm.query.obs
@@ -180,8 +180,8 @@ def test_load_distances_with_include_self(self, adata_spatial, include_self):
         cm_without_self.compute_mapping_matrix(method="gaussian")
 
         # Compute label transfer for both
-        cm_with_self.transfer_labels(obs_keys="leiden", prediction_postfix="with_self")
-        cm_without_self.transfer_labels(obs_keys="leiden", prediction_postfix="without_self")
+        cm_with_self.map_obs(key="leiden", prediction_postfix="with_self")
+        cm_without_self.map_obs(key="leiden", prediction_postfix="without_self")
 
         # Both should have created prediction columns
         assert "leiden_with_self" in adata_spatial.obs
@@ -204,5 +204,5 @@ def test_self_mapping_without_rep(self, adata_pbmc3k):
         assert adata_pbmc3k.obsm["X_pca"].shape[1] == 10
 
         # Test rest of pipeline
-        cm.transfer_labels(obs_keys="leiden")
+        cm.map_obs(key="leiden")
         assert "leiden_pred" in cm.query.obs