Non-parametric Wilcoxon-based Compound Inference for KK Matching-on-the-Fly Designs
Source:R/inference_all_KK_wilcox_ivwc.R
InferenceAllKKWilcoxIVWC.RdFits a non-parametric, rank-based compound (inverse-variance-weighted, IVWC)
estimator of the treatment effect under a
DesignSeqOneByOne-family KK
matching-on-the-fly design (see
DesignSeqOneByOneKK14). For matched
pairs, the sub-estimate \(\hat\beta_m\) is the Hodges-Lehmann
estimate from a Wilcoxon signed-rank test on the within-pair differences (the
median of the Walsh averages \((d_i+d_j)/2\)); for reservoir (unmatched)
subjects, \(\hat\beta_r\) is the Hodges-Lehmann estimate from a Wilcoxon
rank-sum (Mann-Whitney \(U\)) test on treated-vs-control reservoir responses
(the median of all pairwise differences). The two are combined by classical
inverse-variance weighting,
$$\hat\beta_T = w^* \hat\beta_m + (1-w^*)\, \hat\beta_r, \qquad
w^* = \frac{\widehat{\mathrm{Var}}(\hat\beta_r)}{\widehat{\mathrm{Var}}(\hat\beta_r)
+ \widehat{\mathrm{Var}}(\hat\beta_m)},$$
with variance the standard inverse-variance-pooled form (see
$compute_estimate()'s method-level documentation for the full formula
and fallback behavior when only one sub-estimate is usable). Because it is
built from Hodges-Lehmann/Wilcoxon estimators rather than sample means, this
method is robust to outliers and does not assume a specific parametric
distribution for the response — but it does not currently support censored
survival data or incidence (binary) responses (see $initialize()), and
its jackknife methods all report explicit non-estimability rather than
computing a (statistically unreliable) delete-1 jackknife of the
Hodges-Lehmann functional.
Initialize KK inverse-variance combined Wilcoxon inference
and prepare matched/reservoir rank-based components used by
InferenceAllKKWilcoxIVWC.
Requires des_obj to be a KK matching-on-the-fly-capable design
(des_obj$is_a_kk_matching_capable()); errors otherwise. Also
rejects response_type = "incidence" (a message-and-error
recommends a compound mean-difference or conditional-logistic estimator
instead — rank-based methods are not well suited to binary outcomes)
and rejects censored survival data (recommends a restricted-mean or
Cox-based method instead, since this estimator has no censoring
handling). Legal response_type values are "continuous",
"count", "proportion", "survival" (uncensored
only), and "ordinal".
Returns the estimated treatment effect: an inverse-variance-weighted compound (IVWC) of two Hodges-Lehmann median-shift estimates.
Computes a \(1-\alpha\) level confidence interval for the
compound Hodges-Lehmann treatment effect estimator. Although each
sub-estimate is itself derived from a non-parametric rank test, the
inverse-variance-weighted combination \(\hat\beta_T\) (see
$compute_estimate() for the full formula) is treated as
asymptotically normal, so the interval is
\(\hat\beta_T \pm z_{1-\alpha/2}\sqrt{\widehat{\mathrm{Var}}(\hat\beta_T)}\)
(or a \(t\)-based critical value, depending on
private$compute_z_or_t_ci_from_s_and_df's degrees-of-freedom
resolution).
Compute the KK Wilcoxon compound two-sided p-value testing
\(H_0: \beta_T = \code{delta}\), from the same asymptotically-normal
compound estimate/variance (\(z = (\hat\beta_T -
\code{delta})/\widehat{\mathrm{SE}}(\hat\beta_T)\)) that
$compute_asymp_confidence_interval() inverts to form its
interval — see that method's documentation, and
$compute_estimate(), for the compound Hodges-Lehmann estimator's
full formula. Only delta = 0 is currently supported: a non-zero
null shift raises an error (when assertions are enabled) rather than
testing it, because the underlying Wilcoxon tests' null-shift handling
has not been extended to the compound combined estimator. See related
simple Wilcoxon behavior in
InferenceAllSimpleWilcox.
Reports the jackknife point-estimate as explicitly
non-estimable for this compound Hodges-Lehmann estimator, rather than
computing a leave-one-out jackknife. Deletion-based (jackknife)
resampling of a Hodges-Lehmann/Wilcoxon-derived statistic is known to
behave poorly — the median-of-Walsh-averages functional is not smooth
enough for the delete-1 jackknife's linear-approximation machinery to
be reliable at the small matched-pair/reservoir sample sizes typical of
KK designs, and combining two already-jackknife-unstable sub-estimates
compounds the problem. This method exists purely to record that
unavailability (via private$cache_nonestimable_estimate()) rather
than silently returning a misleading number; see
InferenceJackknife for the shared
jackknife contract this method participates in.
Reports the jackknife bias-correction estimate as
non-estimable for this Wilcoxon compound estimator, for the same
reason as $compute_jackknife_estimate() (the Hodges-Lehmann
functional is not smooth enough for the delete-1 jackknife); see
InferenceJackknife for the shared
jackknife contract.
Reports the jackknife standard error as non-estimable for
this Wilcoxon compound estimator, for the same reason as
$compute_jackknife_estimate(); see
InferenceJackknife for the shared
jackknife contract.
Reports the jackknife-Wald p-value as non-estimable here,
for the same reason as $compute_jackknife_estimate(); see
InferenceJackknife.
Reports the jackknife-Wald confidence interval as
non-estimable here, for the same reason as
$compute_jackknife_estimate(); see
InferenceJackknife.
Details
For matched pairs, \(\hat\beta_m\) is the Hodges-Lehmann
estimate from a Wilcoxon signed-rank test on the within-pair
differences (stats::wilcox.test(diffs, conf.int = TRUE)'s
estimate, the median of the Walsh averages
\((d_i + d_j)/2\)), with normal-model calibrated variance
\((2\pi/3)\operatorname{Var}(\text{Walsh})/m\). For
reservoir (unmatched) subjects, \(\hat\beta_r\) is the
Hodges-Lehmann estimate from a Wilcoxon rank-sum test between
treated and control reservoir responses (median of all pairwise
differences \(y_{T,i} - y_{C,j}\)), with normal-model calibrated
variance \(\pi\operatorname{Var}(Y_T-Y_C)(n_T+n_C)/(6n_Tn_C)\).
When both sub-estimates
are usable, the compound estimate is the inverse-variance-weighted
combination
$$\hat\beta_T = w^* \hat\beta_m + (1-w^*)\, \hat\beta_r, \qquad
w^* = \frac{\widehat{\mathrm{Var}}(\hat\beta_r)}{\widehat{\mathrm{Var}}(\hat\beta_r)
+ \widehat{\mathrm{Var}}(\hat\beta_m)},$$
with combined variance \(\widehat{\mathrm{Var}}(\hat\beta_r)\,
\widehat{\mathrm{Var}}(\hat\beta_m) / (\widehat{\mathrm{Var}}(\hat\beta_r) +
\widehat{\mathrm{Var}}(\hat\beta_m))\) — the same combination scheme as
InferenceAllKKMeanDiffIVWC,
but applied to rank-based rather than mean-based sub-estimates. If
only one sub-estimate is usable (e.g. no matched pairs, or a degenerate
reservoir), \(\hat\beta_T\) falls back to that sub-estimate alone.
References
Hodges, J. L., and Lehmann, E. L. (1963). "Estimates of Location Based on Rank Tests." The Annals of Mathematical Statistics, 34(2), 598-611, doi:10.1214/aoms/1177704172 , for the Hodges-Lehmann estimator underlying both sub-estimates; Kapelner, A., and Krieger, A. M. (2014). "Matching on-the-fly: Sequential allocation with higher power and efficiency." Biometrics, 70(2), 378-388, doi:10.1111/biom.12148 , for the KK matching-on-the-fly design and the inverse-variance combination of matched-pair and reservoir estimates.
Legacy class. Not fully tested in comprehensive_tests.R.
Super class
Inference -> InferenceAllKKWilcoxIVWC
Methods
Public methods
+ inherited public methods from Inference
Inference$capabilities()Inference$compute_exact_confidence_interval()Inference$compute_exact_two_sided_pval_for_treatment_effect()Inference$duplicate()Inference$get_analysis_data()Inference$get_covariates()Inference$get_design_object()Inference$get_model_formula()Inference$get_nonestimable_reason()Inference$get_nonestimable_stage()Inference$get_optimization_alg()Inference$get_response()Inference$get_response_type()Inference$get_treatment()Inference$is_nonestimable()Inference$set_optimization_alg()Inference$set_seed()Inference$supports()
InferenceAllKKWilcoxIVWC$new()
Usage
InferenceAllKKWilcoxIVWC$new(
des_obj,
model_formula = NULL,
verbose = FALSE,
smart_cold_start_default = NULL
)Arguments
des_objA DesignSeqOneByOne object (must be a KK design).
model_formulaOptional formula for covariate adjustment. If
NULL(default), the formula from the design object is used and its pre-computed design matrix is reused. If a formula is provided, a new design matrix is constructed from the design's imputed covariates.verboseWhether to print progress messages.
smart_cold_start_defaultWhether to use smart cold start values.
InferenceAllKKWilcoxIVWC$compute_jackknife_wald_two_sided_pval()
Arguments
deltaThe null difference to test against. For any treatment effect at all this is set to zero (the default).
deltaNull treatment-effect value. Default 0.
unitDeletion unit. Default
"auto".unitDeletion unit. Default
"auto".unitDeletion unit. Default
"auto".unitDeletion unit. Default
"auto".unitDeletion unit. Default
"auto".
InferenceAllKKWilcoxIVWC$compute_jackknife_wald_confidence_interval()
Usage
InferenceAllKKWilcoxIVWC$compute_jackknife_wald_confidence_interval(
alpha = 0.05,
unit = "auto"
)Arguments
alphaThe confidence level in the computed confidence interval is 1 -
alpha. The default is 0.05.alphaSignificance level. Default 0.05.
unitDeletion unit. Default
"auto".unitDeletion unit. Default
"auto".unitDeletion unit. Default
"auto".unitDeletion unit. Default
"auto".unitDeletion unit. Default
"auto".
Examples
# \donttest{
seq_des = DesignSeqOneByOneKK14$new(n = 10, response_type = 'continuous')
for (i in 1:10) {
seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1), x2 = rnorm(1)))
}
seq_des$add_all_subject_responses(rnorm(10))
inf = InferenceAllKKWilcoxIVWC$new(seq_des)
inf$compute_estimate()
#> [1] 0.01333035
# }