Teradata Python Package Function Reference - 16.20 - CoxHazardRatio - Teradata Python Package

Teradata® Python Package Function Reference

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

 
teradataml.analytics.mle.CoxHazardRatio = class CoxHazardRatio(builtins.object)
     Methods defined here:
__init__(self, object=None, predicts=None, refs=None, predict_feature_names=None, predict_feature_columns=None, predict_feature_units_columns=None, ref_feature_columns=None, accumulate=None, object_sequence_column=None, predicts_sequence_column=None, refs_sequence_column=None, predicts_partition_column='1', refs_partition_column='1', object_order_column=None, predicts_order_column=None, refs_order_column=None)
DESCRIPTION:
    The CoxHazardRatio function takes as input the coefficient_table teradataml
    DataFrame generated by the function CoxPH and outputs the hazard
    ratios between predictive features and either their corresponding
    reference features or their unit differences.
 
 
PARAMETERS:
    object:
        Required Argument.
        This teradataml DataFrame that specifies the feature coefficients.
 
    object_order_column:
        Optional Argument.
        Specifies Order By columns for object.
        Values to this argument can be provided as a list, if multiple
        columns are used for ordering.
        Types: str OR list of Strings (str)
 
    predicts:
        Required Argument.
        This teradataml DataFrame that specifies new feature values or unit changes
        for prediction.
 
    predicts_partition_column:
        Optional Argument.
        Specifies Partition By columns for predicts.
        Values to this argument can be provided as list, if multiple columns
        are used for partition.
        Default Value: 1
        Types: str OR list of Strings (str)
 
    predicts_order_column:
        Optional Argument.
        Specifies Order By columns for predicts.
        Values to this argument can be provided as a list, if multiple
        columns are used for ordering.
        Types: str OR list of Strings (str)
 
    refs:
        Optional Argument.
        This teradataml DataFrame that specifies reference feature values.
 
    refs_partition_column:
        Optional Argument.
        Specifies Partition By columns for refs.
        Values to this argument can be provided as list, if multiple columns
        are used for partition.
        Default Value: 1
        Types: str OR list of Strings (str)
 
    refs_order_column:
        Optional Argument.
        Specifies Order By columns for refs.
        Values to this argument can be provided as a list, if multiple
        columns are used for ordering.
        Types: str OR list of Strings (str)
 
    predict_feature_names:
        Required Argument.
        Specifies the names of the features in the Cox coefficient model (the
        coefficient teradataml DataFrame generated by the CoxPH function).
        Types: str OR list of Strings (str)
 
    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 corresponds to the ith pf_value_column.
        Types: str OR list of Strings (str)
 
    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 corresponds to the ith pf_unit_column.
        Types: str OR list of Strings (str)
 
    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
        rf_value_column. The default reference values are the distinct
        feature value combinations.
        Note: The function ignores this argument if you specify
              predict_feature_units_columns.
        Types: str OR list of Strings (str)
 
    accumulate:
        Optional Argument.
        Specifies the names of the columns in predict_feature_table that the
        function copies to the output table.
        Types: str OR list of Strings (str)
 
    object_sequence_column:
        Optional Argument.
        Specifies the list 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.
        Types: str OR list of Strings (str)
 
    predicts_sequence_column:
        Optional Argument.
        Specifies the list 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.
        Types: str OR list of Strings (str)
 
    refs_sequence_column:
        Optional Argument.
        Specifies the list 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.
        Types: str OR list of Strings (str)
 
RETURNS:
    Instance of CoxHazardRatio.
    Output teradataml DataFrames can be accessed using attribute
    references, such as CoxHazardRatioObj.<attribute_name>.
    Output teradataml DataFrame attribute name is:
        result
 
 
RAISES:
    TeradataMlException
 
 
EXAMPLES:
    # Load the data to run the example.
    load_example_data("coxhazardratio", ["lungcancer","lc_new_reference","lc_new_predictors"])
 
    # Create teradataml DataFrame objects.
    lungcancer = DataFrame.from_table("lungcancer")
 
    # Input table lc_new_predictors is a list of four patients who have been
    # diagnosed with lung cancer.
    lc_new_predictors = DataFrame.from_table("lc_new_predictors")
 
    # Generate model table.
    td_coxph_out = CoxPH(data = lungcancer,
            feature_columns = ["trt","celltype","karno","diagtime","age","prior"],
            time_interval_column = "time_int",
            event_column = "status",
            categorical_columns = ["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.
    cox_hazard_ratio_out1 = CoxHazardRatio(object = td_coxph_out.coefficient_table,
            predicts = lc_new_predictors,
            predicts_partition_column='id',
            predict_feature_names = ["trt", "celltype","karno","diagtime","age","prior"],
            predict_feature_columns = ["trt","celltype","karno","diagtime","age", "prior"],
            accumulate = ["id", "name"])
 
    # Print the results.
    print(cox_hazard_ratio_out1.result)
 
    # Example 2: Partition by Name/ID and No Reference Values
    cox_hazard_ratio_out2 = CoxHazardRatio(object = td_coxph_out.coefficient_table,
            predicts = lc_new_predictors,
            predicts_partition_column=["id", "name"],
            predict_feature_names = ["trt", "celltype","karno","diagtime","age","prior"],
            predict_feature_columns = ["trt","celltype","karno","diagtime","age", "prior"],
            accumulate = ["id", "name"])
 
    # Print the results.
    print(cox_hazard_ratio_out2.result)
 
    # 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 = DataFrame.from_table("lc_new_reference")
 
    cox_hazard_ratio_out3 = CoxHazardRatio(object=td_coxph_out.coefficient_table,
            predicts=lc_new_predictors,
            refs=lc_new_reference,
            predicts_partition_column='id',
            predict_feature_columns=['trt','celltype','karno','diagtime','age','prior'],
            ref_feature_columns=['trt','celltype','karno','diagtime','age','prior'],
            predict_feature_names=['trt','celltype','karno','diagtime','age','prior'],
            accumulate = ["id", "name"])
 
    # Print the results.
    print(cox_hazard_ratio_out3.result)
 
    # 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.
 
    cox_hazard_ratio_out4 = CoxHazardRatio(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=['trt','celltype','karno','diagtime','age','prior'],
            ref_feature_columns=['trt','celltype','karno','diagtime','age','prior'],
            predict_feature_names=['trt','celltype','karno','diagtime','age','prior'],
            accumulate = ["id", "name"])
 
    # Print the results.
    print(cox_hazard_ratio_out4.result)
 
    # 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_query = DataFrame.from_query("select id, "name",(karno * 1.1) as karno , (diagtime * 1) as diagtime, (age * (0.9))  as age from lc_new_predictors")
    copy_to_sql(lc_new_predictors_query, "lc_new_predictors_2")
    lc_new_predictors_2 = DataFrame("lc_new_predictors_2")
 
    cox_hazard_ratio_out5 = CoxHazardRatio(object=td_coxph_out.coefficient_table,
             predicts=lc_new_predictors_2,
             predict_feature_names=['karno','diagtime','age'],
             predict_feature_units_columns=['karno','diagtime','age'],
             accumulate = ["id", "name"],
             predicts_partition_column='id')
 
    # Print the results.
    print(cox_hazard_ratio_out5.result)
__repr__(self)
Returns the string representation for a CoxHazardRatio class instance.