Clayton Copula / Standard Weibull Compound Inference for KK Designs

This class implements a compound estimator for KK matching-on-the-fly designs with survival responses using a Clayton copula with Weibull AFT margins for matched pairs and a standard Weibull AFT model for the reservoir. The two treatment-effect estimates (on the log-time ratio scale) are combined by inverse-variance weighting.

Computes the randomization distribution of the treatment effect estimate under the sharp null.

Whether compute_rand_two_sided_pval() is actually usable on this instance right now – FALSE exactly when it would stop(): an incidence-response instance with no custom randomization statistic and a design not eligible for design-randomization-based incidence inference (see private$should_use_design_randomization_for_incidence()). TRUE for every other case, including every non-incidence response type. Public, self-contained (only reads already-set instance state, no side effects), so InferenceSuite can check this before attempting the sentinel instead of relying on the stop() being silently swallowed into a pval = NA "ok" row – the single source of truth for both this check and compute_rand_two_sided_pval()'s own guard, so the two can never drift apart.

Computes a randomization-based p-value.

Value

When debug = FALSE (default), a numeric vector of length r. When debug = TRUE, a list with: values, errors (list of character vectors, one per iteration), warnings (list of character vectors, one per iteration), num_errors, num_warnings, prop_iterations_with_errors, prop_iterations_with_warnings, and prop_illegal_values.

A single logical.

Randomization p-value.

Details

Frailty distribution. The Clayton copula for a matched pair, S(t1,t2) = (S1(t1)^-theta + S2(t2)^-theta - 1)^(-1/theta) with Weibull margins S_i, is exactly the closed-form bivariate survival function obtained by multiplying two conditionally-independent Weibull hazards by a shared gamma frailty term Z ~ Gamma(1/theta, 1/theta) and integrating Z out analytically (Clayton 1978; Oakes 1989); theta is the frailty variance / dependence parameter (see ClaytonWeibullLikelihood in fast_survival_models_optim.cpp, which builds the likelihood from the per-subject Weibull cumulative hazards H1, H2). This is the classic textbook Weibull-gamma shared-frailty model, fit here in its closed form (no numerical integration required) rather than as an AFT Gaussian-random-intercept model.

This is a different (and equally standard) frailty assumption from the log-normal-frailty Weibull AFT GLMM implemented by InferenceSurvivalGLMMWeibullFrailtyNormalIVWC / InferenceSurvivalGLMMWeibullFrailtyNormalOneLik, which instead places a Gaussian random intercept on the log-time (AFT) scale and integrates it out by Gauss-Hermite quadrature. Prefer this Clayton-copula class for the classic gamma-frailty / proportional-hazards dependence structure; prefer the Weibull-frailty class for a Gaussian-random-intercept / GLMM-style dependence structure.

References

Clayton DG (1978). "A Model for Association in Bivariate Life Tables and Its Application in Epidemiological Studies of Familial Tendency in Chronic Disease Incidence." Biometrika, 65(1), 141-151. doi:10.2307/2335289

Oakes D (1989). "Bivariate Survival Models Induced by Frailties." Journal of the American Statistical Association, 84(406), 487-493. doi:10.2307/2289934

Legacy class. Not fully tested in comprehensive_tests.R.

See also

InferenceSurvivalGLMMWeibullFrailtyNormalIVWC for the corresponding log-normal-frailty IVWC estimator.

Super class

Inference -> InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC

Methods

Public methods

• InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$approximate_randomization_distribution_beta_hat_T()

• InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$supports_rand_pval_for_incidence()

• InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$compute_rand_two_sided_pval()

• InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$clone()

+ inherited public methods from Inference

• Inference$capabilities()
• Inference$compute_asymp_confidence_interval()
• Inference$compute_asymp_two_sided_pval()
• Inference$compute_estimate()
• 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$initialize()
• Inference$is_nonestimable()
• Inference$set_optimization_alg()
• Inference$set_seed()
• Inference$supports()

---

InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$approximate_randomization_distribution_beta_hat_T()

Usage

InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$approximate_randomization_distribution_beta_hat_T(
  r = 501,
  delta = 0,
  transform_responses = "none",
  show_progress = TRUE,
  permutations = NULL,
  debug = FALSE,
  zero_one_logit_clamp = .Machine$double.eps
)

Arguments

r

Number of randomization vectors. Default 501.

r

Number of randomization vectors.

delta

The null difference. Default 0.

delta

Null difference.

transform_responses

Type of transformation. Default "none".

transform_responses

Transformation.

show_progress

Show progress bar. Default TRUE.

show_progress

Show progress.

permutations

Pre-computed permutations. Default NULL.

permutations

Pre-computed permutations.

debug

If TRUE, return a list with the distribution values and per-iteration diagnostics including error messages, warning messages, counts of each, and summary proportions for iterations with errors, warnings, and illegal (non-finite) values. Runs serially. Default FALSE.

zero_one_logit_clamp

The clamping amount for exact 0 and 1 values when logging

zero_one_logit_clamp

The clamping amount for exact 0 and 1 values when logging

---

InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$supports_rand_pval_for_incidence()

Usage

InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$supports_rand_pval_for_incidence(

)

---

InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$compute_rand_two_sided_pval()

Usage

InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$compute_rand_two_sided_pval(
  r = 501,
  delta = 0,
  transform_responses = "none",
  na.rm = TRUE,
  show_progress = TRUE,
  permutations = NULL,
  zero_one_logit_clamp = .Machine$double.eps
)

Arguments

r

Number of randomization vectors. Default 501.

r

Number of randomization vectors.

delta

The null difference. Default 0.

delta

Null difference.

transform_responses

Type of transformation. Default "none".

transform_responses

Transformation.

na.rm

Remove NAs.

show_progress

Show progress bar. Default TRUE.

show_progress

Show progress.

permutations

Pre-computed permutations. Default NULL.

permutations

Pre-computed permutations.

zero_one_logit_clamp

The clamping amount for exact 0 and 1 values when logging

zero_one_logit_clamp

The clamping amount for exact 0 and 1 values when logging

---

InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$clone()

The objects of this class are cloneable with this method.

Usage

InferenceSurvivalGLMMWeibullFrailtyLoggammaIVWC$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.