Compute the additive feasibility index (Efron or Morris)

Compute one of two additive feasibility statistics built on the per-site shrinkage \(S_j = \sigma_\tau^2 / (\sigma_\tau^2 + \widehat{se}_j^2)\): the Efron form \(\sum_{j=1}^{J} S_j\) (total effective information; default) or the Morris form \(\sum_{j=1}^{J} (1 - S_j)\) (total residual variation). Group A diagnostic (top-of-funnel feasibility — Dr. Chen's question 1: "Is there enough effective site-level information for partial pooling to do real work?"). Run this before committing a long simulation to disk.

Usage

feasibility_index(
  se2_j,
  sigma_tau = NULL,
  kind = c("efron", "morris"),
  warn = TRUE
)

Arguments

se2_j

A positive numeric \(\widehat{se}_j^2\) vector, or a multisitedgp_data object whose se2_j column will be used.

sigma_tau

Numeric scalar (\(\ge 0\)). Between-site SD. Required when se2_j is numeric; optional when se2_j is a data object (auto-read from the attached design when NULL). Default NULL.

kind

Character. Feasibility convention. "efron" (default) returns \(\sum_j S_j\); "morris" returns \(\sum_j (1 - S_j)\).

warn

Logical. If TRUE (default), emit a warning when the Efron statistic lands in the FAIL band defined by default_thresholds()$feasibility_min. Ignored for kind = "morris".

Value

A scalar double. For "efron", in [0, J]. For "morris", in [0, J] complementary.

Details

Two conventions. kind = "efron" returns \(\sum_j S_j\), interpretable as "the equivalent number of perfectly-informative sites": a design with \(J = 50\) and \(\sum_j S_j = 8\) has the effective information of about eight noise-free sites. kind = "morris" returns \(\sum_j (1 - S_j)\), the residual-variation form used in Morris-style empirical-Bayes diagnostics. The two are linked by \(\sum_j S_j + \sum_j (1 - S_j) = J\).

Reading guide. The canonical quality gate is the Efron form \(\sum_j S_j \ge 5\) (see default_thresholds()$feasibility_min = 5.0). Designs that fall below this threshold are unlikely to support partial-pooling estimators well — heterogeneity cannot be reliably recovered from the available site-level information. With warn = TRUE (default), the function emits a warning when the Efron statistic crosses into the FAIL band.

Method dispatch. When se2_j is a multisitedgp_data object, sigma_tau is auto-read from attr(se2_j, "design")$sigma_tau if not supplied; the function then operates on se2_j$se2_j. When se2_j is a bare numeric vector, sigma_tau is required.

For how feasibility interacts with the other Group A/B/C/D gates see the A3 · Diagnostics in practice vignette.

References

Lee, J., Che, J., Rabe-Hesketh, S., Feller, A., & Miratrix, L. (2025). Improving the estimation of site-specific effects and their distribution in multisite trials. Journal of Educational and Behavioral Statistics, 50(5), 731–764. doi:10.3102/10769986241254286 .

See also

compute_shrinkage for the per-site \(S_j\) the index sums; informativeness for the geometric-mean Group A companion; mean_shrinkage for the Group D mean of \(S_j\); default_thresholds for the feasibility_min gate; scenario_audit for the audit pipeline; the A3 · Diagnostics in practice vignette.

Other family-diagnostics: bhattacharyya_coef(), compute_I(), compute_kappa(), compute_shrinkage(), default_thresholds(), heterogeneity_ratio(), informativeness(), ks_distance(), mean_shrinkage(), realized_rank_corr(), realized_rank_corr_marginal(), scenario_audit()

Examples

dat <- sim_multisite(J = 10L, seed = 1L)

# Efron form (default): sum of S_j; equivalent number of perfectly
# informative sites.
feasibility_index(dat, warn = FALSE)
#> [1] 3.453587

# Morris form: sum of (1 - S_j); total residual variation.
feasibility_index(dat, kind = "morris", warn = FALSE)
#> [1] 6.546413

# The two conventions sum to J.
feasibility_index(dat, kind = "efron", warn = FALSE) +
  feasibility_index(dat, kind = "morris", warn = FALSE)
#> [1] 10

# Numeric path: pass se2_j and sigma_tau directly.
feasibility_index(dat$se2_j, sigma_tau = 0.20, warn = FALSE)
#> [1] 3.453587