Teradata Package for Python Function Reference - 17.00 - IdentityMatch - Teradata Package for Python

Teradata® Package for Python Function Reference

Product
Teradata Package for Python
Release Number
17.00
Release Date
April 2021
Content Type
Programming Reference
Publication ID
B700-4008-070K
Language
English (United States)

 
teradataml.analytics.mle.IdentityMatch = class IdentityMatch(builtins.object)
     Methods defined here:
__init__(self, source_data=None, reference_data=None, source_id_column=None, reference_id_column=None, source_nominalmatch_columns=None, reference_nominalmatch_columns=None, fuzzymatch_columns=None, threshold=0.5, source_accumulate=None, reference_accumulate=None, source_data_sequence_column=None, reference_data_sequence_column=None, source_data_partition_column='ANY', reference_data_partition_column=None, source_data_order_column=None, reference_data_order_column=None, handle_nulls='mismatch')
DESCRIPTION:
    The IdentityMatch function tries to match source data with reference 
    data, using specified attributes to calculate the similarity score of
    each source-reference pair, and then computes the final similarity score.
    Typically, the source data is about business customers and the reference
    data is from external sources, such as online forums and social networking
    services. The IdentityMatch function is designed to help determine if customers
    with similar identifiers are the same customer. The function supports both
    nominal (exact) matching and weighted fuzzy matching.
 
