B-spline copula using the five M-spline basis functions

Description

spline.copula computes the B-spline copula (or its density) based on the five-parameter M-spline basis functions. This copula is a specific instance of the B-spline copula family and can be implemented using matrix-based operations with M.spline and I.spline from the joint.Cox package.

Usage

spline.copula(
  u,
  v,
  R = "PE1",
  mat = FALSE,
  density = FALSE,
  Kendall = FALSE,
  Spearman = FALSE
)

Arguments

Details

If density = TRUE, the function computes the copula density c(u, v); otherwise, it returns the copula distribution function C(u, v). If density = FALSE, it returns the copula function. The implementation uses five M-spline or I-spline basis functions defined on [0,1]. The coefficient matrix is fixed internally but can be modified in advanced use.

Value

If both Kendall = FALSE and Spearman = FALSE (default), returns:

• A numeric vector of length length(u) if mat = FALSE.

• A numeric matrix of size length(u) \times length(v) if mat = TRUE.

If Kendall = TRUE or Spearman = TRUE, returns a list containing:

• value: A numeric vector or matrix representing the evaluated copula function or copula density.

• Kendall_tau: (Optional) Kendall’s tau, included only if Kendall = TRUE.

• Spearman_rho: (Optional) Spearman’s rho, included only if Spearman = TRUE.

See Also

M.spline, I.spline

Examples

N <- 50
u <- v <- seq(from = 0, to = 1, length.out = N)
U <- rep(u, N)
V <- rep(v, each = N)

c.data <- data.frame(
  U = U,
  V = V,
  C = spline.copula(U, V, R = "PE1", density = TRUE)
)

if (requireNamespace("ggplot2", quietly = TRUE)) {
  ggplot2::ggplot(c.data, ggplot2::aes(x = U, y = V)) +
    ggplot2::geom_contour(
      ggplot2::aes(z = C, colour = ggplot2::after_stat(level)),
      bins = 25
    ) +
    ggplot2::xlab("u") + ggplot2::ylab("v")
}

Random generation from the B-spline copula using five M-spline basis functions

Description

spline.copula.simu generates random samples (U, V) from the B-spline copula defined by a 5×5 coefficient matrix R. The simulation uses the inverse transform method based on the conditional distribution V \mid U=u.

Usage

spline.copula.simu(
  n,
  R = "PE1",
  seed = NULL,
  report_tau = TRUE,
  report_rho = TRUE,
  verbose = FALSE
)

Arguments

Details

Given U \sim \mathrm{Uniform}(0,1), the conditional distribution function of V \mid U = u is

F_{V\mid U=u}(v) = M(u)^\top R I(v),

where M(\cdot) and I(\cdot) are the five M-spline and I-spline basis vectors. For each u, a draw V is obtained by solving F_{V\mid U=u}(v)=W for v, where W\sim U(0,1).

If report_tau = TRUE, the function also returns:

• tau_emp: empirical Kendall's tau of the simulated values;

• tau_theory: theoretical Kendall's tau computed using spline.copula with Kendall = TRUE.

If report_rho = TRUE, the function also returns:

• rho_emp: empirical Spearman's rho of the simulated values;

• rho_theory: theoretical Spearman's rho computed using spline.copula with Spearman = TRUE.

Value

A list containing:

• U: simulated U-values;

• V: simulated V-values;

• R: user-specified R (preset name or matrix).

If report_tau = TRUE, the list also returns:

• tau_emp: empirical Kendall's tau;

• tau_theory: theoretical Kendall's tau.

If report_rho = TRUE, the list also returns:

• rho_emp: empirical Spearman's rho;

• rho_theory: theoretical Spearman's rho.

Examples

set.seed(123)
out <- spline.copula.simu(2000, R = "PE1",
                          report_tau = TRUE,
                          report_rho = TRUE)
out$tau_emp
out$tau_theory
out$rho_emp
out$rho_theory

Fitting the five-parameter spline Cox model giving a specified shape

Description

