fit_copula_OrdOrd: Fit ordinal-ordinal vine copula model

In Surrogate: Evaluation of Surrogate Endpoints in Clinical Trials

Fit ordinal-ordinal vine copula model

Description

fit_copula_OrdOrd() fits the ordinal-ordinal vine copula model. See Details for more information about this model.

Usage

fit_copula_OrdOrd(
  data,
  copula_family,
  K_S,
  K_T,
  start_copula,
  method = "BFGS",
  ...
)

Arguments

data	data frame with three columns in the following order: surrogate endpoint, true endpoint, and treatment indicator (0/1 coding). Ordinal endpoints should be integers starting from 1.
copula_family	One of the following parametric copula families: "clayton", "frank", "gaussian", or "gumbel". The first element in copula_family corresponds to the control group, the second to the experimental group.
K_S, K_T	Number of categories in the surrogate and true endpoints.
start_copula	Starting value for the copula parameter.
method	Optimization algorithm for maximizing the objective function. For all options, see ?maxLik::maxLik. Defaults to "BFGS".
...	Extra argument to pass onto maxLik::maxLik

Details

Vine Copula Model for Ordinal Endpoints

Following the Neyman-Rubin potential outcomes framework, we assume that each patient has four potential outcomes, two for each arm, represented by \boldsymbol{Y} = (T_0, S_0, S_1, T_1)'. Here, \boldsymbol{Y_z} = (S_z, T_z)' are the potential surrogate and true endpoints under treatment Z = z.

The latent variable notation and D-vine copula model for \boldsymbol{Y} is a straightforward extension of the notation in ordinal_continuous_loglik().

Observed-Data Likelihood

In practice, we only observe (S_0, T_0)' or (S_1, T_1)'. Hence, to estimate the (identifiable) parameters of the D-vine copula model, we need to derive the observed-data likelihood. The observed-data loglikelihood for (S_z, T_z)' is as follows:

f_{\boldsymbol{Y_z}}(s, t; \boldsymbol{\beta}) = P \left( c^{S_z}_{s - 1} < \tilde{S}_z, c^{T_z}_{t - 1} < \tilde{T}_z \right) - P \left( c^{S_z}_{s} < \tilde{S}_z, c^{T_z}_{t - 1} < \tilde{T}_z \right) - P \left( c^{S_z}_{s - 1} < \tilde{S}_z, c^{T_z}_{t} < \tilde{T}_z \right) + P \left( c^{S_z}_{s} < \tilde{S}_z, c^{T_z}_{t} < \tilde{T}_z \right).

The above expression is used in ordinal_ordinal_loglik() to compute the loglikelihood for the observed values for Z = 0 or Z = 1.

Value

Returns an S3 object that can be used to perform the sensitivity analysis with sensitivity_analysis_copula().

Author(s)

Florian Stijven

See Also

sensitivity_analysis_copula(), print.vine_copula_fit(), plot.vine_copula_fit()

Surrogate documentation built on June 8, 2025, 1:09 p.m.