scatrans 0.9.8.dev3__tar.gz → 0.9.8.dev5__tar.gz

{scatrans-0.9.8.dev3 → scatrans-0.9.8.dev5}/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.8 bugfix 2026-07-04]
+
+### Fixed
+- **Pseudobulk `strict_pydeseq2_counts` check ran on already-rounded data**: `_pseudobulk_with_layers`
+  always rounds aggregated sums to integers, so the PyDESeq2 count-likeness check in
+  `_run_de_wrapper` (which inspected the rounded pseudobulk `.X`) could never detect that the
+  underlying per-cell source (e.g. a `pb_x_layer` pointing at log-normalized data) was not raw
+  counts. The check now runs on the pre-aggregation, pre-rounding source matrix inside
+  `_pseudobulk_with_layers` and the verdict is carried via `adata.uns["pb_x_is_count_like"]` to
+  `_run_de_wrapper`, so `strict_pydeseq2_counts=True` correctly rejects non-count pseudobulk input.
+- **`de_preprocess="auto"` false "already log-normalized" detection regressed by real cell
+  heterogeneity**: the per-cell library-size CV heuristic added to detect raw counts when
+  `uns['log1p']` is missing (e.g. after `anndata.concat()`, which drops `.uns`) could misfire on
+  correctly log-normalized data from heterogeneous cell populations (different cell types/states
+  varying in expression breadth inflate per-cell CV even post-log1p), triggering a spurious
+  second `normalize_total` + `log1p` pass that systematically compresses effect sizes. Added a
+  cross-gene mean-variance dispersion check (`_x_gene_dispersion_looks_raw`), which is not
+  confounded by cell-level heterogeneity, and now require it to corroborate the library-size CV
+  signal before concluding data still needs normalization.
+
+### Documentation
+- README: noted that `anndata.concat()` drops `uns['log1p']` and recommends re-setting the marker
+  or passing `de_preprocess="none"` explicitly after combining pre-normalized samples.
+
 ## [0.9.8] - 2026-07-03
 
 ### Changed (user-visible default behavior)

