One-Likelihood Clayton-Copula Weibull AFT Inference for KK Survival Designs

Estimates a treatment log-time-ratio \(\beta_T\) for right-censored survival outcomes collected under a KK matching-on-the-fly design (DesignSeqOneByOneKK14 or subclass) by maximizing a single combined likelihood: matched-pair survival times are modeled with a Weibull accelerated-failure-time (AFT) margin joined by a Clayton copula (dependence parameter \(\theta\)) to account for within-pair correlation induced by shared matching covariates, while unmatched reservoir subjects are modeled by the same Weibull AFT margin marginally (no dependence term). All subjects share one treatment coefficient, estimated jointly.

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

Estimand. \(\beta_T\), the treatment coefficient of a Weibull AFT model \(\log T = \beta_0 + \beta_T W + X\beta + \sigma\epsilon\) with \(\epsilon\) extreme-value-distributed; \(\exp(\hat\beta_T)\) is the treatment-vs-control survival-time ratio (an acceleration factor). This is a distinct scale from the log hazard ratio reported by Cox-based KK survival classes.

Model. .fit_clayton_weibull_aft() jointly optimizes the AFT regression coefficients, the Weibull shape (\(\log\sigma\)), and the Clayton copula dependence parameter (\(\log\theta\)) by direct maximum likelihood over the combined matched-pair-copula / reservoir-marginal log-likelihood; right-censoring enters as the usual survival contribution (density for observed failures, survival function for censored times). likelihood_tier = "full", so a parametric likelihood bootstrap (simulate_under_lik_null, which draws new pair times from the fitted Clayton copula and new singleton times from the marginal Weibull) is available alongside Wald inference.

Assumptions. Weibull AFT margin correctly specified; Clayton copula correctly captures within-pair dependence (a positive-dependence, single-parameter Archimedean copula); independent censoring given covariates; a KK matching-on-the-fly design supplying the matched/ reservoir partition.

References

Clayton, D. G. (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.1093/biomet/65.1.141 . (Clayton1978 in REFERENCES.md.)

Oakes, D. (1989). "Bivariate survival models induced by frailties." Journal of the American Statistical Association, 84(406), 487-493. doi:10.1080/01621459.1989.10478795 . (Oakes1989 in REFERENCES.md.)

See also

Analogous Python API for AFT/copula survival models: lifelines WeibullAFTFitter, copulas. Copula (probability theory) (orientation).

Super class

Inference -> InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik

Methods

Public methods

• InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$approximate_randomization_distribution_beta_hat_T()

• InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$supports_rand_pval_for_incidence()

• InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$compute_rand_two_sided_pval()

• InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$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()

---

InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$approximate_randomization_distribution_beta_hat_T()

Usage

InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$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

---

InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$supports_rand_pval_for_incidence()

Usage

InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$supports_rand_pval_for_incidence(

)

---

InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$compute_rand_two_sided_pval()

Usage

InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$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

---

InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$clone()

The objects of this class are cloneable with this method.

Usage

InferenceSurvivalGLMMWeibullFrailtyLoggammaOneLik$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.