Compute realized informativeness from data or a sampling-variance vector

Compute the realized informativeness scalar \(\widehat{I} = \sigma_\tau^2 / (\sigma_\tau^2 + \mathrm{GM}(\widehat{se}_j^2))\), where \(\mathrm{GM}\) is the geometric mean across sites. Group A diagnostic (precision and feasibility — Dr. Chen's question 1: "Is the design precise enough at the site level for the between-site signal to be recoverable?"). informativeness() is the user-facing S3 wrapper around compute_I.

Usage

informativeness(x, ...)

Arguments

x

A multisitedgp_data object (data method) or a positive numeric se2_j vector (numeric method).

...

Method-specific named arguments. The numeric method requires sigma_tau (numeric scalar \(\ge 0\), between-site SD on the response scale; the diagnostic is scale-aware and cannot be computed from sampling variances alone). The data method reads sigma_tau from the attached design and ignores any explicit value here. The numeric method also accepts tau_j for signature compatibility; it is not used in the computation. All other ... are forwarded to compute_I.

Value

A scalar double in [0, 1). Returns 0 exactly when sigma_tau = 0.

Details

\(\widehat{I}\) reads as the shrinkage at a representative (geometric-mean-precision) site: \(\widehat{I} \to 1\) means site-level estimates dominate the prior; \(\widehat{I} \to 0\) means the prior dominates and site-specific identification is weak. Under the direct-precision path with a deterministic \(\widehat{se}_j^2\) grid, \(\widehat{I}\) matches the design target exactly; under the site-size-driven path or any custom se_fn, the realized value is what the simulation produces.

Method dispatch. The multisitedgp_data method reads sigma_tau from attr(x, "design")$sigma_tau and forwards x$se2_j (and x$tau_j, kept for signature compatibility) to compute_I. The numeric method requires an explicit sigma_tau argument and treats x as the \(\widehat{se}_j^2\) vector. The default method errors with a hint pointing to either entry.

For the full Group A/B/C/D diagnostic workflow 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_I for the underlying scalar formula; compute_shrinkage for the per-site \(S_j\) the geometric mean aggregates; compute_kappa for the precision constant on the site-size-driven path; heterogeneity_ratio for the Group A companion diagnostic \(R\); feasibility_index for the additive feasibility variants; the A3 · Diagnostics in practice vignette.

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

Examples

# Data method: sigma_tau is read from the attached design.
dat <- sim_multisite(J = 10L, seed = 1L)
informativeness(dat)
#> [1] 0.3355902

# Numeric method: sigma_tau must be supplied explicitly.
informativeness(dat$se2_j, sigma_tau = 0.20)
#> [1] 0.3355902

# Compare realized I against the design target.
attr(dat, "design")$sigma_tau
#> [1] 0.2