Update Perturb-seq example

Author: jaydu1

causarray/DR_learner.py

@@ -301,19 +301,29 @@ def LFC(
 
         * ``'unequal'`` (default, v0.0.6+): Welch variance
           ``s₀²/n₀ + s₁²/n₁`` with Welch-Satterthwaite degrees of
-          freedom; p-values use the t-distribution. This is the recommended
-          choice for perturbation screens and for case-control, bulk, and
-          donor-level pseudo-bulk analyses. Independence of the rows does not
-          imply equal treatment-arm variances, and biological heterogeneity or
-          unequal effective sample sizes can make pooled inference
-          anti-conservative.
+          freedom; p-values use the t-distribution. Prefer this estimator when
+          treatment and control sample sizes or effective sample sizes are
+          meaningfully unbalanced, when arm-specific pseudo-outcome variances
+          may differ, and for case-control, bulk, and donor-level pseudo-bulk
+          analyses. Independence of the rows does not imply equal
+          treatment-arm variances, and biological heterogeneity or imbalance
+          can make pooled inference anti-conservative.
         * ``'pooled'``: pooled-variance estimator ``(s² + eps_var) / n``.
-          Treat this as an opt-in sensitivity or legacy analysis, not as the
-          default for small case-control studies. Use it only when equal arm
-          variances have a strong scientific and empirical justification.
-          Pooled inference can produce substantially smaller standard errors
-          and many more discoveries; donor-level independence alone is not a
-          justification for pooling.
+          For a small, approximately balanced perturbation comparison, this
+          estimator may provide better power when the independent sampling
+          units and arm-specific pseudo-outcome variances are reasonably
+          comparable. Treat it as an opt-in, empirically justified analysis,
+          not as an automatic choice for every small study. Balanced sample
+          counts alone are insufficient for case-control data, where biological
+          heterogeneity commonly favors ``'unequal'``. Pooled inference can
+          produce substantially smaller standard errors and many more
+          discoveries.
+
+        There is no universal arm-size ratio at which the choice should switch.
+        Inspect nominal and propensity-weighted effective sample sizes,
+        arm-specific pseudo-outcome variability, and sensitivity of the
+        discoveries. When those diagnostics are uncertain, retain
+        ``'unequal'``.
 
         ``'unequal'`` accommodates arm-specific variance but does not model
         within-donor or within-subject correlation. Repeated cells from the
@@ -634,10 +644,13 @@ def gcate_lfc_batch(
     lfc_kwargs : dict or None
         Extra keyword arguments forwarded to :func:`LFC`
         (e.g. ``usevar``, ``fdx``, ``thres_min``). Retain the default
-        ``usevar='unequal'`` for perturbation screens and for case-control,
-        bulk, or pseudo-bulk analyses. Pass
-        ``lfc_kwargs=dict(usevar='pooled')`` only for a deliberately justified
-        equal-variance sensitivity or legacy analysis.
+        ``usevar='unequal'`` when arm sizes or effective sample sizes are
+        meaningfully unbalanced, when arm-specific variability may differ, and
+        for case-control, bulk, or pseudo-bulk analyses. For a small,
+        approximately balanced perturbation comparison with comparable
+        pseudo-outcome variability, ``lfc_kwargs=dict(usevar='pooled')`` may
+        improve power. There is no universal balance threshold; compare the
+        relevant diagnostics and retain ``'unequal'`` when uncertain.
     **kwargs
         Additional arguments forwarded to both :func:`fit_gcate_batch` and
         :func:`LFC`.  When a key collides with ``gcate_kwargs`` /

docs/source/main_function/lfc.rst

@@ -13,20 +13,29 @@ Choosing the variance estimator
 -------------------------------
 
 ``LFC`` defaults to ``usevar='unequal'`` (Welch inference), which estimates
-the treatment and control variances separately. Retain this default for
-perturbation screens and for case-control, bulk, and donor-level pseudo-bulk
-analyses. Independence of the rows does not imply equal treatment-arm
-variances: disease severity, biological response, residual composition,
-library size, treatment imbalance, and heterogeneous expression can all make
-pooled inference anti-conservative.
-
-Treat ``usevar='pooled'`` as an opt-in sensitivity or legacy analysis. Use it
-only when equal arm variances have a strong scientific and empirical
-justification; do not select it merely because a case-control study has a
-small number of independent samples. Pooled inference can produce much smaller
-standard errors and substantially more discoveries. For a deliberately
-justified batched sensitivity analysis, pass
-``lfc_kwargs=dict(usevar='pooled')``.
+the treatment and control variances separately. Prefer this default when the
+treatment and control sample sizes, or their propensity-weighted effective
+sample sizes, are meaningfully unbalanced. Also retain it when arm-specific
+pseudo-outcome variances may differ and for case-control, bulk, and donor-level
+pseudo-bulk analyses. Independence of the rows does not imply equal
+treatment-arm variances: disease severity, biological response, residual
+composition, library size, treatment imbalance, and heterogeneous expression
+can all make pooled inference anti-conservative.
+
+For a small, approximately balanced perturbation comparison,
+``usevar='pooled'`` may provide better power when the independent sampling
+units and arm-specific pseudo-outcome variances are reasonably comparable.
+Treat it as an opt-in, empirically justified analysis rather than an automatic
+small-sample choice. Balanced counts alone do not justify pooling in a
+case-control study. Pooled inference can produce much smaller standard errors
+and substantially more discoveries. For a deliberately justified batched
+analysis, pass ``lfc_kwargs=dict(usevar='pooled')``.
+
+There is no universal sample-size ratio at which the recommendation changes.
+Compare nominal arm sizes, propensity-weighted effective sample sizes,
+arm-specific pseudo-outcome variability, and the stability of discoveries
+under both estimators. Retain ``usevar='unequal'`` when these diagnostics do not
+support pooling.
 
 Donor-level independence alone does not establish equal arm variances. For
 example, the SEA-AD tutorial uses ``usevar='unequal'`` because disease severity,

docs/source/tutorial/perturbseq/perturbseq-py.ipynb

@@ -69,12 +69,12 @@ res_gate <- causarray$fit_gcate(Y, X, A, r, verbose=TRUE) # a list of results fr
 U <- res_gate[[2]]$U
 ```
 
-Next, we apply causarray to estimate the causal effects of perturbations on gene expression. We use unequal (Welch) variance because treatment and control cells can have different pseudo-outcome variability; pooling those variances can be anti-conservative in a perturbation screen.
+Next, we apply causarray to estimate the causal effects of perturbations on gene expression. Here the 106 GFP control cells and the perturbation groups (median 89 cells) are approximately balanced. We therefore use pooled variance to retain power in this relatively small comparison. This is a dataset-specific choice: unequal variance remains preferable when arm sizes or effective sample sizes are meaningfully unbalanced, when pseudo-outcome variability differs between arms, and for the Replogle and case-control tutorials.
 
 ```{r}
 offsets <- log(res_gate[[2]][['kwargs_glm']][['size_factor']]) # use the precomputed size factors
 res <- causarray$LFC(Y, cbind(X, U), A, cbind(X_A, U), offset=offsets,
-                    usevar="unequal", verbose=TRUE)
+                    usevar="pooled", verbose=TRUE)
 ```
 
 ```{r}

docs/source/tutorial/perturbseq/perturbseq-r.Rmd

@@ -132,14 +132,18 @@ U <- res_gate[[2]]$U
 ```
 
 Next, we apply causarray to estimate the causal effects of perturbations
-on gene expression. We use unequal (Welch) variance because treatment and
-control cells can have different pseudo-outcome variability; pooling those
-variances can be anti-conservative in a perturbation screen.
+on gene expression. Here the 106 GFP control cells and the perturbation
+groups (median 89 cells) are approximately balanced. We therefore use
+pooled variance to retain power in this relatively small comparison. This
+is a dataset-specific choice: unequal variance remains preferable when arm
+sizes or effective sample sizes are meaningfully unbalanced, when
+pseudo-outcome variability differs between arms, and for the Replogle and
+case-control tutorials.
 
 ``` r
 offsets <- log(res_gate[[2]][['kwargs_glm']][['size_factor']]) # use the precomputed size factors
 res <- causarray$LFC(Y, cbind(X, U), A, cbind(X_A, U), offset=offsets,
-                    usevar="unequal", verbose=TRUE)
+                    usevar="pooled", verbose=TRUE)
 ```
 
     ## 'Estimating LFC...'