Teradata Package for Python Function Reference | 20.00 - TargetEncodingFit - Teradata Package for Python - Look here for syntax, methods and examples for the functions included in the Teradata Package for Python.

Teradata® Package for Python Function Reference - 20.00

Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
VMware
Product
Teradata Package for Python
Release Number
20.00
Published
March 2024
Language
English (United States)
Last Update
2024-04-10
dita:id
TeradataPython_FxRef_Enterprise_2000
Product Category
Teradata Vantage
 
 
TargetEncodingFit

 
Functions
       
TargetEncodingFit(data=None, category_data=None, encoder_method=None, target_columns=None, response_column=None, alpha_prior=None, beta_prior=None, alpha_priors=None, num_distinct_responses=None, u0_prior=None, v0_prior=None, alpha0_prior=None, beta0_prior=None, default_values=None, **generic_arguments)
DESCRIPTION:
    The TargetEncodingFit() function generally uses the likelihood or expected
    value of the target variable for each category and encodes that category with
    that value. This technique works for both binary classification and regression
    and for multiclass classification a similar technique is applied, which encodes
    the categorical variable with k new variables, where k is the number of classes.
 
    The TargetEncodingFit() function takes the input data and a categorical data as
    input and generates the required hyperparameters, which will be used by the
    TargetEncodingTransform() function for encoding the categorical values.
 
    Notes:
        * This function requires the UTF8 client character set.
        * This function does not support Pass-Through Characters (PTCs).
        * This function does not support KanjiSJIS or Graphic data types.
        * The maximum number of unique categories in the particular
          column is 4000.
        * The maximum category length is 128 characters.
        * Columns with a large number of distinct categories can have an
          impact on query execution time.
 
    Usage considerations for TargetEncodingFit() function are:
        * The input data in the TargetEncodingFit() function can have no
          partition at all or have data_partition_column="ANY" .
        * The TargetEncodingFit() function requires a category data to be
          passed as a dimension. The category data should be generated by the
          CategoricalSummary() function.
        * Null categories will not be encoded.
        * The "default_values" argument should be provided to TargetEncodingFit()
          if user want to assign any target value for missing categories in the
          TargetEncodingTransform() function.
 
 
PARAMETERS:
    data:
        Required Argument.
        Specifies the input data containing the categorical
        target columns.
        Types: teradataml DataFrame
 
    category_data:
        Required Argument.
        Specifies the data containing the unique categories and their counts
        for each target columns.
        Types: teradataml DataFrame
 
    encoder_method:
        Required Argument.
        Specifies the encoder method:
            * If the response variable is following a binary classification,
              for example, values are either 0 or 1, use "encoder_method" as 'CBM_BETA'.
            * If the response variable is following a multi-class classification,
              for example, values are (1,...,k, where k is the number of classes),
              use "encoder_method" as 'CBM_DIRICHLET'.
            * If the response variable is following a regression, for example,
              values are contiguous numeric values, use "encoder_method" as
              'CBM_GAUSSIAN_INVERSE_GAMMA'.
        Notes:
            * The maximum length supported is 128.
            * "encoder_method" are not case sensitive.
        Permitted Values: CBM_BETA, CBM_DIRICHLET, CBM_GAUSSIAN_INVERSE_GAMMA
        Types: str
 
    target_columns:
        Required Argument.
        Specifies the column from the "data" that contains the categorical values
        to be encoded.
        Notes:
            * The maximum length supported is 128.
            * The maximum list length is 2018.
            * "target_columns" are not case sensitive.
        Types: str OR list of Strings (str)
 
    response_column:
        Required Argument.
        Specifies column from the "data" that contains the response values.
        Notes:
            * The maximum length supported is 128.
            * "response_column" are not case sensitive.
        Types: str
 
    alpha_prior:
        Optional Argument.
        Specifies the prior parameter of the 'CBM_BETA' encoder method.
        Types: int
 
    beta_prior:
        Optional Argument.
        Specifies the prior parameter of the 'CBM_BETA' encoder method.
        Types: int
 
    alpha_priors:
        Optional Argument.
        Specifies the prior parameter of the 'CBM_DIRICHLET' encoder method.
        Notes:
            * The number of values specified in this argument must be equal to
              "num_distinct_responses" value.
            * The maximum list length is 2018.
        Types: int OR list of ints
 
    num_distinct_responses:
        Required when "encoder_method" is 'CBM_DIRICHLET',
        optional otherwise.
        Specifies the number of distinct values present in the
        "response_column".
        Types: int
 
    u0_prior:
        Optional Argument.
        Specifies the prior parameter of the 'CBM_GAUSSIAN_INVERSE_GAMMA'
        encoder method.
        Types: int
 
    v0_prior:
        Optional Argument.
        Specifies the prior parameter of the 'CBM_GAUSSIAN_INVERSE_GAMMA'
        encoder method.
        Types: int
 
    alpha0_prior:
        Optional Argument.
        Specifies the prior parameter of the 'CBM_GAUSSIAN_INVERSE_GAMMA'
        encoder method.
        Types: int
 
    beta0_prior:
        Optional Argument.
        Specifies the prior parameter of the 'CBM_GAUSSIAN_INVERSE_GAMMA'
        encoder method.
        Types: int
 
    default_values:
        Optional Argument.
        Specifies the values to use when the category is not found during transform.
        When only one value is specified, it will be applied to all the target columns,
        otherwise the number of default values must be equal to the number of target
        columns.
        Note:
            * The maximum list length is 2018.
        Types: int OR list of ints
 
    **generic_arguments:
        Specifies the generic keyword arguments SQLE functions accept. Below
        are the generic keyword arguments:
            persist:
                Optional Argument.
                Specifies whether to persist the results of the
                function in a table or not. When set to True,
                results are persisted in a table; otherwise,
                results are garbage collected at the end of the
                session.
                Default Value: False
                Types: bool
 
            volatile:
                Optional Argument.
                Specifies whether to put the results of the
                function in a volatile table or not. When set to
                True, results are stored in a volatile table,
                otherwise not.
                Default Value: False
                Types: bool
 
        Function allows the user to partition, hash, order or local
        order the input data. These generic arguments are available
        for each argument that accepts teradataml DataFrame as
        input and can be accessed as:
            * "<input_data_arg_name>_partition_column" accepts str or
              list of str (Strings)
            * "<input_data_arg_name>_hash_column" accepts str or list
              of str (Strings)
            * "<input_data_arg_name>_order_column" accepts str or list
              of str (Strings)
            * "local_order_<input_data_arg_name>" accepts boolean
        Note:
            These generic arguments are supported by teradataml if
            the underlying SQL Engine function supports, else an
            exception is raised.
 
