Teradata R Package Function Reference - 16.20 - CoxHazardRatio - Teradata R Package

Teradata® R Package Function Reference

prodname
Teradata R Package
vrm_release
16.20
created_date
February 2020
category
Programming Reference
featnum
B700-4007-098K

Description

The CoxHazardRatio function takes as input the coefficient table generated by the function td_coxph_mle and outputs the hazard ratios between predictive features and either their corresponding reference features or their unit differences.

Usage

  td_cox_hazard_ratio_mle (
      object = NULL,
      predicts = NULL,
      refs = NULL,
      predict.feature.names = NULL,
      predict.feature.columns = NULL,
      predict.feature.units.columns = NULL,
      ref.feature.columns = NULL,
      accumulate = NULL,
      object.sequence.column = NULL,
      predicts.sequence.column = NULL,
      refs.sequence.column = NULL,
      predicts.partition.column = NULL,
      refs.partition.column = NULL
  )

Arguments

object

Required Argument.
Specifies the Cox coefficient model table generated by the td_coxph_mle function or the tibble object of the coefficients table output by td_coxph_mle function.

predicts

Required Argument.
Specifies the input tibble object defining new feature values or unit changes for prediction.

predicts.partition.column

Optional Argument.
Partition By columns for predicts. Values to this argument can be provided as vector, if multiple columns are used for ordering.

refs

Optional Argument.
Specifies the input tibble object containing reference feature values.

refs.partition.column

Optional Argument. Partition By columns for argument refs. Values to this argument can be provided as vector, if multiple columns are used for ordering.

predict.feature.names

Required Argument.
Specifies the names of the features in the Cox coefficient model (the coefficient table generated by the td_coxph_mle function).

predict.feature.columns

Optional Argument.
Specifies the names of the columns that contain the values of the features in the Cox coefficient model. This argument must specify a column for each feature specified by predict.feature.names. The ith predict.feature.names corresponds to the ith predict.feature.columns(values of the prediction variables).

predict.feature.units.columns

Optional Argument.
Specifies the names of the columns that contain the unit values of the features in the Cox coefficient model. This argument must specify a column for each feature specified by predict.feature.names. The ith predict.feature.names corresponds to the ith predict.feature.units.columns.

ref.feature.columns

Optional Argument.
Specifies the names of the columns that contain the reference values. This argument must specify a column for each feature specified by predict.feature.names. The ith predict.feature corresponds to the ith ref.feature.columns. The default reference values are the distinct feature-value combinations.
Note: The function ignores this argument if you specify predict.feature.units.columns.

accumulate

Optional Argument.
Specifies the names of the columns in the table specified in "predicts" argument that the function copies to the output table.

object.sequence.column

Optional Argument.
Specifies the vector of column(s) that uniquely identifies each row of the input argument "object". The argument is used to ensure deterministic results for functions which produce results that vary from run to run.

predicts.sequence.column

Optional Argument.
Specifies the vector of column(s) that uniquely identifies each row of the input argument "predicts". The argument is used to ensure deterministic results for functions which produce results that vary from run to run.

refs.sequence.column

Optional Argument.
Specifies the vector of column(s) that uniquely identifies each row of the input argument "refs". The argument is used to ensure deterministic results for functions which produce results that vary from run to run.

Value

Function returns an object of class "td_cox_hazard_ratio_mle" which is a named list containing Teradata tbl object.
Named list member can be referenced directly with the "$" operator using name: result.

