scatrans 0.9.8.dev0__tar.gz → 0.9.8.dev1__tar.gz

{scatrans-0.9.8.dev0 → scatrans-0.9.8.dev1}/CHANGELOG.md

@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.9.2 bugfix 2026-07-02]
 
 ### Fixed
+- **compare_enrichment / concat_compare_results metadata**: `attrs["clusters"]` now lists only clusters that contributed rows to the combined table (skipped, failed, and empty per-cluster runs remain in `per_cluster` diagnostics only). Fixes ghost cluster names in both the main compare API and the concat wrapper.
+- **DE schema validation**: `_run_de_wrapper` validates that all backends return `logFC`, `p_val`, `p_adj` with at least one finite value per column.
+- **MixedLM robustness**: near-constant genes use variance threshold; non-converged fits and missing condition coefficients are counted as failed fits instead of guessing the second coefficient; `failed_fit_rate` added to result attrs with percentage in warning log.
+- **DE warnings**: selective `_de_warning_context()` suppresses deprecation/future noise only (scanpy/PyDESeq2/MixedLM/BH), no longer blanket `ignore` on all warning categories.
+- **Memento audit column**: native adjusted p-values preserved as `memento_p_adj_native` when returned by memento-de; package `p_adj` still uses BH for cross-backend consistency.
+- **DE edge-case tests**: new `tests/test_de_edge_cases.py` (schema validation, constant-gene MixedLM failure counting, scanpy direction agreement, all-zero gene finiteness).
+- **Diagnostics / docs**: `failed_fit_rate` exposed in `active_score` mixed-model diagnostics and `differential_expression` metadata; README adds a short DE backend decision guide.
+- **copy_input performance**: `active_score` and `differential_expression` now honor `copy_input=False` — combined obs filters (subset + target/reference) perform at most one `AnnData.copy()` when `copy_input=True`, and zero when `copy_input=False` and no obs filtering is required (previously an unconditional `[keep_mask].copy()` always ran).
 - **filter_active_genes permissive mode**: default/permissive thresholds for `pval_cutoff`, `active_score_fdr_cutoff`, and `unspliced_excess_fdr_cutoff` now use `float("inf")` instead of `1.0`, so genes with adjusted p-value or permutation FDR exactly equal to 1.0 are no longer silently dropped (strict `<` vs `1.0` bug).
 - **CI lint**: removed unused `import scanpy as sc` from `tl.py` and `_permutation.py` (leftover from permutation refactor); fixed `test_enrich_api.py` formatting.
 - **CI tests**: `test_pp_bias_cli` GTF generator tests now `pytest.importorskip("gtfparse")` so base installs without `scatrans[gene_features]` skip instead of failing.