RETURNS:
    Instance of TargetEncodingFit.
    Output teradataml DataFrames can be accessed using attribute
    references, such as TargetEncodingFitObj.<attribute_name>.
    Output teradataml DataFrame attribute name is:
        1. result
        2. output_data
 
 
RAISES:
    TeradataMlException, TypeError, ValueError
 
 
EXAMPLES:
    # Notes:
    #     1. Get the connection to Vantage to execute the function.
    #     2. One must import the required functions mentioned in
    #        the example from teradataml.
    #     3. Function will raise error if not supported on the Vantage
    #        user is connected to.
 
    # Load the example data.
    load_example_data("teradataml", ["titanic"])
 
    # Create teradataml DataFrame objects.
    data_input = DataFrame.from_table("titanic")
 
    # Check the list of available analytic functions.
    display_analytic_functions()
 
    # Find the distinct values and counts for column 'sex' and 'embarked'.
    categorical_summ = CategoricalSummary(data = data_input,
                                          target_columns = ["sex", "embarked"]
                                          )
 
    # Find the distinct count of 'sex' and 'embarked' in which only 2 column should be present
    # name 'ColumnName' and 'CategoryCount'.
    category_data=categorical_summ.result.groupby('ColumnName').count()
    category_data = category_data.assign(drop_columns = True,
                                         ColumnName = category_data.ColumnName,
                                         CategoryCount = category_data.count_DistinctValue)
 
    # Example 1 : Generates the required hyperparameters when "encoder_method" is
    #             'CBM_BETA'.
    TargetEncodingFit_out1 = TargetEncodingFit(data = data_input,
                                               category_data = category_data,
                                               encoder_method = 'CBM_BETA',
                                               target_columns = ['sex', 'embarked'],
                                               response_column = 'survived',
                                               default_values = [-1, -2]
                                               )
    # Print the result DataFrame.
    print(TargetEncodingFit_out1.result)
    print(TargetEncodingFit_out1.output_data)
 
    # Example 2 : Generates the required hyperparameters when "encoder_method" is
    #             'CBM_DIRICHLET'.
    TargetEncodingFit_out2 = TargetEncodingFit(data = data_input,
                                               category_data = category_data,
                                               encoder_method = 'CBM_DIRICHLET',
                                               target_columns = ['sex', 'embarked'],
                                               response_column = 'pclass',
                                               num_distinct_responses = 3
                                               )
    # Print the result DataFrame.
    print(TargetEncodingFit_out2.result)
    print(TargetEncodingFit_out2.output_data)
 
    # Example 3 : Generates the required hyperparameters when "encoder_method" is
    #             'CBM_GAUSSIAN_INVERSE_GAMMA'.
    TargetEncodingFit_out3 = TargetEncodingFit(data = data_input,
                                               category_data = category_data,
                                               encoder_method = 'CBM_GAUSSIAN_INVERSE_GAMMA',
                                               target_columns = ['sex', 'embarked'],
                                               response_column = 'age',
                                               default_values = [-1, -2]
                                               )
 
    # Print the result DataFrame.
    print(TargetEncodingFit_out3.result)
    print(TargetEncodingFit_out3.output_data)