causarray 0.0.7__tar.gz → 0.0.9__tar.gz

{causarray-0.0.7 → causarray-0.0.9}/.gitignore

@@ -184,6 +184,8 @@ docs/source/tutorial/replogle/replogle_subset.h5ad
 docs/source/tutorial/replogle/replogle_subset_norm*.h5ad
 docs/source/tutorial/replogle/replogle_normed.h5ad
 docs/source/tutorial/replogle/replogle_results.h5
+docs/source/tutorial/replogle/replogle_supt5h_go_*.csv
+docs/source/tutorial/replogle/replogle_propensity_batch12*
 
 # Unrelated tutorial directory (not part of causarray package docs)
 docs/source/tutorial/scp/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: causarray
-Version: 0.0.7
+Version: 0.0.9
 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/).
 
 
@@ -89,6 +98,30 @@ df_res = gcate_lfc_batch(
 See the [Replogle-E-K562 tutorial](https://causarray.readthedocs.io/en/latest/tutorial/replogle/replogle-py.html)
 for a demonstration on 200 perturbations from a genome-wide CRISPRi screen.
 
+### Diagnostic masks without refitting effects
+
+Treatment-by-gene support or quality-control rules can be aligned to an
+existing causarray result table by label, even when its rows are reordered:
+
+```python
+from causarray import align_test_mask
+
+keep = align_test_mask(
+    df_res,
+    support_mask,                 # treatments × genes, Boolean
+    treatment_names=perturbations,
+    gene_names=genes,
+)
+df_res_flagged = df_res.assign(support_keep=keep)
+```
+
+This operation only annotates or subsets existing results. It does not refit
+the causarray LFC or change standard errors and p-values. If a diagnostic rule
+was selected after inspecting the outcomes, retain the original adjusted
+p-values rather than redefining the multiple-testing family post hoc. The
+[Replogle tutorial](https://causarray.readthedocs.io/en/latest/tutorial/replogle/replogle-py.html)
+compares several expression-support rules with marginal Wilcoxon results.
+
 ## Changelog
 
 See [CHANGELOG](https://causarray.readthedocs.io/en/latest/changelog.html) for a full version history.

{causarray-0.0.7 → causarray-0.0.9}/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/).
 
 
@@ -64,6 +73,30 @@ df_res = gcate_lfc_batch(
 See the [Replogle-E-K562 tutorial](https://causarray.readthedocs.io/en/latest/tutorial/replogle/replogle-py.html)
 for a demonstration on 200 perturbations from a genome-wide CRISPRi screen.
 
+### Diagnostic masks without refitting effects
+
+Treatment-by-gene support or quality-control rules can be aligned to an
+existing causarray result table by label, even when its rows are reordered:
+
+```python
+from causarray import align_test_mask
+
+keep = align_test_mask(
+    df_res,
+    support_mask,                 # treatments × genes, Boolean
+    treatment_names=perturbations,
+    gene_names=genes,
+)
+df_res_flagged = df_res.assign(support_keep=keep)
+```
+
+This operation only annotates or subsets existing results. It does not refit
+the causarray LFC or change standard errors and p-values. If a diagnostic rule
+was selected after inspecting the outcomes, retain the original adjusted
+p-values rather than redefining the multiple-testing family post hoc. The
+[Replogle tutorial](https://causarray.readthedocs.io/en/latest/tutorial/replogle/replogle-py.html)
+compares several expression-support rules with marginal Wilcoxon results.
+
 ## Changelog
 
 See [CHANGELOG](https://causarray.readthedocs.io/en/latest/changelog.html) for a full version history.

{causarray-0.0.7 → causarray-0.0.9}/causarray/DR_estimation.py

@@ -1,4 +1,5 @@
 import numpy as np
+import pandas as pd
 from sklearn.linear_model import LogisticRegression
 from sklearn.tree import DecisionTreeClassifier, DecisionTreeRegressor
 from sklearn_ensemble_cv import reset_random_seeds, Ensemble, ECV
@@ -10,6 +11,7 @@ from joblib import Parallel, delayed
 from tqdm import tqdm
 import pprint
 import warnings
+from collections.abc import Mapping
 
 from sklearn.model_selection import KFold, ShuffleSplit
 
@@ -40,6 +42,27 @@ def _get_func_ps(ps_model, **kwargs):
     return func_ps, params_ps
 
 
+def _validate_clip(clip):
+    """Validate a propensity clipping bound and return it as ``(lower, upper)``.
+
+    Raises
+    ------
+    ValueError
+        If ``clip`` is not a pair of numbers satisfying
+        ``0 <= lower < upper <= 1``.
+    """
+    message = 'clip must be None or a pair 0 <= lower < upper <= 1'
+    if isinstance(clip, (str, bytes)) or np.ndim(clip) != 1:
+        raise ValueError(message)
+    try:
+        lower, upper = (float(bound) for bound in clip)
+    except (TypeError, ValueError):
+        raise ValueError(message) from None
+    if not 0 <= lower < upper <= 1:
+        raise ValueError(message)
+    return lower, upper
+
+
 def estimate_propensity_scores(
     A, X_A, K=1, ps_model='logistic', mask=None, clip=None,
     random_state=0, verbose=False, class_weight='balanced', **kwargs,
@@ -172,12 +195,280 @@ def estimate_propensity_scores(
                 pi_hat[test_index, j] = func_ps(x_train, y_train, XA_test)
 
     if clip is not None:
-        if len(clip) != 2 or not 0 <= clip[0] < clip[1] <= 1:
-            raise ValueError('clip must be None or a pair 0 <= lower < upper <= 1')
-        pi_hat = np.clip(pi_hat, clip[0], clip[1])
+        lower, upper = _validate_clip(clip)
+        pi_hat = np.clip(pi_hat, lower, upper)
     return pi_hat
 
 
+def refit_propensity_scores(
+    A, X_A, drop_by_treatment=None, pi_hat=None, treatment_names=None,
+    covariate_names=None, penalty_factors_by_treatment=None, K=1,
+    ps_model='logistic', mask=None, clip=None, random_state=0, verbose=False,
+    class_weight='balanced', **kwargs,
+):
+    """Refit propensity scores with treatment-specific covariate filtering.
+
+    This helper supports sensitivity analyses in which different treatments
+    omit different observed covariates or latent factors, or apply stronger L2
+    regularization to selected covariates. When existing scores are supplied,
+    only treatments named in either treatment-specific mapping are refitted;
+    the remaining columns are carried over from ``pi_hat`` unchanged, up to the
+    shared ``clip`` described below. Outcome models are not fit by this function
+    and cached ``Y_hat`` values can be reused in :func:`LFC`.
+
+    Parameters
+    ----------
+    A : array-like, shape (n, a)
+        Binary treatment indicator matrix.
+    X_A : array-like, shape (n, d_A)
+        Full propensity-model design before treatment-specific filtering.
+    drop_by_treatment : mapping or None
+        Treatment names or indices mapped to covariate names or indices to
+        remove for that treatment. Defaults to no removals.
+    pi_hat : array-like or None, shape (n, a)
+        Existing raw propensity scores. If supplied, treatments absent from
+        ``drop_by_treatment`` are not refitted.
+    treatment_names, covariate_names : sequence, optional
+        Column labels, inferred from DataFrames when possible.
+    penalty_factors_by_treatment : mapping or None
+        Treatment names or indices mapped to ``{covariate: factor}`` mappings.
+        A factor greater than one applies that multiple of the ordinary L2
+        penalty to the named coefficient. This is implemented by dividing the
+        covariate by ``sqrt(factor)`` during both fitting and prediction and is
+        available only for ``ps_model='logistic'`` with an L2 penalty. A factor
+        of one leaves the covariate unchanged. Interpret relative penalties on
+        a common scale; ``prep_causarray_data`` standardizes log-library size.
+    K, ps_model, mask, random_state, verbose, class_weight, **kwargs
+        Passed to :func:`estimate_propensity_scores` for each refitted model.
+    clip : tuple(float, float) or None, optional
+        Bounds applied to the **whole** returned matrix, refitted columns and
+        carried-over columns alike, so that a single consistent bound reaches
+        :func:`LFC`. Pass ``None`` to leave carried-over scores exactly as
+        supplied.
+
+    Returns
+    -------
+    pi_updated : ndarray, shape (n, a)
+        Updated propensity scores.
+    report : DataFrame
+        Audit table of refitted treatments, retained/dropped covariates, and
+        the resulting score spread. ``degenerate_design`` flags a treatment
+        whose retained design is constant, and ``score_std`` reports the
+        standard deviation of its refitted scores on eligible rows; both make a
+        collapsed propensity model visible without reading the warning stream.
+
+    Warns
+    -----
+    RuntimeWarning
+        If filtering leaves a constant design for some treatment, in which case
+        its scores carry no covariate information.
+
+    Notes
+    -----
+    A very large penalty factor shrinks a coefficient towards zero without
+    making the design constant. That case leaves ``degenerate_design`` False
+    but drives ``score_std`` towards zero.
+
+    .. versionadded:: 0.0.9
+    """
+    if drop_by_treatment is None:
+        drop_by_treatment = {}
+    if penalty_factors_by_treatment is None:
+        penalty_factors_by_treatment = {}
+    if not isinstance(drop_by_treatment, Mapping):
+        raise ValueError('drop_by_treatment must be a mapping')
+    if not isinstance(penalty_factors_by_treatment, Mapping):
+        raise ValueError('penalty_factors_by_treatment must be a mapping')
+    if penalty_factors_by_treatment:
+        if ps_model != 'logistic':
+            raise ValueError(
+                'penalty_factors_by_treatment is supported only for logistic models'
+            )
+        if kwargs.get('penalty', 'l2') != 'l2':
+            raise ValueError(
+                'penalty_factors_by_treatment requires logistic penalty="l2"'
+            )
+
+    if isinstance(A, pd.DataFrame):
+        if treatment_names is None:
+            treatment_names = list(A.columns)
+        A_array = A.to_numpy()
+    else:
+        A_array = np.asarray(A)
+    if A_array.ndim == 1:
+        A_array = A_array[:, None]
+    if A_array.ndim != 2 or not np.all(np.isin(A_array, (0, 1))):
+        raise ValueError('A must be a one- or two-dimensional binary matrix')
+    if treatment_names is None:
+        treatment_names = list(range(A_array.shape[1]))
+    treatment_names = list(treatment_names)
+    if len(treatment_names) != A_array.shape[1]:
+        raise ValueError('treatment_names must match the number of treatments')
+    if len(set(treatment_names)) != len(treatment_names):
+        raise ValueError('treatment_names must be unique')
+
+    if isinstance(X_A, pd.DataFrame):
+        if covariate_names is None:
+            covariate_names = list(X_A.columns)
+        X_array = X_A.to_numpy()
+    else:
+        X_array = np.asarray(X_A)
+    if X_array.ndim != 2 or X_array.shape[0] != A_array.shape[0]:
+        raise ValueError('X_A must be two-dimensional with the same rows as A')
+    try:
+        X_array = np.asarray(X_array, dtype=float)
+    except (TypeError, ValueError) as exc:
+        raise ValueError('X_A must contain numeric covariates') from exc
+    if not np.all(np.isfinite(X_array)):
+        raise ValueError('X_A must contain only finite values')
+    if covariate_names is None:
+        covariate_names = [f'covariate_{j + 1}' for j in range(X_array.shape[1])]
+    covariate_names = list(covariate_names)
+    if len(covariate_names) != X_array.shape[1]:
+        raise ValueError('covariate_names must match the number of covariates')
+    if len(set(covariate_names)) != len(covariate_names):
+        raise ValueError('covariate_names must be unique')
+
+    treatment_lookup = {name: j for j, name in enumerate(treatment_names)}
+    covariate_lookup = {name: j for j, name in enumerate(covariate_names)}
+
+    def resolve_treatment(value):
+        if value in treatment_lookup:
+            return treatment_lookup[value]
+        if isinstance(value, (int, np.integer)) and 0 <= int(value) < A_array.shape[1]:
+            return int(value)
+        raise ValueError(f'Unknown treatment: {value}')
+
+    def resolve_covariate(value):
+        if value in covariate_lookup:
+            return covariate_lookup[value]
+        if isinstance(value, (int, np.integer)) and 0 <= int(value) < X_array.shape[1]:
+            return int(value)
+        raise ValueError(f'Unknown covariate: {value}')
+
+    drops = {}
+    for treatment, covariates in drop_by_treatment.items():
+        j = resolve_treatment(treatment)
+        if j in drops:
+            raise ValueError(f'Treatment {treatment_names[j]} is specified more than once')
+        if isinstance(covariates, (str, bytes)):
+            covariates = [covariates]
+        indices = [resolve_covariate(value) for value in covariates]
+        if len(set(indices)) != len(indices):
+            raise ValueError(
+                f'Duplicate dropped covariates for treatment {treatment_names[j]}'
+            )
+        drops[j] = set(indices)
+
+    penalty_factors = {}
+    for treatment, factors in penalty_factors_by_treatment.items():
+        j = resolve_treatment(treatment)
+        if j in penalty_factors:
+            raise ValueError(f'Treatment {treatment_names[j]} is specified more than once')
+        if not isinstance(factors, Mapping):
+            raise ValueError(
+                f'Penalty factors for treatment {treatment_names[j]} must be a mapping'
+            )
+        resolved = {}
+        for covariate, factor in factors.items():
+            k = resolve_covariate(covariate)
+            try:
+                factor = float(factor)
+            except (TypeError, ValueError) as exc:
+                raise ValueError('Penalty factors must be finite numbers at least 1') from exc
+            if not np.isfinite(factor) or factor < 1:
+                raise ValueError('Penalty factors must be finite numbers at least 1')
+            if k in resolved:
+                raise ValueError(
+                    f'Duplicate penalty factors for covariate {covariate_names[k]}'
+                )
+            resolved[k] = factor
+        penalty_factors[j] = resolved
+
+    for j in set(drops).intersection(penalty_factors):
+        conflict = drops[j].intersection(penalty_factors[j])
+        if conflict:
+            names = [covariate_names[k] for k in sorted(conflict)]
+            raise ValueError(
+                f'Covariates cannot be both dropped and penalized for '
+                f'{treatment_names[j]}: {names}'
+            )
+
+    if pi_hat is None:
+        pi_updated = np.empty(A_array.shape, dtype=float)
+        refit_indices = range(A_array.shape[1])
+    else:
+        pi_updated = np.asarray(pi_hat, dtype=float).copy()
+        if pi_updated.shape != A_array.shape:
+            raise ValueError('pi_hat must have the same shape as A')
+        if (not np.all(np.isfinite(pi_updated))
+                or np.any((pi_updated < 0) | (pi_updated > 1))):
+            raise ValueError('pi_hat must contain finite probabilities in [0, 1]')
+        refit_indices = sorted(set(drops).union(penalty_factors))
+
+    mask_array = None
+    if mask is not None:
+        mask_array = np.asarray(mask, dtype=bool)
+        if mask_array.ndim == 1:
+            mask_array = mask_array[:, None]
+        if mask_array.shape != A_array.shape:
+            raise ValueError('Mask must have the same shape as the treatment matrix')
+
+    ctrl = np.sum(A_array, axis=1) == 0
+    rows = []
+    for j in refit_indices:
+        dropped = drops.get(j, set())
+        retained = [k for k in range(X_array.shape[1]) if k not in dropped]
+        if not retained:
+            raise ValueError(
+                f'Filtering removes every covariate for treatment {treatment_names[j]}'
+            )
+        eligible = ctrl | (A_array[:, j] == 1)
+        if mask_array is not None:
+            eligible &= mask_array[:, j]
+        X_treatment = X_array[:, retained].copy()
+        treatment_penalties = penalty_factors.get(j, {})
+        for position, k in enumerate(retained):
+            factor = treatment_penalties.get(k, 1.0)
+            X_treatment[:, position] /= np.sqrt(factor)
+        degenerate = bool(np.all(np.ptp(X_treatment[eligible], axis=0) == 0))
+        if degenerate:
+            warnings.warn(
+                f'The propensity design for treatment {treatment_names[j]} is '
+                'constant after filtering; its scores fall back to a '
+                'class-weighted prevalence and carry no covariate information.',
+                RuntimeWarning, stacklevel=2,
+            )
+        scores = estimate_propensity_scores(
+            A_array[:, [j]], X_treatment, K=K,
+            ps_model=ps_model, mask=eligible[:, None], clip=None,
+            random_state=random_state, verbose=verbose,
+            class_weight=class_weight, **kwargs,
+        )
+        pi_updated[:, j] = scores[:, 0]
+        rows.append({
+            'treatment': treatment_names[j],
+            'dropped_covariates': [covariate_names[k] for k in sorted(dropped)],
+            'retained_covariates': [covariate_names[k] for k in retained],
+            'penalty_factors': {
+                covariate_names[k]: treatment_penalties[k]
+                for k in retained if treatment_penalties.get(k, 1.0) != 1.0
+            },
+            'n_retained': len(retained),
+            'degenerate_design': degenerate,
+            'score_std': float(np.std(scores[eligible, 0])),
+        })
+
+    if clip is not None:
+        lower, upper = _validate_clip(clip)
+        pi_updated = np.clip(pi_updated, lower, upper)
+    report = pd.DataFrame(rows, columns=[
+        'treatment', 'dropped_covariates', 'retained_covariates',
+        'penalty_factors', 'n_retained', 'degenerate_design', 'score_std',
+    ])
+    return pi_updated, report
+
+
 def cross_fitting(
     Y, A, X, X_A, family='poisson', K=1, glm_alpha=1e-4,
     ps_model='logistic', ps_class_weight='balanced',

{causarray-0.0.7 → causarray-0.0.9}/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.9/causarray/__about__.py

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

{causarray-0.0.7 → causarray-0.0.9}/causarray/__init__.py

@@ -11,13 +11,19 @@ __all__ = [
     'fit_glm', 'fit_glm_fast', 'fit_glm_ondisk',
     'reset_random_seeds', 'fit_gcate', 'fit_gcate_batch',
     'estimate_propensity_scores', 'summarize_propensity_scores',
-    'plot_propensity_scores',
+    'plot_propensity_scores', 'refit_propensity_scores',
+    'summarize_treatment_associations', 'plot_treatment_associations',
+    'align_test_mask',
     ]
 
 
 from causarray.DR_learner import LFC, gcate_lfc_batch, LFC_batch  # ATE, SATE, FC
-from causarray.DR_estimation import estimate_propensity_scores
-from causarray.diagnostics import summarize_propensity_scores, plot_propensity_scores
+from causarray.DR_estimation import estimate_propensity_scores, refit_propensity_scores
+from causarray.diagnostics import (
+    summarize_propensity_scores, plot_propensity_scores,
+    summarize_treatment_associations, plot_treatment_associations,
+    align_test_mask,
+)
 from causarray.gcate_glm import fit_glm
 from causarray.nb_glm_fast import fit_glm_fast, fit_glm_ondisk
 from causarray.utils import prep_causarray_data, reset_random_seeds, comp_size_factor