splineCox.reg1 estimates the parameters of a five-parameter spline Cox model based on a specified shape for the baseline hazard function. The function calculates the estimates for the model parameters (beta) and the baseline hazard scale parameter (gamma), using non-linear optimization. If a numeric vector is provided for the model parameter, it will be normalized to have an L1 norm of 1. Additionally, if plot = TRUE, the function generates a plot of the estimated baseline hazard function with 95% confidence intervals. The x-axis represents time, and the y-axis represents the estimated hazard. The solid line indicates the estimated hazard function, while the dashed red lines represent the confidence intervals.

Usage

splineCox.reg1(
  t.event,
  event,
  Z,
  xi1 = min(t.event),
  xi3 = max(t.event),
  model = "constant",
  p0 = rep(0, 1 + ncol(as.matrix(Z))),
  plot = TRUE
)

Arguments

Value

A list containing the following components:

• model: A shape of the baseline hazard function or the normalized custom numeric vector used.

• parameter: A numeric vector of the parameters defining the baseline hazard shape.

• beta: A named vector with the estimates, standard errors, and 95\

• gamma: A named vector with the estimate, standard error, and 95\

• loglik: A named vector containing the log-likelihood (LogLikelihood), Akaike Information Criterion (AIC), and Bayesian Information Criterion (BIC).

• plot: A baseline hazard function plot (if plot = TRUE).

References

Teranishi, R.; Furukawa, K.; Emura, T. (2025). A Two-Stage Estimation Approach to Cox Regression Under the Five-Parameter Spline Model Mathematics 13(4), 616. doi:10.3390/math13040616 Available at https://www.mdpi.com/2227-7390/13/4/616

Examples

# Example data
library(joint.Cox)
data(dataOvarian)
t.event = dataOvarian$t.event
event = dataOvarian$event
Z = dataOvarian$CXCL12

reg1 <- splineCox.reg1(t.event, event, Z, model = "constant")
print(reg1)

Fitting the five-parameter spline Cox model with a specified shape, selecting the best fit

Description

splineCox.reg2 estimates the parameters of a five-parameter spline Cox model for multiple specified shapes and selects the best-fitting model based on the maximization of the log-likelihood function. This function supports predefined model shapes and custom numeric vectors of length 5. If numeric vectors are provided, they will be normalized to have an L1 norm of 1. Additionally, if plot = TRUE, the function generates a plot of the estimated baseline hazard function for the best-fitting model, along with its 95% confidence intervals. The x-axis represents time, and the y-axis represents the estimated hazard. The solid line indicates the estimated hazard function, while the dashed red lines represent the confidence intervals.

Usage

splineCox.reg2(
  t.event,
  event,
  Z,
  xi1 = min(t.event),
  xi3 = max(t.event),
  model = names(shape.list),
  p0 = rep(0, 1 + ncol(as.matrix(Z))),
  plot = TRUE
)

Arguments

Value

A list containing the following components:

• model: A character string indicating the shape of the baseline hazard function used.

• parameter: A numeric vector of the parameters defining the baseline hazard shape.

• beta: A named vector with the estimates, standard errors, and 95\

• gamma: A named vector with the estimate, standard error, and 95\

• loglik: A named vector containing the log-likelihood (LogLikelihood), Akaike Information Criterion (AIC), and Bayesian Information Criterion (BIC) for the best-fitting model.

• other_models: A data frame containing the log-likelihood (LogLikelihood) for all other evaluated models, with model names as row names.

• plot: A baseline hazard function plot for the best-fitting model (if plot = TRUE).

References

Teranishi, R.; Furukawa, K.; Emura, T. (2025). A Two-Stage Estimation Approach to Cox Regression Under the Five-Parameter Spline Model Mathematics 13(4), 616. doi:10.3390/math13040616 Available at https://www.mdpi.com/2227-7390/13/4/616

Examples

# Example data
library(joint.Cox)
data(dataOvarian)
t.event = dataOvarian$t.event
event = dataOvarian$event
Z = dataOvarian$CXCL12

M = c("constant", "increase", "decrease")
reg2 <- splineCox.reg2(t.event, event, Z, model = M)
print(reg2)