Make cell-eval trust explicit log1p scale

Author: abhinadduri

README.md

@@ -58,9 +58,13 @@ cell-eval run \
     -ap <your/path/to/pred>.h5ad \
     -ar <your/path/to/real>.h5ad \
     --num-threads 64 \
+    --is-log1p \
     --profile full
 ```
 
+`cell-eval run` trusts the declared input scale. It does not guess whether
+matrices are log1p-normalized and does not transform `.X` internally.
+
 To run this as a python module you will need to use the `MetricsEvaluator` class.
 
 ```python
@@ -75,6 +79,7 @@ evaluator = MetricsEvaluator(
     control_pert="control",
     pert_col="perturbation",
     num_threads=64,
+    is_log1p=True,
 )
 (results, agg_results) = evaluator.compute()
 ```

src/cell_eval/_baseline.py

@@ -85,7 +85,7 @@ def build_base_mean_adata(
             groupby=pert_col,
             reference=control_pert,
             threads=num_threads,
-            allow_discrete=allow_discrete,
+            is_log1p=not allow_discrete,
             pdex_kwargs=pdex_kwargs,
         )
         frame = pdex(

src/cell_eval/_cli/_run.py

@@ -82,7 +82,13 @@ def parse_args_run(parser: ap.ArgumentParser):
     parser.add_argument(
         "--allow-discrete",
         action="store_true",
-        help="Allow discrete data to be evaluated (usually expected to be norm-logged inputs)",
+        help="Deprecated; inputs are trusted as provided. Use --no-is-log1p to configure pdex for non-log1p inputs.",
+    )
+    parser.add_argument(
+        "--is-log1p",
+        action=ap.BooleanOptionalAction,
+        default=True,
+        help="Whether input AnnData .X is already log1p-normalized. cell-eval trusts this flag and does not transform inputs [default: %(default)s]",
     )
     parser.add_argument(
         "--profile",
@@ -159,6 +165,7 @@ def run_evaluation(args: ap.Namespace):
                 allow_discrete=args.allow_discrete,
                 prefix=ct,
                 skip_de=args.profile == "pds",
+                is_log1p=args.is_log1p,
             )
             evaluator.compute(
                 profile=args.profile,
@@ -179,6 +186,7 @@ def run_evaluation(args: ap.Namespace):
             outdir=args.outdir,
             allow_discrete=args.allow_discrete,
             skip_de=args.profile == "pds",
+            is_log1p=args.is_log1p,
         )
         evaluator.compute(
             profile=args.profile,

src/cell_eval/_evaluator.py

@@ -57,12 +57,15 @@ class MetricsEvaluator:
     outdir: str = "./cell-eval-outdir"
         Output directory.
     allow_discrete: bool = False
-        Allow discrete data.
+        Deprecated; cell-eval now trusts the caller-provided scale.
     prefix: str | None = None
         Prefix for output files.
     pdex_kwargs: dict[str, Any] | None = None
         Keyword arguments for parallel_differential_expression.
-        These will overwrite arguments passed to MetricsEvaluator.__init__ if they conflict.
+        These may not conflict with ``is_log1p``.
+    is_log1p: bool = True
+        Whether input AnnData matrices are already log1p-normalized. cell-eval trusts
+        this flag and does not inspect or transform input matrices.
     """
 
     def __init__(
@@ -79,6 +82,7 @@ def __init__(
         prefix: str | None = None,
         pdex_kwargs: dict[str, Any] | None = None,
         skip_de: bool = False,
+        is_log1p: bool = True,
     ):
         # Enable a global string cache for categorical columns
         pl.enable_string_cache()
@@ -97,7 +101,6 @@ def __init__(
             pred=adata_pred,
             control_pert=control_pert,
             pert_col=pert_col,
-            allow_discrete=allow_discrete,
         )
 
         if skip_de:
@@ -108,10 +111,10 @@ def __init__(
                 de_pred=de_pred,
                 de_real=de_real,
                 num_threads=num_threads,
-                allow_discrete=allow_discrete,
                 outdir=outdir,
                 prefix=prefix,
                 pdex_kwargs=pdex_kwargs or {},
+                is_log1p=is_log1p,
             )
 
         self.outdir = outdir
@@ -170,7 +173,6 @@ def _build_anndata_pair(
     pred: ad.AnnData | str,
     control_pert: str,
     pert_col: str,
-    allow_discrete: bool = False,
 ):
     if isinstance(real, str):
         logger.info(f"Reading real anndata from {real}")
@@ -183,10 +185,6 @@ def _build_anndata_pair(
     _cast_float16_to_float32(real, which="real")
     _cast_float16_to_float32(pred, which="pred")
 
-    # Validate that the input is normalized and log-transformed
-    _convert_to_normlog(real, which="real", allow_discrete=allow_discrete)
-    _convert_to_normlog(pred, which="pred", allow_discrete=allow_discrete)
-
     # Build the anndata pair
     return PerturbationAnndataPair(
         real=real, pred=pred, control_pert=control_pert, pert_col=pert_col
@@ -234,31 +232,31 @@ def _build_de_comparison(
     de_pred: pl.DataFrame | str | None = None,
     de_real: pl.DataFrame | str | None = None,
     num_threads: int = 1,
-    allow_discrete: bool = False,
     outdir: str | None = None,
     prefix: str | None = None,
     pdex_kwargs: dict[str, Any] | None = None,
+    is_log1p: bool = True,
 ):
     return initialize_de_comparison(
         real=_load_or_build_de(
             mode="real",
             de_path=de_real,
             anndata_pair=anndata_pair,
             num_threads=num_threads,
-            allow_discrete=allow_discrete,
             outdir=outdir,
             prefix=prefix,
             pdex_kwargs=pdex_kwargs or {},
+            is_log1p=is_log1p,
         ),
         pred=_load_or_build_de(
             mode="pred",
             de_path=de_pred,
             anndata_pair=anndata_pair,
             num_threads=num_threads,
-            allow_discrete=allow_discrete,
             outdir=outdir,
             prefix=prefix,
             pdex_kwargs=pdex_kwargs or {},
+            is_log1p=is_log1p,
         ),
     )
 
@@ -267,21 +265,23 @@ def _build_pdex_kwargs(
     reference: str,
     groupby: str,
     threads: int,
-    allow_discrete: bool,
+    is_log1p: bool,
     pdex_kwargs: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
-    pdex_kwargs = pdex_kwargs or {}
+    pdex_kwargs = dict(pdex_kwargs or {})
     if "reference" not in pdex_kwargs:
         pdex_kwargs["reference"] = reference
     if "groupby" not in pdex_kwargs:
         pdex_kwargs["groupby"] = groupby
     if "threads" not in pdex_kwargs:
         pdex_kwargs["threads"] = threads
     if "is_log1p" not in pdex_kwargs:
-        if allow_discrete:
-            pdex_kwargs["is_log1p"] = False
-        else:
-            pdex_kwargs["is_log1p"] = True
+        pdex_kwargs["is_log1p"] = is_log1p
+    elif bool(pdex_kwargs["is_log1p"]) != is_log1p:
+        raise ValueError(
+            "Conflicting log1p configuration: MetricsEvaluator(is_log1p="
+            f"{is_log1p}) but pdex_kwargs['is_log1p']={pdex_kwargs['is_log1p']!r}"
+        )
     return pdex_kwargs
 
 
@@ -292,8 +292,8 @@ def _load_or_build_de(
     num_threads: int = 1,
     outdir: str | None = None,
     prefix: str | None = None,
-    allow_discrete: bool = False,
     pdex_kwargs: dict[str, Any] | None = None,
+    is_log1p: bool = True,
 ) -> pl.DataFrame:
     if de_path is None:
         if anndata_pair is None:
@@ -303,8 +303,8 @@ def _load_or_build_de(
             reference=anndata_pair.control_pert,
             groupby=anndata_pair.pert_col,
             threads=num_threads,
-            allow_discrete=allow_discrete,
             pdex_kwargs=pdex_kwargs or {},
+            is_log1p=is_log1p,
         )
         logger.info(f"Using the following pdex kwargs: {pdex_kwargs}")
         frame = pdex(

tests/test_eval.py

@@ -70,6 +70,7 @@ def test_broken_adata_not_normlog():
         control_pert=CONTROL_VAR,
         pert_col=PERT_COL,
         outdir=OUTDIR,
+        is_log1p=False,
     )
     evaluator.compute(
         break_on_error=True,
@@ -86,32 +87,37 @@ def test_broken_adata_not_normlog_skip_check():
         pert_col=PERT_COL,
         outdir=OUTDIR,
         allow_discrete=True,
+        is_log1p=False,
     )
     evaluator.compute(
         break_on_error=True,
     )
 
 
-def test_broken_adata_invalid_pred_scale():
-    """Test that predicted data with invalid scale is rejected."""
+def test_eval_trusts_declared_log1p_without_scale_scan():
+    """MetricsEvaluator should not scan or transform .X when is_log1p is set."""
     adata_real = build_random_anndata(normlog=True)
     adata_pred = adata_real.copy()
 
-    # Create invalid predicted data: mix of raw counts and log1p
+    # Values above the old log1p threshold used to fail during scale guessing.
     adata_pred.X = np.random.uniform(
         0,
         5000,
         size=adata_pred.X.shape,  # type: ignore
     )
+    before = np.asarray(adata_pred.X).copy()
 
-    with pytest.raises(ValueError, match="Invalid scale.*exceeds log1p threshold"):
-        MetricsEvaluator(
-            adata_pred=adata_pred,
-            adata_real=adata_real,
-            control_pert=CONTROL_VAR,
-            pert_col=PERT_COL,
-            outdir=OUTDIR,
-        )
+    evaluator = MetricsEvaluator(
+        adata_pred=adata_pred,
+        adata_real=adata_real,
+        control_pert=CONTROL_VAR,
+        pert_col=PERT_COL,
+        outdir=OUTDIR,
+        skip_de=True,
+        is_log1p=True,
+    )
+
+    np.testing.assert_array_equal(evaluator.anndata_pair.pred.X, before)
 
 
 def test_broken_adata_missing_pertcol_in_real():
@@ -292,6 +298,22 @@ def test_eval_pdex_kwargs_duplicated():
     )
 
 
+def test_eval_pdex_kwargs_is_log1p_conflict():
+    adata_real = build_random_anndata()
+    adata_pred = downsample_cells(adata_real, fraction=0.5)
+    with pytest.raises(ValueError, match="Conflicting log1p configuration"):
+        MetricsEvaluator(
+            adata_pred=adata_pred,
+            adata_real=adata_real,
+            control_pert="control",
+            pert_col="perturbation",
+            is_log1p=True,
+            pdex_kwargs={
+                "is_log1p": False,
+            },
+        )
+
+
 def validate_expected_files(
     outdir: str, prefix: str | None = None, remove: bool = True
 ):