pdex 0.2.0__tar.gz → 0.2.2__tar.gz

{pdex-0.2.0 → pdex-0.2.2}/.github/workflows/ci.yml

@@ -5,10 +5,41 @@ on: [push, pull_request]
 jobs:
   all_jobs:
     runs-on: ubuntu-latest
-    needs: [formatting, type-checking, pytest]
+    needs: [formatting, type-checking, pytest, semver-check]
+    if: always()
     steps:
       - name: Complete
-        run: echo "Complete"
+        run: |
+          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
+            echo "One or more required jobs failed."
+            exit 1
+          fi
+          echo "Complete"
+
+  semver-check:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: check version bump
+        run: |
+          BASE_VERSION=$(git show origin/${{ github.base_ref }}:pyproject.toml \
+            | python3 -c "import sys, tomllib; print(tomllib.load(sys.stdin.buffer)['project']['version'])")
+          PR_VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "Base version: $BASE_VERSION"
+          echo "PR version:   $PR_VERSION"
+          if [ -z "$BASE_VERSION" ] || [ -z "$PR_VERSION" ]; then
+            echo "ERROR: failed to parse version from pyproject.toml"
+            exit 1
+          fi
+          if [ "$BASE_VERSION" = "$PR_VERSION" ]; then
+            echo "ERROR: version in pyproject.toml ($PR_VERSION) must be bumped before merging."
+            exit 1
+          fi
 
   install-job:
     runs-on: ubuntu-latest

{pdex-0.2.0 → pdex-0.2.2}/CLAUDE.md

@@ -36,7 +36,7 @@ uv run ty check
 
 ### Core Pipeline (`src/pdex/__init__.py`)
 
-The main entry point is `pdex(adata, groupby, mode, threads, is_log1p, geometric_mean, as_pandas, **kwargs)`, which:
+The main entry point is `pdex(adata, groupby, mode, threads, is_log1p, geometric_mean, as_pandas, epsilon, **kwargs)`, which:
 
 1. Validates the `groupby` column in `adata.obs`
 2. Extracts unique groups (filters NaN and empty strings)
@@ -79,8 +79,9 @@ The returned Polars DataFrame (or pandas DataFrame when `as_pandas=True`) has co
 | `ref_mean`          | float | Pseudobulk mean for the reference, always in natural (count) space    |
 | `target_membership` | int   | Number of cells in the target group                                   |
 | `ref_membership`    | int   | Number of cells in the reference                                      |
-| `fold_change`       | float | log2(target_mean / ref_mean) — computed from pseudobulk means         |
-| `percent_change`    | float | (target_mean - ref_mean) / ref_mean — computed from pseudobulk means  |
+| `fold_change`       | float | **Deprecated** alias for `log2_fold_change` (identical values). Retained for one release; emits a `FutureWarning` on every `pdex(...)` call and will be removed in pdex 0.3.0. |
+| `log2_fold_change`  | float | log2((target_mean + epsilon) / (ref_mean + epsilon)) — computed from pseudobulk means |
+| `percent_change`    | float | (target_mean - ref_mean) / (ref_mean + epsilon) — computed from pseudobulk means |
 | `p_value`           | float | Mann-Whitney U p-value (per-cell vectors)                             |
 | `statistic`         | float | Mann-Whitney U statistic                                              |
 | `fdr`               | float | FDR-corrected p-value, applied per-group across genes. For `on_target` mode, applied across all groups.                 |