PARAMETERS:
    source_data:
        Required Argument.
        Specifies the source input teradataml DataFrame.
    
    source_data_partition_column:
        Optional Argument.
        Specifies Partition By columns for source_data.
        Values to this argument can be provided as a list, if multiple 
        columns are used for partition.
        Default Value: ANY
        Types: str OR list of Strings (str)
    
    source_data_order_column:
        Optional Argument.
        Specifies Order By columns for source_data.
        Values to this argument can be provided as a list, if multiple 
        columns are used for ordering.
        Types: str OR list of Strings (str)
    
    reference_data:
        Required Argument.
        Specifies the reference input teradataml DataFrame.
    
    reference_data_partition_column:
        Optional Argument.
        Specifies Partition By columns for reference_data.
        Values to this argument can be provided as a list, if multiple 
        columns are used for partition.
        Types: str OR list of Strings (str)
    
    reference_data_order_column:
        Optional Argument.
        Specifies Order By columns for reference_data.
        Values to this argument can be provided as a list, if multiple 
        columns are used for ordering.
        Types: str OR list of Strings (str)
    
    source_id_column:
        Required Argument.
        Specifies the name of the column in the source_data DataFrame
        that contain row identifiers. The function copies this column
        to the output DataFrame.
        Types: str
 
    reference_id_column:
        Required Argument.
        Specifies the name of the column in the reference_data DataFrame
        that contain row identifiers. The function copies this column
        to the output DataFrame.
        Types: str
    
    source_nominalmatch_columns:
        Optional Argument. Required if you omit fuzzymatch_columns.
        Specifies the names of the columns (attributes) in the source_data DataFrame
        to check for exact matching with the columns specified in
        reference_nominalmatch_columns. If any pair (a column in source_nominalmatch_columns
        and a column in reference_nominalmatch_columns argument) matches exactly,
        then their records are considered to be exact matches, and the function
        does not compare the fuzzy match attributes.
        Note:
            1. If this argument is provided, the 'reference_nominalmatch_columns' argument
               should also be provided.
            2. The number of columns provided in the 'source_nominalmatch_columns' and
            'reference_nominalmatch_columns' arguments should be equal.
        Types: str OR list of Strings (str)
 
    reference_nominalmatch_columns:
        Optional Argument. Required if you omit fuzzymatch_columns.
        Specifies the names of the columns (attributes) in the reference_data DataFrame
        to check for exact matching with the columns specified in
        source_nominalmatch_columns. If any pair (a column in source_nominalmatch_columns
        and a column in reference_nominalmatch_columns argument) matches exactly,
        then their records are considered to be exact matches, and the function
        does not compare the fuzzy match attributes.
        Note:
            1. If this argument is provided, the 'source_nominalmatch_columns' argument
               should also be provided.
            2. The number of columns provided in the 'source_nominalmatch_columns' and
            'reference_nominalmatch_columns' arguments should be equal.
        Types: str OR list of Strings (str)
    
    fuzzymatch_columns:
        Optional Argument. Required if you omit source_nominalmatch_columns and
        reference_nominalmatch_columns.
        Specifies the names of source_data and reference_data columns (attributes)
        and the fuzzy matching parameters match_metric, match_weight, and
        synonym_file (whose descriptions follow). If any pair is a fuzzy match,
        then their records are considered to be fuzzy matches, and the function
        reports the similarity score of these attributes.
        Fuzzy matching parameters:
        1. match_metric:
           This parameter specifies the similarity metric, which is a function that
           returns the similarity score (a value between 0 and 1) of two strings.
           The possible values of match_metric are:
            * EQUAL: If strings a and b are equal, then their similarity score
              is 1.0; otherwise it 0.0.
            * LD: The similarity score of strings a and b is
              f(a,b)=LD(a,b)/max(len(a),len(b)), where LD(a,b) is the Levenshtein
              distance between a with b.
            * D-LD: The similarity score of strings a and b is
              f(a,b)=LD(a,b)/max(len(a),len(b)), where LD(a,b) is the Damerau-Levenshtein
              distance between a and b.
            * JARO: The similarity score of strings a and b is the Jaro distance
              between them.
            * JARO-WINKLER: The similarity score of strings a and b
              is the Jaro-Winkler distance between them.
            * NEEDLEMAN-WUNSCH: The similarity score of strings a and b is the
              Needleman-Wunsch distance between them.
            * JD: The similarity score of strings a and b is the Jaccard distance
              between them. The function converts the strings a and b to sets s and t
              by splitting them by space and then uses the formula f(s,t)=|S intersection T|/|s union t|.
            * COSINE: The similarity score of strings a and b is calculated with
              their term frequency-inverse document frequency (TF-IDF) and cosine
              similarity.
              Note: The function calculates IDF only on the input relation stored in memory.
        2. match_weight:
           This parameter specifies the weight (relative importance) of the attribute
           represented by source_data and reference_data columns.
           The match_weight must be a positive number. The function normalizes each
           match_weight to a value in the range [0, 1]. Given match_weight values,
           w1, w2, ..., wn, the normalized value of wi is: wi /(w1+w2+...+ wn).
           For example, given two pairs of columns, whose match weights are 3 and 7,
           the function uses the weights 3/(3+7)=0.3 and 7/(3+7)=0.7 to compute the
           similarity score.
        3. synonym_file:
           This parameter (optional) specifies the dictionary that the function
           uses to check the two strings for semantic equality. In the dictionary,
           each line is a comma-separated list of synonyms.
           Note: You must install the dictionary before running the function.
        The dictionary has to be of the following form:
            {
                "source_column" : <name of column from source_data>,
                "reference_column" : <name of column from reference_data>,
                "match_metric": <value of match_metric>,
                "match_weight" : <weight of the attribute>,
                "synonym_file": <name of dictionary for semantic check>
            }
        where the synonym_file key and associated value are optional. You may pass a
        dictionary or list of dictionaries of the above form as a value to this argument.
        Types: dict OR list of Dictionaries (dict)
    
    threshold:
        Optional Argument.
        Specifies the threshold similarity score, a float value between 0 and 1.
        The function outputs only the records whose similarity score exceeds threshold.
        The higher the threshold, the higher the matching accuracy.
        Default Value: 0.5
        Types: float
    
    source_accumulate:
        Optional Argument.
        Specifies source_data teradataml DataFrame columns to copy to the output
        teradataml DataFrame.
        Types: str OR list of Strings (str)
 
    reference_accumulate:
        Optional Argument.
        Specifies reference_data teradataml DataFrame columns to copy to the output
        teradataml DataFrame.
        Types: str OR list of Strings (str)
    
    source_data_sequence_column:
        Optional Argument.
        Specifies the list of column(s) that uniquely identifies each row of 
        the input argument "source_data". 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)
    
    reference_data_sequence_column:
        Optional Argument.
        Specifies the list of column(s) that uniquely identifies each row of 
        the input argument "reference_data". 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)
 
    handle_nulls:
        Optional Argument.
        Specifies what score should be assigned for null/empty value.
        Note:
            "handle_nulls" argument support is only available when teradataml
            is connected to Vantage 1.3 version.
        Default Value: "mismatch"
        Permitted Values: mismatch, match-if-null, match-if-both-null
        Types: str
 
