AdPaikModel {TimeDepFrail}R Documentation

Adapted Paik et Al.'s Model: Time-Dependent Shared Frailty Cox Model

Description

Function for applying the 'Adapted Paik et al.'s Model', a Cox Model with time-dependent frailty, shared by individuals belonging to the same group/cluster.

To generate time-dependence, the temporal domain is divided into a certain number of intervals. The model log-likelihood function depends on a certain number of parameters and is maximized with respect to all of them, using a reinterpretation of the 'Powell's method in multidimension', that is a multi-dimensional optimization method based on repeated one-dimensional optimization of the log-likelihood function (with respect to one parameter at the time). In this context, the one-dimensional optimization is performed through the 'optimize' R function. For more information about the unknown model parameters, their type and numerosity refer to Details.

Several quantities are estimated at the end of the optimization phase, such as optimal parameters, baseline hazard, frailty dispersion (standard deviation and variance), posterior frailty estimates, with their variance and confidence interval, conditional survival function, Akaike Information Criterion (AIC), ...

Usage

AdPaikModel(
  formula,
  data,
  time_axis,
  categories_range_min,
  categories_range_max,
  n_extrarun = 60,
  tol_ll = 1e-06,
  tol_optimize = 1e-06,
  h_dd = 0.001,
  verbose = FALSE,
  print_previous_ll_values = c(TRUE, 3)
)

Arguments

formula

Formula object having on the left hand side the time-to-event variable, that is the time-instant in which the individual failed. On the right hand side, it has the regressors and the cluster variable.

data

Dataset in which all variables of the formula object must be found and contained. This dataset can also contain other variables, but they will not be considered. It can be either a dataframe or a matrix, but in both cases the name of each column must correspond to the name of the formula variables. It is not necessary to attach it (in case of a data.frame)

time_axis

Temporal domain

categories_range_min

Vector containing the minimum value assumable by each parameter category.

categories_range_max

Vector containing the maximum value assumable by each parameter category.

n_extrarun

Total number of runs (iterations) are obtained summing to the number of parameters and n_extrarun.

tol_ll

Tolerance on the log-likelihood value.

tol_optimize

Internal tolerance for the one-dimensional optimization through 'optimize' R function.

h_dd

Discretization step used for the numerical approximation of the second derivative of the log-likelihood function.

verbose

Logical. If TRUE, detailed progress messages will be printed to the console. Defaults to FALSE.

print_previous_ll_values

If we want to print the previous values of the log-likelihood function. This can be useful for controlling that the optimization procedure is proceeding in a monotone way and it does not oscillate. This argument is composed of two elements: TRUE/FALSE if we want or not to print the previous values and how many values we want to print on the console. Default is (TRUE, 3), so that only the previous 3 values of the log-likelihood are printed.

Details

Two observation needs to made about the time-domain:

The parameters with respect to which the log-likelihood function must be optimized are:

The output of the model call 'AdPaikModel(...)' is a S3 object of class 'AdPaik', composed of the following quantities:

Value

S3 object of class 'AdPaik', composed of several elements. See Details.

Examples

# Consider the 'Academic Dropout dataset'
data(data_dropout)

# Define the variables needed for the model execution
formula <- time_to_event ~ Gender + CFUP + cluster(group)
time_axis <- c(1.0, 1.4, 1.8, 2.3, 3.1, 3.8, 4.3, 5.0, 5.5, 5.8, 6.0)
eps <- 1e-10
categories_range_min <- c(-8, -2, eps, eps, eps)
categories_range_max <- c(-eps, 0, 1 - eps, 1, 10)


# Call the main model
result <- AdPaikModel(formula, data_dropout, time_axis,
                      categories_range_min, categories_range_max, TRUE)


[Package TimeDepFrail version 0.1.0 Index]