{pdex-0.2.0 → pdex-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdex
-Version: 0.2.0
+Version: 0.2.2
 Summary: Parallel differential expression for single-cell perturbation sequencing
 Author-email: noam teyssier <noam.teyssier@arcinstitute.org>
 License-File: LICENSE
@@ -113,7 +113,8 @@ Returns a Polars DataFrame (or pandas if `as_pandas=True`) with one row per (gro
 | `ref_mean`          | Pseudobulk mean for the reference (count space)    |
 | `target_membership` | Number of cells in the target group                |
 | `ref_membership`    | Number of cells in the reference                   |
-| `fold_change`       | log2(target_mean / ref_mean)                       |
+| `fold_change`       | **Deprecated alias** for `log2_fold_change` (identical values). Will be removed in pdex 0.3.0. |
+| `log2_fold_change`  | log2(target_mean / ref_mean)                       |
 | `percent_change`    | (target_mean - ref_mean) / ref_mean                |
 | `p_value`           | Mann-Whitney U p-value                             |
 | `statistic`         | Mann-Whitney U statistic                           |

{pdex-0.2.0 → pdex-0.2.2}/README.md

@@ -95,7 +95,8 @@ Returns a Polars DataFrame (or pandas if `as_pandas=True`) with one row per (gro
 | `ref_mean`          | Pseudobulk mean for the reference (count space)    |
 | `target_membership` | Number of cells in the target group                |
 | `ref_membership`    | Number of cells in the reference                   |
-| `fold_change`       | log2(target_mean / ref_mean)                       |
+| `fold_change`       | **Deprecated alias** for `log2_fold_change` (identical values). Will be removed in pdex 0.3.0. |
+| `log2_fold_change`  | log2(target_mean / ref_mean)                       |
 | `percent_change`    | (target_mean - ref_mean) / ref_mean                |
 | `p_value`           | Mann-Whitney U p-value                             |
 | `statistic`         | Mann-Whitney U statistic                           |

{pdex-0.2.0 → pdex-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pdex"
-version = "0.2.0"
+version = "0.2.2"
 description = "Parallel differential expression for single-cell perturbation sequencing"
 readme = "README.md"
 authors = [{ name = "noam teyssier", email = "noam.teyssier@arcinstitute.org" }]

{pdex-0.2.0 → pdex-0.2.2}/src/pdex/__init__.py

@@ -12,7 +12,7 @@ from scipy.sparse import csr_matrix, issparse
 from scipy.stats import false_discovery_control
 from tqdm import tqdm
 
-from pdex._math import fold_change, mwu, percent_change, pseudobulk
+from pdex._math import log2_fold_change, mwu, percent_change, pseudobulk
 
 from ._utils import _detect_is_log1p, set_numba_threadpool
 
@@ -129,9 +129,9 @@ def _isolate_matrix(
     if adata.X is None:
         raise ValueError("AnnData object does not have a matrix.")
     if mask_y is None:
-        result = adata.X[mask_x]  # type: ignore[not-subscriptable]
+        result = adata.X[mask_x]  # ty: ignore[not-subscriptable]
     else:
-        result = adata.X[mask_x, mask_y]  # type: ignore[not-subscriptable]
+        result = adata.X[mask_x, mask_y]  # ty: ignore[not-subscriptable]
 
     # Fast path: already in-memory
     if isinstance(result, (np.ndarray, csr_matrix)):
@@ -151,6 +151,7 @@ def pdex(
     is_log1p: bool | None = None,
     geometric_mean: bool = True,
     as_pandas: bool = False,
+    epsilon: float = 0.0,
     **kwargs,
 ) -> pl.DataFrame | pd.DataFrame:
     """Run parallel differential expression analysis on single-cell data.
@@ -201,6 +202,22 @@ def pdex(
     as_pandas:
         If ``True``, return a :class:`pandas.DataFrame` instead of a
         :class:`polars.DataFrame`. Requires ``pyarrow``.
+    epsilon:
+        Pseudocount added to both ``target_mean`` and ``ref_mean`` before computing
+        ``fold_change`` and ``percent_change``. When ``epsilon > 0``, extreme
+        values from near-zero reference means (scRNA-seq sparsity artifact) are
+        dampened toward zero. Has no effect on the Mann-Whitney U p-value or FDR.
+        Default ``0.0`` preserves existing behaviour.
+
+        **Recommended usage:** For scRNA-seq CRISPRi/CRISPRa screens where many
+        genes are unexpressed in the reference group, start with ``epsilon=0.5``.
+        This provides modest dampening without substantially compressing fold changes
+        for well-expressed genes. For complete suppression of the sparsity artifact,
+        combine with a ``min_mean_expression`` pre-filter on the reference group —
+        ``epsilon`` alone cannot eliminate low p-values arising from per-cell
+        distributional shifts in near-zero genes.
+
+        Must be non-negative. Raises :class:`ValueError` if negative.
     **kwargs:
         Mode-specific keyword arguments:
 
@@ -216,14 +233,21 @@ def pdex(
     pl.DataFrame | pd.DataFrame
         One row per (group, feature) pair with columns: ``target``, ``feature``,
         ``target_mean``, ``ref_mean``, ``target_membership``, ``ref_membership``,
-        ``fold_change``, ``percent_change``, ``p_value``, ``statistic``, ``fdr``.
+        ``fold_change``, ``log2_fold_change``, ``percent_change``, ``p_value``,
+        ``statistic``, ``fdr``.
 
         ``target_mean`` and ``ref_mean`` are always in **natural (count) space**.
 
-        ``fold_change`` and ``percent_change`` are derived from the pseudobulk
-        means (not from the per-cell MWU test inputs): ``fold_change`` is
-        ``log2(target_mean / ref_mean)`` and ``percent_change`` is
-        ``(target_mean - ref_mean) / ref_mean``.  The MWU ``p_value`` and
+        ``log2_fold_change`` and ``percent_change`` are derived from the pseudobulk
+        means (not from the per-cell MWU test inputs): ``log2_fold_change`` is
+        ``log2((target_mean + epsilon) / (ref_mean + epsilon))`` and
+        ``percent_change`` is ``(target_mean - ref_mean) / (ref_mean + epsilon)``.
+
+        ``fold_change`` is a **deprecated** alias for ``log2_fold_change``
+        (identical values). It is retained for one release to ease migration
+        and will be removed in pdex 0.3.0. New code should read
+        ``log2_fold_change`` directly. A :class:`FutureWarning` is emitted
+        on every ``pdex(...)`` call.  The MWU ``p_value`` and
         ``statistic`` are computed directly on the per-cell expression vectors.
 
         For ``mode="ref"``, the reference group itself is excluded from the output.
@@ -239,6 +263,17 @@ def pdex(
         adata.n_vars,
     )
 
+    if epsilon < 0:
+        raise ValueError(f"epsilon must be non-negative, got {epsilon}")
+
+    warnings.warn(
+        "The `fold_change` column in pdex output is deprecated and will be "
+        "removed in pdex 0.3.0. Use `log2_fold_change` instead — it contains "
+        "the same values (`log2(target_mean / ref_mean)`).",
+        FutureWarning,
+        stacklevel=2,
+    )
+
     # Set the global threadpool for numba
     set_numba_threadpool(threads)
 
@@ -270,6 +305,7 @@ def pdex(
             reference=reference,
             geometric_mean=geometric_mean,
             is_log1p=is_log1p,
+            epsilon=epsilon,
         )
     elif mode == "all":
         if kwargs:
@@ -283,6 +319,7 @@ def pdex(
             groupby=groupby,
             geometric_mean=geometric_mean,
             is_log1p=is_log1p,
+            epsilon=epsilon,
         )
     elif mode == "on_target":
         gene_col = kwargs.pop("gene_col", None)
@@ -303,6 +340,7 @@ def pdex(
             reference=reference,
             geometric_mean=geometric_mean,
             is_log1p=is_log1p,
+            epsilon=epsilon,
         )
     else:
         raise ValueError(f"Invalid mode: {mode}")
@@ -318,6 +356,7 @@ def _pdex_ref(
     reference: str = DEFAULT_REFERENCE,
     geometric_mean: bool = True,
     is_log1p: bool = False,
+    epsilon: float = 0.0,
 ) -> pl.DataFrame:
     unique_groups, unique_group_indices = _unique_groups(adata.obs, groupby)
     log.info("Found %d groups (excluding reference)", len(unique_groups) - 1)
@@ -353,8 +392,8 @@ def _pdex_ref(
             group_matrix, geometric_mean=geometric_mean, is_log1p=is_log1p
         )
 
-        fc = fold_change(group_bulk, ref_bulk)
-        pc = percent_change(group_bulk, ref_bulk)
+        lfc = log2_fold_change(group_bulk, ref_bulk, epsilon)
+        pc = percent_change(group_bulk, ref_bulk, epsilon)
         mwu_result = mwu(group_matrix, ref_data)
 
         mwu_statistic = mwu_result.statistic
@@ -370,7 +409,8 @@ def _pdex_ref(
                     "ref_mean": np.asarray(ref_bulk).ravel(),
                     "target_membership": group_mask.size,
                     "ref_membership": ref_membership,
-                    "fold_change": fc,
+                    "fold_change": lfc,
+                    "log2_fold_change": lfc,
                     "percent_change": pc,
                     "p_value": mwu_pvalue,
                     "statistic": mwu_statistic,
@@ -386,6 +426,7 @@ def _pdex_all(
     groupby: str,
     geometric_mean: bool = True,
     is_log1p: bool = False,
+    epsilon: float = 0.0,
 ) -> pl.DataFrame:
     unique_groups, unique_group_indices = _unique_groups(adata.obs, groupby)
     log.info("Found %d groups for 1-vs-rest comparison", len(unique_groups))
@@ -414,8 +455,8 @@ def _pdex_all(
             rest_matrix, geometric_mean=geometric_mean, is_log1p=is_log1p
         )
 
-        fc = fold_change(group_bulk, rest_bulk)
-        pc = percent_change(group_bulk, rest_bulk)
+        lfc = log2_fold_change(group_bulk, rest_bulk, epsilon)
+        pc = percent_change(group_bulk, rest_bulk, epsilon)
         mwu_result = mwu(group_matrix, rest_matrix)
 
         mwu_statistic = mwu_result.statistic
@@ -431,7 +472,8 @@ def _pdex_all(
                     "ref_mean": np.asarray(rest_bulk).ravel(),
                     "target_membership": group_mask.size,
                     "ref_membership": rest_mask.size,
-                    "fold_change": fc,
+                    "fold_change": lfc,
+                    "log2_fold_change": lfc,
                     "percent_change": pc,
                     "p_value": mwu_pvalue,
                     "statistic": mwu_statistic,
@@ -450,6 +492,7 @@ def _pdex_on_target(
     reference: str = DEFAULT_REFERENCE,
     geometric_mean: bool = True,
     is_log1p: bool = False,
+    epsilon: float = 0.0,
 ) -> pl.DataFrame:
     unique_groups, unique_group_indices = _unique_groups(adata.obs, groupby)
     ref_index = _identify_reference_index(unique_groups, reference)
@@ -501,8 +544,12 @@ def _pdex_on_target(
             pseudobulk(ref_col, geometric_mean=geometric_mean, is_log1p=is_log1p)[0]
         )
 
-        fc = float(fold_change(np.array([target_mean]), np.array([ref_mean]))[0])
-        pc = float(percent_change(np.array([target_mean]), np.array([ref_mean]))[0])
+        lfc = float(
+            log2_fold_change(np.array([target_mean]), np.array([ref_mean]), epsilon)[0]
+        )
+        pc = float(
+            percent_change(np.array([target_mean]), np.array([ref_mean]), epsilon)[0]
+        )
 
         mwu_result = mwu(group_col, ref_col)
         p_value = float(np.clip(np.asarray(mwu_result.pvalue).ravel()[0], 0, 1))
@@ -516,7 +563,8 @@ def _pdex_on_target(
                 "ref_mean": ref_mean,
                 "target_membership": group_mask.size,
                 "ref_membership": ref_membership,
-                "fold_change": fc,
+                "fold_change": lfc,
+                "log2_fold_change": lfc,
                 "percent_change": pc,
                 "p_value": p_value,
                 "statistic": statistic,

{pdex-0.2.0 → pdex-0.2.2}/src/pdex/_math.py

@@ -14,7 +14,7 @@ def _log1p_col_mean(matrix: np.ndarray) -> np.ndarray:
     """Mean of log1p(X) across rows (axis=0) for a dense 2-D array."""
     n_rows, n_cols = matrix.shape
     result = np.zeros(n_cols)
-    for j in nb.prange(n_cols):  # type: ignore[attr-defined]
+    for j in nb.prange(n_cols):  # ty: ignore[not-iterable]
         s = 0.0
         for i in range(n_rows):
             s += np.log1p(matrix[i, j])
@@ -26,7 +26,7 @@ def _log1p_col_mean(matrix: np.ndarray) -> np.ndarray:
 def _expm1_vec(x: np.ndarray) -> np.ndarray:
     """Element-wise expm1 over a 1-D array."""
     result = np.empty_like(x)
-    for i in nb.prange(len(x)):  # type: ignore[attr-defined]
+    for i in nb.prange(len(x)):  # ty: ignore[not-iterable]
         result[i] = np.expm1(x[i])
     return result
 
@@ -36,7 +36,7 @@ def _expm1_vec_mean(matrix: np.ndarray) -> np.ndarray:
     """Mean of expm1(X) across rows (axis=0) for a dense 2-D array."""
     n_rows, n_cols = matrix.shape
     result = np.zeros(n_cols)
-    for j in nb.prange(n_cols):  # type: ignore[attr-defined]
+    for j in nb.prange(n_cols):  # ty: ignore[not-iterable]
         s = 0.0
         for i in range(n_rows):
             s += np.expm1(matrix[i, j])
@@ -106,15 +106,27 @@ def bulk_matrix_geometric(
 
 
 @nb.njit(parallel=True)
-def fold_change(x: np.ndarray, y: np.ndarray) -> np.ndarray:
-    """Calculates the log2-fold change between two arrays."""
-    return np.log2(x / y)
+def log2_fold_change(x: np.ndarray, y: np.ndarray, epsilon: float = 0.0) -> np.ndarray:
+    """Calculates the log2-fold change between two arrays.
+
+    When ``epsilon > 0``, adds a small pseudocount to both numerator and
+    denominator before taking the ratio, dampening extreme fold changes that arise
+    when the reference mean is near zero (scRNA-seq sparsity artifact).
+    """
+    return np.log2((x + epsilon) / (y + epsilon))
 
 
 @nb.njit(parallel=True)
-def percent_change(x: np.ndarray, y: np.ndarray) -> np.ndarray:
-    """Calculates the change between two arrays."""
-    return (x - y) / y
+def percent_change(
+    x: np.ndarray, y: np.ndarray, prior_count: float = 0.0
+) -> np.ndarray:
+    """Calculates the percent change between two arrays.
+
+    When ``prior_count > 0``, adds a pseudocount to the denominator before
+    computing the ratio, dampening extreme values when the reference mean is
+    near zero (scRNA-seq sparsity artifact).
+    """
+    return (x - y) / (y + prior_count)
 
 
 def mwu(

{pdex-0.2.0 → pdex-0.2.2}/tests/test_math.py

@@ -1,32 +1,32 @@
-"""Tests for pdex._math (fold_change, percent_change, bulk_matrix_geometric)."""
+"""Tests for pdex._math (log2_fold_change, percent_change, bulk_matrix_geometric)."""
 
 import numpy as np
 
-from pdex._math import bulk_matrix_geometric, fold_change, percent_change
+from pdex._math import bulk_matrix_geometric, log2_fold_change, percent_change
 
 
 class TestFoldChange:
     def test_ratio_of_two(self):
         x = np.array([4.0, 8.0])
         y = np.array([2.0, 4.0])
-        result = fold_change(x, y)
+        result = log2_fold_change(x, y)
         np.testing.assert_allclose(result, [1.0, 1.0])
 
     def test_equal_values(self):
         x = np.array([3.0, 5.0])
-        result = fold_change(x, x)
+        result = log2_fold_change(x, x)
         np.testing.assert_allclose(result, [0.0, 0.0])
 
     def test_half(self):
         x = np.array([1.0])
         y = np.array([2.0])
-        result = fold_change(x, y)
+        result = log2_fold_change(x, y)
         np.testing.assert_allclose(result, [-1.0])
 
     def test_known_values(self):
         x = np.array([1.0, 2.0, 4.0, 8.0])
         y = np.array([1.0, 1.0, 1.0, 1.0])
-        result = fold_change(x, y)
+        result = log2_fold_change(x, y)
         np.testing.assert_allclose(result, [0.0, 1.0, 2.0, 3.0])
 
 
@@ -55,6 +55,72 @@ class TestPercentChange:
         np.testing.assert_allclose(result, [-0.5, 0.0, 0.5])
 
 
+class TestFoldChangeWithEpsilon:
+    def test_zero_epsilon_matches_baseline(self):
+        """epsilon=0.0 must be identical to calling without it."""
+        x = np.array([4.0, 8.0, 0.1])
+        y = np.array([2.0, 4.0, 0.001])
+        np.testing.assert_array_equal(
+            log2_fold_change(x, y), log2_fold_change(x, y, 0.0)
+        )
+
+    def test_dampens_extreme_fc_from_near_zero_denominator(self):
+        """epsilon=0.5 pulls extreme FC toward zero."""
+        x = np.array([0.1])
+        y = np.array([0.001])
+        fc_raw = log2_fold_change(x, y)[0]
+        fc_dampened = log2_fold_change(x, y, 0.5)[0]
+        assert abs(fc_dampened) < abs(fc_raw)
+        np.testing.assert_allclose(fc_dampened, np.log2(0.6 / 0.501), rtol=1e-5)
+
+    def test_preserves_direction(self):
+        """epsilon should not flip the sign of fold change."""
+        x = np.array([2.0, 0.5])
+        y = np.array([1.0, 1.0])
+        result = log2_fold_change(x, y, 0.5)
+        assert result[0] > 0
+        assert result[1] < 0
+
+    def test_equal_means_still_zero(self):
+        """When target_mean == ref_mean, FC should be 0 regardless of epsilon."""
+        x = np.array([0.5, 2.0])
+        result = log2_fold_change(x, x, 0.5)
+        np.testing.assert_allclose(result, [0.0, 0.0])
+
+
+class TestPercentChangeWithPriorCount:
+    def test_zero_epsilon_matches_baseline(self):
+        """epsilon=0.0 must be identical to calling without it."""
+        x = np.array([4.0, 8.0, 0.1])
+        y = np.array([2.0, 4.0, 0.001])
+        np.testing.assert_array_equal(percent_change(x, y), percent_change(x, y, 0.0))
+
+    def test_dampens_extreme_pc_from_near_zero_denominator(self):
+        """epsilon=0.5 pulls extreme percent change toward zero."""
+        x = np.array([0.1])
+        y = np.array([0.001])
+        pc_raw = percent_change(x, y)[0]
+        pc_dampened = percent_change(x, y, 0.5)[0]
+        assert abs(pc_dampened) < abs(pc_raw)
+        np.testing.assert_allclose(
+            pc_dampened, (0.1 - 0.001) / (0.001 + 0.5), rtol=1e-5
+        )
+
+    def test_preserves_direction(self):
+        """epsilon should not flip the sign of percent change."""
+        x = np.array([2.0, 0.5])
+        y = np.array([1.0, 1.0])
+        result = percent_change(x, y, 0.5)
+        assert result[0] > 0
+        assert result[1] < 0
+
+    def test_equal_means_still_zero(self):
+        """When target_mean == ref_mean, percent_change should be 0 regardless of epsilon."""
+        x = np.array([0.5, 2.0])
+        result = percent_change(x, x, 0.5)
+        np.testing.assert_allclose(result, [0.0, 0.0])
+
+
 class TestBulkMatrixGeometric:
     """Tests for bulk_matrix_geometric."""
 

{pdex-0.2.0 → pdex-0.2.2}/tests/test_pdex.py

@@ -15,6 +15,7 @@ EXPECTED_COLUMNS = {
     "target_membership",
     "ref_membership",
     "fold_change",
+    "log2_fold_change",
     "percent_change",
     "p_value",
     "statistic",
@@ -137,6 +138,21 @@ class TestPdexRefMode:
                 typo_arg="oops",
             )
 
+    def test_epsilon_accepted(self, small_adata):
+        """epsilon parameter is accepted without error."""
+        result = pdex(small_adata, groupby="guide", is_log1p=False, epsilon=0.5)
+        assert isinstance(result, pl.DataFrame)
+
+    def test_epsilon_zero_matches_default(self, small_adata):
+        """epsilon=0.0 produces identical results to omitting the parameter."""
+        default_result = pdex(small_adata, groupby="guide", is_log1p=False)
+        explicit_result = pdex(
+            small_adata, groupby="guide", is_log1p=False, epsilon=0.0
+        )
+        assert isinstance(default_result, pl.DataFrame)
+        assert isinstance(explicit_result, pl.DataFrame)
+        assert default_result.equals(explicit_result)
+
 
 class TestPdexRefSparse:
     """Tests for pdex with sparse CSR input."""
@@ -463,6 +479,10 @@ class TestPdexOnTargetValidation:
 
 
 class TestPdexValidation:
+    def test_negative_epsilon_raises(self, small_adata):
+        with pytest.raises(ValueError, match="epsilon must be non-negative"):
+            pdex(small_adata, groupby="guide", is_log1p=False, epsilon=-0.1)
+
     def test_invalid_mode(self, small_adata):
         with pytest.raises(ValueError, match="Invalid mode"):
             pdex(
@@ -645,3 +665,20 @@ class TestPdexBacked:
                 rtol=1e-6,
                 err_msg=f"Mismatch in column {col}",
             )
+
+
+class TestLog2FoldChangeColumn:
+    """Regression test for the `log2_fold_change` column semantics."""
+
+    @pytest.mark.parametrize("mode", ["ref", "all"])
+    def test_log2_fold_change_equals_log2_ratio(self, small_adata, mode):
+        """log2_fold_change == log2(target_mean / ref_mean) on finite entries."""
+        result = pdex(small_adata, groupby="guide", mode=mode, is_log1p=False)
+        target = result["target_mean"].to_numpy()
+        ref = result["ref_mean"].to_numpy()
+        actual = result["log2_fold_change"].to_numpy()
+        with np.errstate(divide="ignore", invalid="ignore"):
+            expected = np.log2(target / ref)
+        finite = np.isfinite(expected) & np.isfinite(actual)
+        assert finite.any()
+        np.testing.assert_allclose(actual[finite], expected[finite], rtol=1e-6)