Examples

    # Get the current context/connection
    con <- td_get_context()$connection
    
    # Load example data.
    loadExampleData("coxhazardratio_example", "lc_new_reference", "lc_new_predictors")
    loadExampleData("coxph_example", "lungcancer")
    
    # Create remote tibble objects.
    lungcancer <- tbl(con, "lungcancer")
    
    # Input table lc_new_predictors is a list of four patients who have been
    # diagnosed with lung cancer.
    lc_new_predictors <- tbl(con,"lc_new_predictors")
    
    # Generate model table.
    td_coxph_out <- td_coxph_mle(data = lungcancer,
                             feature.columns = c("trt","celltype","karno","diagtime","age","prior"),
                             time.interval.column = "time_int",
                             event.column = "status",
                             categorical.columns = c("trt","celltype","prior")
                             )
    
    
    # Example 1 - No Reference Values Provided.
    # This example calculates four hazard ratios for each patient, 
    # using individual patient characteristics as a reference.
    td_cox_hazard_ratio_out1 <- td_cox_hazard_ratio_mle(object = td_coxph_out$coefficient.table,
                                                   predicts = lc_new_predictors,
                                                   predict.feature.names = c("trt", "celltype","karno","diagtime","age",
                                                                             "prior"),
                                                   predict.feature.columns = c("trt",
                                                                               "celltype","karno","diagtime","age", "prior"),
                                                   accumulate = c("id", "name")
                                                   )
                                                   
    # Example 2: Partition by Name/ID and No Reference Values
    td_cox_hazard_ratio_out2 <- td_cox_hazard_ratio_mle(object = td_coxph_out$coefficient.table,
                                                   predicts = lc_new_predictors,
                                                   predicts.partition.column=c("id", "name"),
                                                   predict.feature.names = c("trt", "celltype","karno","diagtime","age",
                                                                             "prior"),
                                                   predict.feature.columns = c("trt",
                                                                               "celltype","karno","diagtime","age", "prior"),
                                                   accumulate = c("id", "name")
                                                   )
                                                   
    # Example 3:  Use Reference Values
    # Each of the four new patients in the table lc_new_predictors are compared with each of the attribute reference values provided
    # in the table lc_new_reference, and a hazard ratio is calculated.
    
    lc_new_reference <- tbl(con,"lc_new_reference")
      
    td_cox_hazard_ratio_out3 <- td_cox_hazard_ratio_mle(object=td_coxph_out$coefficient.table,
                                                   predicts=lc_new_predictors,
                                                   refs=lc_new_reference,
                                                   predict.feature.columns=c('trt','celltype','karno','diagtime','age','prior'),
                                                   ref.feature.columns=c('trt','celltype','karno','diagtime','age','prior'),
                                                   predict.feature.names=c('trt','celltype','karno','diagtime','age','prior'),
                                                   accumulate = c("id", "name")
                                                   )                                            
       
    # Example 4: Use Reference values and Partition by id
    # In this example, the new patients in the input table lc_new_predictors
    # are compared with the reference table using partition by id. 
    # The hazard ratio is calculated only when the patient's id matches the reference id.
    
    td_cox_hazard_ratio_out4  <- td_cox_hazard_ratio_mle(object=td_coxph_out$coefficient.table,
                                                   predicts=lc_new_predictors,
                                                   predicts.partition.column='id',
                                                   refs=lc_new_reference,
                                                   refs.partition.column='id',
                                                   predict.feature.columns=c('trt','celltype','karno','diagtime','age','prior'),
                                                   ref.feature.columns=c('trt','celltype','karno','diagtime','age','prior'),
                                                   predict.feature.names=c('trt','celltype','karno','diagtime','age','prior'),
                                                   accumulate = c("id", "name")
                                                   ) 
    
      
     # Example 5: Use Units Values
     # This example increases the variable karno by 10%, decreases the variable age by
     # 10%, leaves the variable diagtime unchanged, and calculates the hazard ratios.
     
     lc_new_predictors_2 <- lc_new_predictors %>% transmute(id, name,karno = karno * 1.1 , diagtime = diagtime * 1, age = age * (0.9)) 
     td_cox_hazard_ratio_out5  <- td_cox_hazard_ratio_mle(object=td_coxph_out$coefficient.table,
                                                   predicts=lc_new_predictors_2,
                                                   predict.feature.names=c('karno','diagtime','age'),
                                                   predict.feature.units.columns=c('karno','diagtime','age'),
                                                   accumulate = c("id", "name")
                                                   )