RETURNS:
    Instance of IdentityMatch.
    Output teradataml DataFrame can be accessed using attribute
    references, such as IdentityMatchObj.<attribute_name>.
    The "result" teradataml DataFrame has column names as "a.<column_name1>"
    and "b.<column_name2>", where:
    1. "a.<column_name1>" refers to "<column_name1>" column of "source_data"
       teradataml DataFrame.
    2. "b.<column_name2>" refers to "<column_name2>" column of "reference_data"
       teradataml DataFrame.
    Output teradataml DataFrame attribute name is:
        result
 
 
RAISES:
    TeradataMlException, TypeError, ValueError
 
 
EXAMPLES:
    # Load the data to run the example.
    load_example_data("IdentityMatch", ["applicant_reference", "applicant_external"])
 
    # Create teradataml DataFrame object.
    applicant_reference = DataFrame.from_table("applicant_reference")
    applicant_external = DataFrame.from_table("applicant_external")
 
    # Example - Find the credit scores of job applicants by matching the information in teradataml
    # DataFrames 'applicant_reference' and 'applicant_external'.
    # The example looks for exact matches (nominalmatch_columns) to the email address and approximate
    # matches (fuzzymatch_columns) for lastname, firstname, zip code, city, and department, with different
    # match metrics and match weights.
    # source_data: applicant_reference, which has hypothetical information from job applicants.
    # reference_data: applicant_external, an external source table, which has missing and incomplete
    # information, but includes credit scores.
    identitymatch_out = IdentityMatch(source_data=applicant_reference,
                                  source_data_partition_column='ANY',
                                  reference_data=applicant_external,
                                  source_id_column="id",
                                  reference_id_column="id",
                                  source_nominalmatch_columns="email",
                                  reference_nominalmatch_columns="email",
                                  fuzzymatch_columns=[ {"source_column" : "lastname", "reference_column" : "lastname",
                                  "match_metric": "JARO-WINKLER", "match_weight" : 3}, {"source_column" : "firstname",
                                  "reference_column" : "firstname", "match_metric": "JARO-WINKLER", "match_weight" : 2},
                                  {"source_column" : "zipcode", "reference_column" : "zipcode", "match_metric": "JD",
                                  "match_weight" : 2}, {"source_column" : "city", "reference_column" : "city",
                                  "match_metric": "LD", "match_weight" : 2}, {"source_column" : "department",
                                  "reference_column" : "department", "match_metric": "COSINE", "match_weight" : 1}],
                                  threshold=0.5,
                                  source_accumulate=["firstname","lastname","email","zipcode"],
                                  reference_accumulate=["lastname","email","zipcode","department","creditscore"],
                                  source_data_sequence_column='id'
                                  )
 
    # Print the output DataFrames.
    print(identitymatch_out.result)
__repr__(self)
Returns the string representation for a IdentityMatch class instance.
get_build_time(self)
Function to return the build time of the algorithm in seconds.
When model object is created using retrieve_model(), then the value returned is
as saved in the Model Catalog.
get_prediction_type(self)
Function to return the Prediction type of the algorithm.
When model object is created using retrieve_model(), then the value returned is
as saved in the Model Catalog.
get_target_column(self)
Function to return the Target Column of the algorithm.
When model object is created using retrieve_model(), then the value returned is
as saved in the Model Catalog.
show_query(self)
Function to return the underlying SQL query.
When model object is created using retrieve_model(), then None is returned.