{scatrans-0.9.8.dev3 → scatrans-0.9.8.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scatrans
-Version: 0.9.8.dev3
+Version: 0.9.8.dev5
 Summary: Single-cell Active Transcription Analysis
 Author: scATrans Developers
 License: Apache-2.0
@@ -1232,6 +1232,8 @@ adata, de_res = scat.differential_expression(adata, use_memento_de=True, ...)
 
 `ensure_raw_counts()` will also try to recover from `adata.raw`. The functions emit clear warnings when they detect this situation.
 
+**Note on `anndata.concat()` and `de_preprocess="auto"`:** `ad.concat()` drops `.uns` by default, including the `uns['log1p']` marker that scATrans uses to detect already-log-normalized data. This is common when combining multiple samples for a case-vs-control comparison — each sample may be correctly `normalize_total` + `log1p`'d before concatenation, but the marker is gone afterward. `de_preprocess="auto"` still guards against double-log1p in this case via heuristics on `.X`, but for certainty, either re-set the marker after concatenating (`combined.uns["log1p"] = {"base": None}`) or pass `de_preprocess="none"` explicitly when you know `.X` is already log-normalized.
+
 ---
 
 ## Limitations

{scatrans-0.9.8.dev3 → scatrans-0.9.8.dev5}/README.md

@@ -1181,6 +1181,8 @@ adata, de_res = scat.differential_expression(adata, use_memento_de=True, ...)
 
 `ensure_raw_counts()` will also try to recover from `adata.raw`. The functions emit clear warnings when they detect this situation.
 
+**Note on `anndata.concat()` and `de_preprocess="auto"`:** `ad.concat()` drops `.uns` by default, including the `uns['log1p']` marker that scATrans uses to detect already-log-normalized data. This is common when combining multiple samples for a case-vs-control comparison — each sample may be correctly `normalize_total` + `log1p`'d before concatenation, but the marker is gone afterward. `de_preprocess="auto"` still guards against double-log1p in this case via heuristics on `.X`, but for certainty, either re-set the marker after concatenating (`combined.uns["log1p"] = {"base": None}`) or pass `de_preprocess="none"` explicitly when you know `.X` is already log-normalized.
+
 ---
 
 ## Limitations

{scatrans-0.9.8.dev3 → scatrans-0.9.8.dev5}/src/scatrans/_de.py

@@ -125,7 +125,7 @@ def _run_de_wrapper(
     This is treated as a third parallel cell-level backend (alongside scanpy-style and mixed-model).
 
     logFC is normalized toward log2 scale for cross-backend comparability of logfc_cutoff:
-      - PyDESeq2 + scanpy backends (wilcoxon, t-test, logreg, etc.): native log2
+      - PyDESeq2 + scanpy backends (wilcoxon, t-test, t-test_overestim_var): native log2
       - mixedlm + memento: converted from natural/log1p scale (/ log(2))
 
     Internal function: type hints strengthened for mypy/pyright.
@@ -185,18 +185,6 @@ def _run_de_wrapper(
             _ann_log.setLevel(_prev_ann)
 
     if is_pseudobulk and pb_backend == "pydeseq2":
-        try:
-            from pydeseq2.dds import DeseqDataSet
-            from pydeseq2.ds import DeseqStats
-        except ImportError as e:
-            raise ImportError(
-                "PyDESeq2 backend requested but 'pydeseq2' is not installed.\n"
-                "Install with:\n"
-                '    pip install "scatrans[pseudobulk]"\n'
-                "or\n"
-                "    pip install pydeseq2"
-            ) from e
-
         n_t = (ad_temp.obs[use_groupby] == target_group).sum()
         n_r = (ad_temp.obs[use_groupby] == reference_group).sum()
         if n_t < 2 or n_r < 2:
@@ -208,17 +196,26 @@ def _run_de_wrapper(
         # but are integer-valued. Use a tolerant check + pre-coercion so users don't have to set
         # strict_pydeseq2_counts=False for normal aggregated data.
         if is_pseudobulk:
-            # Coerce a tolerant view for the "looks like counts" decision
-            try:
-                if sparse.issparse(ad_temp.X):
-                    X_check_arr = np.asarray(ad_temp.X.todense())
-                else:
-                    X_check_arr = np.asarray(ad_temp.X)
-                X_check_arr = np.clip(np.round(np.nan_to_num(X_check_arr)), 0, None)
-                is_count_like = _is_integer_counts_like(X_check_arr)
-            except Exception as _e:
-                logger.debug("Count-like check fallback: %s", _e)
-                is_count_like = _is_integer_counts_like(ad_temp.X)
+            if "pb_x_is_count_like" in ad_temp.uns:
+                # Authoritative verdict computed by _pseudobulk_with_layers on the
+                # pre-aggregation, pre-rounding source matrix. Summing+rounding after
+                # aggregation always yields integer-valued output, so checking ad_temp.X
+                # here (post-rounding) would always pass and defeat strict_pydeseq2_counts.
+                is_count_like = bool(ad_temp.uns["pb_x_is_count_like"])
+            else:
+                # Fallback for pseudobulk AnnData not built via _pseudobulk_with_layers
+                # (e.g. user-supplied pseudobulk). No pre-aggregation matrix is available,
+                # so we check the (already rounded) X as a best effort.
+                try:
+                    if sparse.issparse(ad_temp.X):
+                        X_check_arr = np.asarray(ad_temp.X.todense())
+                    else:
+                        X_check_arr = np.asarray(ad_temp.X)
+                    X_check_arr = np.clip(np.nan_to_num(X_check_arr), 0, None)
+                    is_count_like = _is_integer_counts_like(X_check_arr)
+                except Exception as _e:
+                    logger.debug("Count-like check fallback: %s", _e)
+                    is_count_like = _is_integer_counts_like(ad_temp.X)
         else:
             is_count_like = _is_integer_counts_like(ad_temp.X)
 
@@ -259,6 +256,18 @@ def _run_de_wrapper(
                 f"No genes passed the DESeq2 count filter (sum(counts) >= {min_counts_per_gene})."
             )
 
+        try:
+            from pydeseq2.dds import DeseqDataSet
+            from pydeseq2.ds import DeseqStats
+        except ImportError as e:
+            raise ImportError(
+                "PyDESeq2 backend requested but 'pydeseq2' is not installed.\n"
+                "Install with:\n"
+                '    pip install "scatrans[pseudobulk]"\n'
+                "or\n"
+                "    pip install pydeseq2"
+            ) from e
+
         condition = ad_temp.obs[use_groupby].astype(str).values
         metadata = pd.DataFrame(
             {use_groupby: pd.Categorical(condition, categories=[reference_group, target_group])},
@@ -341,16 +350,45 @@ def _run_de_wrapper(
 
     else:
         # Standard scanpy path (works for both regular and pseudobulk when not using pydeseq2)
+        if de_method == "logreg":
+            raise ValueError(
+                "de_method='logreg' is not supported: scanpy's logreg ranks genes by logistic "
+                "regression scores and does not produce logFC, p-values, or adjusted p-values. "
+                "Use 'wilcoxon', 't-test', or 't-test_overestim_var' instead."
+            )
+        labels = ad_temp.obs[use_groupby].astype(str)
+        n_target = int((labels == str(target_group)).sum())
+        n_reference = int((labels == str(reference_group)).sum())
+        if n_target < 2 or n_reference < 2:
+            raise ValueError(
+                f"scanpy DE (method='{de_method}') requires at least 2 cells per group. "
+                f"Found {n_target} in target '{target_group}' and {n_reference} in reference "
+                f"'{reference_group}'. With a single cell per group, no valid statistics can be "
+                f"computed. Consider pseudobulk aggregation (use_pseudobulk=True with sample_col) "
+                f"if you have multiple biological replicates per condition."
+            )
         rank_key = "_scatrans_rank_genes_groups"
         with _de_warning_context():
-            sc.tl.rank_genes_groups(
-                ad_temp,
-                groupby=use_groupby,
-                groups=[target_group],
-                reference=reference_group,
-                method=de_method,
-                key_added=rank_key,
-            )
+            try:
+                sc.tl.rank_genes_groups(
+                    ad_temp,
+                    groupby=use_groupby,
+                    groups=[target_group],
+                    reference=reference_group,
+                    method=de_method,
+                    key_added=rank_key,
+                )
+            except Exception as exc:
+                msg = str(exc)
+                if "only contain one sample" in msg or "one sample" in msg.lower():
+                    raise ValueError(
+                        f"scanpy could not compute DE statistics: each group needs at least 2 "
+                        f"cells (found {n_target} target, {n_reference} reference for "
+                        f"'{use_groupby}'). For single-cell-per-group designs, use pseudobulk "
+                        f"with biological replicates (use_pseudobulk=True, sample_col=...) or "
+                        f"add more cells per group."
+                    ) from exc
+                raise
         de_raw = sc.get.rank_genes_groups_df(ad_temp, group=target_group, key=rank_key).set_index(
             "names"
         )

{scatrans-0.9.8.dev3 → scatrans-0.9.8.dev5}/src/scatrans/_utils.py

@@ -143,6 +143,7 @@ __all__ = [
     "_resolve_results_column",
     "_write_unspliced_excess_columns",
     "_is_integer_counts_like",
+    "_warn_if_negative_layer_values",
     "_warn_if_not_integer_counts_matrix",
     "_warn_if_low_counts_matrix",
     "_safe_add_matrices",
@@ -161,6 +162,30 @@ __all__ = [
 ]
 
 
+def _warn_if_negative_layer_values(layer: Any, layer_name: str, *, max_check: int = 100000) -> None:
+    """Warn when a count layer contains negative values (physically invalid for RNA counts)."""
+    if sparse.issparse(layer):
+        vals = np.asarray(layer.data, dtype=float)
+    else:
+        vals = np.asarray(layer, dtype=float).ravel()
+    vals = vals[np.isfinite(vals)]
+    if vals.size == 0:
+        return
+    if vals.size > max_check:
+        rng = np.random.default_rng(0)
+        vals = rng.choice(vals, size=max_check, replace=False)
+    if np.any(vals < 0):
+        n_neg = int(np.sum(vals < 0))
+        logger.warning(
+            "Layer '%s' contains %d negative value(s) (min=%.4g). "
+            "RNA count layers should be non-negative; results may be unreliable. "
+            "Check for data corruption or incorrect layer assignment.",
+            layer_name,
+            n_neg,
+            float(np.min(vals)),
+        )
+
+
 def _is_integer_counts_like(X: Any, max_check: int = 100000, atol: float = 1e-6) -> bool:
     """Return True if the matrix contains non-negative values that are integer-valued
     (within tolerance). This is tolerant of float64 summed counts that are exactly
@@ -223,7 +248,74 @@ def _x_looks_zscore_scaled(finite: np.ndarray) -> bool:
     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:
+def _x_carries_library_size_signal(X: Any, *, min_cv: float = 0.12, max_cells: int = 5000) -> bool:
+    """Return True when per-cell library sizes show meaningful sequencing-depth variation.
+
+    Raw counts (including kallisto/salmon decimal UMIs) retain depth signal in row sums;
+    normalize_total+log1p data does not. Used to avoid false 'already log-normalized'
+    detection on small-magnitude decimal count matrices.
+    """
+    if sparse.issparse(X):
+        lib = np.asarray(X.sum(axis=1)).ravel(dtype=float)
+    else:
+        lib = np.asarray(X, dtype=float).sum(axis=1)
+    lib = lib[np.isfinite(lib)]
+    if lib.size < 2:
+        return False
+    if lib.size > max_cells:
+        rng = np.random.default_rng(0)
+        lib = rng.choice(lib, size=max_cells, replace=False)
+    mean = float(np.mean(lib))
+    if mean <= 0:
+        return False
+    cv = float(np.std(lib) / mean)
+    return cv >= min_cv
+
+
+def _x_gene_dispersion_looks_raw(
+    X: Any, *, slope_threshold: float = 1.0, min_genes: int = 20, max_cells: int = 5000
+) -> bool:
+    """Return True when the cross-gene mean-variance relationship looks like raw counts.
+
+    Raw RNA-seq counts (Poisson/NB) have variance that grows roughly linearly-to-quadratically
+    with the mean across genes (log-log slope >= ~1). normalize_total+log1p compresses this
+    relationship to a much flatter slope. Unlike per-cell library-size CV
+    (``_x_carries_library_size_signal``), this is a cross-gene statistic and is not confounded
+    by real biological heterogeneity between cells/cell types, which can inflate per-cell
+    library-size CV even in properly log-normalized data (e.g. after ``anndata.concat`` drops
+    the ``uns['log1p']`` marker). Returns False (conservatively "not raw-looking") when there
+    are too few informative genes to estimate the relationship reliably.
+    """
+    if sparse.issparse(X):
+        n_cells = X.shape[0]
+        if n_cells > max_cells:
+            rng = np.random.default_rng(0)
+            idx = rng.choice(n_cells, size=max_cells, replace=False)
+            X = X[idx]
+        mean = np.asarray(X.mean(axis=0)).ravel()
+        mean_sq = np.asarray(X.multiply(X).mean(axis=0)).ravel()
+    else:
+        arr = np.asarray(X, dtype=float)
+        if arr.shape[0] > max_cells:
+            rng = np.random.default_rng(0)
+            idx = rng.choice(arr.shape[0], size=max_cells, replace=False)
+            arr = arr[idx]
+        mean = arr.mean(axis=0)
+        mean_sq = (arr**2).mean(axis=0)
+    var = np.clip(mean_sq - mean**2, 0, None)
+
+    mask = np.isfinite(mean) & np.isfinite(var) & (mean > 0.05) & (var > 0)
+    if int(mask.sum()) < min_genes:
+        return False
+    log_mean = np.log(mean[mask])
+    log_var = np.log(var[mask])
+    slope = float(np.polyfit(log_mean, log_var, 1)[0])
+    return slope >= slope_threshold
+
+
+def _x_looks_log_normalized(
+    X: Any, *, max_check: int = 100000, has_log1p_marker: bool = False
+) -> 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):
         return False
@@ -235,7 +327,18 @@ def _x_looks_log_normalized(X: Any, *, max_check: int = 100000) -> bool:
         return False
     mx = float(np.nanmax(finite))
     has_neg = bool(np.any(finite < 0))
-    return has_neg or mx <= 20.0
+    if has_neg:
+        return True
+    if has_log1p_marker and mx <= 20.0:
+        return True
+    if mx > 20.0:
+        return False
+    # Per-cell library-size CV alone is unreliable: real biological heterogeneity (different
+    # cell types/states with different expression breadth) can produce high CV even in data
+    # that is already correctly log-normalized, most commonly after anndata.concat() drops the
+    # uns['log1p'] marker. Require corroboration from the cross-gene mean-variance dispersion
+    # check (robust to cell-level heterogeneity) before concluding "still needs normalization".
+    return not (_x_carries_library_size_signal(X) and _x_gene_dispersion_looks_raw(X))
 
 
 def _clear_log_preprocess_metadata(adata: ad.AnnData) -> None:
@@ -286,7 +389,7 @@ def _reconcile_log1p_marker(adata: ad.AnnData) -> bool:
     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)
+    x_is_log = _x_looks_log_normalized(adata.X, has_log1p_marker=has_marker)
 
     if has_marker and x_is_scaled:
         _clear_log_preprocess_metadata(adata)
@@ -308,9 +411,10 @@ def _reconcile_log1p_marker(adata: ad.AnnData) -> bool:
 
     if x_is_log:
         if not has_marker:
-            logger.debug(
-                "DE preprocess: .X appears log-normalized without uns['log1p']; "
-                "skipping re-normalization."
+            logger.warning(
+                "DE preprocess: .X appears log-normalized without uns['log1p'] metadata; "
+                "skipping re-normalization. If this is raw decimal counts (e.g. kallisto/salmon "
+                "UMIs), pass de_preprocess='normalize_log1p' explicitly."
             )
         return True
 
@@ -595,6 +699,11 @@ def _pseudobulk_with_layers(
         X_source = adata.X if x_layer is None else adata.layers[x_layer]
         x_source_name = "adata.X" if x_layer is None else f"layer '{x_layer}'"
 
+    # Check count-likeness on the pre-aggregation, pre-rounding source matrix.
+    # Summing+rounding below always produces integer-valued output, so checking
+    # after aggregation would always pass and defeat strict_pydeseq2_counts.
+    x_source_is_count_like = _is_integer_counts_like(X_source)
+
     valid_mask = adata.obs[sample_col].notna() & adata.obs[groupby].notna()
     if not valid_mask.any():
         raise ValueError(
@@ -679,6 +788,10 @@ def _pseudobulk_with_layers(
         for layer in layers:
             adata_pb.layers[layer] = sparse.vstack(layer_rows[layer]).tocsr()
         adata_pb.obs_names_make_unique()
+        # Carry the pre-aggregation count-likeness verdict so downstream consumers
+        # (e.g. PyDESeq2 strict_pydeseq2_counts check) don't re-check the already-rounded X.
+        adata_pb.uns["pb_x_is_count_like"] = bool(x_source_is_count_like)
+        adata_pb.uns["pb_x_source_desc"] = x_source_name
     return adata_pb
 
 
@@ -721,10 +834,10 @@ def _fit_huber_bias_correction(
         the basic analysis clean for users who do not want the correction.
 
     Returns (residual, bias_info_dict) where bias_info contains:
-      - "bias_corrected": bool
+      - "bias_corrected": bool — True only when Huber length+intron regression succeeded
       - "method": the effective method used ("huber_length_intron" or "none")
       - "n_genes_used_for_fit": int
-      - "fallback_to_median": bool
+      - "fallback_to_median": bool — median centering used instead of Huber regression
       - "coef_gene_length", "coef_intron_number" (if regression succeeded)
       - "intercept" (if available)
     """
@@ -790,7 +903,8 @@ def _fit_huber_bias_correction(
     if not regression_succeeded and valid_expr.sum() > 0:
         residual[valid_expr] = delta_velocity[valid_expr] - np.nanmedian(delta_velocity[valid_expr])
         bias_info["fallback_to_median"] = True
-        bias_info["bias_corrected"] = True  # median correction still applied
+        # Median centering is a safe fallback but is not length/intron Huber correction.
+        bias_info["bias_corrected"] = False
 
     residual[~valid_expr] = 0.0
     return residual, bias_info

{scatrans-0.9.8.dev3 → scatrans-0.9.8.dev5}/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.dev3'
-__version_tuple__ = version_tuple = (0, 9, 8, 'dev3')
+__version__ = version = '0.9.8.dev5'
+__version_tuple__ = version_tuple = (0, 9, 8, 'dev5')
 
 __commit_id__ = commit_id = None

{scatrans-0.9.8.dev3 → scatrans-0.9.8.dev5}/src/scatrans/enrich.py

@@ -366,23 +366,25 @@ def _warn_user(msg: str) -> None:
 
 
 def _resolve_enrichment_padj_cutoff(
-    pval_cutoff: float,
+    pval_cutoff: float | None,
     padj_cutoff: float | None,
 ) -> float:
     """Resolve the effective adjusted-p cutoff; warn on legacy ``pval_cutoff`` usage."""
     if padj_cutoff is not None:
         cutoff = float(padj_cutoff)
-        if pval_cutoff != 0.05:
+        if pval_cutoff is not None:
             _warn_user(
                 "Both pval_cutoff and padj_cutoff were provided. "
                 "Using padj_cutoff; pval_cutoff is ignored."
             )
         return cutoff
-    _warn_user(
-        "`pval_cutoff` is deprecated (it applies to *adjusted* p-values, not raw p-values). "
-        "Please use `padj_cutoff` instead for clarity."
-    )
-    return float(pval_cutoff)
+    if pval_cutoff is not None:
+        _warn_user(
+            "`pval_cutoff` is deprecated (it applies to *adjusted* p-values, not raw p-values). "
+            "Please use `padj_cutoff` instead for clarity."
+        )
+        return float(pval_cutoff)
+    return 0.05
 
 
 def _apply_gene_case(genes: Iterable[Any], gene_case: str | None) -> list[str]:
@@ -659,7 +661,7 @@ def run_enrichment(
     background: Iterable[Any] | None = None,
     adata: Any
     | None = None,  # NEW: if provided and no explicit universe, we try to use the preserved raw_gene_list
-    pval_cutoff: float = 0.05,
+    pval_cutoff: float | None = None,
     padj_cutoff: float | None = None,
     min_size: int = 5,
     max_size: int = 500,
@@ -1071,7 +1073,7 @@ def run_kegg(
     universe: Iterable[Any] | None = None,
     background: Iterable[Any] | None = None,
     adata: Any | None = None,  # forwarded to run_enrichment for smart universe default
-    pval_cutoff: float = 0.05,
+    pval_cutoff: float | None = None,
     padj_cutoff: float | None = None,
     min_size: int = 5,
     max_size: int = 500,
@@ -1152,7 +1154,7 @@ def run_go(
     universe: Iterable[Any] | None = None,
     background: Iterable[Any] | None = None,
     adata: Any | None = None,
-    pval_cutoff: float = 0.05,
+    pval_cutoff: float | None = None,
     padj_cutoff: float | None = None,
     min_size: int = 5,
     max_size: int = 500,
@@ -1279,7 +1281,7 @@ def run_go(
     # "ALL" case: run three and concat
     frames = []
     per_ontology_attrs: dict[str, dict] = {}
-    eff_cut = padj_cutoff if padj_cutoff is not None else pval_cutoff
+    eff_cut = _resolve_enrichment_padj_cutoff(pval_cutoff, padj_cutoff)
 
     for o in ont_list:
         gs_name = ont_map[o]
@@ -1961,6 +1963,25 @@ def expand_enrichment_genes(res: pd.DataFrame) -> pd.DataFrame:
             base_cols = ["Ontology"] + base_cols
         return pd.DataFrame(columns=base_cols)
 
+    base_cols = [
+        "Term",
+        "Description",
+        "Gene",
+        "Count",
+        "GeneRatio",
+        "GeneRatio_str",
+        "BgRatio",
+        "BgRatio_str",
+        "FoldEnrichment",
+        "RichFactor",
+        "Overlap",
+        "pvalue",
+        "p.adjust",
+        "TermSize",
+    ]
+    if has_ontology:
+        base_cols = ["Ontology"] + base_cols
+
     rows = []
     for _, row in res.iterrows():
         genes_str = str(row.get("Genes", "") or "")
@@ -1994,7 +2015,7 @@ def expand_enrichment_genes(res: pd.DataFrame) -> pd.DataFrame:
             )
             rows.append(rec)
 
-    df = pd.DataFrame(rows)
+    df = pd.DataFrame(rows, columns=base_cols) if not rows else pd.DataFrame(rows)
     # Ensure Ontology first if present
     if "Ontology" in df.columns:
         cols = ["Ontology"] + [c for c in df.columns if c != "Ontology"]
@@ -2738,7 +2759,7 @@ def compare_enrichment(
     gene_clusters: Mapping[str, Iterable[Any]],
     *,
     fun: Callable | None = None,
-    pval_cutoff: float = 0.05,
+    pval_cutoff: float | None = None,
     padj_cutoff: float | None = None,
     min_size: int = 5,
     max_size: int = 500,
@@ -2818,7 +2839,7 @@ def compare_enrichment(
             "For best cross-cluster comparability, pass the same adata (after store_raw_counts) or explicit universe."
         )
 
-    eff_cut = padj_cutoff if padj_cutoff is not None else pval_cutoff
+    eff_cut = _resolve_enrichment_padj_cutoff(pval_cutoff, padj_cutoff)
     eff_return_all = return_all
     if adjust_across_clusters:
         if not return_all:

{scatrans-0.9.8.dev3 → scatrans-0.9.8.dev5}/src/scatrans/pl.py

@@ -1885,6 +1885,13 @@ def gseaplot(
     pheno_pos, pheno_neg : labels for phenotype (shown in plot).
     """
     with _style_context_if(use_style):
+        if isinstance(ranked_genes, pd.DataFrame):
+            raise TypeError(
+                "ranked_genes must be a one-dimensional pd.Series, dict, or gene list, "
+                f"but received a DataFrame with shape {ranked_genes.shape}. "
+                "Did you mean to pass the run_gsea() result as the second argument "
+                "(gsea_result=...) instead of the first positional argument?"
+            )
         # Normalize ranked input to Series
         if isinstance(ranked_genes, (list, tuple)):
             # assume order high->low, make scores

{scatrans-0.9.8.dev3 → scatrans-0.9.8.dev5}/src/scatrans/pp_bias.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import logging
 import sys
+import warnings
 from collections.abc import Iterator
 from contextlib import contextmanager
 from pathlib import Path
@@ -257,6 +258,7 @@ def generate_gene_features_from_gtf(
         )
 
     n_before_names = len(gene_df)
+    gene_df["gene_name"] = gene_df["gene_name"].replace("", np.nan)
     gene_df = gene_df.dropna(subset=["gene_name"])
     n_missing_names = n_before_names - len(gene_df)
     if n_missing_names:
@@ -410,4 +412,17 @@ def add_gene_features(
     valid_count = int(adata.var["gene_length"].notna().sum())
     logger.info("Successfully mapped features for %d out of %d genes.", valid_count, adata.n_vars)
 
+    mapping_rate = valid_count / max(int(adata.n_vars), 1)
+    if mapping_rate < 0.2:
+        example_input = [str(g) for g in adata.var_names[:5]]
+        example_feat = [str(g) for g in gf.index[:5]]
+        msg = (
+            f"Low gene feature mapping rate ({mapping_rate:.1%}). "
+            f"Input examples: {example_input}; feature table examples: {example_feat}. "
+            "Check gene symbol casing (e.g. ACTB vs actb), organism, and whether "
+            "adata.var_names match the annotation used to build the feature table."
+        )
+        warnings.warn(msg, UserWarning, stacklevel=2)
+        logger.warning(msg)
+
     return adata