{scatrans-0.9.8.dev0 → scatrans-0.9.8.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scatrans
-Version: 0.9.8.dev0
+Version: 0.9.8.dev1
 Summary: Single-cell Active Transcription Analysis
 Author: scATrans Developers
 License: Apache-2.0
@@ -76,6 +76,18 @@ It also supports conventional differential expression workflows (no velocity dat
 
 The simple wrappers (`active_score_simple`, `run_default_pipeline`) keep permutation off by default so new users explore ranked tables first; enable `use_permutation=True` explicitly when you need FDR on unspliced excess.
 
+### Choosing a DE backend (decision guide)
+
+| Your design | Recommended backend | Caveats |
+|-------------|---------------------|---------|
+| Exploratory / default | scanpy `wilcoxon` or `t-test` on normalized data | Fast; standard pseudoreplication limits |
+| ≥2 biological replicates per group, aggregated counts | `use_pseudobulk=True` + `pydeseq2` | Requires raw counts (`store_raw_counts`); DESeq2 assumptions |
+| Few pseudobulk samples, no DESeq2 | `use_pseudobulk=True` + `pseudobulk_de_backend="scanpy"` | Non-parametric on aggregated profiles |
+| Cell-level data + true sample replicates | `use_mixed_model=True` + `sample_col` | Lightweight LMM (log1p); check `diagnostics["mixed_model"]["failed_fit_rate"]` — not NB-GLMM/voom |
+| Method-of-moments cell-level DE | `use_memento_de=True` | Raw integer counts required; compare `memento_p_adj_native` vs package `p_adj` if auditing |
+
+Always run `recommend_workflow(...)` first; inspect `adata.uns["scatrans"]["diagnostics"]` (bias, gamma, permutation `disabled_reason`) before publication claims.
+
 ## Quick Reference + Reporting Checklist (one page)
 
 | Step | Function | Key outputs |

{scatrans-0.9.8.dev0 → scatrans-0.9.8.dev1}/README.md

@@ -25,6 +25,18 @@ It also supports conventional differential expression workflows (no velocity dat
 
 The simple wrappers (`active_score_simple`, `run_default_pipeline`) keep permutation off by default so new users explore ranked tables first; enable `use_permutation=True` explicitly when you need FDR on unspliced excess.
 
+### Choosing a DE backend (decision guide)
+
+| Your design | Recommended backend | Caveats |
+|-------------|---------------------|---------|
+| Exploratory / default | scanpy `wilcoxon` or `t-test` on normalized data | Fast; standard pseudoreplication limits |
+| ≥2 biological replicates per group, aggregated counts | `use_pseudobulk=True` + `pydeseq2` | Requires raw counts (`store_raw_counts`); DESeq2 assumptions |
+| Few pseudobulk samples, no DESeq2 | `use_pseudobulk=True` + `pseudobulk_de_backend="scanpy"` | Non-parametric on aggregated profiles |
+| Cell-level data + true sample replicates | `use_mixed_model=True` + `sample_col` | Lightweight LMM (log1p); check `diagnostics["mixed_model"]["failed_fit_rate"]` — not NB-GLMM/voom |
+| Method-of-moments cell-level DE | `use_memento_de=True` | Raw integer counts required; compare `memento_p_adj_native` vs package `p_adj` if auditing |
+
+Always run `recommend_workflow(...)` first; inspect `adata.uns["scatrans"]["diagnostics"]` (bias, gamma, permutation `disabled_reason`) before publication claims.
+
 ## Quick Reference + Reporting Checklist (one page)
 
 | Step | Function | Key outputs |

{scatrans-0.9.8.dev0 → scatrans-0.9.8.dev1}/scatrans.egg-info/SOURCES.txt

@@ -41,10 +41,12 @@ tests/__init__.py
 tests/conftest.py
 tests/test_basic.py
 tests/test_de_backends.py
+tests/test_de_edge_cases.py
 tests/test_enrich_api.py
 tests/test_enrich_go.py
 tests/test_pl_coverage.py
 tests/test_pl_extended.py
 tests/test_pp_bias_cli.py
 tests/test_public_api.py
+tests/test_regression_bugs.py
 tests/test_tl_coverage.py

{scatrans-0.9.8.dev0 → scatrans-0.9.8.dev1}/src/scatrans/_de.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import logging
 import warnings
+from contextlib import contextmanager
 from importlib.metadata import version
 from typing import Any
 
@@ -29,6 +30,44 @@ from ._utils import (
 )
 
 logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+_DE_REQUIRED_COLS = frozenset({"logFC", "p_val", "p_adj"})
+
+# Suppress noisy deprecation/future warnings from scanpy/anndata/PyDESeq2 during DE,
+# but keep convergence/runtime/user warnings visible to callers.
+_DE_SUPPRESS_WARNING_CATEGORIES = (
+    DeprecationWarning,
+    FutureWarning,
+    PendingDeprecationWarning,
+)
+
+
+@contextmanager
+def _de_warning_context():
+    with warnings.catch_warnings():
+        for cat in _DE_SUPPRESS_WARNING_CATEGORIES:
+            warnings.simplefilter("ignore", category=cat)
+        yield
+
+
+def _validate_de_result(de_df: pd.DataFrame, *, backend: str) -> pd.DataFrame:
+    """Assert all DE backends return the minimal schema expected downstream."""
+    missing = _DE_REQUIRED_COLS - set(de_df.columns)
+    if missing:
+        raise RuntimeError(
+            f"DE backend '{backend}' returned incomplete results; "
+            f"missing columns: {sorted(missing)}"
+        )
+    if len(de_df) == 0:
+        return de_df
+    for col in _DE_REQUIRED_COLS:
+        vals = pd.to_numeric(de_df[col], errors="coerce")
+        if not np.isfinite(vals.to_numpy()).any():
+            raise RuntimeError(
+                f"DE backend '{backend}' returned no finite values in column {col!r}."
+            )
+    return de_df
 
 
 def _pydeseq2_uses_design_factors() -> bool:
@@ -94,15 +133,18 @@ def _run_de_wrapper(
     if use_mixed_model:
         if sample_col is None:
             raise ValueError("sample_col must be provided when use_mixed_model=True")
-        return _run_mixedlm_de(
-            adata,
-            groupby=groupby,
-            target_group=target_group,
-            reference_group=reference_group,
-            sample_col=sample_col,
-            n_jobs=n_jobs,
-            labels=labels,
-            mixed_model_pval=mixed_model_pval,
+        return _validate_de_result(
+            _run_mixedlm_de(
+                adata,
+                groupby=groupby,
+                target_group=target_group,
+                reference_group=reference_group,
+                sample_col=sample_col,
+                n_jobs=n_jobs,
+                labels=labels,
+                mixed_model_pval=mixed_model_pval,
+            ),
+            backend="mixedlm",
         )
 
     if use_memento_de:
@@ -111,16 +153,19 @@ def _run_de_wrapper(
                 "use_memento_de=True is not supported with use_pseudobulk=True "
                 "(Memento is a cell-level method-of-moments estimator; use PyDESeq2 for pseudobulk)."
             )
-        return _run_memento_de(
-            adata,
-            groupby=groupby,
-            target_group=target_group,
-            reference_group=reference_group,
-            labels=labels,
-            capture_rate=memento_capture_rate,
-            num_boot=memento_num_boot,
-            n_cpus=memento_n_cpus,
-            counts=counts,
+        return _validate_de_result(
+            _run_memento_de(
+                adata,
+                groupby=groupby,
+                target_group=target_group,
+                reference_group=reference_group,
+                labels=labels,
+                capture_rate=memento_capture_rate,
+                num_boot=memento_num_boot,
+                n_cpus=memento_n_cpus,
+                counts=counts,
+            ),
+            backend="memento",
         )
 
     ad_temp = adata.copy() if labels is not None else adata
@@ -220,8 +265,7 @@ def _run_de_wrapper(
             index=counts_use.index,
         )
 
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
+        with _de_warning_context():
             if _pydeseq2_uses_design_factors():
                 dds = DeseqDataSet(
                     counts=counts_use,
@@ -259,16 +303,23 @@ def _run_de_wrapper(
 
         res2 = stat_res.results_df.copy().reindex(ad_temp.var_names)
         de_df = pd.DataFrame(index=ad_temp.var_names)
-        de_df["logFC"] = res2["log2FoldChange"].fillna(0.0)
-        de_df["p_val"] = res2.get("pvalue", pd.Series(1.0, index=res2.index)).fillna(1.0)
-        de_df["p_adj"] = res2.get("padj", pd.Series(1.0, index=res2.index)).fillna(1.0)
+        de_df["logFC"] = res2["log2FoldChange"].reindex(ad_temp.var_names)
+        de_df["p_val"] = res2.get("pvalue", pd.Series(np.nan, index=res2.index)).reindex(
+            ad_temp.var_names
+        )
+        de_df["p_adj"] = res2.get("padj", pd.Series(np.nan, index=res2.index)).reindex(
+            ad_temp.var_names
+        )
+        _validate_de_result(de_df, backend="pydeseq2")
+        de_df["logFC"] = de_df["logFC"].fillna(0.0)
+        de_df["p_val"] = de_df["p_val"].fillna(1.0)
+        de_df["p_adj"] = de_df["p_adj"].fillna(1.0)
         return de_df
 
     else:
         # Standard scanpy path (works for both regular and pseudobulk when not using pydeseq2)
         rank_key = "_scatrans_rank_genes_groups"
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
+        with _de_warning_context():
             sc.tl.rank_genes_groups(
                 ad_temp,
                 groupby=use_groupby,
@@ -281,13 +332,16 @@ def _run_de_wrapper(
             "names"
         )
         de_df = pd.DataFrame(index=ad_temp.var_names)
-        raw_lfc = de_raw["logfoldchanges"].reindex(ad_temp.var_names).fillna(0.0)
         # scanpy rank_genes_groups always returns logfoldchanges on log2 scale:
         # log2( (expm1(mean_t) + eps) / (expm1(mean_r) + eps) ), independent of the
         # statistical method (wilcoxon / t-test / etc.). No secondary conversion needed.
-        de_df["logFC"] = raw_lfc
-        de_df["p_val"] = de_raw["pvals"].reindex(ad_temp.var_names).fillna(1.0)
-        de_df["p_adj"] = de_raw["pvals_adj"].reindex(ad_temp.var_names).fillna(1.0)
+        de_df["logFC"] = de_raw["logfoldchanges"].reindex(ad_temp.var_names)
+        de_df["p_val"] = de_raw["pvals"].reindex(ad_temp.var_names)
+        de_df["p_adj"] = de_raw["pvals_adj"].reindex(ad_temp.var_names)
+        _validate_de_result(de_df, backend=f"scanpy:{de_method}")
+        de_df["logFC"] = de_df["logFC"].fillna(0.0)
+        de_df["p_val"] = de_df["p_val"].fillna(1.0)
+        de_df["p_adj"] = de_df["p_adj"].fillna(1.0)
         return de_df
 
 
@@ -354,13 +408,12 @@ def _run_mixedlm_de(
     # The explicit flag avoids counting truly neutral (logFC~0, p~1, dvar~0) biological genes as "failed".
     def _fit_gene_mixed(idx: int):
         y = expr_mat[:, idx].astype(float)
-        # guard against all-zero / constant (mixedlm will be singular)
-        if np.allclose(y, y[0]):
+        # guard against near-constant expression (mixedlm will be singular)
+        if float(np.nanvar(y)) < 1e-12:
             return idx, 0.0, 1.0, 1.0, 0.0, True
         df = pd.DataFrame({"y": y, "condition": condition, "sample": samples})
         try:
-            with warnings.catch_warnings():
-                warnings.simplefilter("ignore")
+            with _de_warning_context():
                 # Full model
                 md_full = smf.mixedlm("y ~ C(condition)", df, groups=df["sample"])
                 m_full = md_full.fit(reml=False, maxiter=200, disp=False)
@@ -369,6 +422,9 @@ def _run_mixedlm_de(
                 md_null = smf.mixedlm("y ~ 1", df, groups=df["sample"])
                 m_null = md_null.fit(reml=False, maxiter=200, disp=False)
 
+            if not getattr(m_full, "converged", True) or not getattr(m_null, "converged", True):
+                return idx, 0.0, 1.0, 1.0, 0.0, True
+
             # LRT statistic and p (chi2 df=1 for the added fixed effect term(s))
             lrt_stat = -2.0 * (m_null.llf - m_full.llf)
             lrt_p = float(chi2.sf(max(lrt_stat, 0.0), 1))
@@ -381,11 +437,7 @@ def _run_mixedlm_de(
                     coef_name = pname
                     break
             if coef_name is None:
-                # fallback: take the second coef if intercept + one more
-                if len(m_full.params) >= 2:
-                    coef_name = m_full.params.index[1]
-                else:
-                    coef_name = m_full.params.index[0]
+                return idx, 0.0, 1.0, 1.0, 0.0, True
             logfc = float(m_full.params.get(coef_name, 0.0))
             p_wald = float(m_full.pvalues.get(coef_name, 1.0))
 
@@ -441,8 +493,7 @@ def _run_mixedlm_de(
             logger.warning("mixed_model_pval must be 'wald' or 'lrt'; falling back to 'wald'.")
         main_pvals = p_walds
 
-    with warnings.catch_warnings():
-        warnings.simplefilter("ignore")
+    with _de_warning_context():
         p_adjs = multipletests(main_pvals, method="fdr_bh")[1]
 
     de_df = pd.DataFrame(index=var_names)
@@ -456,14 +507,19 @@ def _run_mixedlm_de(
     # Use explicit failure flag returned from workers (avoids counting true biological
     # neutral genes (logFC~0, p~1, dvar~0) as "failed fits").
     n_failed = int(np.sum(failed_flags))
+    n_total = len(de_df)
+    failed_rate = (n_failed / n_total) if n_total else 0.0
     de_df.attrs["n_genes_failed_fit"] = n_failed
+    de_df.attrs["failed_fit_rate"] = failed_rate
     if n_failed > 0:
         logger.warning(
-            "MixedLM: %d/%d genes had degenerate fits (e.g. small n per group, collinearity) "
+            "MixedLM: %d/%d genes (%.1f%%) had degenerate or non-convergent fits "
+            "(near-constant expression, singular Hessian, missing condition coefficient, etc.) "
             "and received neutral values (logFC=0, p_val=1, delta_variance=0). "
             "See diagnostics['mixed_model']['n_genes_failed_fit'].",
             n_failed,
-            len(de_df),
+            n_total,
+            100.0 * failed_rate,
         )
     return de_df
 
@@ -535,6 +591,15 @@ def _run_memento_de(
             else:
                 raise ValueError(f"counts='{counts}' layer not found in adata.layers")
         elif isinstance(counts, ad.AnnData):
+            if not np.array_equal(counts.obs_names, ad_temp.obs_names):
+                missing = ad_temp.obs_names.difference(counts.obs_names)
+                if len(missing):
+                    raise ValueError(
+                        f"counts AnnData is missing {len(missing)} cell(s) required by the "
+                        f"comparison subset (first missing: {missing[0]!r}). "
+                        "Pass counts aligned to adata.obs_names or use a matrix layer."
+                    )
+                counts = counts[ad_temp.obs_names]
             raw_counts = counts.X
             if counts.var_names.tolist() != ad_temp.var_names.tolist():
                 common = counts.var_names.intersection(ad_temp.var_names)
@@ -640,9 +705,15 @@ def _run_memento_de(
     pvals = pd.to_numeric(pval_raw, errors="coerce").reindex(res_index).fillna(1.0)
     de_df["p_val"] = pvals
 
-    # BH adjustment (Memento may return raw p; we make p_adj consistent with other backends)
-    with warnings.catch_warnings():
-        warnings.simplefilter("ignore")
+    # Preserve Memento-native adjusted p if present (audit trail); package p_adj uses BH for consistency.
+    for native_col in ("de_padj", "de_padjs", "padj", "p_adj", "de_fdr"):
+        if isinstance(result, pd.DataFrame) and native_col in result.columns:
+            de_df["memento_p_adj_native"] = pd.to_numeric(
+                result[native_col], errors="coerce"
+            ).reindex(res_index)
+            break
+
+    with _de_warning_context():
         de_df["p_adj"] = multipletests(pvals.values, method="fdr_bh")[1]
 
     # Expose Memento's native columns for users who want mean + variability signals

{scatrans-0.9.8.dev0 → scatrans-0.9.8.dev1}/src/scatrans/_permutation.py

@@ -26,6 +26,46 @@ from ._utils import (
 from ._velocity import _compute_velocity_delta
 
 logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+def _compute_perm_velocity_delta(
+    *,
+    velocity_source: str,
+    uns_layer: Any,
+    spl_layer: Any,
+    t_mask: np.ndarray,
+    r_mask: np.ndarray,
+    prior_weight: float,
+    gamma_method: str,
+    eb_prior: dict[str, Any] | None,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, dict[str, Any]]:
+    """Velocity delta for one permutation replicate.
+
+    For ``scvelo_moments*`` sources the layers are pre-smoothed Mu/Ms from the main
+    analysis (label permutation keeps smoothed values fixed). For heuristic sources
+    they are library-size-normalized unspliced/spliced layers.
+    """
+    if velocity_source.startswith("scvelo_moments"):
+        # Same groupwise ratio estimator as _compute_moments_velocity_delta (on Mu/Ms).
+        return _compute_velocity_delta(
+            uns_layer,
+            spl_layer,
+            t_mask,
+            r_mask,
+            prior_weight,
+            gamma_method=gamma_method,
+            eb_prior=eb_prior,
+        )
+    return _compute_velocity_delta(
+        uns_layer,
+        spl_layer,
+        t_mask,
+        r_mask,
+        prior_weight,
+        gamma_method=gamma_method,
+        eb_prior=eb_prior,
+    )
 
 
 def _single_permutation_task(
@@ -60,6 +100,7 @@ def _single_permutation_task(
     memento_capture_rate: float = 0.07,
     memento_num_boot: int = 5000,
     memento_n_cpus: int = -1,
+    velocity_source: str = "heuristic_global_ratio",
 ) -> tuple[np.ndarray, np.ndarray]:
     """One permutation replicate.
 
@@ -108,12 +149,13 @@ def _single_permutation_task(
 
     t_mask = shuffled_labels == target_group
     r_mask = shuffled_labels == reference_group
-    delta_velocity, _, _gamma_ref, _ = _compute_velocity_delta(
-        uns_layer,
-        spl_layer,
-        t_mask,
-        r_mask,
-        prior_weight,
+    delta_velocity, _, _gamma_ref, _ = _compute_perm_velocity_delta(
+        velocity_source=velocity_source,
+        uns_layer=uns_layer,
+        spl_layer=spl_layer,
+        t_mask=t_mask,
+        r_mask=r_mask,
+        prior_weight=prior_weight,
         gamma_method=gamma_method,
         eb_prior=eb_prior,
     )
@@ -177,6 +219,7 @@ def run_permutation_test(
     real_score: np.ndarray,
     real_residual: np.ndarray,
     eb_prior: dict[str, Any] | None = None,
+    velocity_source: str = "heuristic_global_ratio",
     bias_correction: str = "huber_length_intron",
     # Memento forwarding for advanced consistent permutation
     use_memento_de: bool = False,
@@ -224,6 +267,7 @@ def run_permutation_test(
                 de_preprocess,
                 strict_pydeseq2_counts,
                 eb_prior,
+                velocity_source=velocity_source,
                 bias_correction=bias_correction,
                 use_memento_de=use_memento_de,
                 memento_capture_rate=memento_capture_rate,
@@ -287,7 +331,7 @@ def run_permutation_test(
     # - For very small permutation spaces (n_perm < 100, common in pseudobulk with few samples),
     #   we mark use_fdr=False and provide reason so callers can avoid using FDR for significance
     #   (p-values become coarse; BH adjustment less reliable). This eliminates vestigial logic in tl.py.
-    use_fdr = n_perm >= 100
+    use_fdr = n_success >= 100
     disabled_reason = None if use_fdr else "small_permutation_space"
 
     return (

{scatrans-0.9.8.dev0 → scatrans-0.9.8.dev1}/src/scatrans/_utils.py

@@ -22,6 +22,7 @@ from scipy import sparse
 from sklearn.linear_model import HuberRegressor
 
 logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
 
 
 def _normalize_group_label(val: Any) -> str | None:
@@ -187,7 +188,16 @@ def _is_integer_counts_like(X: Any, max_check: int = 100000, atol: float = 1e-6)
 
     if vals.size > max_check:
         rng = np.random.default_rng(0)
-        vals = rng.choice(vals, size=max_check, replace=False)
+        # Stride + random subsample: stride covers the full matrix deterministically;
+        # random supplement catches sparse non-integer contamination missed by stride alone.
+        stride = max(1, vals.size // (max_check // 2))
+        stride_vals = vals[::stride]
+        n_random = max_check - stride_vals.size
+        if n_random > 0:
+            random_vals = rng.choice(vals, size=min(n_random, vals.size), replace=False)
+            vals = np.concatenate([stride_vals, random_vals])
+        else:
+            vals = stride_vals[:max_check]
 
     # Tolerant check: allows tiny floating point noise from summation / cast
     rounded = np.round(vals)
@@ -200,6 +210,19 @@ def _dense_expression_matrix(X: Any) -> np.ndarray:
     return np.asarray(X, dtype=float)
 
 
+def _x_looks_zscore_scaled(finite: np.ndarray) -> bool:
+    """Return True when values look z-score scaled (e.g. after ``sc.pp.scale``)."""
+    if finite.size == 0 or not np.any(finite < 0):
+        return False
+    mx = float(np.nanmax(finite))
+    mn = float(np.nanmin(finite))
+    mean = float(np.nanmean(finite))
+    std = float(np.nanstd(finite))
+    if mx > 25.0:
+        return False
+    return abs(mean) < 1.0 and 0.25 < std < 5.0 and mn < -0.1
+
+
 def _x_looks_log_normalized(X: Any, *, max_check: int = 100000) -> bool:
     """Return True when *X* is unlikely to be raw integer counts needing normalize+log1p."""
     if _is_integer_counts_like(X, max_check=max_check):
@@ -208,6 +231,8 @@ def _x_looks_log_normalized(X: Any, *, max_check: int = 100000) -> bool:
     finite = arr[np.isfinite(arr)]
     if finite.size == 0:
         return False
+    if _x_looks_zscore_scaled(finite):
+        return False
     mx = float(np.nanmax(finite))
     has_neg = bool(np.any(finite < 0))
     return has_neg or mx <= 20.0
@@ -218,6 +243,36 @@ def _clear_log_preprocess_metadata(adata: ad.AnnData) -> None:
     adata.uns.pop("log1p", None)
 
 
+def _restore_log_from_scaled_x(adata: ad.AnnData) -> bool:
+    """Reverse ``sc.pp.scale`` on ``.X`` when mean/std are stored in ``adata.var``."""
+    arr = _dense_expression_matrix(adata.X)
+    finite = arr[np.isfinite(arr)]
+    if finite.size == 0 or not _x_looks_zscore_scaled(finite):
+        return False
+
+    if "mean" not in adata.var.columns or "std" not in adata.var.columns:
+        return False
+
+    mean = pd.to_numeric(adata.var["mean"], errors="coerce").to_numpy(dtype=float)
+    std = pd.to_numeric(adata.var["std"], errors="coerce").to_numpy(dtype=float)
+    if not np.all(np.isfinite(mean)) or not np.all(np.isfinite(std)):
+        return False
+
+    if sparse.issparse(adata.X):
+        X = np.asarray(adata.X.toarray(), dtype=float)
+    else:
+        X = np.asarray(adata.X, dtype=float)
+
+    adata.X = X * std + mean
+    logger.warning(
+        ".X appeared z-score scaled (typical after sc.pp.scale). Restored log-normalized "
+        "expression from adata.var['mean']/'std' for DE. Keep scaled data in a separate "
+        "AnnData copy for PCA/clustering."
+    )
+    adata.uns.setdefault("log1p", {"base": None})
+    return True
+
+
 def _reconcile_log1p_marker(adata: ad.AnnData) -> bool:
     """Align ``uns['log1p']`` with the current ``.X`` scale.
 
@@ -228,8 +283,20 @@ def _reconcile_log1p_marker(adata: ad.AnnData) -> bool:
     normalize_total + log1p.
     """
     has_marker = "log1p" in adata.uns
+    arr = _dense_expression_matrix(adata.X)
+    finite = arr[np.isfinite(arr)]
+    x_is_scaled = _x_looks_zscore_scaled(finite) if finite.size else False
     x_is_log = _x_looks_log_normalized(adata.X)
 
+    if has_marker and x_is_scaled:
+        _clear_log_preprocess_metadata(adata)
+        logger.warning(
+            "Removed stale uns['log1p'] metadata: .X appears z-score scaled (e.g. after "
+            "sc.pp.scale) while the log1p marker was still set. Downstream DE preprocessing "
+            "will re-apply normalize_total + log1p when de_preprocess='auto'."
+        )
+        return False
+
     if has_marker and not x_is_log:
         _clear_log_preprocess_metadata(adata)
         logger.warning(
@@ -257,6 +324,17 @@ def _apply_de_preprocess(
     skip_auto: bool = False,
 ) -> None:
     """Apply normalize_total + log1p according to ``de_preprocess`` mode."""
+    if de_preprocess in ("auto", "normalize_log1p") and not skip_auto:
+        arr = _dense_expression_matrix(adata.X)
+        finite = arr[np.isfinite(arr)]
+        if finite.size and _x_looks_zscore_scaled(finite) and not _restore_log_from_scaled_x(adata):
+            raise ValueError(
+                ".X appears z-score scaled (e.g. after sc.pp.scale) but cannot be restored "
+                "for DE (missing adata.var['mean']/'std']). Use an AnnData copy from before "
+                "scaling, pass de_preprocess='none' with a suitable matrix, or store "
+                "log-normalized expression in adata.raw or a layer."
+            )
+
     if de_preprocess == "normalize_log1p":
         logger.info("DE preprocessing: applying normalize_total + log1p (explicit).")
         sc.pp.normalize_total(adata, target_sum=1e4)

{scatrans-0.9.8.dev0 → scatrans-0.9.8.dev1}/src/scatrans/_velocity.py

@@ -23,6 +23,7 @@ from scipy import sparse
 from ._utils import _get_group_mean
 
 logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
 
 _EPS = 1e-8
 _MIN_GENES_FOR_EB_PRIOR = 10
@@ -211,7 +212,10 @@ def _compute_velocity_delta(
     gamma_method: str = "heuristic_shrink",
     eb_prior: dict[str, Any] | None = None,
 ) -> tuple[np.ndarray, np.ndarray, np.ndarray, dict[str, Any]]:
-    """Classic (global ratio) velocity delta used by the heuristic track.
+    """Groupwise velocity delta (U_t - gamma_ref * S_t) on arbitrary expression layers.
+
+    Used by the heuristic track (normalized unspliced/spliced) and, after scVelo
+    moments smoothing, by the advanced track (Mu/Ms).
 
     gamma_method:
         - "heuristic_shrink": original global ratio + additive shrinkage using prior_weight

{scatrans-0.9.8.dev0 → scatrans-0.9.8.dev1}/src/scatrans/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.9.8.dev0'
-__version_tuple__ = version_tuple = (0, 9, 8, 'dev0')
+__version__ = version = '0.9.8.dev1'
+__version_tuple__ = version_tuple = (0, 9, 8, 'dev1')
 
 __commit_id__ = commit_id = None