causarray 0.0.7__tar.gz → 0.0.8__tar.gz

{causarray-0.0.7 → causarray-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: causarray
-Version: 0.0.7
+Version: 0.0.8
 Summary: causarray is a Python module for simultaneous causal inference with an array of outcomes.
 Author-email: Jin-Hong Du <jinhongd@hku.hk>, Maya Shen <myshen@andrew.cmu.edu>, Hansruedi Mathys <mathysh@pitt.edu>, Kathryn Roeder <jinhongd@hku.hk>
 Maintainer-email: Jin-Hong Du <jinhongd@hku.hk>
@@ -54,7 +54,16 @@ For optimal parallel performance, we recommend installing `llvm-openmp` if using
 conda install -c conda-forge llvm-openmp
 ```
 
-For `R` users, `reticulate` can be used to call `causarray` from `R`.
+For `R` users, `reticulate` can be used to call `causarray` from R while
+keeping NumPy >2 in the Python environment. Create the separate R environment
+with a current NumPy-2-compatible reticulate build:
+
+```bash
+conda env create -f environment-r.yaml
+```
+
+The R tutorial runs from `causarray-r` and connects to the Python package in
+the `causarray` environment.
 The documentation and tutorials using both `Python` and `R` are available at [causarray.readthedocs.io](https://causarray.readthedocs.io/en/latest/).
 
 

{causarray-0.0.7 → causarray-0.0.8}/README.md

@@ -29,7 +29,16 @@ For optimal parallel performance, we recommend installing `llvm-openmp` if using
 conda install -c conda-forge llvm-openmp
 ```
 
-For `R` users, `reticulate` can be used to call `causarray` from `R`.
+For `R` users, `reticulate` can be used to call `causarray` from R while
+keeping NumPy >2 in the Python environment. Create the separate R environment
+with a current NumPy-2-compatible reticulate build:
+
+```bash
+conda env create -f environment-r.yaml
+```
+
+The R tutorial runs from `causarray-r` and connects to the Python package in
+the `causarray` environment.
 The documentation and tutorials using both `Python` and `R` are available at [causarray.readthedocs.io](https://causarray.readthedocs.io/en/latest/).
 
 

{causarray-0.0.7 → causarray-0.0.8}/causarray/DR_learner.py

@@ -10,6 +10,24 @@ from causarray.DR_inference import fdx_control, bh_correction
 from causarray.utils import reset_random_seeds, pprint, tqdm, comp_size_factor, _filter_params
 
 
+def _add_log2fc_columns(df_res):
+    """Add base-2 LFC aliases while retaining natural-log result columns."""
+    log2 = np.log(2.0)
+    log2fc = df_res['tau'].to_numpy() / log2
+    log2fc_se = df_res['std'].to_numpy() / log2
+
+    # Recompute existing aliases as well as missing ones.  This normalizes
+    # mixed old/new frames loaded from resumable batch caches and guarantees
+    # that the aliases remain exact transformations of tau and std.
+    for name in ('log2fc', 'log2fc_se'):
+        if name in df_res.columns:
+            df_res.pop(name)
+    insert_at = df_res.columns.get_loc('std') + 1
+    df_res.insert(insert_at, 'log2fc', log2fc)
+    df_res.insert(insert_at + 1, 'log2fc_se', log2fc_se)
+    return df_res
+
+
 
 def compute_causal_estimand(
     estimand,
@@ -301,19 +319,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
@@ -359,9 +387,17 @@ def LFC(
     Returns
     -------
     df_res : DataFrame
-        Test results with effect estimates and inference columns, raw
-        ``mean_control`` and ``mean_treated`` counterfactual means, and an
-        ``estimable`` flag (plus ``trt`` for multiple treatments).
+        Test results with natural-log effect estimate ``tau`` and standard
+        error ``std``, together with their base-2 equivalents ``log2fc`` and
+        ``log2fc_se``. The fold change is treatment relative to control, and
+        ``log2fc_se`` is a standard error (not a sample standard deviation).
+        The result also contains inference columns, raw ``mean_control`` and
+        ``mean_treated`` counterfactual means, and an ``estimable`` flag (plus
+        ``trt`` for multiple treatments).
+
+        .. versionadded:: 0.0.8
+            Added the ``log2fc`` and ``log2fc_se`` convenience columns. The
+            original natural-log ``tau`` and ``std`` columns remain unchanged.
     """
 
     def estimand(etas, A, **kwargs):
@@ -448,12 +484,13 @@ def LFC(
     if K is None:
         K = 2 if cross_est else 1
 
-    return compute_causal_estimand(
+    df_res, estimation = compute_causal_estimand(
         estimand, Y, W, A, W_A, family, offset,    
         Y_hat=Y_hat, pi_hat=pi_hat, mask=mask,
         fdx=fdx, fdx_alpha=fdx_alpha, fdx_c=fdx_c,
         verbose=verbose, backend=backend, K=K, ps_clip=ps_clip,
         ps_class_weight=ps_class_weight, **kwargs)
+    return _add_log2fc_columns(df_res), estimation
 
 
 
@@ -634,10 +671,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`` /
@@ -649,8 +689,10 @@ def gcate_lfc_batch(
     Returns
     -------
     df_res : DataFrame
-        Concatenated result from all batches.  Includes a ``'batch'``
-        column with the 0-based batch index so batches can be identified.
+        Concatenated result from all batches. Includes natural-log ``tau`` and
+        ``std`` columns, base-2 ``log2fc`` and ``log2fc_se`` columns, and a
+        ``'batch'`` column with the 0-based batch index. Older compatible
+        caches containing only ``tau`` and ``std`` are upgraded in memory.
     """
     import gc
     from causarray.gcate import fit_gcate_batch
@@ -821,7 +863,7 @@ def gcate_lfc_batch(
         result = pd.concat(
             [new_dfs[i] for i in all_indices], axis=0
         ).reset_index(drop=True)
-    return result
+    return _add_log2fc_columns(result)
 
 
 def LFC_batch(*args, **kwargs):

causarray-0.0.8/causarray/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.0.8"

causarray-0.0.7/causarray/__about__.py

@@ -1 +0,0 @@
-__version__ = "0.0.7"